@alxia/create

Start an alxia app in one command: a minimal one to try alxia with, an API with Zod written OpenAPI spec first, a GraphQL API written schema first, or React Router's official template served by alxia.

bun create @alxia my-app

bun create @alxia runs this package's bin, as bun create <name> runs create-<name> and bun create @scope runs @scope/create. It asks for what it is not given, writes the project, installs it and prints the next steps:

cd my-app
bun dev

It needs Bun 1.4.2 or later, which the projects it writes run on.

Templates

bun create @alxia my-app --template minimal      # the template to try alxia with
bun create @alxia my-api --template api
bun create @alxia my-graph --template graphql
bun create @alxia my-site --template react-router

minimal is the one to start with: one file, one dependency, a test, and bun dev answering in 30 seconds.

The heart of the api project, its middleware and a route bound to an operation of openapi.yaml (the whole file, and how to add an operation, are in the guide):

// src/context.ts, in part: the base, registered
export const base = alxia().decorate({ todos });

declare module "@alxia/core" {
  interface Register {
    context: typeof base;
  }
}

// src/routes/todos.ts, in part: no import of the app
const requireKey = defineMiddleware(({ request, reply }, next) =>
  request.headers.get("x-api-key") === env.API_KEY
    ? next()
    : reply(401, { error: "unauthorized" as const }),
);

export const todoRoutes = defineRoutes()
  .route(operations.createTodo, requireKey, ({ body, todos, reply }) => {
    const todo = { id: todos.length + 1, title: body.title, done: false };
    todos.push(todo);
    return reply.created(todo);
  });

// src/app.ts
export const app = base.plugin(todoRoutes);

operations.createTodo is POST /todos as openapi.yaml declares it: the body is validated just before the handler, which reads it typed, and the handler's reply is checked against the spec's responses; requireKey's 401 is its own, sent as it is. To change the API, edit openapi.yaml and run bun run generate; never edit src/generated/.

The graphql project's heart, a schema and a resolver reading the typed viewer (the walk-through, with subscriptions and how to add a field, is in the guide):

// schema.graphql, in part
//   type Mutation { addNote(text: String!): Note! }

// src/context.ts, in part: a middleware, then the resolvers' context
const viewerOf = defineMiddleware(({ request }, next) => {
  const token = request.headers.get("authorization")?.match(/^Bearer (.+)$/i)?.[1];
  const id = token === undefined ? undefined : db.tokens.get(token);
  return next({ viewer: (id === undefined ? undefined : db.users.get(id)) ?? null });
});
export const base = alxia().decorate({ env, db }).use(viewerOf);
export type Context = GraphQLContext<typeof base, { loaders: Loaders }>;

// src/resolvers.ts, in part: `Resolvers` is generated from the schema
export const resolvers: Resolvers = {
  Mutation: {
    addNote: (_, { text }, { viewer, db }) => {
      if (viewer === null) {
        throw new GraphQLError("Sign in to add a note", {
          extensions: { code: "UNAUTHENTICATED" },
        });
      }
      // …
    },
  },
  Note: {
    // The notes of one query load their authors in one batch (N+1 otherwise).
    author: (note, _, { loaders }) => loaders.user.load(note.authorId),
  },
};

To change the API, edit schema.graphql and run bun run generate; never edit src/generated/.

Lint and format

Every project ships Biome, set up the same way: a biome.json of its own with Biome's recommended rules, spaces and double quotes, imports sorted, the build output (and .react-router/ or src/generated/, where the project has them) skipped; @biomejs/biome pinned exactly, as Biome asks; and .vscode/ recommending its extension, formatting on save. A new project passes bun run check:ci with no finding.

cd my-api
bun run verify

check:ci and not ci, since bun ci is Bun's frozen-lockfile install, which a script named ci would not replace. The guide has the settings and why.

Docker

Every project builds into an image as it is written: built on oven/bun:1, run on oven/bun:1-alpine as the non-root bun user, an image of about 130 MB. Each Dockerfile builds in a stage of its own, and the image holds the build output alone, no node_modules:

