Skip to content
xtarter
Blog

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

Section titled “Package Structure”

Package Dependencies

Section titled “Package Dependencies”
flowchart TD
    CLI["xtarterize<br/>apps/xtarterize"] --> 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

How It Works

Section titled “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

Section titled “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 createFileTask, createJsonMergeTask, or createMultiFileTask to eliminate boilerplate, with shared seams in json-config.ts and ops.ts
  • Shared command orchestration — init and sync share a runCommand() helper in the CLI layer

Core Modules

Section titled “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

Section titled “Task Categories”
flowchart LR
    Tasks["@xtarterize/tasks"] --> Lint["lint/<br/>biome, oxlint, oxfmt"]
    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, git-hooks"]
    Tasks --> Quality["quality/<br/>knip, lint-staged"]
    Tasks --> Codegen["codegen/<br/>plop"]
    Tasks --> Monorepo["monorepo/<br/>turbo"]
    Tasks --> Editor["editor/<br/>vscode (settings + extensions)"]
    Tasks --> Agent["agent/<br/>agents-md, skills-install"]
    Tasks --> Scripts["scripts/<br/>package-scripts, npmrc"]
    Tasks --> Factory["factory.ts + factory-*<br/>task creation helpers"]


    style Tasks fill:#6366f1,color:#fff

Development Workflow

Section titled “Development Workflow”
Terminal window
# Install dependencies
vp install

Toolchain

Section titled “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

Section titled “References”
Explore project detection →