Tailwind Canonicalize

https://github.com/xylex-group/tailwind-canonicalize
Admin
Tailwind Canonicalize is a semantic canonicalizer for Tailwind CSS utility classes that safely...
Tokens:20,527
Snippets:354
Trust Score:8.5
License:MIT
Update:2 months ago
Show doc for...
Tokens:
Raw
### Example CLI Output

Source: https://github.com/xylex-group/tailwind-canonicalize/blob/main/apps/docs/docs/cli.mdx

Standard console output summary after running a command.

```text
✓ 1,523 files
✓ 9,421 replacements
! 1 conflicts detected (not rewritten)
  · canonical-class: 9,000
Completed in 1.82s · v0.1.10
```

--------------------------------

### Install dependencies

Source: https://github.com/xylex-group/tailwind-canonicalize/blob/main/docs/guides/oxlint.md

Install tailwind-canonicalize and oxlint as development dependencies.

```bash
pnpm add -D tailwind-canonicalize oxlint
```

--------------------------------

### Configure CI pipeline

Source: https://github.com/xylex-group/tailwind-canonicalize/blob/main/docs/guides/eslint.md

Example CI steps for running checks.

```yaml
- run: pnpm exec tailwind-canonicalize . --check --json
- run: pnpm exec eslint .
```

--------------------------------

### Installation commands

Source: https://github.com/xylex-group/tailwind-canonicalize/blob/main/docs/guides/biome.md

Commands to install tailwind-canonicalize alongside Biome or the Ultracite preset.

```bash
pnpm add -D tailwind-canonicalize @biomejs/biome
# or with Ultracite
pnpm add -D tailwind-canonicalize ultracite @biomejs/biome
```

--------------------------------

### Install dependencies

Source: https://github.com/xylex-group/tailwind-canonicalize/blob/main/docs/guides/eslint.md

Install tailwind-canonicalize and optional Tailwind class helpers.

```bash
pnpm add -D tailwind-canonicalize eslint
# optional Tailwind class helpers (sorting / conflict detection only)
pnpm add -D eslint-plugin-tailwindcss
```

--------------------------------

### Initialize Development Environment

Source: https://github.com/xylex-group/tailwind-canonicalize/blob/main/docs/guides/contributing.md

Commands to install dependencies, build the project, and run the test suite.

```bash
pnpm install
pnpm build
pnpm test
```

--------------------------------

### Development commands

Source: https://github.com/xylex-group/tailwind-canonicalize/blob/main/README.md

Standard commands for installing dependencies, building, testing, and managing the documentation site.

```bash
pnpm install
pnpm build
pnpm test
pnpm benchmark

# Docs site
pnpm docs:dev
pnpm docs:build
pnpm docs:deploy
```

--------------------------------

### Configure CI pipeline

Source: https://github.com/xylex-group/tailwind-canonicalize/blob/main/docs/guides/oxlint.md

Example CI configuration for running canonicalization and linting.

```yaml
- name: Tailwind canonicalize
  run: pnpm exec tailwind-canonicalize . --check --json

- name: Oxlint
  run: pnpm exec oxlint .
```

--------------------------------

### Configure .oxlintrc.json

Source: https://github.com/xylex-group/tailwind-canonicalize/blob/main/docs/guides/oxlint.md

Example configuration for Oxlint, including ignoring the canonicalization cache.

```json
{
  "rules": {
    "correctness/noUnusedVariables": "warn"
  },
  "ignorePatterns": [
    "dist",
    "node_modules",
    ".tailwind-canonicalize-cache.json"
  ]
}
```

--------------------------------

### Configure Nx executors

Source: https://github.com/xylex-group/tailwind-canonicalize/blob/main/docs/guides/eslint.md

Example Nx target configuration for canonicalization and linting.

```json
{
  "targets": {
    "canonicalize": {
      "command": "tailwind-canonicalize src --check",
      "options": { "cwd": "{projectRoot}" }
    },
    "lint": {
      "executor": "@nx/eslint:lint",
      "dependsOn": ["canonicalize"]
    }
  }
}
```

--------------------------------

### Install tailwind-canonicalize

Source: https://github.com/xylex-group/tailwind-canonicalize/blob/main/packages/cli/README.md

Install the package as a development dependency using npm.

```bash
npm i -D tailwind-canonicalize
```

--------------------------------

### Install tailwind-canonicalize

Source: https://github.com/xylex-group/tailwind-canonicalize/blob/main/apps/docs/docs/installation.mdx

Install the package as a development dependency using various package managers.

```package-install
pnpm add -D tailwind-canonicalize
```

```bash
# npm
npm i -D tailwind-canonicalize

# yarn
yarn add -D tailwind-canonicalize
```

--------------------------------

### Install tailwind-canonicalize

Source: https://github.com/xylex-group/tailwind-canonicalize/blob/main/apps/docs/docs/index.mdx

Command to add the package as a development dependency.

```bash
pnpm add -D tailwind-canonicalize
```

--------------------------------

### Configure scripts for Oxlint and Biome

Source: https://github.com/xylex-group/tailwind-canonicalize/blob/main/docs/guides/oxlint.md

Example scripts when using Oxlint, Biome, and tailwind-canonicalize together.

```json
{
  "scripts": {
    "fix": "tailwind-canonicalize . --write --safe && biome check --write .",
    "lint": "oxlint . && biome check .",
    "check": "tailwind-canonicalize . --check && oxlint . && biome ci ."
  }
}
```

--------------------------------

### Configure ESLint flat config

Source: https://github.com/xylex-group/tailwind-canonicalize/blob/main/docs/guides/eslint.md

Basic ESLint 9+ flat configuration setup.

```js
// eslint.config.js
import js from "@eslint/js";
import tseslint from "typescript-eslint";

export default tseslint.config(
  js.configs.recommended,
  ...tseslint.configs.recommended,
  {
    ignores: ["dist/**", "node_modules/**", ".tailwind-canonicalize-cache.json"],
  },
);
```

--------------------------------

### Manifest configuration schema

Source: https://github.com/xylex-group/tailwind-canonicalize/blob/main/docs/guides/tokens.md

Example structure of the token manifest file used for mapping and theme generation.

