@vantris/react

@vantris/react

The official React plugin for Vantris. It brings React Fast Refresh (stateful hot reload) to the dev server, compiling JSX and the refresh instrumentation through oxc — no Babel.

Vantris already understands JSX out of the box. This plugin is what turns a save into an in-place component update that keeps your state, instead of a full page reload.

Features

• ️ Fast Refresh — edit a component, it updates in place; useState and other hook state survive the edit. Falls back to a full reload only when a module's exports stop being a valid refresh boundary.
• oxc-powered — JSX + refresh instrumentation come from the standalone oxc-transform; the only other runtime dependency is react-refresh.
• Typed config — options live under the react key of defineConfig, fully typed and autocompleted.
• Dev-only — in a production build the plugin steps aside; no refresh code ever ships.

Install

pnpm add -D @vantris/react

Peers: vantris >= 1.5.0, plus react / react-dom (>= 18) in your app.

Usage

Reference the plugin by string, then configure it (optionally) under the typed react key:

// vantris.config.ts
import { defineConfig } from 'vantris'

export default defineConfig({
  plugins: ['@vantris/react'],
  // Optional — every field has a default:
  react: {
    jsxRuntime: 'automatic',   // or 'classic'
    jsxImportSource: 'react',  // e.g. '@emotion/react'
    fastRefresh: true,
  },
})

That's it. vantris dev now has Fast Refresh; vantris build compiles JSX as usual. The react key type-checks and autocompletes — the plugin augments Vantris's PluginConfigs.

Options

Option	Type	Default	Description
fastRefresh	boolean	true	Enable Fast Refresh in dev (always off in a build).
jsxRuntime	'automatic' | 'classic'	'automatic'	automatic needs no import React.
jsxImportSource	string	'react'	Module the automatic runtime imports JSX helpers from.
include	FilterPattern[]	.[mj|t]sx?	Files to transform.
exclude	FilterPattern[]	node_modules, .d.ts	Files to skip (always added to the defaults).

A FilterPattern is a substring, a RegExp, or an (id: string) => boolean.

How it works

• config — seeds optimizeDeps.include with react, react-dom, react-dom/client, and the JSX runtimes so the dev server is warm on first load.
• transform (dev only) — oxc strips TypeScript, compiles JSX, and emits the Fast Refresh registrations ($RefreshReg$/$RefreshSig$); the module is then wrapped with a boundary that self-accepts over import.meta.hot.
• transformIndexHtml (dev only) — injects the preamble, which inlines the react-refresh runtime and installs the shared refresh globals before any application module runs.

In a production build the plugin defers JSX compilation to Vantris/Rolldown and does nothing else — verify with vantris build: the output contains no $RefreshReg$ or react-refresh.

License

MIT