{"id":16237,"library":"tailwind-api-utils","title":"Tailwind CSS API Utilities","description":"tailwind-api-utils is a utility library designed to expose and simplify interaction with the internal Tailwind CSS API. It enables programmatic access to Tailwind's configuration and class processing functionalities, allowing developers to, for example, load a Tailwind configuration object and sort CSS class names according to Tailwind's internal rules. The current stable version is 1.0.3. The package has seen consistent updates, particularly to maintain compatibility with both Tailwind CSS v3 and the upcoming v4. Key differentiators include its explicit support for different Tailwind CSS versions and functionalities like class name sorting, which can be useful for linting or maintaining consistent class order in projects. It primarily targets build tools and environments where programmatic interaction with Tailwind's core features is beneficial.","status":"active","version":"1.0.3","language":"javascript","source_language":"en","source_url":"https://github.com/hyoban/tailwind-api-utils","tags":["javascript","typescript"],"install":[{"cmd":"npm install tailwind-api-utils","lang":"bash","label":"npm"},{"cmd":"yarn add tailwind-api-utils","lang":"bash","label":"yarn"},{"cmd":"pnpm add tailwind-api-utils","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required for accessing the Tailwind CSS API and configuration; it's a peer dependency.","package":"tailwindcss","optional":false}],"imports":[{"note":"The library primarily uses ESM; CJS require is possible but less idiomatic for modern TypeScript/Node.js projects.","wrong":"const loadConfig = require('tailwind-api-utils').loadConfig;","symbol":"loadConfig","correct":"import { loadConfig } from 'tailwind-api-utils';"},{"note":"Functions are named exports from the main package entry point.","wrong":"import sortClassname from 'tailwind-api-utils/sortClassname';","symbol":"sortClassname","correct":"import { sortClassname } from 'tailwind-api-utils';"},{"note":"Type imports should be used for better type-checking and bundle optimization.","symbol":"Config","correct":"import type { Config } from 'tailwind-api-utils';"}],"quickstart":{"code":"import { loadConfig, sortClassname } from 'tailwind-api-utils';\nimport path from 'path';\nimport process from 'process';\n\n// A dummy Tailwind CSS configuration file content for demonstration\nconst tailwindConfigFileContent = `\n  module.exports = {\n    content: ['./index.html', './src/**/*.{js,ts,jsx,tsx}'],\n    theme: {\n      extend: {},\n    },\n    plugins: [],\n  };\n`;\n\nasync function runExample() {\n  // In a real application, you would load your actual tailwind.config.js\n  // For this example, we'll simulate a config file.\n  // This path needs to be valid in the execution environment.\n  const dummyConfigPath = path.join(process.cwd(), 'tailwind.config.js');\n  // You might write this content to a temporary file if truly testing `loadConfig`\n  // For simplicity, `loadConfig` tries to find it, so ensuring it exists is key.\n\n  try {\n    // Load the Tailwind config. This will look for tailwind.config.js by default.\n    // Make sure 'tailwindcss' is installed as a peer dependency.\n    const config = await loadConfig({ configPath: dummyConfigPath });\n    console.log('Loaded Tailwind config:', config.theme.extend);\n\n    const classesToSort = 'p-4 text-lg font-bold mx-auto flex items-center bg-blue-500 rounded-md';\n    const sortedClasses = sortClassname(classesToSort, config);\n    console.log('Original classes:', classesToSort);\n    console.log('Sorted classes:', sortedClasses);\n\n    const v4Classes = 'group/item:hover:p-4 md:text-xl sm:flex-row';\n    const sortedV4Classes = sortClassname(v4Classes, config);\n    console.log('Original v4 classes:', v4Classes);\n    console.log('Sorted v4 classes (with v4 compatibility):', sortedV4Classes);\n\n  } catch (error) {\n    console.error('Failed to run example:', error);\n    console.warn('Ensure `tailwindcss` is installed as a peer dependency.');\n    console.warn('For `loadConfig` to work, a `tailwind.config.js` file (or specified path) must be resolvable.');\n  }\n}\n\nrunExample();\n","lang":"typescript","description":"Demonstrates loading a Tailwind CSS configuration and sorting a string of class names using the library's utilities, compatible with Tailwind CSS v3 and v4 configurations."},"warnings":[{"fix":"Install `tailwindcss` in your project: `npm install tailwindcss` or `yarn add tailwindcss`.","message":"The `tailwind-api-utils` package is a peer dependency on `tailwindcss`. Ensure `tailwindcss` is installed in your project, compatible with the `^3.3.0 || ^4.0.0 || ^4.0.0-beta` range, otherwise the utilities will fail to function or load configurations correctly.","severity":"gotcha","affected_versions":">=0.0.1"},{"fix":"No direct fix needed, but be aware of the new functionality and potential for code style enforcement if adopted.","message":"Version 1.0.0 introduced the `sortClassname` feature. While not a breaking change for existing functionality, users updating from pre-1.0.0 versions might not have been aware of this new core utility.","severity":"breaking","affected_versions":">=1.0.0"},{"fix":"Pass an explicit `configPath` option to `loadConfig({ configPath: './path/to/your/tailwind.config.js' })`.","message":"When using `loadConfig`, the function attempts to resolve `tailwind.config.js` relative to the current working directory or a specified `configPath`. If your configuration is not at a standard location or in a complex monorepo setup, you might need to explicitly provide the `configPath` option.","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"Upgrade to `tailwind-api-utils@1.0.3` or newer for robust Tailwind CSS v4 compatibility: `npm update tailwind-api-utils`.","message":"Compatibility with Tailwind CSS v4 is explicitly handled, including fixes for the use of the separator '-' with v4 configurations. Older versions of `tailwind-api-utils` might not correctly process v4 specific syntax or configurations.","severity":"gotcha","affected_versions":"<1.0.3"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"fix":"Install Tailwind CSS: `npm install tailwindcss` or `yarn add tailwindcss`.","cause":"The `tailwindcss` package is a peer dependency and was not installed in the project.","error":"Error: Cannot find module 'tailwindcss'"},{"fix":"Ensure `tailwind.config.js` exists and is valid at the expected path, or provide an explicit `configPath` to `loadConfig`.","cause":"The `loadConfig` function likely failed to load a valid Tailwind CSS configuration, resulting in an undefined or malformed config object.","error":"TypeError: Cannot read properties of undefined (reading 'theme')"},{"fix":"Either convert your project to use ES Modules by adding `\"type\": \"module\"` to `package.json` or use dynamic `import()` or switch to `require()` if the library provides a CJS entry (though for `tailwind-api-utils`, ESM is preferred).","cause":"Attempting to use `import` syntax in a CommonJS (`.js` without `\"type\": \"module\"` in `package.json`) Node.js environment.","error":"SyntaxError: Cannot use import statement outside a module"}],"ecosystem":"npm"}