create-exodra
create-exodra scaffolds a new Exodra application. The CLI asks at a prompt
(Next.js style): run it and answer a few questions, or pass flags to skip the
prompts. It also installs an exodra binary for generating components, pages,
and API routes inside an existing project.
Quick start
# Using npm
npm create exodra@latest my-app
# Or directly
npx create-exodra my-app
If you omit a project name you'll be prompted for one. Without flags, the CLI
prompts for TypeScript, ESLint, Tailwind CSS, a src/ directory, SSR, App
Router, and the import alias.
After scaffolding:
cd my-app
npm install
npm run dev
CLI usage
npx create-exodra [project-name] [options]
Any option you don't pass is asked interactively. Passing a flag skips that prompt.
Options
--ts,--typescript— use TypeScript--js,--javascript— use JavaScript--tailwind— set up Tailwind CSS--eslint— set up ESLint--src-dir— use asrc/directory--ssr— scaffold a server-side-rendered app--app— use the App Router (@exodra/router)--import-alias <alias>— import alias to use (default@/*)--use-npm/--use-yarn/--use-pnpm/--use-bun— choose the package manager
Examples
# TypeScript app with the App Router and Tailwind, no prompts
npx create-exodra my-app --typescript --app --tailwind
# JavaScript app, no App Router
npx create-exodra simple-app --javascript
# Server-side-rendered app
npx create-exodra my-ssr-app --ssr
What gets generated
The default (Vite) scaffold declares its schemas with exoJsx, which
@exodra/vite-plugin compiles away; the --ssr scaffold and everything the exodra
CLI generates use exoPorts with createExoSchema and contain no JSX. Either way a
component is one value: a schema that declares the shape once when the module
loads, and a machine whose wire fills its ports per instance. See
JSX for the exoJsx dialect.
A standard (non-SSR) app uses Vite with @exodra/vite-plugin and depends on
@exodra/core and @exodra/dom — plus @exodra/router
when the App Router is enabled, which also gets src/pages, a generated route
table from virtual:exodra-routes, and a main that provides the router inside
a machine (provideExoRouter(c, router)), places the boundary with
c.one(port, ExoOutlet) and appends the nav's ExoLinks with c.appendChild(port, node).
Either way main renders through withExoCompiler(new ExoDomBackend()).
An SSR app (--ssr) instead depends on @exodra/string alongside @exodra/core
and @exodra/dom, with an Express dev/prod server. One component module is
shared by both halves: new ExoStrBackend().render(App) prints it on the server,
and a @exodra/dom backend composed with withExoHydration adopts exactly
those nodes on the client through backend.hydrate(App, root), so only listeners
and subscriptions are added. See the
SSR guide.
The exodra CLI
The package also installs an exodra binary for scaffolding inside an existing
project:
npx exodra component Button # create a component (alias: c)
npx exodra page Home # create a page (alias: p)
npx exodra api hello # create an API route (alias: a)
npx exodra config # create exodra.config.js
Common options for component / page: -d, --dir <path>,
-t, --typescript, and --naming <PascalCase|kebab-case|snake_case>.
A page is a machine default-exported from its module (the route table
imports it that way), and it takes no props — the match that selected it arrives
as the params of its wire, whose params and pathname are what a page
needs. The outlet mounts a machine and nothing else. A component is a named machine
export, filled from its parent with c.one(port, Name) or repeated with
c.list(port, Name, rows), each row armed with its own entry of rows as its params. With -t the files carry type annotations; without
it they are the same code with the types dropped.
// src/pages/Home.tsx, from `npx exodra page Home -t`
import {
EXO_PORT_TEXT,
composeExoMachine,
createExoMachine,
createExoSchema,
exoPorts,
withExoWire,
} from '@exodra/core';
// A page takes no props — the match that selected it arrives as the params of its wire,
// `withExoWire(m, (c, match) => …)`, whose `params` and `pathname` are what a page needs. It is
// default-exported because the route table imports it that way.
const PagePorts = exoPorts({ heading: EXO_PORT_TEXT });
const pageSchema = createExoSchema(PagePorts, b => {
b.el('div', { class: 'page' }, d => {
d.el('h1', null, h => {
h.textPort(PagePorts.heading);
});
d.el('p', null, p => p.text('Welcome to the Home page.'));
});
});
const pageBase = createExoMachine(pageSchema);
export default composeExoMachine(pageBase, m =>
withExoWire(m, c => {
c.text(PagePorts.heading, 'Home');
})
);
api emits a module with GET and POST handlers: request/response code that
touches no renderer.
Writing Exodra components
State lives in the machine. The createInitialState option runs once per instance and returns
it; one function is the one place that turns that state into port writes; the
wire and the handlers call it. A port written with c.text / c.attr
holds that value until the next write — there is no source attached to it.
import {
EXO_PORT_EVENT,
EXO_PORT_TEXT,
composeExoMachine,
createExoMachine,
createExoSchema,
exoPorts,
withExoHandlers,
withExoWire,
} from '@exodra/core';
import type { TExoMachineNodeOf } from '@exodra/core';
import { ExoDomBackend, withExoCompiler } from '@exodra/dom';
import type { TExoDomNode } from '@exodra/dom';
const backend = withExoCompiler(new ExoDomBackend());
const CounterPorts = exoPorts({ text: EXO_PORT_TEXT, click: EXO_PORT_EVENT });
const counterSchema = createExoSchema(CounterPorts, b => {
b.el('div', { class: 'counter' }, div => {
div.el('span', null, span => {
span.textPort(CounterPorts.text);
});
div.el('button', { class: 'btn', type: 'button' }, btn => {
btn.eventPort(CounterPorts.click, 'click');
btn.text('+1');
});
});
});
const counterBaseMachine = createExoMachine(counterSchema, {
createInitialState: (_c: TExoDomNode) => ({ count: 0 }),
});
function showCount(c: TExoMachineNodeOf<typeof counterBaseMachine>): void {
c.text(CounterPorts.text, `Count: ${c.state.count}`);
}
const counterMachine = composeExoMachine(
counterBaseMachine,
m => withExoWire(m, c => showCount(c)),
m =>
withExoHandlers(m, on => {
on(CounterPorts.click, c => {
c.state.count++;
showCount(c);
});
})
);
backend.render(counterMachine, document.getElementById('app') as HTMLElement);
Data that lives outside the instance — a store several components follow — is read the same way, from an effect that draws first and then subscribes:
function showTotal(c: TExoMachineNodeOf<typeof counterBaseMachine>): void {
c.text(CounterPorts.text, `Total: ${store.getValue()}`);
}
const totalMachine = withExoEffects(counterBaseMachine, effect => {
effect(c => {
showTotal(c);
return store.onChange(() => showTotal(c));
});
});
The Components guide covers the machine and the connector in full; the JSX guide covers the compiled dialect that produces the same pair from markup.
Links
- npm: create-exodra
- GitHub: packages/create-exodra