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

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 (linter + formatter), with Tailwind CSS css.parser.tailwindDirectives support when detected
• TypeScript — strict: true, paths aliases, incremental: true + tsBuildInfoFile, .gitignore *.tsbuildinfo entries
• 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
• Quality — Knip (entry / project detection)
• Codegen — Plop (plopfile.ts scaffolds)
• Monorepo — Turborepo (turbo.json pipeline)
• Editor — VS Code settings.json and extensions.json (additive merging preserves your existing extensions)
• Agent — AGENTS.md, .agents/skills/ directory, and install relevant agent skills via npx skills@latest add for your detected stack
• Scripts — package.json scripts (with Ultracite detection if installed)

Note

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

Ultracite

xtarterize sets up Biome with sensible defaults. If you want stricter, more opinionated linting, we recommend Ultracite — a Biome preset with stricter rules for code quality.

After running xtarterize init, you can optionally run:

npx ultracite init

This will replace the default biome.json with Ultracite’s stricter configuration. The package.json lint scripts will automatically detect Ultracite and use ultracite instead of biome check.

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