Skip to content

Internals

Implementation details that are useful for debugging and understanding how Juice works under the hood. These are not part of the public API and may change between versions.

Islands and Segments

Juice renders every page with react-dom/server, client components included. There is no React Flight payload and no react-server-dom-webpackdependency. Two kinds of HTML markers carry everything the browser needs:

  • <juice-island>: wraps each 'use client'component the server rendered, with its module id and serialized props. The client bootstrap hydrates each one as its own React root, loading the component's chunk on demand. Server-rendered element props (children) sit in <juice-slot> elements and are reused as-is. Client components among those props are recorded in the island's props by id, with the HTML elements between them and the island, and hydrate inside the island's root.
  • <juice-segment>: wraps each layout's children; depth 1 is the root layout's children, depth n the page. A navigation sends the layout chain the document holds in X-Juice-Segment; the server renders from the first layout that differs and answers with that segment and X-Juice-Segment-Depth. Segment responses vary on the request header, are rendered complete (no streaming), and carry no bootstrap scripts.

Both markers render with display: contents, so they do not affect layout. The same code produces them in vite dev and in production builds.

Flight Manifest

The flight manifest is a JSON file generated by the Vite plugin at build time. It maps URL patterns to component modules, tracks client component chunks, and registers server action IDs. The router reads this file at startup — it is the only contract between the build step and the runtime.

{
  "routes": {
    "/": { "moduleId": "./app/routes/home.tsx" },
    "/blog/:slug": { "moduleId": "./app/routes/blog/[slug].tsx" }
  },
  "clientModules": {
    "./app/components/Counter.tsx": {
      "id": "Counter",
      "chunks": ["assets/Counter-abc123.js"]
    }
  },
  "serverActions": {
    "action_1a2b3c": {
      "moduleId": "./app/routes/tasks.tsx",
      "exportName": "createTask"
    }
  }
}

The manifest is plain JSON. You can inspect it after a build at dist/flight-manifest.json. Diffing manifests across deploys shows exactly what routes, components, or actions changed.

Manifest normalization

The compiler and runtime use slightly different field names for historical reasons. The runtime normalizes at startup: module becomes moduleId, name becomes exportName. This is transparent — you never interact with the manifest directly.

Route Matching

Routes are matched using the WinterCG URLPattern API. At startup, createRouter compiles the manifest's route patterns into an array of URLPattern instances, sorted by specificity (static routes before dynamic routes).

Static routes (no :params or * wildcards) are also indexed in a Map for O(1) lookup. The matching flow:

  1. Check the static route map (O(1)) — handles most requests
  2. Fall through to URLPattern iteration for dynamic routes
  3. Try with and without trailing slash for both paths

Streaming Pipeline

The render pipeline uses renderToReadableStream from react-dom/server (the web streams version, not Node.js streams). The three streaming modes control when headers are committed:

  • false (wait): calls stream.allReadybefore creating the Response. All Suspense boundaries resolve before the first byte.
  • 'shell': the shell renders synchronously (the renderToReadableStream promise resolves when the shell is ready). The Response is created immediately, and remaining Suspense content streams in.
  • true (full stream): uses a TransformStreamto pipe React's output to the client immediately. Recovery scripts are injected between data chunks for errors that occur after streaming starts.

Error recovery in full streaming mode works by: React's onError callback pushes recovery HTML chunks into an array. The transform stream writer flushes these between React's data chunks. Each recovery chunk is a <script> that replaces the nearest incomplete Suspense boundary with a fallback message.

Context Isolation

Request context uses a two-tier system:

  1. AsyncLocalStorage (primary): imported from node:async_hooks in a try-catch. When available, each request runs inside als.run(new Map(), fn). This provides implicit context — any function in the async call stack can read it without passing the request.
  2. WeakMap (fallback): keyed by Request object. Requires explicit request reference to read context. Automatically garbage collected when the request completes.

The cache() function stores its deduplication map in whatever storage is active. In ALS mode, the cache is scoped to the ALS store. In WeakMap mode, it uses a _currentRequest reference set by the render pipeline.