```json
{
  "version": 1,
  "mappings": [
    {
      "source": "bg-white",
      "target": "bg-background",
      "token": "--color-background"
    }
  ],
  "pairs": [
    {
      "light": "bg-white",
      "dark": "bg-slate-950",
      "target": "bg-background",
      "token": "--color-background",
      "proven": true
    }
  ],
  "recipes": [],
  "generateTheme": {
    "path": "./src/styles/semantic-theme.css",
    "dualTheme": true,
    "preferAppAliases": true
  }
}
```

--------------------------------

### Integration with Linters and Formatters

Source: https://github.com/xylex-group/tailwind-canonicalize/blob/main/docs/guides/cli.md

Example workflow for running canonicalization alongside other tools like Biome, ESLint, or Prettier.

```bash
tailwind-canonicalize . --write --safe
biome check --write .    # or: eslint --fix / prettier --write
tailwind-canonicalize . --check   # CI
```

--------------------------------

### Canonical class rewrite examples

Source: https://github.com/xylex-group/tailwind-canonicalize/blob/main/apps/docs/docs/features/canonical.mdx

Demonstrates how arbitrary values are mapped to theme scale keys while preserving variants and modifiers.

```tsx
max-w-[160px]        → max-w-40
hover:md:w-[40px]!   → hover:md:w-10!
rounded-[8px]        → rounded-lg
text-[16px]          → text-base
```

--------------------------------

### Ultracite script configuration

Source: https://github.com/xylex-group/tailwind-canonicalize/blob/main/docs/guides/biome.md

Example package.json scripts for integrating tailwind-canonicalize with the Ultracite preset.

```json
{
  "scripts": {
    "canonicalize": "tailwind-canonicalize . --write --safe",
    "canonicalize:check": "tailwind-canonicalize . --check",
    "lint": "ultracite check",
    "fix": "tailwind-canonicalize . --write --safe && ultracite fix",
    "check": "tailwind-canonicalize . --check && ultracite check"
  }
}
```

--------------------------------

### Enable watch mode

Source: https://github.com/xylex-group/tailwind-canonicalize/blob/main/docs/guides/performance.md

Starts a persistent process that watches for file changes with a 150ms debounce.

```bash
tailwind-canonicalize . --watch --write
```

--------------------------------

### Pre-commit Hook Configuration

Source: https://github.com/xylex-group/tailwind-canonicalize/blob/main/docs/guides/ci.md

Example shell script for a pre-commit hook using lint-staged.

```sh
#!/usr/bin/env sh
pnpm exec lint-staged
```

--------------------------------

### Configure lint-staged

Source: https://github.com/xylex-group/tailwind-canonicalize/blob/main/apps/docs/docs/integrations/index.mdx

Example configuration for lint-staged to run tailwind-canonicalize alongside Biome on staged files.

```json
{
  "*.{js,jsx,ts,tsx,vue,astro,html,mdx}": [
    "tailwind-canonicalize --write",
    "biome check --write --no-errors-on-unmatched"
  ]
}
```

--------------------------------

### Verify Tailwind compilation

Source: https://github.com/xylex-group/tailwind-canonicalize/blob/main/apps/docs/docs/installation.mdx

Install Tailwind CSS as a peer dependency and run strict compilation verification.

```package-install
pnpm add -D tailwindcss
```

```bash
pnpm exec tailwind-canonicalize . --strict-compile --write
```

--------------------------------

### Recipe-based utility mapping

Source: https://github.com/xylex-group/tailwind-canonicalize/blob/main/docs/guides/tokens.md

Example of mapping co-occurring color utilities to a coherent semantic recipe.

```tsx
// sources present together
bg-amber-200 border-amber-200 text-slate-800
// →
bg-warning-subtle border-warning-subtle text-warning-foreground
```

--------------------------------

### Doctor Log Output

Source: https://github.com/xylex-group/tailwind-canonicalize/blob/main/docs/audits/2026-08-01-xbp-cloudflare-docs-deploy.md

Example of misleading root path resolution in the doctor log.

```text
[docs] resolved app=tailwind-canonicalize-docs script=… root=apps/docs
…
worker_app=docs root=C:\Users\floris\Documents\GitHub\tailwind-canonicalize\docs
```

--------------------------------

### Canonicalize Tailwind utility classes

Source: https://github.com/xylex-group/tailwind-canonicalize/blob/main/apps/docs/docs/index.mdx

Example showing the transformation of arbitrary utility values into theme-defined tokens.

```tsx
// before
<div className="w-[40px] min-w-[10rem] h-[10px] p-[16px] gap-[8px]" />

// after
<div className="w-10 min-w-40 h-2.5 p-4 gap-2" />
```

--------------------------------

### Ideal XBP Cloudflare Deployment Commands

Source: https://github.com/xylex-group/tailwind-canonicalize/blob/main/docs/audits/2026-08-01-xbp-cloudflare-docs-deploy.md

Recommended one-shot commands for bootstrapping and deploying static documentation to Cloudflare via XBP.

```text
xbp cloudflare bootstrap-static \
  --app tailwind-canonicalize-docs \
  --root apps/docs \
  --assets dist \
  --domain tailwind-canonicalize.xbp.app \
  --build "pnpm run build" \
  --write --deploy --yes
```

```text
xbp deploy docs --to cloudflare --run --yes
```

--------------------------------

### Display Help

Source: https://github.com/xylex-group/tailwind-canonicalize/blob/main/apps/docs/docs/cli.mdx

Prints the full flag reference for the CLI.

```bash
tailwind-canonicalize --help
```

--------------------------------

### View CLI help

Source: https://github.com/xylex-group/tailwind-canonicalize/blob/main/README.md

Display the help menu for the CLI tool.

```bash
npx tailwind-canonicalize --help
```

--------------------------------

### Run project lifecycle commands

Source: https://github.com/xylex-group/tailwind-canonicalize/blob/main/AGENTS.md

Use these commands to execute linting, formatting, testing, and build processes.

```bash
pnpm check   # biome / ultracite when wired
pnpm fix
pnpm test
pnpm build
```

--------------------------------

### CLI Usage Patterns

