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, 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

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

Restore with:

npx xtarterize 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