@herb-tools/tailwind-class-sorter 0.5.0

package/dist/types/config.d.ts

@@ -0,0 +1,2 @@
+import type { ContextContainer, SortTailwindClassesOptions } from './types';
+export declare function getTailwindConfig(options?: SortTailwindClassesOptions): Promise<ContextContainer>;

package/dist/types/expiring-map.d.ts

@@ -0,0 +1,6 @@
+interface ExpiringMap<K, V> {
+    get(key: K): V | undefined;
+    set(key: K, value: V): void;
+}
+export declare function expiringMap<K, V>(duration: number): ExpiringMap<K, V>;
+export {};

package/dist/types/index.d.ts

@@ -0,0 +1,27 @@
+import type { SortTailwindClassesOptions } from './types.js';
+export type { SortTailwindClassesOptions, ContextContainer } from './types.js';
+export { TailwindClassSorter } from './sorter.js';
+/**
+ * Sort Tailwind CSS classes according to the recommended class order.
+ *
+ * @param classStr - String of space-separated CSS classes
+ * @param options - Configuration options
+ * @returns Sorted class string
+ */
+export declare function sortTailwindClasses(classStr: string, options?: SortTailwindClassesOptions): Promise<string>;
+/**
+ * Sort a list of Tailwind CSS classes.
+ *
+ * @param classList - Array of CSS classes
+ * @param options - Configuration options
+ * @returns Object with sorted classList and removed indices
+ */
+export declare function sortTailwindClassList(classList: string[], options?: SortTailwindClassesOptions): Promise<{
+    classList: string[];
+    removedIndices: Set<number>;
+} | {
+    classList: never;
+    removedIndices: Set<unknown>;
+}>;
+export { sortClasses, sortClassList } from './sorting.js';
+export { getTailwindConfig } from './config.js';

package/dist/types/resolve.d.ts

@@ -0,0 +1,4 @@
+export declare function maybeResolve(name: string): string | null;
+export declare function loadIfExists<T>(name: string): Promise<T | null>;
+export declare function resolveJsFrom(base: string, id: string): string;
+export declare function resolveCssFrom(base: string, id: string): string;

package/dist/types/sorter.d.ts

@@ -0,0 +1,53 @@
+import type { SortTailwindClassesOptions, ContextContainer } from './types.js';
+/**
+ * A reusable Tailwind CSS class sorter that holds a context for efficient sorting.
+ * Use this when you need to sort classes multiple times with the same configuration.
+ */
+export declare class TailwindClassSorter {
+    private env;
+    /**
+     * Create a new TailwindClassSorter with a pre-loaded context.
+     *
+     * @param contextContainer - Pre-loaded Tailwind context and generateRules function
+     * @param options - Configuration options (merged with context)
+     */
+    constructor(contextContainer: ContextContainer, options?: SortTailwindClassesOptions);
+    /**
+     * Create a TailwindClassSorter by loading a Tailwind config file.
+     *
+     * @param options - Configuration options including config file path
+     * @returns Promise resolving to a new TailwindClassSorter instance
+     */
+    static fromConfig(options?: SortTailwindClassesOptions): Promise<TailwindClassSorter>;
+    /**
+     * Sort Tailwind CSS classes synchronously.
+     *
+     * @param classStr - String of space-separated CSS classes
+     * @param overrideOptions - Options to override the instance options for this sort
+     * @returns Sorted class string
+     */
+    sortClasses(classStr: string, overrideOptions?: Partial<SortTailwindClassesOptions>): string;
+    /**
+     * Sort a list of Tailwind CSS classes synchronously.
+     *
+     * @param classList - Array of CSS classes
+     * @param overrideOptions - Options to override the instance options for this sort
+     * @returns Object with sorted classList and removed indices
+     */
+    sortClassList(classList: string[], overrideOptions?: Partial<SortTailwindClassesOptions>): {
+        classList: string[];
+        removedIndices: Set<number>;
+    };
+    /**
+     * Get the underlying context container.
+     *
+     * @returns The context container used by this sorter
+     */
+    getContext(): ContextContainer;
+    /**
+     * Get the current options.
+     *
+     * @returns The options used by this sorter
+     */
+    getOptions(): SortTailwindClassesOptions;
+}

package/dist/types/sorting.d.ts

