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, packages/ + apps/ dirs
• 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, or bun.lock.

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

References

• React - UI library
• Vue.js - Progressive JavaScript framework
• Svelte - Cybernetically enhanced web apps
• Solid - Simple and performant reactivity
• React Native - Native apps with React
• Vite - Next-generation frontend tooling
• Next.js - React framework for production
• TanStack Start - Full-stack React framework
• Expo - React Native framework
• Webpack - Module bundler
• Tailwind CSS - Utility-first CSS framework
• pnpm Workspaces - Monorepo support
• Turborepo - Monorepo task runner
• Bun - Fast JavaScript runtime and package manager

Backup Architecture

flowchart LR
    A[File to modify] --> B[backupFile]
    B --> C[.xtarterize/backups/]
    C --> D[.index.json]
    A --> E[apply changes]
    E --> F{Need to undo?}
    F -->|Yes| G[restoreBackup]
    G --> C
    F -->|No| H[Done]
    
    style B fill:#f59e0b,color:#fff
    style E fill:#22c55e,color:#fff