Hydration
Hydration in Juice is selective, not global. The HTML page renders on the server, then only components marked with 'use client' become interactive in the browser.
How Hydration Works in Juice
Juice has two render paths that share the same component tree:
- Initial request (HTML): server renders the full document. Browser paints immediately.
- Client hydration: React hydrates only client boundaries (
'use client'files). - Subsequent navigation (segments): the client fetches only the layout segment that changed, as HTML, and swaps it in without a full reload. Islands inside the new segment hydrate as they appear.
- Regions that change on their own (slices): a
<Slice href>embeds another route in the page and refreshes it after server actions, as HTML. See Partial Rendering.
Server components never hydrate in the browser. They produce HTML and stay server-only by design.
What Juice Injects at Render Time
During HTML rendering, Juice injects bootstrap modules in this order: client entry (the hydration bootstrap), client component chunks, then HMR client in development. This ordering is how the browser gets the code needed to hydrate client boundaries.
The Most Important Rule
Your interactive code must be compiled by the Juice Vite plugin. Hydration requires Juice's manifest, client chunk mapping, and bootstrap scripts. If a page is built in a separate project pipeline, Juice cannot hydrate it.
// Works: component is in Juice app and compiled by Juice plugin
'use client';
import { useState } from 'react';
export function Counter() {
const [count, setCount] = useState(0);
return <button onClick={() => setCount(c => c + 1)}>{count}</button>;
}Checklist: Why Hydration Is Not Working
1) Missing or misplaced 'use client'
The directive must be the first statement in the file (before imports). If it appears later, Juice treats the module as server-only and no client chunk is emitted.
2) Page is outside the Juice compile pipeline
If your page lives in another project or is rendered by a different build system, it will not be registered in Juice's client module registry. Result: HTML renders, but no interactivity.
3) You are only verifying in dev and expecting production behavior
Always verify hydration issues in a production build too. Production is the source of truth for RSC + selective hydration behavior.
bun run build
bun run preview4) Client bundle/bootstrap not loading in browser
Open DevTools and check that module scripts and client chunks load successfully (no 404/500). A failed script request means React never hydrates.
5) Runtime serving stale manifest
Hydration depends on flight-manifest.json. If stale, the runtime can render old routes or miss new client modules. Rebuild to regenerate.
Debug Workflow (Fast)
- Pick one broken interactive component and confirm
'use client'is first. - Confirm that file is imported by a route/layout inside
app/routes/. - Run production build and preview locally.
- In browser network tab, verify JS module scripts/chunks load without errors.
- Click a link and verify the request carries
X-Juice-Segmentand the responseX-Juice-Segment-Depth.
Compliance Rules for Juice Hydration
- Directive correctness:
'use client'must be the first statement in the module. - Boundary separation: do not mix
'use client'and'use server'in the same file. - Client safety: client modules must not import Node builtins like
fs,path,child_process,net. - Runtime contract: run server and manifest from the same build output.
- Navigation contract: for SPA transitions, the client sends its layout chain in
X-Juice-Segmentand the server returns the changed segment as HTML.
Using Juice with a Separate Frontend Project
If your UI is in another project, choose one architecture and keep boundaries explicit:
- Recommended: move interactive route components into the Juice app so Juice compiles and hydrates them.
- Alternative: keep Juice as API/RSC backend and let the other frontend fully own hydration with its own React root.
Mixing output from one toolchain with hydration expectations from another is the most common cause of "it renders but does not hydrate".
Minimal Working Pattern
// app/routes/home.tsx (server component)
import React from 'react';
import { Counter } from '../components/counter';
export default function Home() {
return (
<div>
<h1>Home</h1>
<Counter />
</div>
);
}
// app/components/counter.tsx (client component)
'use client';
import React, { useState } from 'react';
export function Counter() {
const [n, setN] = useState(0);
return <button onClick={() => setN(n + 1)}>Clicked {n} times</button>;
}Compound Components and Context
Each client component a server component renders is hydrated as its own React root, with one exception: client components passed to a client component as props (children included) hydrate inside that component's root. Compound components therefore share React context and state the way they do in a single React app.
// app/ui/index.ts
'use client';
export * as Tabs from './tabs'; // Root, List, Tab, Panel
// app/routes/settings.tsx (server component)
import { Tabs } from '../ui';
export default function Settings() {
return (
<Tabs.Root defaultValue="profile">
<Tabs.List>
<Tabs.Tab value="profile">Profile</Tabs.Tab>
<Tabs.Tab value="billing">Billing</Tabs.Tab>
</Tabs.List>
<Tabs.Panel value="profile"><ProfileForm /></Tabs.Panel>
<Tabs.Panel value="billing"><Invoices /></Tabs.Panel>
</Tabs.Root>
);
}- Parts can be separate exports, an exported object (
export const Tabs = { Root, Tab }), a namespace re-export (export * as Tabs) or properties of a component (Tabs.Tab = Tab). - HTML elements and fragments between the parts (the
<li>around an item) are fine. A server component between them is a boundary: what it renders is HTML to the browser, so a client component inside it is a separate root without the outer context. Above,ProfileFormandInvoicesare such boundaries. - Server content a part receives is only available to the browser if the part rendered it on the server. A panel that leaves its children out while closed has nothing to show when it opens; render them hidden instead.
Troubleshooting Matrix
| Symptom | Likely Cause | Fix |
|---|---|---|
| Button renders but click does nothing | Component not marked as client boundary | Add 'use client' as first statement |
| Part throws "must be used within..." or misses its context in the browser only | A server component sits between the part and its root | Pass the part to the root directly, or make the component in between a client component |
| Works in one app but not another | Different build pipeline, missing Juice plugin pass | Compile interactive code in Juice project |
| Random stale behavior after deploy | Stale flight-manifest.json | Rebuild and redeploy manifest + server together |
| Navigation causes full reload | Client navigation bootstrap/chunks not running | Check script load failures and console errors |