Tools

Config Reference

xo maintains two files in your project automatically. You never need to edit them by hand, but understanding their structure helps when debugging or sharing generator state with your team.

`xo.config.yaml`

Lives at the project root. Stores project-level settings that workflows read and write. Commit this file so your team shares the same generator configuration.

template: next-app
packageManager: pnpm
features:
  - payment/stripe
  - auth/jwt
  - ui/button
ui:
  componentsDir: src/components/ui
  hooksDir: src/hooks
  libDir: src/lib
database:
  provider: postgres
  url: postgresql://localhost:5432/mydb
auth:
  provider: jwt

template

Written automatically by xo create. Records which template scaffolded the project. Used by requires/conflicts validation.

template: next-app

features

Updated automatically by xo add. Tracks which feature workflows have been applied. Used to enforce conflicts and requires rules.

features:
  - payment/stripe
  - auth/jwt

packageManager

Set by xo/detect-pm on first run. Used by subsequent generators so they run the right package manager command.

packageManager: pnpm

Namespace blocks

Any generator can define its own namespace. Common examples are ui, database, and auth — but any key is valid. Workflows read and write these via {{ config.* }} and the xo/json action.

ui:
  componentsDir: src/components/ui
  hooksDir: src/hooks

database:
  provider: postgres
  url: postgresql://localhost:5432/mydb

Auto-population via requires

When a workflow declares requires, xo checks if that key exists in xo.config.yaml. If missing, xo prompts the user and writes the answer back automatically — the config file builds up over time as you run workflows.

# in workflow.yaml
requires:
  - ui.componentsDir

`.xo/state.json`

Lives at .xo/state.json. Tracks every operation for xo undo support. Commit this file so your team shares the same generator history. Do not edit manually.

{
  "operations": [
    {
      "id": "a3f1c2d4-6e8f-...",
      "timestamp": "2025-01-15T10:30:00Z",
      "generator": "payment/stripe",
      "type": "add",
      "files": [
        {
          "filePath": "app/api/stripe/route.ts",
          "action": "created"
        },
        {
          "filePath": ".env.example",
          "action": "modified",
          "before": "NODE_ENV=development\n"
        }
      ]
    }
  ]
}

Field	Description
id	UUID for this operation. Used by xo undo to target the right operation.
timestamp	ISO 8601 timestamp of when the operation ran.
generator	The generator reference that was applied (registry name or @github/ path).
type	"create", "add", or "run" — matches the xo command used.
files	Array of file changes. Each entry records the path, action (created/modified/deleted), and the before-snapshot for modified files.

Run xo history to see all operations in a human-readable format. Run xo undo to revert the most recent one.

Context variables

Variables available inside any string value in a workflow using {{ double-braces }}.

Namespace	Source
{{ inputs.* }}	Input values collected during the current workflow run
{{ config.* }}	Values from xo.config.yaml
{{ steps.<id>.outputs.* }}	Outputs from a previous step that has an id
{{ env.* }}	Environment variables (process.env)

# Use a config value
to: "{{ config.ui.componentsDir }}/{{ inputs.componentName }}.tsx"

# Use an environment variable
value: "{{ env.DATABASE_URL }}"

# Use a step output
run: "{{ steps.pm.outputs.value }} add stripe"

Global xo config (per machine)

xo stores per-machine state in ~/.xo/. This is managed automatically via xo registry, xo link, and xo cache commands — you don't need to edit these files directly.

~/.xo/
├── registry.json        ← registered generator names → GitHub URLs
├── links.json           ← locally linked generators (set by xo link)
└── cache/               ← workflow YAMLs fetched from GitHub
    └── my-org/
        └── xo-stripe/
            ├── workflow.yaml
            ├── .ref
            └── templates/

~/.xo/registry.json

Maps short generator names to GitHub URLs. Managed by xo registry add / remove.

~/.xo/links.json

Maps generator names to local filesystem paths. Managed by xo link / unlink.

~/.xo/cache/

Cached workflow.yaml files fetched from GitHub. Branch refs re-fetch on every run; tag refs are cached forever. Managed by xo cache clear.

See the CLI Reference for the full list of registry, link, and cache commands.