Architecture Overview

xtarterize is a pnpm monorepo orchestrated with Turborepo and built with Vite Plus.

Packages

• @xtarterize/core - detection, task resolution, preflight, the apply engine, and shared services. It has no CLI dependency, so other tools can reuse it.
• @xtarterize/patchers - safe edits to JSON and to Vite config source.
• @xtarterize/tasks - the conformance tasks xtarterize ships.
• xtarterize - the CLI users run.
• create-xtarter-app - a scaffolding CLI for new projects.
• @xtarter/create - the Vite+ organization template manifest.
• @xtarter/docs - this documentation site.

The CLI depends on core and tasks. Tasks depend on core and patchers. Core and patchers are leaf packages with no workspace dependencies.

Pipeline

1. Detect - inspect the project directory and build a profile of framework, bundler, runtime, package manager, and monorepo layout.
2. Resolve - filter the task registry by applicability and scope, then check each task’s status.
3. Plan - collect statuses, diffs, dependencies, and the backup set without writing anything.
4. Confirm - show the plan and ask the user unless the command runs non-interactively.
5. Execute - back up each affected file once, install dependencies in one batch, then run the tasks.
6. Report - print the outcome and set the exit code.

Design decisions

• One resolution per task - status, diffs, apply, and dependency collection all come from the same resolution, so they cannot disagree.
• Plan, then execute - the previewed diffs are exactly what execution writes.
• Idempotency is non-negotiable - a second run makes no changes.
• Tasks are independent - every task can run on its own with add <task-id>.
• Packages return Effects, apps run them - packages/* build Effects and never call a runtime. The CLI runtime is the only Effect edge, and plain Promise leaves are lifted there.
• Services own the effectful edges - process execution, dependency installs, and interactive prompts are services provided at the runtime edge.
• Failures surface - a failed install or task is collected in the result and reflected in the exit code instead of being ignored.

Development

From the repository root:

pnpm install    # install dependencies
pnpm build      # build every package
vp test         # run the test suite
pnpm check      # typecheck, build, lint, and tests
pnpm typecheck  # type checks only
pnpm dev        # development servers

Toolchain

Tool	Purpose
Vite Plus	Build, test, pack, and dev server
Turborepo	Monorepo task orchestration
Biome	Linting and formatting
pnpm	Package management and workspaces
Changesets	Versioning and publishing

Explore project detection