oj README

The project's README from github.com/lovablelabs/oj. As one markdown file: README.md.

OJ logo
OJ

Experimental next generation frontend tooling.

It optimizes for memory and cold start, where running many builds (CI, agents, multi-tenant) under Vite gets expensive. OJ is meant to run real production React apps without changes to their source.

Server rendering

There is an SSR mode: oj dev --ssr src/entry-server.tsx in dev, and oj build --ssr for production. It streams the HTML out with renderToReadableStream instead of buffering, and the client hydrates through the normal dev pipeline, so Fast Refresh and HMR keep working over a server-rendered page.

In dev the server modules run in a small persistent Node process (a module runner using vm.SourceTextModule) that re-evaluates only what changed, instead of rebuilding a bundle per request.

Plugins

Vite/Rollup-style plugins run through a persistent Node plugin host. Drop an oj.plugins.mjs at the app root that default-exports a plugin array, or let oj read an app's vite.config.{ts,js,mjs} and pick up its plugins array directly.

A TypeScript config (including one that imports local .ts files) is loaded via Vite's own config loader when Vite is installed, or bundled with the app's esbuild otherwise. From a vite.config oj also adopts the app's base, server.port/host, define, and resolve.alias for any field its own config leaves unset, alias entries resolve alongside tsconfig paths, in both oj dev and oj build.

Runtime env

Normally an import.meta.env value is baked into the compiled code, so changing it means restarting the dev server. A runtime env key is read when the page loads instead. That helps when the dev server starts before its backend does (a preview whose database comes up later), or when it gets pointed at another backend while it runs.

OJ_RUNTIME_ENV_KEYS=VITE_API_URL,VITE_API_KEY oj dev

OJ_RUNTIME_ENV_KEYS lists the keys, separated by commas. The list is fixed when the server starts. Until a key is given a value, it reads what .env has for it, as it would without this.

Set the values over HTTP, from the same machine:

curl -X POST http://localhost:<port>/@oj/env -d '{"VITE_API_URL": "/_port_8001"}'   # null unsets a key
curl http://localhost:<port>/@oj/env                                                # each key, its value and where it came from

When a value changes, open pages reload and pick it up. Nothing is recompiled. %KEY% in index.html follows the values too.

A value set this way wins over the .env literal. Set values survive a restart of the dev server (a config or .env edit).

The endpoint only answers a direct caller on the same machine. A request from another machine, from a browser or through a proxy is refused.

A script that waits for every key to be set can ask GET /@oj/env: it answers "state": "bound" once they all are.

Good to know:

TanStack Start

Point oj at a TanStack Start app and it runs the framework directly, no source changes. It detects Start from the app itself:

oj dev web                                       # dev server for the ./web Start app
oj build web                                     # production build

Dev serves file-based routes with streaming SSR and client hydration, keeps Fast Refresh working, runs server functions in the module runner, and applies the app's vite.config plugins (React and the app's own). oj build emits a Node server.mjs, a Cloudflare worker.mjs (nodejs_compat), content-hashed client assets, and prerendered routes. oj's own docs site (www/) is a TanStack Start app built by oj and served from a Cloudflare Worker.

In dev, GET /@oj/tanstack/routes.json returns the app's routes as JSON, so a tool next to the page (a route picker in a preview, say) can list them. oj reads the generated route tree (routeTree.gen.ts) on every request, so a route you add or remove shows up right away.

{
  "routes": [
    { "path": "/", "id": "/", "file": "src/routes/index.tsx" },
    { "path": "/dash", "id": "/_layout/dash", "file": "src/routes/_layout/dash.tsx" },
    { "path": "/files/$", "id": "/files/$", "file": "src/routes/files.$.tsx", "params": ["_splat"] },
    { "path": "/posts/$postId", "id": "/posts/$postId", "file": "src/routes/posts.$postId.tsx", "params": ["postId"] }
  ]
}

Pathless layouts and the root aren't listed, since you can't navigate to them. An app whose routes are written in code instead of files gets an empty list.

Type checking

oj typecheck is tsc on tsrs (the Rust port of the TypeScript 7 compiler, built into oj). It takes the arguments tsc (tsgo) takes and prints and exits as TypeScript 7.0's does, so a build that calls tsgo can call oj typecheck in its place. The lib files are TypeScript 7.1's (default target ES2026), listed as bundled:///libs/....

oj dev --typecheck keeps a checker warm beside the dev server, and oj dev-typecheck asks it. It checks the way tsc -b --noEmit does, prints tsc's file(line,col): error TSn: message lines and exits 0 when clean, 2 on type errors and 1 when it cannot check.

