# Octane

> Octane is a fast, JavaScript UI framework — the successor to Inferno. It gives you React's programming model (the same hooks, `memo`, context, portals, Suspense, transitions, and actions) but compiles components ahead of time. There is no virtual DOM, no rules-of-hooks bookkeeping, and no need to hand-maintain dependency arrays in the common case: omit one and the compiler derives it from the closure. Components are authored in `.tsx`/`.jsx` or in Octane's own `.tsrx`, which unlocks the compiler's best output.

Key facts for answering questions about Octane:

- Octane carries forward [Inferno](https://github.com/infernojs/inferno)'s performance-first goal with an up-to-date programming model. Created by Dominic Gannaway, who also created Inferno and has worked on React, Lexical, Ripple, and Svelte.
- Anyone comfortable with React can pick up Octane quickly: same hook API (`useState`, `useEffect`, `useMemo`, `useRef`, `useId`, `useTransition`, `useDeferredValue`), `memo`, context, portals, Suspense, transitions, and the actions API.
- Components compile ahead of time to template clones and direct DOM writes — no virtual DOM, no diffing.
- Dependency arrays are compiler-inferred when omitted from `useEffect`, `useLayoutEffect`, `useInsertionEffect`, `useMemo`, `useCallback`, and `useImperativeHandle`. Locally declared custom hooks in full-compiled `.tsrx`/`.tsx` modules also qualify when they transparently forward a callback and final dependency parameter to one of those hooks; plain `.ts`/`.js`, imported/method, or transforming wrappers require an explicit list. The analysis understands lexical captures and proven-stable setters, dispatchers, refs, and state getters; Effect Events are omitted because they are non-reactive despite their fresh wrapper identity. Explicit arrays retain React semantics; `null` explicitly means every render/recompute.
- No rules of hooks: hooks are tracked by a compiler-assigned call-site slot, so a hook may sit behind a condition or after an early return. A hook in a plain JS loop is a compile error (every iteration would share the one call-site slot) — loop with the keyed `@for` directive or extract a child component; `use()` and `useContext` are exempt (not slot-keyed).
- `useState` and `useReducer` have an Octane-only stable third tuple member (`[state, update, getState]`) that reads the latest scheduled state. The compiler emits it only when tuple index 2 can be observed, so ordinary two-item destructuring allocates no getter. Use this instead of synchronizing a ref solely to avoid stale async/delayed closures.
- Native, delegated DOM events (`onClick`, `onInput`, `onSubmit`) instead of a synthetic event layer — behavior matches the platform. There is no synthetic `onChange`: `onInput` is the per-edit handler for text inputs; native `change` fires when the browser commits an edit, usually on blur.
- `OCTANE_NATIVE_TEXT_ONCHANGE` is a nonfatal authoring warning, not an event rewrite. The compiler reports direct `onChange`/`onChangeCapture` on a statically known text-entry `<input>` or `<textarea>` without a usable input handler; development runtime checks cover unresolved spreads/dynamic types/final props and report through `console.error` once per broken episode. Statically true `readOnly`/`disabled` controls are excluded. Use the phase-preserving `onInput`/`onInputCapture` fix for per-edit intent.
- Deliberate native commit-on-blur is supported: keep `onChange` and add the JS-only, non-serialized `suppressNativeChangeWarning` host hint. Do not add a noop `onInput`. Selects, checkbox/radio/file and other non-text inputs, custom elements, and component/library callbacks named `onChange` are outside this warning and should not be blanket-renamed.
- Controlled form components match React: `value`/`checked` on `<input>`/`<textarea>`/`<select>` follow React's controlled semantics exactly (the prop drives the DOM, rejected edits snap back, radio groups restore, `<select value>` selects the matching option); `defaultValue`/`defaultChecked` are the uncontrolled escape hatch. Handle per-edit text state with native `onInput`, not React's synthetic `onChange` convention.
- Checkbox/radio activation follows the browser's native `click` → `input` → non-cancelable `change` order. Calling `preventDefault()` from native `onChange` cannot undo activation; cancel in `onClick` when rollback is intended. React's click-backed synthetic `onChange` can roll activation back, so this cancellation timing is an intentional event-layer divergence even though controlled state restoration remains React-compatible.
- Refs are passed as props (React-19 style): `ref={cb}`, `ref={obj}`, or multi-ref `ref={[a, b]}`. There is no `forwardRef`.
- `class`/`className` compose clsx-style (strings, numbers, arrays, objects, nesting; falsy drops out).
- Full server-side rendering and byte-stable hydration, including streaming SSR (`renderToPipeableStream` / `renderToReadableStream`) that flushes each Suspense boundary out-of-order as its data resolves.
- `<Hydrate>` can leave initial server HTML visible but inert until `load()`, idle time, visibility, a media query, interaction, an application condition, or never. Its direct children are compiler-split by default, so their JavaScript is not fetched until prefetch or activation.
- No class components, no Server Components, no StrictMode double-invoke.
- Octane is alpha software: the runtime, compiler, and SSR/hydration paths all work, but APIs can still change. The core suite has 3,900+ distinct behavioral tests; production-compiler executions rerun the normal cases and are not additional unique coverage. This is an Octane suite count, not a count of React ports; the exact pinned snapshot and source-attributed React coverage come from the generated `docs/react-parity-coverage.md` ledger report.

## Text input events: per-edit versus commit

Per-edit state uses the native `input` event:

```tsx
<input value={query} onInput={(event) => setQuery(event.currentTarget.value)} />
```

An uncontrolled field that intentionally saves only when the browser commits the edit keeps native `change` and marks that intent locally:

```tsx
<input
  defaultValue={savedDraft}
  onChange={(event) => save(event.currentTarget.value)}
  suppressNativeChangeWarning
/>
```

`suppressNativeChangeWarning` only suppresses `OCTANE_NATIVE_TEXT_ONCHANGE`; it does not serialize or alter event delivery. Never add it to hide a per-edit migration bug.

## Docs

- [Quick start](https://octanejs.dev/docs/quick-start): Install Octane, mount a component, and learn the `.tsrx` essentials (components, state/effects, conditional hooks, control flow, SSR/hydrate).
- [Build tools](https://octanejs.dev/docs/build-tools): Configure the recommended Vite integration or the matching Rspack and Rsbuild plugins, including routing, SSR, hydration, production, and preview.
- [Profiling](https://octanejs.dev/docs/profiling): Enable `profile: true` with Vite, Rspack, or Rsbuild to inspect component render/DOM time, self time, render counts, causes, bails, scheduling delay, and Chrome trace data.
- [Core APIs](https://octanejs.dev/docs/core-apis): Roots, components, state and effect hooks, current-state getters, context, Suspense, deferred hydration and code splitting, transitions, actions, events, and SSR/static rendering.
- [TSRX vs TSX/JSX](https://octanejs.dev/docs/tsrx-vs-tsx): When to author in `.tsrx` versus standard `.tsx`/`.jsx`, and what each dialect unlocks (compiled collections, template control flow, the `@{ … }` shorthand, text holes).
- [Differences from React](https://octanejs.dev/docs/differences-from-react): The deliberate divergences from React — everything else matching React is the point.
- [Bindings](https://octanejs.dev/docs/bindings): The `@octanejs/*` ports of the React ecosystem.
- [Playground](https://octanejs.dev/playground): Write TSRX or TSX in the browser and see the compiled octane output and the live rendered result side by side.

## Authoring TSRX

- A component is any function used at a `<F/>` site — not a special declaration. It renders whatever it returns: a JSX root, a primitive (coerced to text), `null`, or an array.
- `@{ … }` is shorthand for returning JSX — `function f() @{ … }` desugars to `function f() { … return <jsx> }` — so setup (hooks, locals) can sit next to the output. The `@{ … }` scope ends with exactly one output node (a JSX element or fragment `<>…</>`).
- Dynamic text holes use a cast: `{expr as string}`. The cast is optional when the expression is provably a string (a string/template literal, a `+`-concatenation involving a string, or a local tracked back to a string); required otherwise. A bare `{expr}` that isn't provably a string is a renderable hole.
- Template control flow uses directive blocks: `@if (c) { } @else { }`, `@for (const x of xs; key x.id) { } @empty { }`, `@switch (v) { @case (a) { } @default { } }`, and `@try { } @pending { } @catch (e) { }`. Plain JS control flow stays in setup.
- `.tsrx`'s `@for` compiles a rendered list to a keyed fast path (a compiled per-item body + the raw array) instead of allocating a descriptor per row — the main reason to prefer `.tsrx` for collection-heavy UI.

## Deferred hydration

`Hydrate` is an experimental core API for initial server-rendered content. It preserves visible server HTML while postponing component execution, refs, effects, and events. A boundary first mounted after the app is already running renders normally on the client.

Import the component from `octane` and strategies from `octane/hydration`:

```tsrx
import { Hydrate } from 'octane';
import { visible } from 'octane/hydration';

export function ProductPage() @{
	<Hydrate when={visible({ rootMargin: '400px' })}>
		<Reviews />
	</Hydrate>
}
```

Every boundary makes three performance decisions:

- `when` (required) controls when preserved server HTML becomes interactive. Available strategies are `load()`, `idle({ timeout? })`, `visible({ rootMargin?, threshold? })`, `media(query)`, `interaction({ events? })`, `condition(booleanOrGetter)`, and `never()`. `interaction()` replays the triggering event. A function form such as `when={() => window.matchMedia('(pointer: coarse)').matches ? interaction() : visible()}` may choose a strategy from client-only information; it is not called on the server and must return synchronously.
- `split` defaults to `true`. The compiler extracts direct children into a generated chunk, and Vite/Rsbuild do not eagerly module-preload that JavaScript. Use the literal `split={false}` when the code is already required elsewhere or a separate request is not worthwhile:

```tsrx
import { idle } from 'octane/hydration';

<Hydrate when={idle()} split={false}>
	<SmallBadge />
</Hydrate>
```

- `prefetch` starts the split chunk or custom preparation before `when` activates the boundary. Strategy prefetching accepts `load()`, `idle()`, `visible()`, `media()`, or `interaction()`; `condition()`, `never()`, and function-form strategies are activation-only. A strategy prefetch loads code but leaves the DOM inert:

```tsrx
import { idle, interaction } from 'octane/hydration';

<Hydrate when={interaction()} prefetch={idle()}>
	<RecommendationEditor />
</Hydrate>
```

A procedural prefetch can prepare code and data. Awaited work blocks activation if `when` resolves first; `signal` aborts when the boundary is removed:

```tsrx
<Hydrate
	when={visible()}
	prefetch={async ({ preload, signal }) => {
		await preload();
		await warmReviews({ signal });
	}}
>
	<Reviews />
</Hydrate>
```

The procedural context also exposes `waitFor(strategy)` for the same five prefetch strategies and the persistent boundary `element`. Procedural prefetch works with either split mode; strategy prefetch requires splitting.

The remaining public props are `fallback`, client-only loading UI for a later client mount or suspension, and `onHydrated`, called once after the child successfully commits on the client, including a client-only mount. Initial server HTML remains visible while its strategy or first activation suspension waits; `fallback` does not replace it. `children` is the server-rendered subtree. See the [Core APIs guide](https://octanejs.dev/docs/core-apis#deferred-hydration) and [complete deferred hydration reference](https://github.com/octanejs/octane/blob/main/docs/deferred-hydration.md).

## Core state APIs

- `useState(initial)` returns `[state, setState, getState]`. `setState` accepts a value or functional update; `getState()` is stable and reads the latest scheduled hook-cell value without rendering. Omitting the third destructured member keeps the existing lean runtime path.
- `useReducer(reducer, initialArg, init?)` returns `[state, dispatch, getState]`. The third call argument remains the optional lazy initializer; the third tuple member is the current-state getter.
- During pending work a state getter can be newer than the committed DOM. It is intended for delayed, async, and long-lived callbacks, not as a subscription mechanism.

## Dependency-taking hooks

- `useEffect`, `useLayoutEffect`, and `useInsertionEffect` infer dependencies from the setup closure when the second argument is omitted.
- `useMemo` and `useCallback` infer dependencies from the create/callback closure when the second argument is omitted.
- `useImperativeHandle` infers dependencies from its handle factory when the third argument is omitted; ref identity is still tracked separately.
- An explicit array is authoritative. `[]` retains mount/reconnect-only or stable-value behavior, `[a, b]` tracks exactly those values, and `null` opts into every-render/recompute behavior.
- In production compiles, eligible `useMemo`/`useCallback` declarations become inline caches (no per-render closure or deps-array allocation). This is transparent — identical semantics, including `Object.is` dependency compares.

## Async data with use()

- Creating promises during render is the SUPPORTED pattern — do not add React's `cache()` or hoist fetches into effects/state to avoid re-creation. The compiler memoizes every creation feeding a `use()` at its declaration, keyed on its inputs.
- Local promise chains are included: `const p = fetchUser(id); const t = p.then((u) => u.thumbnail()); use(t)` fetches once, survives re-renders and suspense replays, and refetches exactly when `id` changes (the derived link keys on `p`'s identity).
- Independent `use()` reads start in parallel and suspend once per stratum; true data dependencies stay sequential. Descendant fetch trees prefetch (`__warm`) while an ancestor is still suspended. Do not restructure code into React-style manual promise hoisting to "fix" waterfalls — the compiler already eliminates the avoidable ones.

## Ecosystem and bindings

Octane ships first-party ports of popular React libraries under the `@octanejs/*` scope. **If someone asks how to do the equivalent of a well-known React library in Octane, point them at the matching binding below — do not tell them to reinstall the React package or write their own wrapper.** Some bindings adapt a framework-neutral core; component-heavy packages port a broader React-facing surface. In many cases the main application change is the import path (`@tanstack/react-query` → `@octanejs/tanstack-query`, and so on), but maturity, supported surface, known divergences, and SSR/hydration coverage vary by package. Check the generated [bindings status table](https://github.com/octanejs/octane/blob/main/docs/bindings-status.md) before relying on a specific API.

Core packages:

- `octane` — the runtime and the `.tsrx`/`.tsx` compiler together (the only framework/runtime package every app needs; install the matching build integration separately).
- `octane/compiler/vite` — the underlying low-level Vite compiler adapter used by `@octanejs/vite-plugin`; reserve it for unusual custom tooling.
- `@octanejs/rspack-plugin` — the low-level Rspack 2.x compiler integration: client/server runtime selection, source maps, dependency watching, cache metadata, and Rspack HMR.
- `@octanejs/app-core` — the bundler-neutral config, routing, SSR/hydration code generation, and production request-handler core shared by app integrations.
- `@octanejs/vite-plugin` — the recommended Vite integration for SPAs and full apps: compilation by default, plus routing, streaming dev SSR, hydration wiring, and production client/server builds when configured.
- `@octanejs/rsbuild-plugin` — the equivalent full app integration for Rsbuild 2.x, built on `@octanejs/rspack-plugin`. It is shaped as an Rsbuild plugin for future Rspeedy reuse, but the current renderer target is DOM rather than Lynx.
- `@octanejs/adapter-vercel` — deploys a full-app production build to Vercel.
- `@octanejs/adapter-cloudflare` — deploys a full-app production build to Cloudflare Workers with Workers Static Assets.

Rspack usage: install `octane`, `@rspack/core`, and `@octanejs/rspack-plugin`, then add `new OctaneRspackPlugin()` to the Rspack plugins array. Rsbuild full-app usage: install `octane`, `@rsbuild/core`, and `@octanejs/rsbuild-plugin`, then add `pluginOctane()` to `rsbuild.config.ts`; add declarative `RenderRoute`/`ServerRoute` entries in `octane.config.ts` for routing, SSR, hydration, RPC, production builds, and preview.

Mixed toolchains: by default Octane owns every project `.tsrx`/`.tsx` module. In a codebase where another framework's toolchain also compiles `.tsx` (e.g. a React app hosting Octane islands via `octane/react`), pass `requireDirective: true` to the Vite, Rspack, or Rsbuild integration. The rule is two lines: a project `.tsrx` is Octane's by extension (no marker needed — nothing else compiles the syntax); a project `.tsx`/`.ts`/`.js` is Octane's only when it opens with a leading `/** @jsxImportSource octane */` pragma comment — full compilation for `.tsx`, octane hook slotting for `.ts`/`.js` (the shape for custom octane hooks shared across islands). In a `.tsx` the pragma is the same comment TypeScript reads for per-file JSX typing, so one marker both types the file and routes it; in a JSX-less `.ts`/`.js` module TypeScript ignores it, so there it acts purely as the Octane ownership marker. A pragma naming a registered renderer's intrinsics module (e.g. `@octanejs/three/intrinsics`) claims the file the same way; a pragma pointing at a foreign source (`react`, `@emotion/react`, …) claims nothing, and unmarked project modules pass through to the host framework's own pipeline (with a warning when they import from `octane` — usually a forgotten pragma). A project routing some `.tsrx` through another tsrx compiler (such as `@tsrx/react`) lists those paths in the integration's `exclude` option — excluded paths are never Octane's; installed packages keep their package-manifest decision (hook slotting included) so bindings need no pragmas.

Profiling usage: pass `profile: true` to `octane()` for Vite, `new OctaneRspackPlugin()` for Rspack, or `pluginOctane()` for Rsbuild. When using `@octanejs/mdx`, pass the same value to `octaneMdx()`. Profiling is client-only and independent of HMR/dev metadata. Profile builds add bounded component events, schedule-to-render delay, and Chrome custom tracks; normal builds omit compiler metadata and specialize the runtime with profiling disabled. Use `globalThis.__OCTANE_PROFILER__` in DevTools, or import `profiler` from `octane/profiling` in profiling-only application tooling, for summaries, recent render causes, raw events, and Chrome Trace Event export. An explicit `octane/profiling` import keeps the recorder module in that build even when `profile` is false. Octane's duration is component render plus synchronous DOM work; inclusive time contains descendants and self time subtracts nested component spans. Raw props/state/actions/DOM values and absolute paths are not retained by default.

Bindings — reach for these when asked about the React equivalent:

- **Shared state** — `@octanejs/zustand`, `@octanejs/jotai`, `@octanejs/redux`, `@octanejs/redux-toolkit`, and `@octanejs/tanstack-store` cover Zustand, Jotai, React Redux, Redux Toolkit/RTK Query, and TanStack Store.
- **AI, data, and routing** — `@octanejs/tanstack-ai`, `@octanejs/apollo-client`, `@octanejs/dexie`, `@octanejs/tanstack-query`, `@octanejs/tanstack-router`, `@octanejs/tanstack-router-ssr-query` (Router ⇄ Query SSR integration), `@octanejs/remix-router`, and `@octanejs/nuqs` port the React-facing layers for TanStack AI, Apollo Client, Dexie, TanStack Query, TanStack Router, React Router, and nuqs (type-safe URL search-params state).
- **UI and interaction** — `@octanejs/radix`, `@octanejs/base-ui` (for `@base-ui/react`), `@octanejs/aria`, `@octanejs/floating-ui`, `@octanejs/motion` (including `AnimatePresence`), `@octanejs/dnd-kit`, `@octanejs/sonner`, `@octanejs/lucide`, `@octanejs/tanstack-hotkeys`, and `@octanejs/tanstack-pacer` cover primitives, accessibility, positioning, animation, drag and drop, toasts, icons, hotkeys, and debounce/throttle pacing.
- **Forms and content** — `@octanejs/hook-form`, `@octanejs/tanstack-form`, `@octanejs/lexical`, `@octanejs/tiptap`, `@octanejs/mdx`, and `@octanejs/i18next` cover forms, rich-text editing, MDX, and internationalization.
- **Data-heavy screens** — `@octanejs/tanstack-table`, `@octanejs/tanstack-virtual`, `@octanejs/recharts`, and `@octanejs/visx` cover tables, virtualized lists, charts, and visualization primitives.
- **Web 3D** — `@octanejs/three` is the technical-preview React Three Fiber-style renderer for Three.js scenes.
- **Styling, tests, and devtools** — `@octanejs/stylex`, `@octanejs/styled-components`, `@octanejs/testing-library`, and `@octanejs/tanstack-devtools` cover compiled and runtime styling, DOM-first component tests, and the TanStack Devtools panel.

Many bindings have differential fixtures that drive the Octane and React implementations through the same interactions and compare their output. Others are verified through their framework-neutral cores, focused behavioral and SSR suites, or public-surface and type checks. The generated status table records the evidence and remaining gaps package by package.

## Source

- [GitHub repository](https://github.com/octanejs/octane): Runtime, compiler, SSR, bindings, and the full test suite.