Source: https://github.com/xylex-group/tailwind-canonicalize/blob/main/apps/docs/docs/cli.mdx

Basic command syntax for running the tool, analyzing tokens, and applying manifests.

```bash
tailwind-canonicalize [paths...] [options]
tailwind-canonicalize tokens analyze [paths...] [--out manifest.json]
tailwind-canonicalize tokens apply <manifest.json> [paths...] [--write]
```

--------------------------------

### Run CLI for Project Canonicalization

Source: https://github.com/xylex-group/tailwind-canonicalize/blob/main/README.md

Recommended command-line usage for applying semantic class rewrites before running other formatters.

```bash
tailwind-canonicalize . --write --safe   # semantic class rewrites
biome check --write .                    # or ultracite fix / eslint --fix
```

--------------------------------

### Basic CLI Syntax

Source: https://github.com/xylex-group/tailwind-canonicalize/blob/main/docs/guides/cli.md

The standard command structure for invoking the tool.

```bash
tailwind-canonicalize [paths...] [options]
```

--------------------------------

### Run benchmarks

Source: https://github.com/xylex-group/tailwind-canonicalize/blob/main/docs/guides/benchmarks.md

Execute the project benchmark suite using the pnpm package manager.

```bash
pnpm benchmark
```

--------------------------------

### Execute tools via CLI

Source: https://github.com/xylex-group/tailwind-canonicalize/blob/main/docs/guides/prettier.md

Run canonicalize and Prettier using pnpm exec for project-level formatting.

```bash
pnpm exec tailwind-canonicalize . --write --safe
pnpm exec prettier --write .
```

--------------------------------

### Tailwind Class Migration Mapping

Source: https://github.com/xylex-group/tailwind-canonicalize/blob/main/apps/docs/docs/features/migrations.mdx

Examples of class transformations from Tailwind v3 to v4 syntax.

```tsx
bg-gradient-to-br          → bg-linear-to-br
hover:bg-gradient-to-br    → hover:bg-linear-to-br
dark:md:bg-gradient-to-br  → dark:md:bg-linear-to-br
bg-gradient-to-br!         → bg-linear-to-br!
```

--------------------------------

### Reuse existing CSS tokens

Source: https://github.com/xylex-group/tailwind-canonicalize/blob/main/docs/guides/tokens.md

Example of referencing an existing CSS variable within the @theme block.

```css
@theme {
  --color-warning-subtle: var(--warning-subtle);
}
```

--------------------------------

### Recommended Pipeline Order

Source: https://github.com/xylex-group/tailwind-canonicalize/blob/main/docs/README.md

The suggested sequence for running canonicalization, linting, and testing in CI or git hooks.

```text
1. tailwind-canonicalize --write   # semantic (class contents)
2. biome check --write / ultracite fix   # format + lint autofix
   OR eslint --fix / oxlint
3. typecheck / tests
```

--------------------------------

### Project Directory Structure

Source: https://github.com/xylex-group/tailwind-canonicalize/blob/main/docs/guides/contributing.md

Overview of the core packages and top-level directories in the repository.

```text
packages/parser|resolver|transformer|compiler|cli|vscode|tokens
tests/ fixtures/ benchmarks/ docs/ action/
```

--------------------------------

### Analyze and apply semantic tokens

Source: https://github.com/xylex-group/tailwind-canonicalize/blob/main/docs/architecture/transformations.md

Commands to analyze the project for semantic tokens and apply the approved manifest.

```bash
tailwind-canonicalize tokens analyze .
# review proposed manifest
tailwind-canonicalize tokens apply tailwind-tokens.json --write
```

--------------------------------

### Dark mode token pair

Source: https://github.com/xylex-group/tailwind-canonicalize/blob/main/apps/docs/docs/features/tokens.mdx

Example of mapping a dual-theme utility pair to a single semantic token.

```tsx
bg-white dark:bg-slate-950  →  bg-background
```

--------------------------------

### Analyze project color utilities

Source: https://github.com/xylex-group/tailwind-canonicalize/blob/main/docs/guides/tokens.md

Scans the project for color utilities and generates a proposal manifest for semantic migration.

```bash
tailwind-canonicalize tokens analyze . --out tailwind-tokens.proposed.json
```

--------------------------------

### Define theme CSS variables

Source: https://github.com/xylex-group/tailwind-canonicalize/blob/main/docs/guides/tokens.md

Example of defining CSS variables for semantic tokens within a Tailwind v4 theme context.

```css
:root { --app-background: #ffffff; }
.dark { --app-background: #020617; }
@theme inline {
  --color-background: var(--app-background);
}
```

--------------------------------

### Standard package.json template

Source: https://github.com/xylex-group/tailwind-canonicalize/blob/main/docs/guides/biome.md

Recommended scripts for a project using tailwind-canonicalize and Biome.

```json
{
  "scripts": {
    "canonicalize": "tailwind-canonicalize . --write --safe",
    "canonicalize:check": "tailwind-canonicalize . --check --json",
    "lint": "biome check .",
    "lint:fix": "biome check --write .",
    "format": "biome format --write .",
    "fix": "pnpm canonicalize && pnpm lint:fix",
    "check": "pnpm canonicalize:check && pnpm lint && pnpm typecheck"
  }
}
```

--------------------------------

### Workflow execution order

Source: https://github.com/xylex-group/tailwind-canonicalize/blob/main/apps/docs/docs/integrations/index.mdx

The recommended sequence for running canonicalization, linting, and testing tools.

```text
1. tailwind-canonicalize --write/--check
2. biome | eslint | oxlint | prettier
3. typecheck / tests
```

--------------------------------

### Apply token mappings

Source: https://github.com/xylex-group/tailwind-canonicalize/blob/main/apps/docs/docs/features/tokens.mdx

Applies explicit mappings, pairs, and recipes from the manifest to the source code.

```bash
pnpm exec tailwind-canonicalize tokens apply tailwind-tokens.json --write
```

--------------------------------

### Execute one-shot deployment

Source: https://github.com/xylex-group/tailwind-canonicalize/blob/main/docs/audits/2026-08-01-xbp-cloudflare-docs-deploy.md

Command to trigger a full deployment cycle including doctor, build, wrangler, and health probe steps.

