rari Documentation

Use square brackets in filenames to create dynamic segments.

• Single Dynamic Segment: [slug] matches one segment (e.g., /blog/my-post).
• Catch-All Segments: [...slug] matches one or more segments (e.g., /docs/api/ref matches slug = ['api', 'ref']). Requires at least one segment.
• Optional Catch-All Segments: [[...slug]] matches zero or more segments, including the base path (e.g., /docs matches slug = undefined).

Route Priority

1. Static routes (/about)
2. Dynamic routes (/[id])
3. Catch-all routes (/[...slug])
4. Optional catch-all routes (/[[...slug]])

import type { PageProps } from 'rari'

export default async function BlogPost({ params }: PageProps<{ slug: string }>) {
  const post = await fetch(`https://api.example.com/posts/${params.slug}`).then(r => r.json())

  return (
    <article>
      <h1>{post.title}</h1>
      <p>{post.content}</p>
    </article>
  )
}

When a page contains Suspense boundaries (e.g., via a loading.tsx file), rari uses Streaming SSR to send HTML progressively to the browser.

The Streaming Process:

1. Initial Render: The StreamingRenderer executes the composition script in V8. It produces the initial synchronous RSC tree and a list of pending promises for async components.
2. First Chunk: rari converts the initial tree to HTML and sends it immediately. The browser begins painting the shell and synchronous content.
3. Background Resolution: A background task resolves pending promises in V8. When a promise resolves, a boundary update is sent through a channel.
4. Stream Updates: A listener task receives updates, attaches DOM position hints, and forwards them as stream chunks. The server emits a hidden <div> containing the rendered content and an inline <script> to swap the content into the correct DOM position (using the $RC pattern).
5. Hydration: Once all components resolve, the RSC payload is embedded in a <script> tag at the end of the stream for client-side hydration.

rari uses an in-memory cache to serve pre-compressed response bytes (zstd, brotli, or gzip) without re-rendering the page on subsequent requests. This is highly efficient for synchronous server components.

Key Behaviors:

• Automatic Caching: After the first request, the rendered and compressed bytes are stored in an in-memory DashMap.
• Cached Path: Routes that do not have a loading.tsx file use this pre-compressed response cache path. This results in sub-millisecond server-side processing.
• Streaming Path: Routes that do include a loading.tsx file use streaming SSR instead. These pages perform real rendering on each request and do not benefit from the pre-compressed response cache, resulting in higher (though still fast) processing times (typically 2-3ms).

/* Note: Caching behavior is determined by the presence of loading.tsx */

// Path A: No loading.tsx -> Uses pre-compressed response cache (Fastest)
// Path B: Has loading.tsx -> Uses streaming SSR (Real rendering per request)

Rari uses a file-system based router within the src/app/ directory. Different file names within a directory determine the behavior of that route:

• page.tsx: Defines the UI for a specific route.
• layout.tsx: Defines a layout shared by all child routes (nested layouts).
• loading.tsx: Defines a loading state for the route and its children.
• error.tsx: Defines an error boundary for the route and its children.
• not-found.tsx: Defines the UI for 404 errors.
• route.ts: Defines API endpoints (Route Handlers).
• [[...slug]]: Represents an optional catch-all segment.
• [slug]: Represents a single dynamic segment.
• opengraph-image.tsx: Used for generating dynamic Open Graph images.

src/app/
├── layout.tsx              # Root layout
├── page.tsx                # /
├── loading.tsx             # Global loading state
├── error.tsx               # Global error boundary
├── not-found.tsx           # Global 404
├── about/
│   └── page.tsx            # /about
├── blog/
│   ├── layout.tsx          # Blog layout
│   ├── page.tsx           # /blog
│   └── [slug]/
│       ├── page.tsx        # /blog/:slug
│       ├── loading.tsx     # Loading state for blog posts
│       └── opengraph-image.tsx  # Dynamic OG image
├── dashboard/
│   ├── layout.tsx          # Dashboard layout (sidebar nav)
│   ├── page.tsx            # /dashboard
│   ├── error.tsx           # Error boundary for dashboard
│   └── analytics/
│       └── page.tsx        # /dashboard/analytics
├── docs/
│   └── [[...slug]]/
│       └── page.tsx        # /docs, /docs/*, /docs/*/*
└── api/
    └── users/
        ├── route.ts        # GET/POST /api/users
        └── [id]/
            └── route.ts    # GET/PUT/DELETE /api/users/:id