Conformance Tasks

xtarterize applies conformance configuration through discrete, independently applicable tasks. Each task detects whether it’s needed and only applies changes if necessary.

In monorepos, tasks are further filtered by their scope. Root-scoped tasks (CI/CD, release tooling, editor config, etc.) only appear when running from the monorepo root. Package-scoped tasks (Vite plugins, tsconfig paths) only appear inside workspace packages. See the Monorepo guide for details.

Linting & Formatting

Task ID	Description	Applicable When
`lint/biome`	Install Biome + Ultracite, write `biome.json` extending Ultracite presets with framework-aware overrides	Non-Vite+ projects (no ESLint/Oxlint detected)
`lint/oxlint`	Install Oxlint + Ultracite, write `oxlint.config.ts` or `.oxlintrc.json` (legacy) extending Ultracite presets	Vite+ projects (no ESLint/Biome detected)
`lint/oxfmt`	Install Oxfmt + Ultracite, write `oxfmt.config.ts` or `.oxfmtrc.json` (legacy) extending Ultracite preset	Vite+ projects (no ESLint/Biome detected)

All three tasks install Ultracite automatically alongside the tool-specific dependency and generate configs that extend/import Ultracite presets. No separate ultracite init step needed.

Framework-Aware Biome Config

When Tailwind CSS is detected, the generated biome.json includes:

{
  "css": {
    "parser": {
      "tailwindDirectives": true
    }
  }
}

This enables Biome to parse Tailwind v4 directives like @theme without errors. See css.parser.tailwindDirectives in Biome’s configuration reference.

TypeScript

Task ID	Description	Applicable When
`ts/strict`	Patch `tsconfig.json` with 4 compiler options: `strict: true`, `noUnusedLocals: true`, `noUnusedParameters: true`, `verbatimModuleSyntax: true` (each checked independently)	TypeScript detected
`ts/paths`	Patch `tsconfig.json` with `baseUrl` and `paths` aliases (`@/` → `./src/`)	TypeScript detected
`ts/incremental`	Patch `tsconfig.json` with `incremental: true` and `tsBuildInfoFile: ".tsbuildinfo"`	TypeScript detected
`gitignore/tsbuildinfo`	Add `*.tsbuildinfo` and `.tsbuildinfo/` to `.gitignore`	TypeScript detected

Vite Plugins

Task ID	Description	Applicable When
`vite/checker`	Inject `vite-plugin-checker` (`checker()`) into `vite.config.ts` via AST	Bundler is Vite
`vite/visualizer`	Inject `rollup-plugin-visualizer` (`visualizer()`) into `vite.config.ts` via AST	Bundler is Vite

CI/CD

Task ID	Description	Applicable When
`ci/release`	Write `.github/workflows/release.yml` - triggers on `push.tags`	GitHub detected
`ci/auto-update`	Write `.github/workflows/auto-update.yml` - `schedule.cron` for weekly dependency updates	GitHub detected
`ci/ci`	Write `.github/workflows/ci.yml` - lint, typecheck, test on `pull_request`	GitHub detected

Conditional pnpm Setup

For projects using pnpm, CI workflows automatically include pnpm/action-setup@v4 with package_json_file before actions/setup-node@v6. This ensures reproducible pnpm versions across runs. npm and yarn projects are unaffected.

Monorepo Workspace Config

When running in a pnpm monorepo, the workspace/pnpm-workspace task generates a pnpm-workspace.yaml file:

packages:
  - 'apps/*'
  - 'packages/*'

This is the standard pnpm workspace layout. The task only applies when the detected package manager is pnpm.

Dependencies

Task ID	Description	Applicable When
`deps/renovate`	Write `renovate.json` with `extends: ["config:base"]`, `automerge`, and `stabilityDays: 2`	GitHub detected

Release

Task ID	Description	Applicable When
`release/commitlint`	Install commitlint with `@commitlint/config-conventional`, write `commitlint.config.ts`	Git detected
`release/czg`	Install czg (Commitizen adapter), add `commit` script to `package.json`	Always
`release/cat-version`	Install commit-and-tag-version, write `.versionrc`	Always
`release/git-hooks`	Install husky, wire 4 hooks: `commit-msg` (commitlint), `prepare-commit-msg` (czg/commitizen integration), `pre-commit` (lint-staged / biome), `pre-push` (typecheck + test / turbo)	Always
`release/versionrc`	Write `.versionrc.json` mapping conventional commit types to changelog sections (feat/fix/refactor/perf visible, others hidden)	Always

Code Quality

Task ID	Description	Applicable When
`quality/knip`	Install Knip, write `knip.json` with framework-aware `entry` and `project` paths	Always (JSON format if no TypeScript)
`quality/lint-staged`	Install lint-staged, write `.lintstagedrc.json` running Biome on staged files	Non-Vite+ projects
`quality/package-engines`	Add `devEngines` to `package.json` with Node >=24 and detected package manager version constraint	Always

Code Generation

