Getting Started

1. Install xo

Install the xocode package globally. The binary is available as xo.

$npm install -g xocode

Or with pnpm / yarn / bun:

$pnpm add -g xocode
$yarn global add xocode
$bun add -g xocode

2. Scaffold a new project

Use xo create to bootstrap a new project from a template generator. Generators are identified by their GitHub path — owner/repo or owner/repo/subpath.

$mkdir my-app && cd my-app
$xo create acme/nextjs-starter

xo will:

1. Fetch generator.json from https://github.com/acme/nextjs-starter
2. Run any interactive prompts defined in the generator
3. Execute all actions — copy files, render templates, run install commands
4. Write xo.config.json to record the applied template

3. Add features to an existing project

xo add applies a feature generator to your existing project. Before running, xo validates compatibility via detects, requires, and conflicts rules.

$xo add acme/shadcn-setup
$xo add acme/auth-jwt
$xo add acme/docker

4. Preview before applying

Use --dry-run to see exactly what a generator would do without writing any files.

$xo add acme/auth-jwt --dry-run

[dry-run] template: templates/auth.service.ts.hbs → src/auth/auth.service.ts
[dry-run] template: templates/jwt.guard.ts.hbs → src/auth/jwt.guard.ts
[dry-run] json: package.json
[dry-run] command: pnpm install

5. View history and undo

xo records every operation in .xo/state.json. Use xo history to list them and xo undo to revert the last one.

$xo history

Applied generators:

  a1b2c3d4  acme/nextjs-starter          5/4/2025, 10:32:00 AM
  e5f6a7b8  acme/shadcn-setup            5/4/2025, 10:45:12 AM
  c9d0e1f2  acme/auth-jwt               5/4/2025, 11:02:44 AM

$xo undo

✓ Reverted "acme/auth-jwt" — 4 file(s) restored

6. Using local generators

Run generators from a local path — useful during development or for private generators that live inside your repo.

$xo add ./generators/my-feature
$xo create ../shared-generators/api-template

Generators stored in .xo/generators/ inside your project are automatically discovered without any path prefix.