AbsoluteJS

Partial Prerendering

Partial prerendering serves a pre-rendered page as a cached shell, then streams the parts that change per visitor into it. You mark those parts as dynamic slots. It works for React and Svelte pages.

#How It Works

A page that is pre-rendered is the same for every visitor. A page rendered per request waits for all of its data. Partial prerendering splits the page: the static parts are rendered once, and only the dynamic slots are rendered for each request.

1. CaptureAt build time, AbsoluteJS renders each route in static.routes and stores it as a shell. Static slots resolve and their results go into the shell. Dynamic slots keep their fallback, and their resolvers do not run.
2. Serve the shellA request for the route gets the cached shell at once, before the route handler runs.
3. Stream the holesThe route then renders with the visitor's cookies and headers. Only its dynamic slots resolve, and each one streams into the page already sent.

#Static Routes

List the routes to pre-render in static.routes. There is no separate flag. A listed route becomes a partial shell when its page renders at least one dynamic slot. A listed route with no dynamic slot is pre-rendered in full.

TS
// absolute.config.ts
import { defineConfig } from '@absolutejs/absolute';

export default defineConfig({
  reactDirectory: 'src/frontend/react',
  svelteDirectory: 'src/frontend/svelte',
  static: {
    // Re-capture each shell in the background once it is older than 60 seconds
    revalidate: 60,
    routes: ['/pricing', '/account']
  }
});

Pre-rendering runs when you start the production server with absolute start, and in absolute compile. A new build captures every shell again.

A listed route that can't be pre-rendered renders on each request instead. Pre-rendering logs one warning for each such route, with the reason. A route that responds with an error status or with something other than HTML is one example.

TXT
[cli] Could not pre-render /account: the route responded with HTTP 500. It renders on each request instead.

#Dynamic Slots

A dynamic slot is a streaming slot with the dynamic flag. Mark every slot that reads the request, such as a cookie or session, or that must be fresh on each visit.

