prettier-plugin-tailwindcss-canonical-classes

0.1.4 verified Sat Apr 25 auth: no javascript

Prettier plugin (v0.1.4) that automatically converts non-canonical Tailwind CSS v4 classes (e.g., mt-[16px] → mt-4) to their design-system-native equivalents. Requires Prettier ^3.0.0 and Tailwind CSS ^4.0.0. Ships TypeScript types. Differentiates from official sorting plugin by focusing on canonicalization rather than sorting; both can be chained. Active development with frequent releases. Node.js >= 18 required.

Common errors

error Cannot find module 'prettier-plugin-tailwindcss-canonical-classes' ↓

cause Package not installed or not in node_modules; possible missing peer deps.

fix

Run: npm install -D prettier-plugin-tailwindcss-canonical-classes prettier tailwindcss

error Error: prettier-plugin-tailwindcss-canonical-classes: Plugin configuration error. Option 'tailwindcssCanonicalStylesheet' must be a string path or undefined. ↓

cause Provided option value is not a string (e.g., boolean or number).

fix

Set tailwindcssCanonicalStylesheet to a valid path string or omit it.

error TypeError: Cannot read properties of undefined (reading 'canonicalize') ↓

cause Missing core dependency; likely due to mistaken import of @laststance/tailwindcss-canonical-classes-core instead of the plugin.

fix

Use the plugin package name: 'prettier-plugin-tailwindcss-canonical-classes' in plugins array.

error Error: Could not find Tailwind CSS entry file at 'src/index.css' ↓

cause The tailwindcssCanonicalStylesheet path is incorrect or file does not exist.

fix

Correct the path: e.g., tailwindcssCanonicalStylesheet: './src/globals.css' or use default (omit option).

Warnings

breaking Plugin chaining conflict with prettier-plugin-tailwindcss: order matters. prettier-plugin-tailwindcss-canonical-classes must appear before prettier-plugin-tailwindcss in the plugins array. ↓

fix List prettier-plugin-tailwindcss-canonical-classes first in plugins array, e.g., ["prettier-plugin-tailwindcss-canonical-classes", "prettier-plugin-tailwindcss"].

breaking v0.1.2 removed the "exports" field from package.json to fix VSCode extension loading. If you rely on deep imports or programmatic access to subpaths, they may break. ↓

fix Import only from the main package: import plugin from 'prettier-plugin-tailwindcss-canonical-classes'.

deprecated v0.1.3 renamed core dependency from @laststance/tailwindcss-canonical-core to @laststance/tailwindcss-canonical-classes-core. The old core package is deprecated. ↓

fix Update to v0.1.4; do not install @laststance/tailwindcss-canonical-core manually.

gotcha The plugin requires Tailwind CSS v4. Using with Tailwind v3 will cause runtime errors or no canonicalization. ↓

fix Ensure your project uses Tailwind CSS ^4.0.0.

gotcha Plugin only canonicalizes classes in files listed as supported: .astro, .css, .html, .js, .jsx, .less, .mdx, .scss, .svelte, .ts, .tsx, .vue. Other file types are ignored. ↓

fix If you need canonicalization in other file types, consider adding a Prettier override.

Install

npm install prettier-plugin-tailwindcss-canonical-classes

yarn add prettier-plugin-tailwindcss-canonical-classes

pnpm add prettier-plugin-tailwindcss-canonical-classes

Imports

prettier-plugin-tailwindcss-canonical-classes (plugin string)
wrong
```
plugins: ['@laststance/tailwindcss-canonical-classes-core']
```
correct
```
plugins: ['prettier-plugin-tailwindcss-canonical-classes']
```
The plugin is referenced by its npm package name in Prettier config; do not use the core package name.

Default export (if programmatic use)

wrong

const plugin = require('prettier-plugin-tailwindcss-canonical-classes')

correct

import plugin from 'prettier-plugin-tailwindcss-canonical-classes'

Plugin is ESM-only; CommonJS require may fail. For programmatic use, import default.

Plugin options type
```
import type { PluginOptions } from 'prettier-plugin-tailwindcss-canonical-classes'
```
TypeScript types are exported for plugin options (tailwindcssCanonicalStylesheet, tailwindcssCanonicalRootFontSize).

Quickstart

Installs plugin, configures it in .prettierrc with stylesheet path and root font size, then demonstrates canonicalization of arbitrary value classes to design tokens.

// Install: npm install -D prettier-plugin-tailwindcss-canonical-classes prettier tailwindcss
// .prettierrc
{
  "plugins": ["prettier-plugin-tailwindcss-canonical-classes"],
  "tailwindcssCanonicalStylesheet": "./src/globals.css",
  "tailwindcssCanonicalRootFontSize": 16
}

// Input: <div class="mt-[16px] text-[red] p-[1rem]">Hello</div>
// Output after Prettier: <div class="mt-4 text-red p-4">Hello</div>