Configuration

xtarterize doesn’t require a config file. It detects your project’s stack automatically and applies only what’s appropriate.

Detection

When you run init, xtarterize scans your project to build a ProjectProfile:

• Framework - React, Vue, Svelte, Solid, React Native, or Node (from package.json deps)
• Bundler - Vite, Next.js, TanStack Start, Expo, Webpack, Rspack, or none
• Router - TanStack Router, React Router, Vue Router, Expo Router, or none
• Styling - Tailwind CSS, CSS Modules, Styled Components, Vanilla Extract, NativeWind, or Vanilla
• Package Manager - pnpm, npm, yarn, or bun (from lockfiles or packageManager field)
• Monorepo - Detected via pnpm-workspace.yaml, turbo.json, nx.json, lerna.json, or at least two of the packages/, apps/, services/ directories
• GitHub - .github/ directory presence
• Existing Configs - Checks for biome.json, tsconfig.json, renovate.json, vite.config.*, .versionrc, .gitignore, etc.

Detection Flow

flowchart TD
    A[read package.json] --> B[detectFramework]
    A --> C[detectBundler]
    A --> D[detectStyling]
    A --> E[detectVitePlus]
    B --> F[detectRouter]
    C --> F
    
    B --> G[detectRuntime]
    C --> G
    
    A --> H[detectPackageManager]
    A --> I[detectMonorepo]
    A --> J[detectGitHubWorkflows]
    A --> K[detectExistingConfigs]
    
    G --> L[ProjectProfile]
    F --> L
    D --> L
    E --> L
    H --> L
    I --> L
    J --> L
    K --> L
    
    style A fill:#6366f1,color:#fff
    style L fill:#22c55e,color:#fff

Detection Sources

package.json

Framework, bundler, router, styling, and TypeScript are all detected from dependencies and devDependencies.

Lock files

Package manager is detected from lock file presence: pnpm-lock.yaml, yarn.lock, package-lock.json, bun.lock, or bun.lockb.

File system

Monorepo status, GitHub, and existing configs are detected by checking for specific files and directories.

Ambiguity Resolution

Note

If both react and react-native are detected, xtarterize prompts you to clarify which describes the project. In CI mode (--quiet), it defaults to react.

Task Gating

Tasks are gated on the detected profile:

• Vite plugin tasks only run when bundler === 'vite'
• Monorepo tasks only run when monorepo === true
• CI tasks only run when hasGitHub === true
• TypeScript tasks only run when typescript === true

Monorepo scope filtering

When running inside a monorepo, xtarterize further filters tasks based on their scope. Each task declares one of three scopes:

• root - The task applies only at the monorepo root.
• package - The task applies only inside a workspace package.
• both (default) - The task applies everywhere.

At the monorepo root (workspaceRoot: true), package-scoped tasks are hidden. Inside a workspace package (workspaceRoot: false), root-scoped tasks are hidden. Tasks without an explicit scope (or with scope: 'both') are visible in both positions.

In non-monorepo projects, scope filtering is disabled - all tasks that pass the applicable() check are shown regardless of their declared scope.

Parameterized Templates

All templates adapt to the detected profile:

• GitHub workflows use the detected package manager for install commands
• Knip entry points are inferred from the bundler/framework
• Plop generators vary by framework (React gets component+hook, Vue gets component+composable, etc.)
• VS Code extensions include framework-specific recommendations
• AGENTS.md includes framework-specific instructions

Backup System

Before any file is modified, xtarterize creates a timestamped backup in .xtarterize/backups/. An index file tracks all backups for easy restoration.

• Directory.xtarterize/

  • Directorybackups/

    • .index.json
    • tsconfig.json.2024-01-15T10-30-00-000Z
    • biome.json.2024-01-15T10-30-00-000Z

The .xtarterize/ directory is automatically added to your project’s .gitignore when you run any xtarterize command. You won’t see these internal artifacts in git status.

Restore with:

npm

npx xtarterize@latest restore tsconfig.json

pnpm

pnpm xtarterize@latest restore tsconfig.json

yarn

yarn xtarterize@latest restore tsconfig.json

bun

bunx xtarterize@latest restore tsconfig.json

deno

deno x xtarterize@latest restore tsconfig.json

ni

nlx xtarterize@latest restore tsconfig.json

Task selection

.xtarterizerc accepts skip and only arrays alongside plugins so repeat runs apply the same filter without CLI flags. The same fields work in the "xtarterize" key of package.json.

{
  "plugins": ["@acme/xtarterize-tasks"],
  "skip": ["agent/skills-install"],
  "only": ["ts/strict", "lint/biome"]
}

Precedence rules:

• CLI --only overrides the config only list when provided
• CLI --skip extends the config skip list
• A task in both skip and only is excluded - skip wins
• An empty or absent only list means no restriction, not “apply nothing”

For command behavior, see the CLI reference. For generated files, see the task catalog.