Task ID	Description	Applicable When
`codegen/plop`	Install Plop, write `plopfile.ts` with framework-specific generators	Framework detected

Monorepo

Task ID	Description	Applicable When
`monorepo/turbo`	Install Turborepo, write `turbo.json` with `pipeline` for build/lint/test	Monorepo detected
`workspace/pnpm-workspace`	Generate `pnpm-workspace.yaml` with `apps/` and `packages/` globs	`packageManager` is `pnpm`

Editor

Task ID	Description	Applicable When
`editor/vscode`	Write/merge `.vscode/settings.json` (Biome formatter, save/on-paste actions, per-framework config) and `.vscode/extensions.json`	Always

Git Hooks

The release/git-hooks task installs husky and generates 4 hooks:

Hook	Action
commit-msg	Runs `commitlint --edit` on the commit message
prepare-commit-msg	Runs `cz --hook` when `czg` or `commitizen` is detected; no-op otherwise
pre-commit	Runs `lint-staged` (or `biome check --write`, or `vp staged` for Vite+ projects)
pre-push	Runs `typecheck` + `test` (or `check:turbo` for Turborepo monorepos)

In Vite+ projects, hooks are written to .vite-hooks/ instead of .husky/.

Changelog Configuration

The release/versionrc task generates .versionrc.json for commit-and-tag-version with:

Visible: feat (Features), fix (Bug Fixes), refactor (Code Refactoring), perf (Performance Improvements)
Hidden: docs, style, test, chore, ci, build, revert

This is separate from the release/cat-version task, which generates a legacy .versionrc file and installs the commit-and-tag-version dependency. The versionrc task can be used standalone or in combination with cat-version.

Additive Extension Merging

When .vscode/extensions.json already exists, xtarterize adds its recommended extensions to your existing recommendations array rather than replacing them. Your custom extensions are always preserved.

devEngines

The quality/package-engines task adds a devEngines field to package.json:

Field	Value
`runtime.name`	`node`
`runtime.version`	`>=24`
`packageManager.name`	Detected package manager
`packageManager.version`	`>=9` (pnpm) or `>=10` (npm, yarn, bun)

Agent

Task ID	Description	Applicable When
`agent/agents-md`	Write `AGENTS.md` with project description and commands	Always
`agent/skills-install`	Install relevant agent skills via `npx skills@latest add` for your stack	TypeScript detected

Skills Install

The agent/skills-install task automatically installs agent skills from the open ecosystem based on your detected stack. It reads your existing skills-lock.json and local skill directories to avoid reinstalling already-present skills.

Stack	Skills Installed
Web Frontend (all browser/edge projects)	`frontend-design`, `web-design-guidelines`, `baseline-ui`, `fixing-accessibility`, `fixing-metadata`, `fixing-motion-performance`
React (including Next.js)	`vercel-react-best-practices`, `vercel-composition-patterns`, `react-dev`, `react-useeffect`
Next.js	`next-best-practices`, `next-cache-components`, `next-upgrade`
Vue	`vue`, `vue-best-practices`
Nuxt	`nuxt`
Expo / React Native	`expo-tailwind-setup`, `expo-cicd-workflows`, `expo-deployment`, `expo-dev-client`, `building-native-ui`, `native-data-fetching`, `expo-module`, `upgrading-expo`, `vercel-react-native-skills`
Shadcn UI	`shadcn`
Ultracite	`ultracite`
Vite	`vite`
Vitest	`vitest`
tsdown	`tsdown`
Turborepo	`turborepo`
Supabase / Postgres	`supabase-postgres-best-practices`
Drizzle	`postgres-drizzle`
Redis	`redis-best-practices`
Better Auth	`better-auth-best-practices`, `create-auth-skill`
AI SDK	`ai-sdk`
Remotion	`remotion-best-practices`

Scripts

Task ID	Description	Applicable When
`scripts/package-scripts`	Patch `package.json` `scripts` with `lint`, `format`, `typecheck`, etc.	Always
`scripts/npmrc`	Write `.npmrc` with `save-exact`, `strict-peer-dependencies`, and `auto-install-peers`	Always

Idempotency

Each task implements check(), dryRun(), and apply():

check() - Returns new, patch, skip, or conflict based on current state
dryRun() - Returns exact diffs without writing anything
apply() - Writes changes, backing up files first

Smart Equivalence Detection

xtarterize doesn’t just check key names - it also detects when an equivalent value already exists under a different key. This prevents redundant entries:

Scenario	Existing	xtarterize Action
Script name alias	`"type:check": "tsc --noEmit"`	Skips adding `"typecheck": "tsc --noEmit"`
Config extends format	`"extends": "config:base"`	Treats same as `"extends": ["config:base"]`
VS Code extensions	`["biomejs.biome"]`	Adds `"ms-vscode.vscode-typescript-next"`, keeps existing

If the exact same command, value, or configuration already exists somewhere, xtarterize skips adding a duplicate.

Task Gating

Tasks only run when their conditions are met:

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

References