@@ -0,0 +1,19 @@
+import type { SortEnv } from './types';
+export declare function bigSign(bigIntValue: bigint): number;
+export declare function sortClasses(classStr: string, { env, ignoreFirst, ignoreLast, removeDuplicates, collapseWhitespace, }: {
+    env: SortEnv;
+    ignoreFirst?: boolean;
+    ignoreLast?: boolean;
+    removeDuplicates?: boolean;
+    collapseWhitespace?: false | {
+        start: boolean;
+        end: boolean;
+    };
+}): string;
+export declare function sortClassList(classList: string[], { env, removeDuplicates, }: {
+    env: SortEnv;
+    removeDuplicates: boolean;
+}): {
+    classList: string[];
+    removedIndices: Set<number>;
+};

package/dist/types/types.d.ts

@@ -0,0 +1,40 @@
+export 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;
+}
+export interface TailwindContext {
+    tailwindConfig: {
+        prefix: string | ((selector: string) => string);
+    };
+    getClassOrder?: (classList: string[]) => [string, bigint | null][];
+    layerOrder: {
+        components: bigint;
+    };
+}
+export interface SortEnv {
+    context: TailwindContext;
+    generateRules: (classes: Iterable<string>, context: TailwindContext) => [bigint][];
+    options: SortTailwindClassesOptions;
+}
+export interface ContextContainer {
+    context: any;
+    generateRules: (classes: Iterable<string>, context: TailwindContext) => [bigint][];
+}

package/package.json

@@ -0,0 +1,61 @@
+{
+  "type": "module",
+  "name": "@herb-tools/tailwind-class-sorter",
+  "description": "Standalone Tailwind CSS class sorter with Prettier plugin compatibility, extracted from tailwindlabs/prettier-plugin-tailwindcss",
+  "version": "0.5.0",
+  "license": "MIT",
+  "main": "./dist/tailwind-class-sorter.cjs",
+  "module": "./dist/tailwind-class-sorter.esm.js",
+  "types": "./dist/types/index.d.ts",
+  "exports": {
+    "./package.json": "./package.json",
+    ".": {
+      "types": "./dist/types/index.d.ts",
+      "import": "./dist/tailwind-class-sorter.esm.js",
+      "require": "./dist/tailwind-class-sorter.cjs",
+      "default": "./dist/tailwind-class-sorter.esm.js"
+    }
+  },
+  "files": [
+    "package.json",
+    "README.md",
+    "dist/",
+    "src/"
+  ],
+  "bugs": "https://github.com/marcoroth/herb/issues/new?title=Package%20%60@herb-tools/tailwind-class-sorter%60:%20",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/marcoroth/herb.git",
+    "directory": "javascript/packages/tailwind-class-sorter"
+  },
+  "scripts": {
+    "build": "yarn clean && rollup -c",
+    "dev": "rollup -c -w",
+    "clean": "rimraf dist",
+    "test": "vitest run",
+    "test:watch": "vitest --watch",
+    "prepublishOnly": "yarn clean && yarn build && yarn test"
+  },
+  "dependencies": {
+    "clear-module": "^4.1.2",
+    "escalade": "^3.2.0",
+    "jiti": "^2.5.1",
+    "postcss": "^8.5.6",
+    "postcss-import": "^16.1.1"
+  },
+  "devDependencies": {
+    "@types/node": "^24.1.0",
+    "dedent": "^1.6.0",
+    "esbuild": "^0.25.8",
+    "rimraf": "^6.0.1",
+    "tailwindcss": "^3.4.17",
+    "tsup": "^8.5.0",
+    "vitest": "^3.2.4"
+  },
+  "peerDependencies": {
+    "tailwindcss": "^3.0 || ^4.0"
+  },
+  "engines": {
+    "node": ">=14.21.3"
+  }
+}

package/src/config.ts

