Tailwind CSS API Utilities

Common errors

• Error: Cannot find module 'tailwindcss'

  cause The `tailwindcss` package is a peer dependency and was not installed in the project.
  fix Install Tailwind CSS: `npm install tailwindcss` or `yarn add tailwindcss`.

• TypeError: Cannot read properties of undefined (reading 'theme')

  cause The `loadConfig` function likely failed to load a valid Tailwind CSS configuration, resulting in an undefined or malformed config object.
  fix Ensure `tailwind.config.js` exists and is valid at the expected path, or provide an explicit `configPath` to `loadConfig`.

• SyntaxError: Cannot use import statement outside a module

  cause Attempting to use `import` syntax in a CommonJS (`.js` without `"type": "module"` in `package.json`) Node.js environment.
  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).

Warnings

• gotcha 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.
  Fix: Install `tailwindcss` in your project: `npm install tailwindcss` or `yarn add tailwindcss`.
• breaking 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.
  Fix: No direct fix needed, but be aware of the new functionality and potential for code style enforcement if adopted.
• gotcha 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.
  Fix: Pass an explicit `configPath` option to `loadConfig({ configPath: './path/to/your/tailwind.config.js' })`.
• gotcha 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.
  Fix: Upgrade to `tailwind-api-utils@1.0.3` or newer for robust Tailwind CSS v4 compatibility: `npm update tailwind-api-utils`.

Install

• npm install tailwind-api-utils npm
• yarn add tailwind-api-utils yarn
• pnpm add tailwind-api-utils pnpm

Imports

• loadConfig
  wrong:

  const loadConfig = require('tailwind-api-utils').loadConfig;

  correct:

  import { loadConfig } from 'tailwind-api-utils';

  The library primarily uses ESM; CJS require is possible but less idiomatic for modern TypeScript/Node.js projects.
• sortClassname
  wrong:

  import sortClassname from 'tailwind-api-utils/sortClassname';

  correct:

  import { sortClassname } from 'tailwind-api-utils';

  Functions are named exports from the main package entry point.
• Config

  import type { Config } from 'tailwind-api-utils';

  Type imports should be used for better type-checking and bundle optimization.

Quickstart

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.

import { loadConfig, sortClassname } from 'tailwind-api-utils';
import path from 'path';
import process from 'process';

// A dummy Tailwind CSS configuration file content for demonstration
const tailwindConfigFileContent = `
  module.exports = {
    content: ['./index.html', './src/**/*.{js,ts,jsx,tsx}'],
    theme: {
      extend: {},
    },
    plugins: [],
  };
`;

async function runExample() {
  // In a real application, you would load your actual tailwind.config.js
  // For this example, we'll simulate a config file.
  // This path needs to be valid in the execution environment.
  const dummyConfigPath = path.join(process.cwd(), 'tailwind.config.js');
  // You might write this content to a temporary file if truly testing `loadConfig`
  // For simplicity, `loadConfig` tries to find it, so ensuring it exists is key.

  try {
    // Load the Tailwind config. This will look for tailwind.config.js by default.
    // Make sure 'tailwindcss' is installed as a peer dependency.
    const config = await loadConfig({ configPath: dummyConfigPath });
    console.log('Loaded Tailwind config:', config.theme.extend);

    const classesToSort = 'p-4 text-lg font-bold mx-auto flex items-center bg-blue-500 rounded-md';
    const sortedClasses = sortClassname(classesToSort, config);
    console.log('Original classes:', classesToSort);
    console.log('Sorted classes:', sortedClasses);

    const v4Classes = 'group/item:hover:p-4 md:text-xl sm:flex-row';
    const sortedV4Classes = sortClassname(v4Classes, config);
    console.log('Original v4 classes:', v4Classes);
    console.log('Sorted v4 classes (with v4 compatibility):', sortedV4Classes);

  } catch (error) {
    console.error('Failed to run example:', error);
    console.warn('Ensure `tailwindcss` is installed as a peer dependency.');
    console.warn('For `loadConfig` to work, a `tailwind.config.js` file (or specified path) must be resolvable.');
  }
}

runExample();