Export `getTailwindConfig` and `sortClasses` for `Oxfmt` formatter integration

[Dunqing]

Hi Tailwind CSS team! I'm a maintainer of Oxc. We're currently working on Tailwind CSS class sorting support in Oxfmt (a Rust-based JavaScript formatter aiming for 100% Prettier compatibility), and it's nearly complete. Tailwind CSS sorting is the most requested feature from users looking to migrate from Prettier to Oxfmt.

Implementation in Oxfmt

For Tailwind CSS support, we're using getTailwindConfig and sortClasses from this plugin under the hood to follow Tailwind CSS's official sorting rules. However, this package doesn't export these two functions, making it impossible to use them directly. We're currently using pnpm patch as a workaround to export them for development, but this isn't an ideal long-term solution—especially since we're patching a minified package.

Proposed Changes

In addition to exporting these two functions, we'd need small modifications to make the integration work smoothly and more performantly:

1. Change getTailwindConfig to accept configDir and configPath (naming TBD) instead of inferring them from filepath. This allows us to avoid redundant calls to resolvePrettierConfigPath when we already have the config paths resolved on the Oxfmt side. It also avoids bundling prettier in Oxfmt, since resolvePrettierConfigPath depends on it.

2. Re-export getTailwindConfig and sortClasses from a new file like lib.ts using the exports field to make it tree-shakeable. Currently, index.ts contains let base = await loadPlugins();, which imports all parsers and prevents tree-shaking.

Would you consider making these changes and exporting these two functions? This would greatly facilitate our integration efforts and ensure consistency with Tailwind CSS's official sorting logic. All Tailwind CSS users would benefit, as they could use a faster formatter without losing their beloved Tailwind CSS sorting feature.

I'd be happy to work on a PR for this if you're open to the idea. Thank you for your consideration!

[thecrypticace]

Hey! Thanks for reaching out — I'd been thinking about a public API since I saw the implementation of the PR in oxfmt.

We're currently working on Tailwind CSS class sorting support in Oxfmt …

❤️

… especially since we're patching a minified package.

Yeah this was one of the big ones for me. That's a bit of a moving target since minfiication can change variable names all the time.

Re-export getTailwindConfig and sortClasses from a new file like lib.ts …
Currently, index.ts contains let base = await loadPlugins();, which imports all parsers and prevents tree-shaking.

Yeah, I really don't like that the top-level await is used. It also causes an unncessarily large setup cost because of our how our third-party plugin compatibility stuff works which I'm not happy about. I will be dropping the top-level await in #420 to help alleviate some of that cost. We do, at least for now, pull in some parsers eagerly from Prettier. So I think an explicit export at prettier-plugin-tailwindcss/lib (naming TBD) is reasonable.

Would you consider making these changes and exporting these two functions? …

I'm planning on renaming and reworking internals so exporting getTailwindConfig and sortClasses would be a bit limiting and the design of them isn't great imo (and getTailwindConfig is named quite poorly too).

I think a more explicitly designed API like below would be better — naming of all properties and methods is up in the air but probably close to what it'll eventually be. If you have any suggestions, thoughts, questions, etc… would love to hear them:

export interface SorterOptions {
  /**
   * The directory used to resolve relative file paths
   * 
   * For example, the `configPath` and `stylesheetPath`
   * options are resolved relative to this path if they
   * are not absolute paths.
   *
   * When not provided this will be:
   * - Inferred from `formatterConfigPath` if given; otherwise
   * - The current working directory
   */
  base?: string

  /**
   * The path to the config file containing plugin settings
   * 
   * This is typically the path to a Prettier config file,
   * Oxfmt config file, a `package.json` file that contains
   * Prettier settings, etc…
   * 
   * When provded it serves two purposes:
   * - Improved error messages
   * - To determine a suitable value for `base` if it was not provided
   */
  formatterConfigPath?: string

  /**
   * The path to the file being formatted
   *
   * When provided, Tailwind CSS is resolved relative to this path; otherwise,
   * it is resolved relative to `base`.
   */
  filepath?: string
  