@@ -0,0 +1,344 @@
+// @ts-check
+import * as fs from 'fs/promises'
+import * as path from 'path'
+import { pathToFileURL } from 'url'
+import clearModule from 'clear-module'
+import escalade from 'escalade/sync'
+import { createJiti, type Jiti } from 'jiti'
+import postcss from 'postcss'
+// @ts-ignore
+import postcssImport from 'postcss-import'
+// @ts-ignore
+import { generateRules as generateRulesFallback } from 'tailwindcss/lib/lib/generateRules'
+// @ts-ignore
+import { createContext as createContextFallback } from 'tailwindcss/lib/lib/setupContextUtils'
+import loadConfigFallback from 'tailwindcss/loadConfig'
+import resolveConfigFallback from 'tailwindcss/resolveConfig'
+import type { RequiredConfig } from 'tailwindcss/types/config.js'
+import { expiringMap } from './expiring-map.js'
+import { resolveCssFrom, resolveJsFrom } from './resolve'
+import type { ContextContainer, SortTailwindClassesOptions } from './types'
+
+let sourceToPathMap = new Map<string, string | null>()
+let sourceToEntryMap = new Map<string, string | null>()
+let pathToContextMap = expiringMap<string | null, ContextContainer>(10_000)
+
+export async function getTailwindConfig(
+  options: SortTailwindClassesOptions = {},
+): Promise<ContextContainer> {
+  let pkgName = 'tailwindcss'
+
+  let key = [
+    options.baseDir ?? process.cwd(),
+    options.tailwindStylesheet ?? '',
+    options.tailwindConfig ?? '',
+    pkgName,
+  ].join(':')
+
+  let baseDir = getBaseDir(options)
+
+  // Map the source file to it's associated Tailwind config file
+  let configPath = sourceToPathMap.get(key)
+  if (configPath === undefined) {
+    configPath = getConfigPath(options, baseDir)
+    sourceToPathMap.set(key, configPath)
+  }
+
+  let entryPoint = sourceToEntryMap.get(key)
+  if (entryPoint === undefined) {
+    entryPoint = getEntryPoint(options, baseDir)
+    sourceToEntryMap.set(key, entryPoint)
+  }
+
+  // Now see if we've loaded the Tailwind config file before (and it's still valid)
+  let contextKey = `${pkgName}:${configPath}:${entryPoint}`
+  let existing = pathToContextMap.get(contextKey)
+  if (existing) {
+    return existing
+  }
+
+  // By this point we know we need to load the Tailwind config file
+  let result = await loadTailwindConfig(
+    baseDir,
+    pkgName,
+    configPath,
+    entryPoint,
+  )
+
+  pathToContextMap.set(contextKey, result)
+
+  return result
+}
+
+function getBaseDir(options: SortTailwindClassesOptions): string {
+  if (options.baseDir) {
+    return options.baseDir
+  }
+
+  return process.cwd()
+}
+
+async function loadTailwindConfig(
+  baseDir: string,
+  pkgName: string,
+  tailwindConfigPath: string | null,
+  entryPoint: string | null,
+): Promise<ContextContainer> {
+  let createContext = createContextFallback
+  let generateRules = generateRulesFallback
+  let resolveConfig = resolveConfigFallback
+  let loadConfig = loadConfigFallback
+  let tailwindConfig: RequiredConfig = { content: [] }
+
+  try {
+    let pkgFile = resolveJsFrom(baseDir, `${pkgName}/package.json`)
+    let pkgDir = path.dirname(pkgFile)
+
+    try {
+      let v4 = await loadV4(baseDir, pkgDir, pkgName, entryPoint)
+      if (v4) {
+        return v4
+      }
+    } catch {}
+
+    resolveConfig = require(path.join(pkgDir, 'resolveConfig'))
+    createContext = require(
+      path.join(pkgDir, 'lib/lib/setupContextUtils'),
+    ).createContext
+    generateRules = require(
+      path.join(pkgDir, 'lib/lib/generateRules'),
+    ).generateRules
+
+    // Prior to `tailwindcss@3.3.0` this won't exist so we load it last
+    loadConfig = require(path.join(pkgDir, 'loadConfig'))
+  } catch {}
+
+  if (tailwindConfigPath) {
+    try {
+      clearModule(tailwindConfigPath)
+      const loadedConfig = loadConfig(tailwindConfigPath)
+      tailwindConfig = loadedConfig.default ?? loadedConfig
+    } catch (error) {
+      console.warn(`Failed to load Tailwind config from ${tailwindConfigPath}:`, error)
+    }
+  }
+
+  // suppress "empty content" warning
+  tailwindConfig.content = ['no-op']
+
+  // Create the context
+  let context = createContext(resolveConfig(tailwindConfig))
+
+  return {
+    context,
+    generateRules,
+  }
+}
+
+/**
+ * Create a loader function that can load plugins and config files relative to
+ * the CSS file that uses them. However, we don't want missing files to prevent
+ * everything from working so we'll let the error handler decide how to proceed.
+ */
+function createLoader<T>({
+  legacy,
+  jiti,
+  filepath,
+  onError,
+}: {
+  legacy: boolean
+  jiti: Jiti
+  filepath: string
+  onError: (id: string, error: unknown, resourceType: string) => T
+}) {
+  let cacheKey = `${+Date.now()}`
+
+  async function loadFile(id: string, base: string, resourceType: string) {
+    try {
+      let resolved = resolveJsFrom(base, id)
+
+      let url = pathToFileURL(resolved)
+      url.searchParams.append('t', cacheKey)
+
+      return await jiti.import(url.href, { default: true })
+    } catch (err) {
+      return onError(id, err, resourceType)
+    }
+  }
+
+  if (legacy) {
+    let baseDir = path.dirname(filepath)
+    return (id: string) => loadFile(id, baseDir, 'module')
+  }
+
+  return async (id: string, base: string, resourceType: string) => {
+    return {
+      base,
+      module: await loadFile(id, base, resourceType),
+    }
+  }
+}
+
+async function loadV4(
+  baseDir: string,
+  pkgDir: string,
+  pkgName: string,
+  entryPoint: string | null,
+) {
+  // Import Tailwind — if this is v4 it'll have APIs we can use directly
+  let pkgPath = resolveJsFrom(baseDir, pkgName)
+
+  let tw = await import(pathToFileURL(pkgPath).toString())
+
+  // This is not Tailwind v4
+  if (!tw.__unstable__loadDesignSystem) {
+    return null
+  }
+
+  // If the user doesn't define an entrypoint then we use the default theme
+  entryPoint = entryPoint ?? `${pkgDir}/theme.css`
+
+  // Create a Jiti instance that can be used to load plugins and config files
+  let jiti = createJiti(import.meta.url, {
+    moduleCache: false,
+    fsCache: false,
+  })
+
+  let importBasePath = path.dirname(entryPoint)
+
+  // Resolve imports in the entrypoint to a flat CSS tree
+  let css = await fs.readFile(entryPoint, 'utf-8')
+
+  // Determine if the v4 API supports resolving `@import`
+  let supportsImports = false
+  try {
+    await tw.__unstable__loadDesignSystem('@import "./empty";', {
+      loadStylesheet: () => {
+        supportsImports = true
+        return {
+          base: importBasePath,
+          content: '',
+        }
+      },
+    })
+  } catch {}
+
+  if (!supportsImports) {
+    let resolveImports = postcss([postcssImport()])
+    let result = await resolveImports.process(css, { from: entryPoint })
+    css = result.css
+  }
+
+  // Load the design system and set up a compatible context object that is
+  // usable by the rest of the plugin
+  let design = await tw.__unstable__loadDesignSystem(css, {
+    base: importBasePath,
+
+    // v4.0.0-alpha.25+
+    loadModule: createLoader({
+      legacy: false,
+      jiti,
+      filepath: entryPoint,
+      onError: (id, err, resourceType) => {
+        console.error(`Unable to load ${resourceType}: ${id}`, err)
+
+        if (resourceType === 'config') {
+          return {}
+        } else if (resourceType === 'plugin') {
+          return () => {}
+        }
+      },
+    }),
+
+    loadStylesheet: async (id: string, base: string) => {
+      let resolved = resolveCssFrom(base, id)
+
+      return {
+        base: path.dirname(resolved),
+        content: await fs.readFile(resolved, 'utf-8'),
+      }
+    },
+
+    // v4.0.0-alpha.24 and below
+    loadPlugin: createLoader({
+      legacy: true,
+      jiti,
+      filepath: entryPoint,
+      onError(id, err) {
+        console.error(`Unable to load plugin: ${id}`, err)
+
+        return () => {}
+      },
+    }),
+
+    loadConfig: createLoader({
+      legacy: true,
+      jiti,
+      filepath: entryPoint,
+      onError(id, err) {
+        console.error(`Unable to load config: ${id}`, err)
+
+        return {}
+      },
+    }),
+  })
+
+  return {
+    context: {
+      getClassOrder: (classList: string[]) => design.getClassOrder(classList),
+    },
+
+    // Stubs that are not needed for v4
+    generateRules: () => [],
+  }
+}
+
+function getConfigPath(options: SortTailwindClassesOptions, baseDir: string): string | null {
+  if (options.tailwindConfig) {
+    if (options.tailwindConfig.endsWith('.css')) {
+      return null
+    }
+
+    return path.resolve(baseDir, options.tailwindConfig)
+  }
+
+  let configPath: string | void = undefined
+  try {
+    configPath = escalade(baseDir, (_dir, names) => {
+      if (names.includes('tailwind.config.js')) {
+        return 'tailwind.config.js'
+      }
+      if (names.includes('tailwind.config.cjs')) {
+        return 'tailwind.config.cjs'
+      }
+      if (names.includes('tailwind.config.mjs')) {
+        return 'tailwind.config.mjs'
+      }
+      if (names.includes('tailwind.config.ts')) {
+        return 'tailwind.config.ts'
+      }
+    })
+  } catch {}
+
+  if (configPath) {
+    return configPath
+  }
+
+  return null
+}
+
+function getEntryPoint(options: SortTailwindClassesOptions, baseDir: string): string | null {
+  if (options.tailwindStylesheet) {
+    return path.resolve(baseDir, options.tailwindStylesheet)
+  }
+
+  if (options.tailwindConfig && options.tailwindConfig.endsWith('.css')) {
+    console.warn(
+      'Use the `tailwindStylesheet` option for v4 projects instead of `tailwindConfig`.',
+    )
+
+    return path.resolve(baseDir, options.tailwindConfig)
+  }
+
+  return null
+}