```powershell
$env:CLOUDFLARE_ACCOUNT_ID = "a196ad9f98b8a2883f87e0d2d56ec3d5"  # if not already in xbp config
xbp deploy docs --to cloudflare --run --yes --env production
```

--------------------------------

### Build VS Code Extension

Source: https://github.com/xylex-group/tailwind-canonicalize/blob/main/docs/guides/editors.md

Command to build the VS Code extension locally from the workspace.

```bash
pnpm --filter tailwind-canonicalize-vscode build
```

--------------------------------

### Configure package.json scripts

Source: https://github.com/xylex-group/tailwind-canonicalize/blob/main/docs/guides/integrations.md

Standard script definitions for running canonicalization and linting tasks.

```json
{
  "scripts": {
    "canonicalize": "tailwind-canonicalize . --write --safe",
    "canonicalize:check": "tailwind-canonicalize . --check --json",
    "lint": "biome check .",
    "lint:fix": "biome check --write .",
    "check": "pnpm canonicalize:check && pnpm lint && pnpm typecheck",
    "fix": "pnpm canonicalize && pnpm lint:fix"
  }
}
```

--------------------------------

### Run migrations with Biome

Source: https://github.com/xylex-group/tailwind-canonicalize/blob/main/docs/guides/biome.md

Perform Tailwind version migrations followed by a Biome check to reformat class strings.

```bash
pnpm exec tailwind-canonicalize . --migrate --from-tailwind 3 --to-tailwind 4 --write
pnpm exec biome check --write .
```

--------------------------------

### Configure wrangler.jsonc for assets

Source: https://github.com/xylex-group/tailwind-canonicalize/blob/main/docs/audits/2026-08-01-xbp-cloudflare-docs-deploy.md

Minimum required configuration for deploying static assets to Cloudflare via Wrangler.

```jsonc
{
  "name": "tailwind-canonicalize-docs",
  "compatibility_date": "2026-06-21",
  "workers_dev": true,
  "assets": {
    "directory": "./dist",
    "not_found_handling": "404-page",
    "html_handling": "auto-trailing-slash"
  },
  "routes": [
    { "pattern": "tailwind-canonicalize.xbp.app", "custom_domain": true }
  ]
}
```

--------------------------------

### Full Quality Gate Workflow

Source: https://github.com/xylex-group/tailwind-canonicalize/blob/main/docs/guides/ci.md

A comprehensive CI workflow combining Tailwind Canonicalize with Biome, type checking, and tests.

```yaml
name: quality
on:
  pull_request:
  push:
    branches: [main]

jobs:
  quality:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: pnpm/action-setup@v4
        with:
          version: 9
      - uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: pnpm
      - run: pnpm install

      - name: Tailwind canonicalize
        run: pnpm exec tailwind-canonicalize . --check --json --safe

      - name: Biome
        run: pnpm exec biome ci .

      - name: Typecheck
        run: pnpm typecheck

      - name: Test
        run: pnpm test
```

--------------------------------

### Define recommended pipeline

Source: https://github.com/xylex-group/tailwind-canonicalize/blob/main/docs/guides/oxlint.md

Recommended order of operations for linting and canonicalization.

```text
1. tailwind-canonicalize --write / --check
2. oxlint .
3. tsc --noEmit
```

--------------------------------

### Verify Idempotence

Source: https://github.com/xylex-group/tailwind-canonicalize/blob/main/apps/docs/docs/safety.mdx

Demonstrates that running the command multiple times results in zero changes.

```bash
tailwind-canonicalize . --write
tailwind-canonicalize . --write   # zero changes
```

--------------------------------

### Deployment Command Variants

Source: https://github.com/xylex-group/tailwind-canonicalize/blob/main/docs/audits/2026-08-01-xbp-cloudflare-docs-deploy.md

Multiple valid CLI commands for deploying to Cloudflare after scaffolding.

```text
xbp deploy docs --to cloudflare --run --yes
xbp cloudflare workers --app tailwind-canonicalize-docs deploy run
pnpm --filter docs run deploy
```

--------------------------------

### Run Tailwind Migrations via CLI

Source: https://github.com/xylex-group/tailwind-canonicalize/blob/main/apps/docs/docs/features/migrations.mdx

Execute migration commands to update Tailwind classes in the project directory.

```bash
pnpm exec tailwind-canonicalize . --migrate --from-tailwind 3 --to-tailwind 4 --write
pnpm exec tailwind-canonicalize . --migrations-only --write
```

--------------------------------

### Generate style usage report

Source: https://github.com/xylex-group/tailwind-canonicalize/blob/main/apps/docs/docs/features/tokens.mdx

Inventories all color utilities and generates a comprehensive report in JSON and Markdown formats.

```bash
tailwind-canonicalize tokens report . -o styles-report.json --md styles.md
```

--------------------------------

### Configure package.json scripts

Source: https://github.com/xylex-group/tailwind-canonicalize/blob/main/docs/guides/eslint.md

Define scripts for running canonicalization and linting tasks.

```json
{
  "scripts": {
    "canonicalize": "tailwind-canonicalize . --write --safe",
    "canonicalize:check": "tailwind-canonicalize . --check",
    "lint": "eslint .",
    "lint:fix": "eslint . --fix",
    "fix": "pnpm canonicalize && pnpm lint:fix",
    "check": "pnpm canonicalize:check && pnpm lint"
  }
}
```

--------------------------------

### Define configuration

Source: https://github.com/xylex-group/tailwind-canonicalize/blob/main/apps/docs/docs/api.mdx

Configure the library behavior using the defineConfig helper.

```ts
import { defineConfig } from "tailwind-canonicalize";

export default defineConfig({
  tailwind: { version: 4 },
  canonicalize: { arbitraryValues: true },
});
```

--------------------------------

### Configure package.json scripts

Source: https://github.com/xylex-group/tailwind-canonicalize/blob/main/docs/guides/oxlint.md

Define scripts for running canonicalization and linting tasks.

```json
{
  "scripts": {
    "canonicalize": "tailwind-canonicalize . --write --safe",
    "canonicalize:check": "tailwind-canonicalize . --check",
    "lint": "oxlint .",
    "fix": "pnpm canonicalize",
    "check": "pnpm canonicalize:check && pnpm lint"
  }
}
```