• minimal: bun run build bundles src/index.ts into dist/index.js; the image holds dist/ and runs bun --no-install dist/index.js.
• api: bun run build bundles src/server.ts and its dependencies into dist/server.js, src/generated/ included as it is committed, so the build generates nothing; the image holds dist/ and runs bun --no-install dist/server.js.
• graphql: bun run build bundles src/server.ts, its dependencies and schema.graphql (imported as text) into dist/server.js, src/generated/ included as it is committed; the image holds dist/ and runs bun --no-install dist/server.js, with GraphiQL off (NODE_ENV=production, so alxia's dev switch is off).
• react-router: bun run build, every dependency bundled into build/server/index.js by @alxia/react-router's plugin; the image holds build/ and runs bun --no-install build/server/index.js.

cd my-api
docker build -t my-api .
docker run -p 3000:3000 -e API_KEY=change-me my-api   # API_KEY is required: the app does not start without it

minimal and graphql run the same way, with no -e: docker run -p 3000:3000 my-app.

cd my-site
docker build -t my-site .
docker run -p 3000:3000 my-site

Commit the bun.lock that bun install wrote: the image installs from it with --frozen-lockfile. The guide has the stages, and troubleshooting what to do for a dependency that cannot be bundled, and for a native addon built for glibc alone, which does not load on Alpine.

Options

Given both dir and --template, it asks nothing, so it runs in a script or CI.

Versions

• alxia's packages — @alxia/core, @alxia/env (api, graphql), @alxia/openapi (api), @alxia/graphql (graphql) and @alxia/react-router (react-router) — are moved to the newest version on the registry within the ranges this release of @alxia/create was published with: ^0.3.1 writes ^0.3.4 once 0.3.4 is out, never ^0.4.0. Just after a release, while the registry does not serve that version yet, the newest of the same minor is written (^0.3.0, which takes 0.3.1 once it arrives), and the output says so. bunx @alxia/create@<version> picks an older set.
• Everything else — Zod, TypeScript, Vite, React, React Router, GraphQL, Tailwind — is moved to the newest version on the registry when the project is written, within the range alxia's packages accept: TypeScript within ^6.0.3 || ^7.0.0, Vite within ^7.0.0 || ^8.0.0, React Router and its packages within ^8.0.0, Zod within ^4.2.0, graphql within ^16.11.0 || ^17.0.0 and graphql-yoga within ^5.16.0; what no alxia package constrains goes to npm's latest. A newer major outside alxia's range is left out, and the output says so.
• Biome is pinned exactly, and written exactly: the newest patch of the template's minor, 2.5.15 writing 2.5.16 but never 2.6.0, whose new rules the template was not checked against.
• The code generators are pinned exactly and kept at the template's versions, never moved to a newer patch: @nxgt/openapi-codegen (api, 0.11.0) and GraphQL Code Generator's @graphql-codegen/cli, typescript and typescript-resolvers (graphql). bun run verify runs generate --check over the committed src/generated/, which a release that writes the files differently would fail in a fresh project.

The registry is the one BUN_CONFIG_REGISTRY or npm_config_registry names, else npmjs.org; when it does not answer, the template's own versions stay, with a warning.

Other package managers

bunx @alxia/create my-app --template minimal
npm create @alxia my-app -- --template minimal

The bin runs on Bun (#!/usr/bin/env bun) whichever runner starts it, and the project it writes installs with bun install.

API

Documentation

• Guide: each template file by file, adding an operation to the api project and a field to the graphql one, what the react-router template adds to React Router's, Biome's settings, each Dockerfile, how versions are chosen, and running it in CI.
• Troubleshooting: each message the command prints, and what to do about it.
• Roadmap: what is coming, and what is not planned.
• Recipes: Start in 5 minutes, A spec-first CRUD API, A GraphQL API, Deploy with Docker.