Standalone Tailwind CSS Class Sorter

Package: @herb-tools/tailwind-class-sorter

A standalone Tailwind CSS class sorter that automatically sorts classes based on the recommended class order.

Attribution

This package is a fork of the original prettier-plugin-tailwindcss by Tailwind Labs, modified to provide standalone class sorting functionality for @herb-tools/formatter and other use cases. The core sorting logic and algorithms are from the original Tailwind Labs implementation.

Key Features

• Standalone class sorting - Use the sorting algorithm independently from Prettier
• Compatible with @herb-tools/formatter - Designed to work seamlessly with the Herb ecosystem
• Same sorting logic - Uses the same proven algorithm as the original Prettier plugin
• Full Tailwind config support - Works with custom configs, v3 JS configs, and v4 CSS stylesheets

Installation

npm install -D @herb-tools/tailwind-class-sorter

API Reference

Main Functions

sortTailwindClasses(classStr, options?)

Sorts a string of space-separated Tailwind CSS classes.

import { sortTailwindClasses } from '@herb-tools/tailwind-class-sorter'

const result = await sortTailwindClasses('px-4 bg-blue-500 text-white rounded py-2')
// Result: 'rounded bg-blue-500 px-4 py-2 text-white'

Parameters:

• classStr (string): Space-separated CSS classes
• options? (SortTailwindClassesOptions): Configuration options

Returns: Promise<string> - Sorted class string

sortTailwindClassList(classList, options?)

Sorts an array of Tailwind CSS classes.

import { sortTailwindClassList } from '@herb-tools/tailwind-class-sorter'

const result = await sortTailwindClassList(['px-4', 'bg-blue-500', 'text-white'])
// Result: { classList: ['bg-blue-500', 'px-4', 'text-white'], removedIndices: Set() }

Parameters:

• classList (string[]): Array of CSS classes
• options? (SortTailwindClassesOptions): Configuration options

Returns: Promise<{ classList: string[], removedIndices: Set<number> }> - Sorted classes and removed duplicate indices

TailwindClassSorter class

A reusable class sorter that holds a context for efficient, synchronous sorting. Ideal when you need to sort classes multiple times with the same configuration.

import { TailwindClassSorter } from '@herb-tools/tailwind-class-sorter'

const sorter = await TailwindClassSorter.fromConfig({
  tailwindConfig: './tailwind.config.js'
})

const result1 = sorter.sortClasses('px-4 bg-blue-500 text-white')
const result2 = sorter.sortClasses('py-2 bg-red-500 text-black')

Static Methods:

• TailwindClassSorter.fromConfig(options?): Creates sorter from config file (async)

Constructor:

• new TailwindClassSorter(contextContainer, options?): Creates sorter from pre-loaded context (sync)

Instance Methods:

• sortClasses(classStr, overrideOptions?): Sort classes synchronously
• sortClassList(classList, overrideOptions?): Sort class array synchronously
• getContext(): Get the underlying context container
• getOptions(): Get current configuration options

Advanced Functions

sortClasses(classStr, { env, ...options })

Low-level function for sorting with a pre-configured environment.

sortClassList(classList, { env, removeDuplicates })

Low-level function for sorting class arrays with a pre-configured environment.

getTailwindConfig(options)

Loads and configures Tailwind CSS context.

Configuration Options

The SortTailwindClassesOptions interface supports the following options:

interface SortTailwindClassesOptions {
  /** Path to the Tailwind config file */
  tailwindConfig?: string

  /** Path to the CSS stylesheet used by Tailwind CSS (v4+) */
  tailwindStylesheet?: string

  /** Preserve whitespace around Tailwind classes when sorting */
  tailwindPreserveWhitespace?: boolean

  /** Preserve duplicate classes inside a class list when sorting */
  tailwindPreserveDuplicates?: boolean

  /** Base directory for resolving config files (defaults to process.cwd()) */
  baseDir?: string
}

Usage Examples

Basic Usage

import { sortTailwindClasses } from '@herb-tools/tailwind-class-sorter'

const sorted = await sortTailwindClasses('px-4 bg-blue-500 text-white rounded py-2')
// Result: 'rounded bg-blue-500 px-4 py-2 text-white'

With Custom Tailwind Config (v3)

const sorted = await sortTailwindClasses(
  'px-4 bg-custom-primary text-white py-2',
  {
    tailwindConfig: './tailwind.config.js'
  }
)

With Tailwind v4 Stylesheet

const sorted = await sortTailwindClasses(
  'px-4 bg-neon-pink text-brand-primary py-2',
  {
    tailwindStylesheet: './theme.css'
  }
)

Preserving Duplicates and Whitespace

const sorted = await sortTailwindClasses(
  'px-4  bg-blue-500  px-4  text-white',
  {
    tailwindPreserveDuplicates: true,
    tailwindPreserveWhitespace: true
  }
)
// Result: 'px-4  bg-blue-500  px-4  text-white'

Sorting Class Arrays

import { sortTailwindClassList } from '@herb-tools/tailwind-class-sorter'

const { classList, removedIndices } = await sortTailwindClassList(
  ['px-4', 'bg-blue-500', 'px-4', 'text-white'],
  { tailwindConfig: './tailwind.config.js' }
)
// classList: ['bg-blue-500', 'px-4', 'text-white']
// removedIndices: Set([2]) - duplicate px-4 at index 2 was removed

Efficient Repeated Sorting with TailwindClassSorter

For scenarios where you need to sort many class strings with the same configuration, use the TailwindClassSorter class for better performance:

import { TailwindClassSorter } from '@herb-tools/tailwind-class-sorter'

const sorter = await TailwindClassSorter.fromConfig({
  tailwindConfig: './tailwind.config.js',
  tailwindPreserveDuplicates: false
})

const components = [
  'px-4 bg-blue-500 text-white py-2',
  'mx-auto flex items-center justify-center',
  'border-2 border-gray-300 rounded-lg shadow-sm'
]

const sortedComponents = components.map(classes => sorter.sortClasses(classes))

Using Pre-loaded Context

You can also create a sorter from a pre-loaded context:

import { TailwindClassSorter, getTailwindConfig } from '@herb-tools/tailwind-class-sorter'

const contextContainer = await getTailwindConfig({
  tailwindConfig: './tailwind.config.js'
})

const sorter = new TailwindClassSorter(contextContainer, {
  tailwindPreserveDuplicates: false
})

const result = sorter.sortClasses('px-4 px-4 bg-blue-500 text-white')

Per-Sort Option Overrides

You can override options on a per-sort basis without creating new instances:

const sorter = await TailwindClassSorter.fromConfig({
  tailwindPreserveDuplicates: false
})

const normal = sorter.sortClasses('px-4 px-4 bg-blue-500')

const preserved = sorter.sortClasses('px-4 px-4 bg-blue-500', {
  tailwindPreserveDuplicates: true
})

About This Fork

The original prettier-plugin-tailwindcss is designed as a Prettier plugin. This package extracts the sorting functionality for use in other contexts like @herb-tools/formatter, build tools, or any JavaScript application that needs Tailwind class sorting.

For the full Prettier plugin experience, use the original package.

License

MIT License - see LICENSE for details.

Original work Copyright (c) Tailwind Labs Inc. Modified work Copyright (c) Marco Roth