Vite Plugin
@exodra/vite-plugin wires Exodra into Vite: it compiles Exodra JSX through the
Babel preset and generates file-based routes and API endpoints from your directory
structure.
Installation
npm install --save-dev @exodra/vite-plugin
Configuration
Add the plugin to your Vite config. It runs with enforce: 'pre' so it owns the
JSX pipeline before Vite's esbuild, and it sets esbuild's jsx: 'preserve' so
no foreign JSX runtime is injected.
// vite.config.ts
import { defineConfig } from 'vite';
import exodra from '@exodra/vite-plugin';
export default defineConfig({
plugins: [
exodra({
pagesDir: 'src/pages', // Default: src/pages
apiDir: 'src/api', // Default: src/api
}),
],
});
Options
| Option | Type | Default | Description |
|---|---|---|---|
pagesDir | string | 'src/pages' | Directory for page components. |
apiDir | string | 'src/api' | Directory for API routes. |
schemaSource | string | '@exodra/core' | Where the compiled output imports createExoSchema from. |
ssr and alias are still declared on the options type but nothing in the
plugin reads them — passing either changes no behaviour. For server rendering,
see the section at the bottom of this page.
JSX transform
The plugin transforms every .tsx / .jsx file (outside node_modules) through
babel-preset-exodra, which is the same single pipeline Jest, esbuild, Rollup
and Bun use. Each exoJsx(…) declaration becomes a module-level
createExoNamedSchema() — the shape, built once when the module loads — whose
ports the machine fills per instance. Because the plugin runs before esbuild, the output is plain JS by the
time Vite sees it.
esbuild's own JSX handling would be wrong here twice over: it lowers JSX to a
call per element at runtime, and it throws on the namespaced on: listeners the
dialect uses. See the
JSX guide for the dialect itself.
File-based routing
Routes are generated automatically from your pagesDir:
src/pages/
├── index.tsx → /
├── about.tsx → /about
├── _shared.tsx → ignored (starts with `_`)
├── blog/
│ ├── index.tsx → /blog
│ ├── [id].tsx → /blog/:id
│ └── [...slug].tsx → /blog/* (catch-all)
├── shop/
│ ├── [[...path]].tsx → /shop (optional catch-all)
│ └── checkout.tsx → /shop/checkout
└── admin/
└── dashboard.tsx → /admin/dashboard
Special files
index.tsx— default route for a directory.- A file whose name starts with
_is ignored by the generator: it produces no route and nothing else.
Layouts
The generated table is flat — one entry per page file, no children — and
_layout.tsx has no meaning to the generator. In @exodra/router a layout is a
route with children, and its page places its own ExoOutlet: the nested
boundary finds its parent boundary through the context and draws the next entry
of the matched branch. Such a table is written by hand; see
Nested routes. The router has no error
boundary, so catching a throwing page is the application's job.
Dynamic routes
[param].tsx— single dynamic segment (:param).[...params].tsx— catch-all route.[[...params]].tsx— optional catch-all route.
Using generated routes
Import the routes from the virtual:exodra-routes module. Each entry is
{ path, component: exoLazy(() => import(…)) }, and exoLazy resolves the page
module's default export — so a page is a machine default-exported from its
file, and it receives the match that selected it as the params of its wire:
createExoMachine<TExoMachineNode, TExoRouteMatch>(pageSchema), then
withExoWire(m, (c, match) => …).
There is no provider component and no <Outlet /> element: the router is
provided by a call inside a machine, and the route boundary is the ExoOutlet
machine, or exoOutlet(tag) for another element.
```ts no-check // virtual:exodra-routes is generated by the plugin at build time
// main.ts
import { EXO_PORT_CHILDREN, createExoMachine, createExoSchema, exoPorts } from '@exodra/core';
import type { TExoChildrenWiring, TExoMachineNode } from '@exodra/core';
import { ExoDomBackend, withExoCompiler } from '@exodra/dom';
import {
createExoBrowserHistory,
createExoRouter,
exoOutlet,
provideExoRouter,
} from '@exodra/router';
import type { TExoOutletWiring } from '@exodra/router';
import { routes } from 'virtual:exodra-routes';
const router = createExoRouter(routes, { history: createExoBrowserHistory() }); const Routed = exoOutlet('main');
const AppPorts = exoPorts({ body: EXO_PORT_CHILDREN });
const appSchema = createExoSchema(AppPorts, b => { b.el('div', { class: 'app' }, d => { d.childrenPort(AppPorts.body); }); }); const appMachine = createExoMachine<TExoChildrenWiring & TExoMachineNode & TExoOutletWiring>( appSchema, { createInitialState: c => { provideExoRouter(c, router); c.one(AppPorts.body, Routed); }, } );
const backend = withExoCompiler(new ExoDomBackend()); backend.render(appMachine, document.getElementById('app') as HTMLElement);
For TypeScript, declare the virtual module:
```typescript no-check
// env.d.ts
/// <reference types="vite/client" />
declare module 'virtual:exodra-routes' {
import type { TExoRoute } from '@exodra/router';
export const routes: TExoRoute[];
}
API routes
Files in apiDir become API endpoints. Export functions named after the HTTP
method; they are served during development at /api/<file>:
// src/api/users.ts
declare function fetchUsers(): Promise<unknown[]>;
declare function createUser(data: unknown): Promise<unknown>;
export async function GET(request: Request) {
const users = await fetchUsers();
return new Response(JSON.stringify(users), {
headers: { 'Content-Type': 'application/json' },
});
}
export async function POST(request: Request) {
const data = await request.json();
const user = await createUser(data);
return new Response(JSON.stringify(user), {
status: 201,
headers: { 'Content-Type': 'application/json' },
});
}
If no matching method (or default) export is found, the request returns
405 Method not allowed.
Hot Module Replacement
The plugin appends no HMR glue, and a changed component is a full reload. A module that accepts a hot update stops Vite propagating it to its importer, so glue that accepted the update without applying it would suppress the reload that shows the change.
The plugin has no handleHotUpdate hook, so what applies is Vite's own
propagation: a changed page or component that nothing accepts reloads the page.
The route table is built once, in buildStart, and virtual:exodra-routes is
generated from it; nothing re-scans pagesDir while the dev server runs. A page
added, removed or renamed mid-session appears in routes only after the dev
server is restarted.
SSR
Server rendering is a Vite concern rather than a plugin option — mark the Exodra
packages as non-external for the SSR build so they are compiled rather than
required from node_modules:
// vite.config.ts
import { defineConfig } from 'vite';
import exodra from '@exodra/vite-plugin';
export default defineConfig({
plugins: [exodra()],
ssr: {
noExternal: ['@exodra/core', '@exodra/string'],
},
});
The same component renders to markup with ExoStrBackend.render and is adopted
by backend.hydrate on a @exodra/dom backend composed with
withExoHydration. See the SSR guide.
Links
- npm: @exodra/vite-plugin
- GitHub: packages/vite-plugin-exodra