oj typecheck -p web/tsconfig.json --noEmit       # tsc's own command line, output and exit codes
oj dev web --typecheck                           # dev server that keeps a checker warm for ./web
oj dev-typecheck web                             # asks that server
oj dev-typecheck web --changed src/App.tsx       # names a file just written, so the answer covers it
oj dev-typecheck web --json                      # the report as JSON

How the warm checker works:

Linting

oj lint is the project's oxlint with oj as the backend for its type-aware rules (typescript/no-floating-promises, typescript/no-misused-promises and the rest of tsgolint's). oxlint lints syntax itself and hands the rules that need types to a backend process, tsgolint by default; oj carries tsrs's port of those rules, on the checker oj typecheck runs. It takes the arguments oxlint takes, reads the project's oxlint config, and prints and exits as oxlint does.

oj lint                    # oxlint --type-aware, on oj's checker
oj lint --fix src          # oxlint's own flags pass through

oxlint comes from the project (node_modules/.bin/oxlint, from the current directory up; OJ_OXLINT_PATH names another). A project that runs oxlint itself can point it at oj instead: OXLINT_TSGOLINT_PATH=$(which oj) oxlint --type-aware.

Quickstart

Install the CLI from crates.io, then run oj in any app:

cargo install oj --locked                       # install the `oj` CLI
oj dev                                           # dev server for the current app on :5199
oj build                                         # production build into ./dist

Or with Homebrew:

brew install lovable-oj

Or with Nix:

nix run github:lovablelabs/oj -- dev

Supported targets

oj embeds V8, so it builds on the targets rusty_v8 ships prebuilt static libs for: Linux glibc x64/arm64, Linux musl x64/arm64, macOS x64/arm64, and Windows MSVC x64/arm64.

Benchmarks

Generated fanout-10 React component trees, measured save-to-paint with Playwright against Vite 8.3.5 (Rolldown-based) on an Apple M5 Max, in both its default dev mode (vite) and its experimental bundled dev mode (vite-fbm). p50/p95 over 5 cold+warm restart cycles and 10 HMR edits. Measured with oj 0.2.46.

Memory is measured over the whole process tree, and reported two ways: resident set (tree RSS) and macOS physical footprint, which excludes clean and reclaimable resident pages and so bounds retained memory. Forced-GC RSS is not a column because it cannot be measured symmetrically (Node exposes an external GC handle through its inspector; embedded V8 does not) — for reference, forcing GC before measuring lowered vite's tree RSS by roughly a third in our runs, still well above its footprint. Methodology corrections owe to #202.

1,000 components (p50/p95):

tool cold start warm start reload HMR tree RSS footprint
oj 466/558ms 321/327ms 166/168ms 57/59ms 180MB 136MB
vite 641/648ms 600/606ms 167/167ms 38/76ms 398MB 338MB
vite-fbm 317/356ms 317/323ms 47/48ms 56/59ms 357MB 306MB

5,000 components (p50/p95):

tool cold start warm start reload HMR tree RSS footprint
oj 1280/1451ms 1024/1038ms 722/726ms 61/62ms 398MB 146MB
vite 2312/2321ms 2133/2153ms 710/713ms 156/158ms 848MB 731MB
vite-fbm 989/995ms 998/1000ms 177/179ms 60/67ms 978MB 931MB

10,000 components (p50/p95):

tool cold start warm start reload HMR tree RSS footprint
oj 2380/2395ms 1929/1942ms 1431/1452ms 66/175ms 684MB 201MB
vite 4554/4559ms 4163/4185ms 1383/1407ms 152/157ms 1414MB 1331MB
vite-fbm 1379/1381ms 1373/1378ms 266/273ms 67/72ms 1740MB 1741MB

Against Vite's default dev, oj starts faster at every size: cold 1.4x at 1k to 1.9x at 10k, warm 1.9x to 2.2x. Reload is level with it. Vite's experimental bundled dev starts faster than oj and reloads far faster, because it serves one bundle instead of thousands of modules. HMR matches bundled dev at every size, and beats default dev from 5k up (default dev is faster at 1k). Memory is oj's largest and most consistent win: a 136-201MB footprint against Vite's 306MB-1.7GB, from 2.5x less than default dev at 1k to 6.6x less at 10k, measured over whole process trees.

Production builds (oj build vs vite build) produce the same output on the 10,000-component app. oj build is currently slower there: 697ms against Vite's 476ms with oj's cache cleared before each build, 523ms against 479ms primed (median of 7 interleaved runs).