--------------------------------

### Configure linting script in package.json

Source: https://github.com/xylex-group/tailwind-canonicalize/blob/main/apps/docs/docs/integrations/oxlint.mdx

Add a check script to run both tailwind-canonicalize and oxlint sequentially.

```json
{
  "scripts": {
    "check": "tailwind-canonicalize . --check && oxlint ."
  }
}
```

--------------------------------

### Run and inspect canonicalization in CI

Source: https://github.com/xylex-group/tailwind-canonicalize/blob/main/apps/docs/docs/troubleshooting.mdx

Use these commands to execute canonicalization or inspect potential changes during CI processes.

```bash
pnpm exec tailwind-canonicalize . --write --safe
# or inspect
pnpm exec tailwind-canonicalize . --check --verbose --diff
```

--------------------------------

### Run performance optimization commands

Source: https://github.com/xylex-group/tailwind-canonicalize/blob/main/apps/docs/docs/features/performance.mdx

Execute CLI commands to enable incremental hashing, worker threads, or watch mode for tailwind-canonicalize.

```bash
# Incremental hashing
pnpm exec tailwind-canonicalize . --incremental --write

# Worker threads (auto when many files)
pnpm exec tailwind-canonicalize . --workers --concurrency 16

# Watch
pnpm exec tailwind-canonicalize . --watch --write
```

--------------------------------

### Configure lint-staged

Source: https://github.com/xylex-group/tailwind-canonicalize/blob/main/docs/guides/eslint.md

Integrate canonicalization and linting into pre-commit hooks.

```json
{
  "*.{js,jsx,ts,tsx,mjs,cjs,vue}": [
    "tailwind-canonicalize --write",
    "eslint --fix --max-warnings=0"
  ]
}
```

--------------------------------

### Configure lint-staged

Source: https://github.com/xylex-group/tailwind-canonicalize/blob/main/docs/guides/oxlint.md

Integrate canonicalization and linting into pre-commit hooks.

```json
{
  "*.{js,jsx,ts,tsx,mjs,cjs}": [
    "tailwind-canonicalize --write",
    "oxlint"
  ]
}
```

--------------------------------

### loadProjectTheme

Source: https://github.com/xylex-group/tailwind-canonicalize/blob/main/apps/docs/docs/api.mdx

Loads the Tailwind project theme configuration.

```APIDOC
## loadProjectTheme(cwd: string)

### Description
Loads the theme and source type for a project located at the given directory path.
```

--------------------------------

### tokens apply <manifest.json> [paths...]

Source: https://github.com/xylex-group/tailwind-canonicalize/blob/main/apps/docs/docs/cli.mdx

Applies approved mappings from a manifest file to the specified paths.

```APIDOC
## tokens apply <manifest.json> [paths...]

### Description
Applies approved color mappings and optional theme CSS from a manifest file. 

### Options
- **--write** (flag) - Required to persist changes to disk.
```

--------------------------------

### Configure GitHub Actions for Tailwind canonicalize

Source: https://github.com/xylex-group/tailwind-canonicalize/blob/main/apps/docs/docs/integrations/ci.mdx

Run the canonicalize check and Biome CI as part of a GitHub Actions workflow.

```yaml
- name: Tailwind canonicalize
  run: pnpm exec tailwind-canonicalize . --check --json --safe

- name: Biome
  run: pnpm exec biome ci .
```

--------------------------------

### Load project theme

Source: https://github.com/xylex-group/tailwind-canonicalize/blob/main/apps/docs/docs/api.mdx

Load the Tailwind theme configuration from the current working directory.

```ts
const { theme, source } = await loadProjectTheme(process.cwd());
// source: "css" | "v3-config" | "default"
```

--------------------------------

### Run canonicalize CLI

Source: https://github.com/xylex-group/tailwind-canonicalize/blob/main/apps/docs/docs/installation.mdx

Execute the tool to check for issues or apply safe rewrites to the project.

```bash
# Report only
pnpm exec tailwind-canonicalize . --check

# Apply safe rewrites
pnpm exec tailwind-canonicalize . --write --safe
```

--------------------------------

### Run CLI commands

Source: https://github.com/xylex-group/tailwind-canonicalize/blob/main/README.md

Execute scanning, writing, or CI checking operations on the current directory.

```bash
# scan (report)
tailwind-canonicalize .

# write changes (safe mode — exact only)
tailwind-canonicalize . --write --safe

# CI gate
tailwind-canonicalize . --check
```

--------------------------------

### Execute Tailwind migration CLI commands

Source: https://github.com/xylex-group/tailwind-canonicalize/blob/main/docs/guides/migrations.md

Commands to run migrations, specify version ranges, or perform write operations.

```bash
tailwind-canonicalize . --migrate
tailwind-canonicalize . --from-tailwind 3 --to-tailwind 4 --write
tailwind-canonicalize . --migrations-only --write
```

--------------------------------

### Define execution order

Source: https://github.com/xylex-group/tailwind-canonicalize/blob/main/docs/guides/prettier.md

The recommended sequence for running tools to ensure canonicalization occurs before Prettier formatting.

```text
tailwind-canonicalize --write
→ prettier --write
```

--------------------------------

### Analyze tokens

Source: https://github.com/xylex-group/tailwind-canonicalize/blob/main/apps/docs/docs/features/tokens.mdx

Generates a proposal file containing conflicts, duplicates, and cycles without modifying source files.

```bash
pnpm exec tailwind-canonicalize tokens analyze . --out proposed.json
```

--------------------------------

### Configure package.json scripts

Source: https://github.com/xylex-group/tailwind-canonicalize/blob/main/apps/docs/docs/installation.mdx

Add canonicalize commands to the scripts section of your package.json for easier execution.

```json
{
  "scripts": {
    "canonicalize": "tailwind-canonicalize . --write --safe",
    "canonicalize:check": "tailwind-canonicalize . --check --json"
  }
}
```

--------------------------------

### Automate Canonicalization in Neovim

Source: https://github.com/xylex-group/tailwind-canonicalize/blob/main/docs/guides/editors.md