package/src/expiring-map.ts

@@ -0,0 +1,31 @@
+interface ExpiringMap<K, V> {
+  get(key: K): V | undefined
+  set(key: K, value: V): void
+}
+
+export function expiringMap<K, V>(duration: number): ExpiringMap<K, V> {
+  let map = new Map<K, { value: V; expiration: Date }>()
+
+  return {
+    get(key: K) {
+      let result = map.get(key)
+      if (!result) return undefined
+      if (result.expiration <= new Date()) {
+        map.delete(key)
+        return undefined
+      }
+
+      return result.value
+    },
+
+    set(key: K, value: V) {
+      let expiration = new Date()
+      expiration.setMilliseconds(expiration.getMilliseconds() + duration)
+
+      map.set(key, {
+        value,
+        expiration,
+      })
+    },
+  }
+}

package/src/index.ts

@@ -0,0 +1,64 @@
+import { getTailwindConfig } from './config.js'
+import { sortClasses, sortClassList } from './sorting.js'
+import type { SortTailwindClassesOptions, SortEnv } from './types.js'
+
+export type { SortTailwindClassesOptions, ContextContainer } from './types.js'
+export { TailwindClassSorter } from './sorter.js'
+
+/**
+ * Sort Tailwind CSS classes according to the recommended class order.
+ *
+ * @param classStr - String of space-separated CSS classes
+ * @param options - Configuration options
+ * @returns Sorted class string
+ */
+export async function sortTailwindClasses(
+  classStr: string,
+  options: SortTailwindClassesOptions = {}
+): Promise<string> {
+  if (!classStr || typeof classStr !== 'string') {
+    return classStr
+  }
+
+  const { context, generateRules } = await getTailwindConfig(options)
+
+  const env: SortEnv = {
+    context,
+    generateRules,
+    options
+  }
+
+  return sortClasses(classStr, { env })
+}
+
+/**
+ * Sort a list of Tailwind CSS classes.
+ *
+ * @param classList - Array of CSS classes
+ * @param options - Configuration options
+ * @returns Object with sorted classList and removed indices
+ */
+export async function sortTailwindClassList(
+  classList: string[],
+  options: SortTailwindClassesOptions = {}
+) {
+  if (!Array.isArray(classList)) {
+    return { classList, removedIndices: new Set() }
+  }
+
+  const { context, generateRules } = await getTailwindConfig(options)
+
+  const env: SortEnv = {
+    context,
+    generateRules,
+    options
+  }
+
+  return sortClassList(classList, {
+    env,
+    removeDuplicates: !options.tailwindPreserveDuplicates
+  })
+}
+
+export { sortClasses, sortClassList } from './sorting.js'
+export { getTailwindConfig } from './config.js'