Architecture Overview

xtarterize is organized as a monorepo using Turborepo for task orchestration, pnpm for package management, and Vite Plus for build, test, and development workflows.

Package Structure

• Directorypackages/

  • Directorycore/ — @xtarterize/core — detect.ts + detect/, resolve.ts, apply.ts, backup.ts, preflight.ts

    • …
  • Directorypatchers/ — @xtarterize/patchers — json-merge.ts, ast-patch.ts

    • …
  • Directorytasks/ — @xtarterize/tasks — factory.ts, factory-config.ts, factory-ops.ts, all task implementations

    • …
• Directoryapps/

  • Directorycli/ — xtarterize — CLI binary (citty + @clack/prompts)

    • …
  • Directorydocs/ — @xtarterize/docs — This documentation site (Astro/Starlight)

    • …
• Directorytest/

  • Directoryfixtures/ — Test fixtures for various project types

    • …

Package Dependencies

flowchart TD
    CLI["xtarterize<br/>apps/cli"] --> Core["@xtarterize/core"]
    CLI --> Tasks["@xtarterize/tasks"]
    Tasks --> Core
    Tasks --> Patchers["@xtarterize/patchers"]
    
    style CLI fill:#6366f1,color:#fff
    style Core fill:#22c55e,color:#fff
    style Tasks fill:#f59e0b,color:#fff
    style Patchers fill:#a855f7,color:#fff

Note

@xtarterize/patchers and @xtarterize/core have no internal workspace dependencies — they are leaf packages that can be used independently.

How It Works

sequenceDiagram
    participant User
    participant CLI as CLI (citty)
    participant Core as @xtarterize/core
    participant Tasks as @xtarterize/tasks
    participant Patchers as @xtarterize/patchers
    
    User->>CLI: xtarterize init
    CLI->>Core: runPreflight(cwd)
    Core-->>CLI: PreflightResult
    CLI->>Core: detectProject(cwd)
    Core-->>CLI: ProjectProfile
    CLI->>Tasks: getAllTasks()
    Tasks-->>CLI: Task[]
    CLI->>Core: resolveTasks(profile, tasks)
    Core-->>CLI: ApplicableTask[]
    CLI->>Core: resolveTaskStatuses(tasks, cwd, profile)
    Core-->>CLI: Map<taskId, TaskStatus>
    CLI->>User: Display plan
    User->>CLI: Confirm
    CLI->>Core: applyTasks(tasks, cwd, profile)
    Core->>Core: backupFile(cwd, filepath)
    Core->>Tasks: task.apply(cwd, profile)
    Tasks->>Patchers: mergeJson / mergeYaml / injectVitePlugin
    Patchers-->>Tasks: Modified content
    Tasks-->>Core: Applied
    Core-->>CLI: { applied, skipped, errors }
    CLI->>User: Summary

Key Design Decisions

• Detection lives in core — No CLI dependency, reusable by other consumers
• Tasks are independent — Each task can run standalone via add <task-id>
• Dry-run is exact — dryRun() output is bit-for-bit identical to what apply() writes
• Idempotency is non-negotiable — Running twice produces no changes on second run
• Templates are parameterized — All templates receive ProjectProfile and adapt accordingly
• Factory-based task creation — Most tasks use createSimpleFileTask, createJsonMergeTask, or createFileTask to eliminate boilerplate, with shared seams in factory-config.ts and factory-ops.ts
• Shared command orchestration — init and sync share a runCommand() helper in the CLI layer

Core Modules

flowchart TD
    Core["@xtarterize/core"] --> Detect["detect.ts + detect/*<br/>Project detection"]
    Core --> Resolve["resolve.ts<br/>Task resolution"]
    Core --> Apply["apply.ts<br/>Task application"]
    Core --> Backup["backup.ts<br/>File backup/restore"]
    Core --> Preflight["preflight.ts<br/>Pre-flight checks"]
    Core --> Diagnostics["diagnostics.ts<br/>Conflict detection"]
    Core --> Utils["utils/<br/>fs, diff, logger ([picocolors](https://github.com/alexeyraspopov/picocolors)), pkg ([pkg-types](https://github.com/unjs/pkg-types))"]
    
    style Core fill:#6366f1,color:#fff

Task Categories

flowchart LR
    Tasks["@xtarterize/tasks"] --> Lint["lint/<br/>biome"]
    Tasks --> TS["ts/<br/>incremental"]
    Tasks --> Gitignore["gitignore/<br/>tsbuildinfo"]
    Tasks --> Vite["vite/<br/>checker, visualizer"]
    Tasks --> CI["ci/<br/>release, auto-update, ci"]
    Tasks --> Deps["deps/<br/>renovate"]
    Tasks --> Release["release/<br/>commitlint, czg, cat-version"]
    Tasks --> Quality["quality/<br/>knip"]
    Tasks --> Codegen["codegen/<br/>plop"]
    Tasks --> Monorepo["monorepo/<br/>turbo"]
    Tasks --> Editor["editor/<br/>vscode (settings + extensions)"]
    Tasks --> Agent["agent/<br/>agents-md, skills, module"]
    Tasks --> Scripts["scripts/<br/>package-scripts"]
    Tasks --> Factory["factory.ts + factory-*<br/>task creation helpers"]
    
    style Tasks fill:#6366f1,color:#fff

Development Workflow

Setup

# Install dependencies
vp install

Build

# Build all packages
pnpm build

Test

# Run tests
vp test

Check

# Format and lint with Biome
pnpm check

# Type check separately (Turborepo)
pnpm typecheck

Develop

# Start development (watch mode)
pnpm dev

Toolchain

Tool	Purpose	Command
Vite Plus	Build, test, pack, dev server	vp build, vp test, vp pack, vp dev
Turborepo	Monorepo task orchestration	turbo run build, turbo run typecheck
Biome	Linting and formatting	biome lint ., biome check --write .
pnpm	Package management, workspaces	pnpm install, catalog: for shared deps
Changesets	Version management and publishing	changeset, changeset version

References

• Vite Plus Documentation — Unified toolchain for the web
• Turborepo Documentation — Monorepo task orchestration
• pnpm Workspaces — Workspace and monorepo management
• citty — Elegant CLI framework for Node.js
• @clack/prompts — Interactive command-line prompts
• Astro — Content-focused web framework
• Starlight — Documentation framework for Astro
• defu — Deep merge utility
• magicast — AST manipulation for JavaScript/TypeScript
• picocolors — Tiny terminal colors library
• pkg-types — Package.json type definitions and utilities

Explore project detection →