Autocmd configuration to run the canonicalize command on file save for specific web component file types.

```lua
-- run on save for TSX (example)
vim.api.nvim_create_autocmd("BufWritePost", {
  pattern = { "*.tsx", "*.jsx", "*.vue", "*.astro" },
  callback = function(args)
    vim.fn.jobstart({
      "pnpm", "exec", "tailwind-canonicalize", args.file, "--write", "--safe",
    }, { detach = true })
  end,
})
```

--------------------------------

### Generate Changeset

Source: https://github.com/xylex-group/tailwind-canonicalize/blob/main/docs/guides/contributing.md

Command to initiate a new changeset for versioning and release management.

```bash
pnpm changeset
```

--------------------------------

### Configure Biome scripts in package.json

Source: https://github.com/xylex-group/tailwind-canonicalize/blob/main/apps/docs/docs/integrations/biome.mdx

Add these scripts to your package.json to run Tailwind Canonicalize followed by Biome.

```json
{
  "scripts": {
    "fix": "tailwind-canonicalize . --write --safe && biome check --write .",
    "check": "tailwind-canonicalize . --check && biome ci ."
  }
}
```

--------------------------------

### Cloudflare Worker Deployment CLI Commands

Source: https://github.com/xylex-group/tailwind-canonicalize/blob/main/docs/audits/2026-08-01-xbp-cloudflare-docs-deploy.md

Commands used to trigger the deployment, highlighting the correct placement of the --app flag.

```text
xbp cloudflare workers deploy run --app tailwind-canonicalize-docs
```

```text
xbp cloudflare workers --app tailwind-canonicalize-docs deploy run
```

```text
xbp cloudflare workers --app tailwind-canonicalize-docs deploy run
```

```text
xbp deploy docs --to cloudflare --run --yes --env production
```

--------------------------------

### Define target architecture structure

Source: https://github.com/xylex-group/tailwind-canonicalize/blob/main/docs/audits/2026-08-01-xbp-cloudflare-docs-deploy.md

Directory and configuration file layout for XBP services targeting Cloudflare.

```text
apps/docs/
  wrangler.jsonc          # name, assets → dist, routes custom_domain
  package.json            # build, deploy, deploy:worker
  dist/                   # blume build output (gitignored)

.xbp/xbp.toml
  [[services]] name = "docs"
    deploy.provider = "cloudflare-worker"
    destinations.cloudflare.script_name / health_urls
  [[workers]]
    name / root / script_name / service = "docs"
```

--------------------------------

### GitHub Actions workflow steps

Source: https://github.com/xylex-group/tailwind-canonicalize/blob/main/docs/guides/biome.md

Execute canonicalization followed by Biome CI checks in a GitHub Actions pipeline.

```yaml
- name: Tailwind canonicalize
  run: pnpm exec tailwind-canonicalize . --check --json

- name: Biome
  run: pnpm exec biome ci .
```

--------------------------------

### Run canonicalize with pnpm filter

Source: https://github.com/xylex-group/tailwind-canonicalize/blob/main/docs/guides/integrations.md

Execute the tool on a specific workspace package.

```bash
pnpm --filter web exec tailwind-canonicalize src --check
```

--------------------------------

### Run tailwind-canonicalize and Prettier

Source: https://github.com/xylex-group/tailwind-canonicalize/blob/main/apps/docs/docs/integrations/prettier.mdx

Execute the canonicalize command followed by the Prettier command to ensure both semantic rewriting and class sorting are applied.

```bash
tailwind-canonicalize . --write --safe
prettier --write .
```

--------------------------------

### Use Public API for Class Canonicalization

Source: https://github.com/xylex-group/tailwind-canonicalize/blob/main/README.md

Demonstrates importing and using core functions to canonicalize individual classes or entire projects.

```ts
import {
  canonicalizeClass,
  canonicalizeClasses,
  canonicalizeFile,
  canonicalizeProject,
  canonicalizeSource,
  findCanonicalEquivalent,
  loadThemeFromCss,
  loadThemeFromProject,
} from "tailwind-canonicalize";

canonicalizeClass("w-[40px]"); // "w-10"
canonicalizeClass("w-[140px]"); // "w-35" (continuous --spacing multiplier)
findCanonicalEquivalent("w-[10vh]"); // null

const summary = await canonicalizeProject({
  paths: ["src"],
  write: true,
});
```

--------------------------------

### Configure lint-staged

Source: https://github.com/xylex-group/tailwind-canonicalize/blob/main/docs/guides/prettier.md

Integrate canonicalize and Prettier into lint-staged to process files before commits.

```json
{
  "*.{js,jsx,ts,tsx,vue,astro,html,mdx,css,md,json}": [
    "tailwind-canonicalize --write",
    "prettier --write"
  ]
}
```

```json
{
  "*.{js,jsx,ts,tsx,vue,astro,html,mdx}": [
    "tailwind-canonicalize --write",
    "prettier --write"
  ],
  "*.{css,md,json,yml}": [
    "prettier --write"
  ]
}
```

--------------------------------

### Apply approved semantic mappings

Source: https://github.com/xylex-group/tailwind-canonicalize/blob/main/docs/guides/tokens.md

Applies approved mappings, pairs, and recipes from the manifest to the source code.

```bash
tailwind-canonicalize tokens apply tailwind-tokens.json --write
```

--------------------------------

### Use stdin for Editor Formatting

Source: https://github.com/xylex-group/tailwind-canonicalize/blob/main/docs/guides/integrations.md

Pipe buffer text to the CLI for editor integration, where stdout returns the rewritten source.

```bash
tailwind-canonicalize --stdin < %file%
```

--------------------------------

### Configure VS Code for Biome formatting

Source: https://github.com/xylex-group/tailwind-canonicalize/blob/main/docs/guides/biome.md

Sets Biome as the default formatter and enables automatic formatting and code actions on save.

```json
{
  "editor.defaultFormatter": "biomejs.biome",
  "editor.formatOnSave": true,
  "editor.codeActionsOnSave": {
    "source.organizeImports.biome": "explicit",
    "source.fixAll.biome": "explicit"
  }
}
```

--------------------------------

### Run monorepo CI jobs