FrameworkDynamic slot
React<SuspenseSlot dynamic>
React<StreamSlot dynamic>
Svelte<StreamSlot dynamic>
Svelte<AwaitSlot dynamic>
Svelte<!-- absolute:stream dynamic --> before an {#await} block

Everything outside the dynamic slots, including the props the route handler passes to the page, is rendered once when the shell is captured. Keep per-visitor data inside dynamic slots.

#Static Slots

A streaming slot without dynamic is static. When the shell is captured, AbsoluteJS waits for every static slot, including one with an async resolver, and stores its result in the shell. Every visitor gets that stored result. The resolver runs again only when the shell is captured again.

TSX
{/* Static: resolved once, when the shell is captured */}
<StreamSlot
  fallbackHtml="<p>Loading plans...</p>"
  id="plans"
  resolve={async () => {
    const plans = await getPlans();

    return `<ul>${plans.map((plan) => `<li>${plan.name}</li>`).join('')}</ul>`;
  }}
/>

{/* Dynamic: resolved for each visitor */}
<SuspenseSlot
  dynamic
  fallback={<p>Loading your cart...</p>}
  id="cart"
  resolve={async () => {
    const cart = await getCart(userId);

    return <p>{cart.items.length} items in your cart</p>;
  }}
/>

#React

Add dynamic to a SuspenseSlot or StreamSlot from @absolutejs/absolute/react/components. Here the plan list is part of the shell, and the cart is rendered for each visitor.

TSX
// src/frontend/react/pages/Pricing.tsx
import { SuspenseSlot } from '@absolutejs/absolute/react/components';
import { getCart } from '../../../data/cart';

type Plan = { id: string; name: string };
type PricingProps = { plans: Plan[]; userId: string };

export const Pricing = ({ plans, userId }: PricingProps) => (
  <html lang="en">
    <head>
      <meta charSet="utf-8" />
      <title>Pricing</title>
    </head>
    <body>
      <h1>Pricing</h1>

      {/* Static: rendered once into the shell */}
      <ul>
        {plans.map((plan) => (
          <li key={plan.id}>{plan.name}</li>
        ))}
      </ul>

      {/* Dynamic: rendered for each visitor */}
      <SuspenseSlot
        dynamic
        fallback={<p>Loading your cart...</p>}
        id="cart"
        resolve={async () => {
          const cart = await getCart(userId);

          return <p>{cart.items.length} items in your cart</p>;
        }}
      />
    </body>
  </html>
);

StreamSlot takes the same flag and resolves to an HTML string:

TSX
<StreamSlot
  dynamic
  fallbackHtml="<p>Loading your cart...</p>"
  id="cart"
  resolve={async () => {
    const cart = await getCart(userId);

    return `<p>${cart.items.length} items in your cart</p>`;
  }}
/>

React page handlers collect streaming slots by default, so the route needs nothing extra. The route below reads the user from a cookie and loads the plans that end up in the shell.

TS
// src/backend/server.ts
import { asset, prepare } from '@absolutejs/absolute';
import { handleReactPageRequest } from '@absolutejs/absolute/react';
import { handleSveltePageRequest } from '@absolutejs/absolute/svelte';
import { Elysia } from 'elysia';
import { getPlans } from '../data/plans';
import { Pricing } from '../frontend/react/pages/Pricing';
import type Account from '../frontend/svelte/pages/Account.svelte';

const { absolutejs, manifest } = await prepare();

const userIdFrom = (request: Request) =>
  request.headers.get('cookie')?.match(/user=(\w+)/)?.[1] ?? 'guest';

export const server = new Elysia()
  .use(absolutejs)
  .get('/pricing', async ({ request }) =>
    handleReactPageRequest({
      Page: Pricing,
      index: asset(manifest, 'PricingIndex'),
      props: { plans: await getPlans(), userId: userIdFrom(request) }
    })
  )
  .get('/account', ({ request }) =>
    handleSveltePageRequest<typeof Account>({
      // Svelte pages opt in to streaming slots
      collectStreamingSlots: true,
      indexPath: asset(manifest, 'AccountIndex'),
      pagePath: asset(manifest, 'Account'),
      props: { userId: userIdFrom(request) }
    })
  );

#Svelte

In Svelte, pass dynamic to StreamSlot or AwaitSlot, or put <!-- absolute:stream dynamic --> directly before an {#await} block.

SVELTE
<!-- src/frontend/svelte/pages/Account.svelte -->
<script lang="ts">
  import StreamSlot from '@absolutejs/absolute/svelte/components/StreamSlot.svelte';
  import { getCart, getRecommendations } from '../../../data/cart';

  let { userId }: { userId: string } = $props();

  const renderCart = async () => {
    const cart = await getCart(userId);

    return `<p>${cart.items.length} items in your cart</p>`;
  };

  const recommendations = getRecommendations(userId);
</script>

<main>
  <h1>Your account</h1>

  <StreamSlot
    dynamic
    fallbackHtml="<p>Loading your cart...</p>"
    id="cart"
    resolve={renderCart}
  />

  <!-- absolute:stream dynamic -->
  {#await recommendations}
    <p>Loading recommendations...</p>
  {:then items}
    <p>{items.length} picked for you</p>
  {/await}
</main>

Svelte routes opt in to streaming slots with collectStreamingSlots: true, as the /account route above does.

The branches of a streamed {#await} block are sent as HTML strings. They can hold elements, {expressions} and {@html}. Expressions are escaped as Svelte escapes them. A component, {#if} or {#each} inside them fails the build. Use StreamSlot when the slot needs more.

#Per-Request Rendering

The shell is the first thing the browser receives. Time to first byte is the cost of reading a file, whatever the route handler or the slots do. Each dynamic slot patches into its placeholder as it resolves.

HTML
HTTP/1.1 200 OK
Content-Type: text/html
Cache-Control: private, no-cache
x-absolute-partial-prerender: shell

<!-- The cached shell arrives first, with the slot fallback in place -->
<div data-absolute-slot="true" id="cart"><p>Loading your cart...</p></div>
...
<!-- This visitor's slot content streams in afterwards -->
<script nonce="...">...("cart", "<p>3 items in your cart</p>")</script>
</body></html>
Request dataThe route handler and page render run with a copy of the visitor's request, so slots see their cookies and headers. Each visitor gets their own holes.
CSP nonceUnder secureHeaders(), the shell is restamped with the request's CSP nonce, and every streamed patch carries the same nonce.
CachingThe response is sent with Cache-Control: private, no-cache, because the holes differ per visitor.
FailuresA slot that fails or times out keeps its fallback. If the render throws, the shell keeps all its fallbacks and the error is logged.
Status and redirectsThe status and headers are sent with the shell, so a partial route cannot redirect afterwards. Put auth redirects on routes that are not pre-rendered.

#Revalidation

Set static.revalidate to a number of seconds. When a shell is older than that, the next request still gets the stored shell, and AbsoluteJS captures a new one in the background. Later requests get the new shell.

Dynamic slots are never cached, so revalidate only controls how fresh the static parts of the page are.

#Development

absolute dev does not pre-render. Pages render in full on every request, and dynamic slots stream like any other slot.