Project setup · Ajo Kit docs

A small wooden pier linking three cabins over calm water.

Ajo Kit turns Ajo components into an application. Files under src become routes, server loaders and actions sit next to the pages that use them, and one command line runs development, builds, migrations and seeds. This page lists the files a Kit application needs and every kit command. To start from a working App, follow the quick start.

Where it runs

Node 22.18 or newer is the host for development, builds, tests and the kit command. It is not a production server. A built application runs only on Ajo Engine, which loads its own platform and database modules. The Node versions that Kit ships exist so that Vite, Vitest and the CLI can run your code on your machine.

Project files

A Kit application is an ES module package with a small set of files at its root.

Path	Purpose
`package.json`	Declares `"type": "module"`, the `kit` scripts and the dependencies. An optional `kit.engine` block declares what the engine may access.
`pnpm-workspace.yaml`	Allows the install scripts of dependencies such as `better-sqlite3` and `esbuild`.
`vite.config.ts`	Registers the `kit()` Vite plugin.
`tsconfig.json`	Compiles JSX to Ajo and type-checks the project.
`index.html`	The document template, with three slots Kit fills on every server render.
`src/`	Routes, handlers, middleware and the rest of your application code.
`db/migrations`, `db/seeds`	Optional. Migrations and seed files for the database.
`.env`	Optional local environment values. The `kit` command loads this file before it runs.
`.ajo/`, `dist/ajo`	Build output: the staged engine inputs and the sealed artifact. Keep both out of version control.

The starter that pnpm create ajo creates is a complete example of this layout. Pin exact versions; ajo-kit declares ajo and vite as peer dependencies. The plugins that kit() registers, and their options, are described in Build and configuration.

If you import modules with absolute /src/… paths, also add "paths": { "/src/*": ["./src/*"] } to tsconfig.json so TypeScript resolves them the way Vite does.

index.html

The document template has three slots that Kit fills on every server render:

Slot	Filled with
`<!-- ssr:head -->`	The title, meta and link tags merged from the route’s `head()` loaders.
`<!-- ssr:data -->`	A `<script type="application/json" id="__SSR__">` with the route state the client starts from.
`<!-- ssr:root -->`	The rendered route. The client takes over the element with `id="root"`.

/src/client is an alias for ajo-kit/client, so the application has no client entry file of its own. Once the client has started it sets data-ajo-ready="true" on the html element, which browser tests can wait for. kit dev falls back to a built-in document when index.html is missing; kit build needs the file.

The src directory

Four file names have a meaning to Kit. Everything else under src is ordinary application code, imported where you need it.

File	Role
`page.tsx`	The component for a URL. See Routing.
`layout.tsx`	A component that wraps every page below its directory.
`handler.ts`	Server code for that directory: loaders, actions and API methods.
`wares.ts`	Middleware for that directory and everything below it. See API routes and middleware.

Pages and layouts may be .js, .jsx, .ts or .tsx files.

The starter

pnpm create ajo <dir> creates an App from the official starter, Ajo Notes. It demonstrates account registration, cookie sessions with CSRF protection, SQLite migrations, notes visible only to their owner, live updates across tabs, and an action that emails you your latest 50 notes. The quick start creates it, runs it and lists what each of its files does.

The kit command

ajo-kit installs a kit executable in the project. Run it as pnpm kit: pnpm runs the project’s own binary when no script has that name, so nothing is installed globally. kit <command> --help prints a command’s options.

Command	What it does	Options
`kit dev`	Starts the development server: Vite in middleware mode with server rendering. If the port is taken, it tries the next one.	`-p, --port`, default `5173`
`kit build`	Builds the client, the closed server graph and the compiled migrations into `.ajo/` and writes the `.ajo/compiler.json` descriptor. When the project has `ajo-engine-compiler` installed, it seals `.ajo/` into `dist/ajo`, replacing any previous one.	None
`kit migrate`	Creates, runs, rolls back and lists migrations; Database covers its subcommands.	`-d, --database`, default `./database.sqlite`
`kit seed`	Imports each `db/seeds/*.ts` file in name order and calls its exported `seed(db)`.	`-d, --database`

Terminal

pnpm kit dev -p 3000

The migrations folder is always db/migrations and the seeds folder is always db/seeds, relative to the directory where you run the command. Every build rejects Node built-ins and any other import outside the engine’s closed module graph, so those problems appear at build time.

Installed ajo-* packages can extend the command line. ajo-kit-server, for example, adds kit host and kit deploy, described in Deploy your first App.

Full reference: ajo-kit packages/ajo-kit/README.md