  /**
   * Path to the Tailwind CSS config file (v3).
   *
   * Paths is resolved relative to `base`
   *
   * e.g. `./tailwind.config.js`
   *
   * Default: The closest `tailwind.config.{js,mjs,cjs,ts}` file relative to
   *          `filepath` if a local installation of Tailwind CSS v3 is found.
   */
  configPath?: string

  /**
   * Path to the CSS stylesheet used by Tailwind CSS (v4+)
   *
   * Paths is resolved relative to `base`
   *
   * e.g. `./src/app.css`
   *
   * Default: The default Tailwind CSS v4 stylesheet if a local installation of
   * Tailwind CSS v4 is found.
   */
  stylesheetPath?: string

  /**
   * Whether or not to preserve whitespace around classes.
   * 
   * Only applies to `sortClassAttributes`.
   *
   * Default: false
   */
  preserveWhitespace?: boolean

  /**
   * Whether or not to preserve duplicate classes.
   *
   * Default: false
   */
  preserveDuplicates?: boolean
}

export interface Sorter {
  /**
   * Sort one or more class attributes.
   *
   * Each element is the value of an HTML `class` attribute (or similar). i.e. a
   * space separated list of class names as a string.
   *
   * Postconditions:
   * - The returned list is the same length and in the same order as `classes`.
   * - Unknown classes are kept in their original, relative order but are moved
   *   to the beginning of the list.
   * - The special "..." class token is sorted to the end.
   * 
   * TODO: Naming?
   */
  sortClassAttributes(classes: string[]): string[]

  /**
   * Sort one or more class lists.
   *
   * Each element is an array of class names. Passing a space separated class
   * list in each element is not supported.
   *
   * Postconditions:
   * - The returned list is the same length and in the same order as `classes`.
   * - Unknown classes are kept in their original, relative order but are moved
   *   to the beginning of the list.
   * - The special "..." class token is sorted to the end.
   * - When removing duplicates they are replaced with `null`
   */
  sortClassLists(classes: string[][]): (string | null)[][]
}

export function createSorter(opts: SorterOptions): Promise<Sorter>;

I'd be happy to work on a PR for this if you're open to the idea. Thank you for your consideration!

That's much appreciated. Since I'm proposing a more explicit API I don't mind taking this one on myself. Need to think over the design a bit more but definitely open to feedback.

I'd already started work on an API like this here: https://github.com/tailwindlabs/prettier-plugin-tailwindcss/blob/feat/public-api/src/sorter.ts

I'll need to update the above branch since, given some of the information about the config file loading, I've tweaked the above API definitions some to account for that.

[Dunqing]

Thank you for working on this! I just know you've been working on the export public API for a while, and that is actually what we needed! We will probably use sortClassLists because we've handled a little bit of preserveSpace work on our side.

The API design is great overall! Just prettierConfigPath would be better renamed to formatterConfigPath or just configPath, and the documentation for it should be updated to include that it may be an Oxfmt config file since it has become formatter-agnostic.

[thecrypticace]

Yeah having two options named config and configPath doesn't feel ideal to me. Naming it formatterConfigPath seems fine but will think over it some more.

I may end up renaming the config property as well.

[Dunqing]

I may end up renaming the config property as well.

Actually, I prefer this. I've never thought this was a Tailwind CSS config path without looking at its description. 😂

[thecrypticace]

The some of the properties basically mirror the Prettier config option names just without the tailwind* prefix but in this case tailwindConfig is clear while config… not so much 😅

[Dunqing]

The some of the properties basically mirror the Prettier config option names just without the tailwind* prefix but in this case tailwindConfig is clear while config… not so much 😅

I am going to do the same thing in Oxfmt. We will have a top-level field in the Oxfmt configuration file that is experimentalTailwindcss (add the experimental prefix until we think it is stable).

It looks like:

// .oxfmtrc.json
{
  "experimentalTailwindcss": {
     "config": "./tailwindcss.config.js",
     "functions": ["clsx"],
      ...
  }
}

It's fine without the tailwind prefix under the experimentalTailwindcss, but it requires some tweaks to the configurations from Prettier to migrate to Oxfmt.

So it actually benefits Oxfmt, as there is no need to map configuration fields.