Initialization

Initialize a Project

To apply conformance configuration to a project:

npx xtarterize init

1. Scan your project directory to detect framework, bundler, package manager, monorepo status, and existing configs
2. Resolve which conformance tasks are applicable for your stack
3. Check each task’s current status (new, patch, skip, or conflict)
4. Display a conformance plan table showing what will change
5. Prompt you to apply all, select specific tasks, dry-run, or quit

Example Output

✦ Scanning project...

  Detected:
    Framework:   React 18
    Bundler:     Vite 5
    Package Manager: pnpm

  Conformance plan:

    ✔ Biome (lint + format)              lint/biome           [new]
    ✔ vite-plugin-checker                vite/checker         [new]
    ~ tsconfig — incremental: true       ts/incremental       [patch]
    = Turbo                              monorepo/turbo       [skip — no monorepo]

  [A] Apply all   [S] Select items   [D] Dry-run   [Q] Quit

Options

Flag	Description
--dry-run	Preview all changes without applying anything
--yes	Skip all confirmations, apply all changes automatically
--skip <task-id>	Exclude a specific task (comma-separated)
--only <task-id>	Apply only a specific task (comma-separated)
--quiet	Suppress interactive prompts and verbose output

Examples

Preview

npx xtarterize init --dry-run

Apply all

npx xtarterize init --yes

Skip tasks

npx xtarterize init --skip codegen/plop,agent/skills-install

Only specific

npx xtarterize init --only lint/biome

What Gets Applied

The init command applies all tasks that are applicable to your detected stack:

• Linting & Formatting — Biome (non-Vite+) or Oxlint + Oxfmt (Vite+), with Ultracite presets installed automatically and configs extended/imported from Ultracite
• TypeScript — strict: true, paths aliases, incremental: true + tsBuildInfoFile, .gitignore *.tsbuildinfo entries and .tsbuildinfo/ directory
• Vite Plugins — vite-plugin-checker (checker() for TypeScript), rollup-plugin-visualizer
• CI/CD — GitHub Actions workflows (on.push.tags for release, schedule.cron for auto-updates, on.pull_request for CI) with pnpm/action-setup@v4 for pnpm projects
• Dependencies — Renovate config (extends: config:base, automerge)
• Release — Commitlint (@commitlint/config-conventional), czg (commitizen), commit-and-tag-version, simple-git-hooks (commit-msg, pre-commit, pre-push hooks)
• Quality — Knip (entry / project detection), lint-staged (runs linters on staged files, non-Vite+ projects)
• Codegen — Plop (plopfile.ts scaffolds, only for projects with a detected framework)
• Monorepo — Turborepo (turbo.json pipeline)
• Editor — VS Code settings.json and extensions.json (additive merging preserves your existing extensions)
• Agent — AGENTS.md and install relevant agent skills via npx skills@latest add for your detected stack
• Scripts — package.json scripts (uses Ultracite-aware lint/check/fix scripts when Ultracite is in dependencies), .npmrc with save-exact, strict-peer-dependencies, and auto-install-peers

Note

Each task checks if it’s already applied and skips if conformant. Running init twice produces no changes on the second run.

Ultracite

Ultracite is installed automatically alongside any lint tool (Biome, Oxlint, or Oxfmt). The generated configs extend or import Ultracite presets by default — no separate ultracite init step needed.

xtarterize overlays its own conventions on top of Ultracite defaults where they differ (e.g., kebab-case filenames, single quotes, generic array types). You can further customize by editing the generated config files directly.

References

• Biome Configuration — Full biome.json reference
• TypeScript tsconfig Reference — All compiler options explained
• Vite Plugin Checker — Type-checking during development
• GitHub Actions Documentation — Workflow syntax and features
• Renovate Configuration Options — Dependency automation reference
• Commitlint Rules — Conventional commit validation
• Knip Documentation — Finding unused files, dependencies, and exports
• Plop Documentation — Code scaffolding and generators
• Turborepo Documentation — Monorepo task orchestration
• Ultracite — Strict Biome preset for code quality
• Agent Skills — Open ecosystem of reusable AI agent capabilities

Init Flow

sequenceDiagram
    participant U as User
    participant CLI as CLI
    participant Core as @xtarterize/core
    participant Tasks as @xtarterize/tasks

    U->>CLI: xtarterize init
    CLI->>Core: runPreflight()
    Core-->>CLI: valid / errors
    CLI->>Core: detectProject()
    Core-->>CLI: ProjectProfile
    CLI->>Tasks: getAllTasks()
    CLI->>Core: resolveTasks(profile)
    Core-->>CLI: Applicable tasks
    CLI->>Core: resolveTaskStatuses()
    Core-->>CLI: Status map
    CLI->>U: Display plan
    U->>CLI: Confirm
    CLI->>Tasks: applyTasks()
    Tasks-->>CLI: Result
    CLI->>U: Summary