Next.js AI Workbench Hydration Budgets: Tightening Client Boundaries and Initial JavaScript

AI workbenches often wrap the conversation tree, model selector, file panel, Markdown renderer, and editor in a top-level 'use client' page because "it contains an input field." In the Next.js App Router, this directive declares a client module graph boundary, so its imports and child components enter the client bundle. The server having already generated HTML does not mean the browser can skip downloading, executing, and hydrating these modules. Deep Dive into Next.js Server Components covers the architecture; this article defines a performance contract for the repository's current Next.js 16.2.6 version.

Inventory Boundaries Before Splitting Code

For each component in the initial viewport, document why it must run on the client: the editor needs state and events, the stop button needs interactivity, and size measurement needs browser APIs. Static headings, completed message bodies, account information, and server-side data fetching do not. Keep pages and layouts as Server Components, and make only the smallest ComposerIsland, RunControls, and components that genuinely need local state into Client Components. A Server Component can be passed into a client shell as children; visual nesting alone is not a reason to convert the entire static tree into client code.

Props passed to a Client Component must be serializable and contain only the fields required for initial interactions. Do not put the complete model catalog, the ASTs of every historical message, or server-side SDK configuration into the RSC payload. Load rich-text editors, charts, and advanced file previews with next/dynamic when the user opens them. The Next.js 16.2.6 documentation explicitly states that lazy loading applies to Client Components, while Server Components are code-split by default. ssr: false can be used only in a Client Component, and it must not be used to conceal hydration mismatches. The general principles in React Code Splitting must be supported here by evidence from actual route chunks.

Constrain Cold Starts with Two Sets of Metrics

The build gate reads the route asset manifest from the same production build and records the AI route's first-load JS files, raw bytes, compressed bytes, and dependency ownership. Initially set a 180 KiB ceiling for compressed initial-route JS while also requiring that it not grow by more than 5% over the approved baseline; the stricter condition applies. List shared framework chunks separately, but do not arbitrarily exclude them from before-and-after reports. The dynamic editor must not appear in cold-start requests and must be downloaded only once after it is opened.

The browser gate uses a fresh profile with an empty cache, replays 50 completed messages and one empty editor, and runs 30 times on either an approved mid-range mobile device or under fixed conditions of 4x CPU throttling, a 1.6 Mbps downlink, and 150 milliseconds of round-trip latency. LCP P75 must not exceed 2.5 seconds; the P75 time from navigation start until the editor accepts input and completes the next paint must not exceed 2 seconds; hydration may contain no more than two main-thread tasks longer than 50 milliseconds; the Event Timing duration P75 for the first click on the stop button must not exceed 200 milliseconds; and recoverable hydration errors must remain at 0. The Event Timing observer must explicitly set durationThreshold: 16, retain only entries with interactionId > 0, take the maximum duration for each interaction, and then aggregate the results. It must not use raw event entries collected under the default threshold. Store laboratory budgets separately from the field percentiles in Core Web Vitals; a single Lighthouse score is not a substitute.

instrumentation-client.ts runs after the HTML loads but before React hydration, making it suitable for establishing ai_boot_start and a lightweight PerformanceObserver. The Next.js 16.2.6 development environment warns when initialization there exceeds 16 milliseconds, so register only the mark and observer at this stage and defer the monitoring SDK dynamically. The editor component records composer_ready after its layout effect. Automation then immediately focuses the editor, types, and waits for a paint before calculating the actual time until the editor is operable; neither the load event nor an estimated hydration time is precise enough. Web Performance RUM samples production devices using the same fields.

Reproducibly Find Imports That Cross the Boundary

Run the benchmark separately for a direct visit, same-origin route navigation, and browser back navigation, saving the Network capture, Performance trace, script coverage, and build summary. Deliberately import the Markdown highlighter into ComposerIsland; the test must detect increases in initial JS and parse/compile time. After changing it to a dynamic import triggered when the user opens the preview, the cold start must not request that chunk. Then inject different default models on the server and client. The gate must catch the hydration error and must not allow it to pass through suppressHydrationWarning.

Suspense boundaries around streaming Server Components must also reserve stable fallback dimensions so that content replacement does not produce CLS. The LCP element should not be hidden inside a slow boundary. Next.js streaming HTML and client-side token streaming are two separate pipelines; the latter must still manage the connection lifecycle as described in Governing Next.js AI Streaming Responses. Narrower boundaries also do not mean that the server should resend an RSC payload for every high-frequency response.

At release time, save the build summary, chunk list, and approved thresholds in route-performance-manifest.json. First enable the narrow boundary for 1% of new sessions, then compare initial JS, composer ready, INP, and hydration errors by browser, device memory, and navigation type. Do not swap component graphs midway through existing sessions. If initial JS grows by more than 5%, composer ready P75 regresses by 20%, any recoverable hydration error occurs, or the dynamic chunk failure rate exceeds 0.5%, deploy the previous build and disable the boundary flag. A rollback must restore a matching set of HTML, RSC payload, and client chunks; reverting only one lazy-loaded file is insufficient.

Further Reading

• Deep Dive into Next.js Server Components
• React Code Splitting
• Core Web Vitals
• Web Performance RUM