Source: https://github.com/xylex-group/tailwind-canonicalize/blob/main/docs/guides/oxlint.md

Execute linting and canonicalization in parallel for large monorepos.

```bash
# CI job A — fast lint
pnpm exec oxlint apps packages

# CI job B — semantic gate (can use workers)
pnpm exec tailwind-canonicalize apps packages --check --workers --incremental
```

--------------------------------

### Importing API functions

Source: https://github.com/xylex-group/tailwind-canonicalize/blob/main/apps/docs/docs/api.mdx

Import the core utilities from the tailwind-canonicalize package.

```ts
import {
  canonicalizeClass,
  canonicalizeClasses,
  canonicalizeFile,
  canonicalizeProject,
  canonicalizeSource,
  findCanonicalEquivalent,
  defineConfig,
  createDefaultTheme,
  loadProjectTheme,
  createTailwindCompileEqual,
  watchProject,
} from "tailwind-canonicalize";
```

--------------------------------

### Run lint-staged in pre-commit

Source: https://github.com/xylex-group/tailwind-canonicalize/blob/main/apps/docs/docs/integrations/ci.mdx

Execute lint-staged via pnpm to trigger canonicalization during pre-commit hooks.

```sh
pnpm exec lint-staged
```

--------------------------------

### Configure Nx targets

Source: https://github.com/xylex-group/tailwind-canonicalize/blob/main/docs/guides/integrations.md

Define canonicalization targets for Nx projects.

```json
{
  "targets": {
    "canonicalize": {
      "command": "tailwind-canonicalize src --check",
      "options": { "cwd": "{projectRoot}" }
    }
  }
}
```

--------------------------------

### CI Reproduction and Fix Commands

Source: https://github.com/xylex-group/tailwind-canonicalize/blob/main/docs/guides/ci.md

Commands for developers to reproduce CI failures locally and apply fixes.

```bash
# Developers reproduce CI
pnpm exec tailwind-canonicalize . --check --verbose --diff
# Apply
pnpm exec tailwind-canonicalize . --write --safe
```

--------------------------------

### Configure lint-staged for pre-commit hooks

Source: https://github.com/xylex-group/tailwind-canonicalize/blob/main/apps/docs/docs/integrations/eslint.mdx

Use this configuration in lint-staged to automatically run canonicalization and linting on staged files before committing.

```json
{
  "*.{js,jsx,ts,tsx}": [
    "tailwind-canonicalize --write",
    "eslint --fix --max-warnings=0"
  ]
}
```

--------------------------------

### Configure Biome in VS Code

Source: https://github.com/xylex-group/tailwind-canonicalize/blob/main/docs/guides/editors.md

Settings to enable Biome as the default formatter and enable code actions on save.

```json
// .vscode/settings.json
{
  "editor.defaultFormatter": "biomejs.biome",
  "editor.formatOnSave": true,
  "editor.codeActionsOnSave": {
    "source.organizeImports.biome": "explicit",
    "source.fixAll.biome": "explicit"
  }
}
```

--------------------------------

### Run tailwind-canonicalize CLI

Source: https://github.com/xylex-group/tailwind-canonicalize/blob/main/packages/cli/README.md

Execute the canonicalizer on the current directory with various flags for writing changes or checking status.

```bash
npx tailwind-canonicalize .
npx tailwind-canonicalize . --write --safe
npx tailwind-canonicalize . --check
```

--------------------------------

### Configure lint-staged

Source: https://github.com/xylex-group/tailwind-canonicalize/blob/main/docs/guides/integrations.md

Automate canonicalization on staged files before commits.

```json
{
  "*.{js,jsx,ts,tsx,mjs,cjs,vue,astro,svelte,html,mdx}": [
    "tailwind-canonicalize --write",
    "biome check --write --no-errors-on-unmatched"
  ]
}
```

--------------------------------

### Configure Ultracite scripts in package.json

Source: https://github.com/xylex-group/tailwind-canonicalize/blob/main/apps/docs/docs/integrations/biome.mdx

Use these scripts when integrating Tailwind Canonicalize with Ultracite.

```json
{
  "scripts": {
    "fix": "tailwind-canonicalize . --write --safe && ultracite fix",
    "check": "tailwind-canonicalize . --check && ultracite check"
  }
}
```

--------------------------------

### Apply semantic tokens

Source: https://github.com/xylex-group/tailwind-canonicalize/blob/main/apps/docs/docs/examples.mdx

Analyzes and applies approved semantic token mappings to replace hardcoded color values.

```bash
pnpm exec tailwind-canonicalize tokens analyze .
# review proposed.json → save as tailwind-tokens.json
pnpm exec tailwind-canonicalize tokens apply tailwind-tokens.json --write
```

```tsx
// before
<div className="bg-white text-slate-800 border-slate-200" />

// after
<div className="bg-background text-foreground border-border" />
```

--------------------------------

### Configure Lefthook

Source: https://github.com/xylex-group/tailwind-canonicalize/blob/main/docs/guides/integrations.md

Define canonicalization and linting commands within lefthook.yml.

```yaml
# lefthook.yml
pre-commit:
  commands:
    canonicalize:
      glob: "*.{js,jsx,ts,tsx,vue,astro,html,mdx}"
      run: pnpm exec tailwind-canonicalize {staged_files} --write
    biome:
      glob: "*.{js,jsx,ts,tsx,json,jsonc}"
      run: pnpm exec biome check --write --no-errors-on-unmatched {staged_files}
```

--------------------------------

### tokens analyze [paths...]

Source: https://github.com/xylex-group/tailwind-canonicalize/blob/main/apps/docs/docs/cli.mdx

Analyzes files to propose semantic color mappings without modifying files.

```APIDOC
## tokens analyze [paths...]

### Description
Proposes semantic color mappings based on the provided paths. This command is read-only and does not perform any file writes.
```

--------------------------------

### tokens report [paths...]

Source: https://github.com/xylex-group/tailwind-canonicalize/blob/main/apps/docs/docs/cli.mdx

Generates a style usage report including color frequency, health, and CSS theme scans.

```APIDOC
## tokens report [paths...]

### Description
Generates a comprehensive style usage report. Supports outputting to JSON or Markdown formats using the report flag.
```