Reference reading

Misc

cargo run -p oj -- dev                            # dev server for ./playground on :5199
cargo run -p oj -- dev --ssr src/entry-server.tsx # streaming SSR + hydration
cargo run -p oj -- build playground               # production build into playground/dist
make test                                         # rust unit + integration tests (nextest, in parallel)
node --test e2e/unit/*.test.mjs                   # js unit tests (adapter helpers)
node e2e/run.mjs                                  # browser e2e suite
node e2e/ssr-dev.mjs                              # SSR dev e2e, e2e/ssr-prod.mjs for the built server
cargo test -p oj --test start                     # tanstack start integration (see e2e/fixtures/start-app)
node e2e/dep-optimize.mjs                         # dependency pre-bundle + cjs interop integration
cargo test -p oj --bin oj plugin_api_tests       # build plugin API, rollupOptions, ssr, css and assetsDir options (in-process)
cargo test -p oj_server --test dev                # dev server config, css, plugin hooks, ws and HMR sockets (in-process)
node e2e/config-proxy.mjs                         # adopt vite.config server.proxy + ignored-config warnings
node e2e/proxy-regex-context.mjs                  # server.proxy "^..." regex contexts (path + query), like Vite
node e2e/hmr-overlay-recovery.mjs                 # startup compile error: buffered overlay, reload on first update
node e2e/hmr-json-update.mjs                      # editing an imported .json hot-updates its boundary (?t= stamp)
node e2e/hmr-unresolved-import.mjs                # missing ./import fails with an overlay; creating the file recovers
node e2e/host-binding.mjs                         # dev/preview --host + server.host bind all interfaces
node e2e/awkward-paths.mjs                         # percent-encoded filenames served, traversal contained
node bench/generate.mjs 1000                      # generate a benchmark app (then npm i inside it)
node bench/run.mjs 1000                           # p50/p95 benchmark vs vite
node bench/card.mjs                               # render bench/card.html to oj-benchmarks.png

Testing

make test                                         # unit + integration suites
node e2e/run.mjs                                  # the end-to-end suite

The suite is organized by failure mode rather than by module ~ adversarial input, boundary shapes, contention, injected faults, and properties that hold for every input ~ and docs/development/testing.md describes the layers, the fuzz targets, and the behaviours that are deliberate boundaries rather than gaps.

License

MIT, see LICENSE.

OJ was created by Raphael Amorim and has since migrated to Lovable, which now maintains the project.

oj (lovablelabs/oj)

tanstack
Searching Database…

641 ·GitHub
What is this?OJ is a Rust-native build tool for React apps — a Vite-style dev server and bundler optimized for memory and cold start, built for setups that run many builds (CI, coding agents, multi-tenant).
Is this a replacement for Vite, or does it still need Vite to run?It's a standalone replacement, not a Vite plugin: point oj at an existing React app and it runs with no source changes, reading your vite.config where available. Production output comes from Rolldown, the same engine Vite uses.
How do I try it on my existing React app?Install the CLI from crates.io (Nix also works), then run oj in the app directory. No code changes are needed — it picks up your existing setup.
Will my Vite config and plugins carry over?Mostly yes — oj can read vite.config.{ts,js,mjs} and take its plugins array directly, or you can drop an oj.plugins.mjs at the app root. It also adopts base, server.port/host, define and resolve.alias for fields its own config leaves unset.
Does it work on macOS, Linux and Windows?All three, on x64 and arm64. Since oj embeds V8, it builds only where rustyv8 ships prebuilt static libs: Linux glibc and musl, macOS, and Windows MSVC.
Why build this when Vite already exists?Running many builds under Vite — CI jobs, coding agents, multi-tenant setups — gets expensive in memory and cold-start time. OJ optimizes exactly those costs while keeping Vite's plugin model and output.
How does the dev server stay fast between edits?In dev, server modules run in a small persistent Node process that re-evaluates only what changed, instead of rebuilding a bundle on every request.
Is HMR still as fast as Vite's?Yes — the benchmarks show HMR is essentially a wash across oj and both Vite dev modes, staying within roughly 10ms at every app size tested.
Is it ready for real projects today?The project calls itself experimental, but it is built to run real production React apps unmodified, and production builds are byte-identical to Vite's since both use the Rolldown engine.
What are similar projects?rolldown, esbuild, vite, oxc, rollup, vite-plus, rspack, nx
Size
21.2 MB
Stars
641
Age
3mo
Commits · 90 Days