Skip to main content

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​

OptionTypeDefaultDescription
pagesDirstring'src/pages'Directory for page components.
apiDirstring'src/api'Directory for API routes.
schemaSourcestring'@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.