--------------------------------

### Enable incremental hashing

Source: https://github.com/xylex-group/tailwind-canonicalize/blob/main/docs/guides/performance.md

Uses a SHA-256 hash to cache processed files and skip unchanged ones.

```bash
tailwind-canonicalize . --incremental --write
```

--------------------------------

### Run tailwind-canonicalize CLI

Source: https://github.com/xylex-group/tailwind-canonicalize/blob/main/apps/docs/docs/index.mdx

Commands for writing changes to files or checking for potential canonicalization.

```bash
pnpm exec tailwind-canonicalize . --write --safe
pnpm exec tailwind-canonicalize . --check
```

--------------------------------

### Use Stdin Mode

Source: https://github.com/xylex-group/tailwind-canonicalize/blob/main/docs/guides/editors.md

Command to process Tailwind classes via standard input, useful for custom editor bridges.

```bash
tailwind-canonicalize --stdin < Component.tsx > Component.out.tsx
```

--------------------------------

### Load theme and canonicalize classes

Source: https://github.com/xylex-group/tailwind-canonicalize/blob/main/README.md

Uses loadThemeFromProject to discover CSS tokens and canonicalizeClass to map arbitrary values to theme-defined aliases.

```ts
import { loadThemeFromProject, canonicalizeClass } from "tailwind-canonicalize";

const { theme } = await loadThemeFromProject(process.cwd());
canonicalizeClass("text-[#ff0000]", { theme }); // "text-brand" if defined
```

--------------------------------

### CI execution

Source: https://github.com/xylex-group/tailwind-canonicalize/blob/main/docs/guides/biome.md

Commands for running checks in a CI environment.

```bash
pnpm exec tailwind-canonicalize . --check
pnpm exec biome ci .
# or
pnpm exec ultracite check
```

--------------------------------

### ESLint and Oxlint Matrix Integration

Source: https://github.com/xylex-group/tailwind-canonicalize/blob/main/docs/guides/ci.md

Steps to include Tailwind Canonicalize alongside Oxlint and ESLint in a CI job.

```yaml
      - name: Tailwind canonicalize
        run: pnpm exec tailwind-canonicalize src --check --workers

      - name: Oxlint
        run: pnpm exec oxlint .

      - name: ESLint
        run: pnpm exec eslint .
```

--------------------------------

### Canonicalize project

Source: https://github.com/xylex-group/tailwind-canonicalize/blob/main/apps/docs/docs/api.mdx

Run canonicalization across a project directory with configurable performance and safety modes.

```ts
const summary = await canonicalizeProject({
  paths: ["src"],
  write: true,
  mode: "safe",
  incremental: true,
  workers: "auto",
});
```

--------------------------------

### Configure package.json scripts for linting

Source: https://github.com/xylex-group/tailwind-canonicalize/blob/main/apps/docs/docs/integrations/eslint.mdx

Add these scripts to your package.json to run tailwind-canonicalize alongside ESLint for fixing and checking code.

```json
{
  "scripts": {
    "fix": "tailwind-canonicalize . --write --safe && eslint . --fix",
    "check": "tailwind-canonicalize . --check && eslint ."
  }
}
```

--------------------------------

### Use Tailwind canonicalize composite action

Source: https://github.com/xylex-group/tailwind-canonicalize/blob/main/apps/docs/docs/integrations/ci.mdx

Execute the canonicalize action using the official GitHub composite action.

```yaml
- uses: tailwind-canonicalize/action@v1
  with:
    path: src
```

--------------------------------

### Compose CI Jobs for Tailwind Canonicalize

Source: https://github.com/xylex-group/tailwind-canonicalize/blob/main/docs/guides/integrations.md

Run canonicalize as a standalone step in your CI pipeline alongside other linters like Biome or Oxlint.

```yaml
- name: Canonicalize (Tailwind)
  run: pnpm canonicalize:check

- name: Lint (Biome)
  run: pnpm lint

- name: Lint (Oxlint)   # optional second linter
  run: pnpm oxlint
```

--------------------------------

### canonicalizeProject(options?)

Source: https://github.com/xylex-group/tailwind-canonicalize/blob/main/docs/api/reference.md

Scans project paths in parallel to canonicalize files based on project configuration.

```APIDOC
## canonicalizeProject(options?)

### Description
Scans project paths and applies canonicalization.

### Parameters
- **paths** (string[]) - Files or directories to scan (default: ['.']).
- **write** (boolean) - Persist changes (default: false).
- **autoTheme** (boolean) - Load project CSS theme (default: true).
- **concurrency** (number) - Worker count (default: 8).
- **rootFontSizePx** (number) - rem conversion base (default: 16).
- **ignore** (string[]) - Extra ignore names.
```

--------------------------------

### Configure Turborepo tasks

Source: https://github.com/xylex-group/tailwind-canonicalize/blob/main/docs/guides/integrations.md

Define canonicalization tasks and dependencies in Turborepo configuration.

```json
{
  "tasks": {
    "canonicalize": {
      "dependsOn": ["^build"],
      "outputs": []
    },
    "lint": {
      "dependsOn": ["canonicalize"]
    }
  }
}
```

```json
// apps/web/package.json
{
  "scripts": {
    "canonicalize": "tailwind-canonicalize src --write --safe",
    "canonicalize:check": "tailwind-canonicalize src --check",
    "lint": "biome check ."
  }
}
```

--------------------------------

### defineConfig

Source: https://github.com/xylex-group/tailwind-canonicalize/blob/main/apps/docs/docs/api.mdx

Defines the configuration for tailwind-canonicalize.

```APIDOC
## defineConfig(config: object)

### Description
Helper function to define the library configuration, including Tailwind version and canonicalization rules.
```

--------------------------------

### Monorepo CI Configuration

Source: https://github.com/xylex-group/tailwind-canonicalize/blob/main/docs/guides/ci.md

Commands for running Tailwind Canonicalize across monorepo packages using pnpm.

```yaml
- run: pnpm --filter "./apps/*" --filter "./packages/*" exec tailwind-canonicalize . --check
```

```bash
pnpm exec tailwind-canonicalize apps packages --check --workers --concurrency 16
```
Tokens:
Raw