AbsoluteJS

Server Components

React Server Components are an opt-in page type for React. A server component runs only on the server. It can be async and read data directly, and its code never ships to the browser. Components marked 'use client' render on the server and hydrate in the browser. You serve each page from an ordinary Elysia route.

#Setup

Server components need react-server-dom-webpack. Install it at the same version as react, 19.2.3 or later. The build reads it from your project and fails with an install instruction when it is missing.

BASH
# Use the exact version of react in your package.json (19.2.3 or later)
bun add react-server-dom-webpack@19.2.3

Then set reactServerComponentsDirectory in absolute.config.ts. It is separate from reactDirectory, so your existing React pages build and render exactly as before.

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

export default defineConfig({
  reactDirectory: 'src/frontend/react',
  reactServerComponentsDirectory: 'src/frontend/rsc'
});

Each file directly in the directory's pages folder is a page. Put shared server and client components anywhere else, for example in a components folder.

TXT
src/frontend/rsc/
├── pages/
│   ├── Dashboard.tsx     → asset(manifest, 'DashboardRSC')
│   └── ReportsRSC.tsx    → asset(manifest, 'ReportsRSC')
└── components/
    └── LikeButton.tsx    'use client'

#Page Keys

A page's manifest key is its file name with RSC appended. A file whose name already ends in RSC keeps its name, so pages/HomeRSC.tsx is 'HomeRSC'. Its old doubled key, 'HomeRSCRSC', still points to the same bundle as a deprecated alias.

Page fileasset(manifest, …) key
pages/Dashboard.tsxDashboardRSC
pages/HomeRSC.tsxHomeRSC
pages/HomeRSC.tsxHomeRSCRSC (deprecated alias, warns once in dev)

If pages/Home.tsx and pages/HomeRSC.tsx both exist, Home.tsx keeps HomeRSC, HomeRSC.tsx stays at HomeRSCRSC, and the build warns about the clash.

The page component is the export named after the file (Dashboard for Dashboard.tsx), or the default export.

#Async Pages

A page is a server component that renders the whole document, from <html> down. It can be an async function and await your database or API calls directly. Nested server components can be async too.

TSX
// src/frontend/rsc/pages/Dashboard.tsx
import { Suspense } from 'react';
import { getActivity, getProject } from '../../../data/projects';
import { LikeButton } from '../components/LikeButton';

export type DashboardProps = { projectId: string };

const Activity = async ({ projectId }: DashboardProps) => {
  const events = await getActivity(projectId);

  return (
    <ul>
      {events.map((event) => (
        <li key={event.id}>{event.label}</li>
      ))}
    </ul>
  );
};

export const Dashboard = async ({ projectId }: DashboardProps) => {
  const project = await getProject(projectId);

  return (
    <html lang="en">
      <head>
        <meta charSet="utf-8" />
        <title>{project.name}</title>
      </head>
      <body>
        <h1>{project.name}</h1>
        <LikeButton initialLikes={project.likes} />
        <Suspense fallback={<p>Loading activity...</p>}>
          <Activity projectId={projectId} />
        </Suspense>
      </body>
    </html>
  );
};

getProject and getActivity run on the server. Their code and the data modules they import stay out of the browser bundle. Page props go to the server component only; they are not written into the page as hydration props.

#Client Components

Add 'use client' at the top of a file to make its exports client components. They can use state, effects and event handlers. The server renders them into the HTML, and the browser hydrates them.

TSX
// src/frontend/rsc/components/LikeButton.tsx
'use client';

import { useState } from 'react';

type LikeButtonProps = { initialLikes: number };

export const LikeButton = ({ initialLikes }: LikeButtonProps) => {
  const [likes, setLikes] = useState(initialLikes);

  return (
    <button onClick={() => setLikes(likes + 1)} type="button">
      {likes} likes
    </button>
  );
};
Serializable propsProps passed from a server component to a client component cross to the browser, so they must be serializable. Pass data, not event handlers.
Per-page loadingThe browser downloads only the client components a page renders. Each one is loaded as its own chunk.
ImportsA client component can import anything, including components from your reactDirectory.

#Serving a Page

Call handleReactServerPageRequest from @absolutejs/absolute/react in any Elysia route. Pass the page's key as page and its props as props.

TS
// src/backend/server.ts
import { asset, prepare } from '@absolutejs/absolute';
import { handleReactServerPageRequest } from '@absolutejs/absolute/react';
import { Elysia } from 'elysia';
import type { DashboardProps } from '../frontend/rsc/pages/Dashboard';

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

export const server = new Elysia()
  .use(absolutejs)
  .get('/projects/:id', ({ params }) =>
    handleReactServerPageRequest<DashboardProps>({
      page: asset(manifest, 'DashboardRSC'),
      props: { projectId: params.id }
    })
  );

page is a manifest key, not a component, so the handler can't infer the page's props. Pass the props type as the generic, as above, to have props checked.

#Streaming

React's <Suspense> streams. In the dashboard above, the shell and the Loading activity... fallback arrive first, and the activity list streams in when getActivity resolves.

SuspenseSlot and StreamSlot also work inside server components. SuspenseSlot takes React content: a fallback plus resolve, promise or a render-prop children. StreamSlot resolves to an HTML string.

TSX
// src/frontend/rsc/pages/ReportsRSC.tsx
import {
  Link,
  StreamSlot,
  SuspenseSlot
} from '@absolutejs/absolute/react/components';
import { getAlerts, getRevenue } from '../../../data/reports';

const renderAlerts = async () => {
  const alerts = await getAlerts();

  return `<p>${alerts.length} open alerts</p>`;
};

export const ReportsRSC = () => (
  <html lang="en">
    <head>
      <meta charSet="utf-8" />
      <title>Reports</title>
    </head>
    <body>
      <Link href="/projects/42">Back to the dashboard</Link>

      {/* React content, rendered on the server */}
      <SuspenseSlot
        fallback={<p>Loading revenue...</p>}
        id="revenue"
        promise={getRevenue()}
      >
        {(revenue) => <p>Revenue: {revenue}</p>}
      </SuspenseSlot>

      {/* An HTML string */}
      <StreamSlot
        fallbackHtml="<p>Loading alerts...</p>"
        id="alerts"
        resolve={renderAlerts}
      />
    </body>
  </html>
);

The handler collects streaming slots by default. Pass collectStreamingSlots: false to turn that off for a route; slots there keep their fallback.

#AbsoluteJS Components

Import from @absolutejs/absolute/react/components directly in a server component. You don't need to wrap these in your own 'use client' file.

Server renderedSuspenseSlot, StreamSlot, Head, Image and JsonLd render on the server.
Client componentsLink and usePrefetch come from a client module. A server component can render <Link>, and it hydrates as a client component. Its props must be serializable.

#CSP Nonce

With secureHeaders() in use, every inline script a server components page writes carries the request's nonce. That covers the inlined server payload, React's streaming scripts and slot patches. The hydration entry script gets it too. No page code is needed.

TS
import { asset, prepare, secureHeaders } from '@absolutejs/absolute';
import { handleReactServerPageRequest } from '@absolutejs/absolute/react';
import { Elysia } from 'elysia';

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

export const server = new Elysia()
  .use(secureHeaders())
  .use(absolutejs)
  .get('/reports', () =>
    handleReactServerPageRequest({ page: asset(manifest, 'ReportsRSC') })
  );