Reora

Reora is a Bun-native React framework prototype with:

• server components by default
• 'use client' graph splitting
• file-level 'use server' actions
• 'use cache' wrapping with request and process caches
• a small custom Flight-style protocol
• Bun-native build, dev, and production server flows

The repo is organized as a workspace:

apps/
  playground/          # example app
packages/
  compiler/            # scan, graph, transform, emit, build
  protocol/            # custom Flight-style wire format
  runtime/             # server, render, cache, actions, dev session
  reora/               # public package and CLI
test/                  # compiler, protocol, cache, and server integration tests

Commands

Install dependencies:

bun install

Run the playground in development:

bun run dev

This command intentionally starts the Reora dev server directly. Reora already watches app and workspace source files for rebuilds, so wrapping it with bun --watch causes conflicting restarts during app edits.

Create a production build:

bun run build

Start the production server from build artifacts:

bun run start

Run checks:

bun run test
bun run typecheck

App Conventions

Reora looks for application code under src/ and routes under src/app/.

src/
  app/
    page.tsx
    about/page.tsx
    posts/[id]/page.tsx
    api/route.ts
    actions.ts
  components/
  lib/
styles/
  globals.css
reora.config.ts

Supported route files:

• page.tsx
• layout.tsx
• loading.tsx
• error.tsx
• not-found.tsx
• route.ts
• optional actions.ts

Directives

'use client'

Marks a client boundary. The compiler moves that subtree into the browser graph, emits client references for RSC decoding, and prevents direct imports of server-only modules from that subtree.

'use server'

Supported today for file-level async exports. The compiler emits an action manifest and client stubs that call POST /_reora/actions.

Native HTML form posts are also supported at the endpoint level by sending:

• _action or id
• _csrf
• optional args

'use cache'

Supported for file-level and inline cacheable async exports. The server transform wraps those exports with the cache runtime and keys entries by function id plus serialized args.

Build And Runtime Model

packages/compiler performs:

1. route and module scanning
2. graph splitting for server and client boundaries
3. source transforms for client references, action stubs, and cache wrappers
4. generated source emission into .reora/cache/generated/<buildId>
5. Bun browser bundling into dist/client
6. manifest emission into dist/manifests

packages/runtime performs:

• HTML document rendering
• Flight endpoint rendering
• action execution with CSRF and same-origin checks
• request memoization and process cache access
• static asset serving
• development rebuilds with SSE live reload

Output Layout

Build artifacts are written to:

dist/
  client/
  manifests/
  styles/
.reora/
  cache/
    entries/
    generated/<buildId>/

Important manifests:

• dist/manifests/routes.json
• dist/manifests/actions.json
• dist/manifests/cache.json
• dist/manifests/client.json
• dist/manifests/runtime.json

Development Notes

Development mode now keeps generated source trees versioned by build id, so Bun does not keep serving stale route, RSC, or action modules after a rebuild. The dev server exposes /_reora/live as an SSE stream and the browser runtime reloads when a new build id is published.

Production mode serves only prebuilt artifacts. It does not rebuild on requests.

Protocol Scope

The custom protocol is intentionally narrow. It currently supports:

• plain objects
• arrays
• strings, numbers, booleans, null, undefined
• React elements
• client references
• Suspense boundaries

It intentionally rejects unsupported values such as Date, Map, class instances, and other non-plain objects. That contract is enforced in tests so protocol behavior fails explicitly instead of silently degrading.

Current Status

The framework is stable enough for local development and iteration, but it is still a prototype. The current test suite covers:

• directive scanning and graph splitting
• cache wrapping and invalidation
• protocol roundtrips and unsupported-value rejection
• artifact-backed production startup
• native form action CSRF handling
• development rebuild freshness and live reload signaling

Known limitations:

• no inline server actions yet
• no durable remote cache adapter yet
• no official react-server-dom-webpack transport
• live reload is full-page reload, not Fast Refresh