☂️ Tailwind class sorting lint rule

[DaniGuardiola]

Update: I'm working on this! Follow the updates in this Twitter thread: https://twitter.com/daniguardio_la/status/1739715412131238122

PRs

• feat(linter): implement class sorting rule (first pass) #1362

Description

Port the TailwindCSS Prettier plugin that sorts Tailwind CSS utility classes. In Biome, it is being implemented as a lint rule that formats classes in JavaScript files though auto-fixes (ref).

Feature support / tasks checklist

Features with an asterisk are not likely to be implemented as part of this task. They are listed for exhaustiveness, and considered in architectural decisions so that future support is possible, but they are not high priority.

Features with a question mark are ideas that I'm not sure about, or I don't know enough about to determine if they make sense or how they could be implemented.

• Visitor:
  • Custom functions (clsx, etc).
  • Custom functions: tagged template support
  • JSX attributes (class and className)
  • Custom JSX attributes
  • Object properties (e.g. in objects passed to clsx)
• Sorting:
  • Utility classes
  • Utility classes: arbitrary values
  • Static variants
  • Dynamic variants
  • Arbitrary variants
  • Arbitrary CSS
  • Parasite utilities
  • Screens e.g. md:, max-md: (simple config, px-only)
  • Screens (advanced config)
  • Negative values
  • With prefix
  • With important prefix (!class)
  • With custom separator
• Preset/config generation:
  • Tailwind CSS v3 (WIP)
  • Tailwind CSS v4
  • UnoCSS*
• Presets:
  • Tailwind CSS preset
  • UnoCSS presets?*
• Config:
  • Custom functions
  • Custom JSX attributes
  • Class order
  • Exclude classes?*
  • Utilities/layers
  • Variants
  • Screens
  • Preset (Tailwind CSS or no preset)
  • Extend utilities
  • Extend variants
  • Extend screens? (replace might be the only sane option)
  • Prefix
  • Separator
• Other features:
  • Automatic migration/sync tailwind.config.js -> biome.json
  • Resiliency to UnoCSS variant groups (naive sorting could mangle these) docs?*
  • UnoCSS variant groups sorting?*
  • UnoCSS attributify mode sorting?*
• Other tasks
  • Lint rule documentation
  • Config documentation
  • Migration documentation
• Polish:
  • PartialOrd / improved check perf
  • Single sort pass / lexicographical sort as last compare sort?
  • Better name for the rule (useSortedUtilityClasses?)
  • Avoid string allocations whenever possible.

Upvote & Fund

• We're using Polar.sh so you can upvote and help fund this issue.
• We receive the funding once the issue is completed & confirmed by you.
• Thank you in advance for helping prioritize & fund our backlog.

[ematipico]

Hey @DaniGuardiola , thank you for opening this.

If you have the knowledge, do you know how this sorting thing works? Does Biome need to read the tailwind configuration file?

[DaniGuardiola]

@ematipico yeah I'm like 99% sure the config file is read. JavaScript is involved. Not sure how it fits in the biome way of doing things.

Is running JavaScript a possibility, at least to load the config file and transfer it to the rust program (or however that'd work)? or is it considered too slow?

[ematipico]

What I am interested in is the business logic of the plugin and how the configuration is involved in the sorting to the CSS classes.

I don't know Tailwind that well (as well as other people), so if someone with more knowledge can shed some light, it would help us to implement the feature in a faster way.

[DaniGuardiola]

@ematipico I will do a bit of research and get back to you.

[DaniGuardiola]

Leaving these as notes for the future.

This is where it all ultimately happens: https://github.com/tailwindlabs/tailwindcss/blob/master/src/lib/setupContextUtils.js#L930-L969

This function defers to this other function: https://github.com/tailwindlabs/tailwindcss/blob/master/src/lib/generateRules.js#L885-L930

The way sorting works is by leveraging the exact same mechanism that tailwind uses to sort the outputs. For example, p-4 pt-6 and pt-6 p-4 result in the same css, something like this:

.p-4 {
  padding: 1rem;
}

.pt-6 {
  padding-top: 1.5rem;
}

So the class order after sorting will match this: p-4 pt-6.

This is explained here: https://tailwindcss.com/blog/automatic-class-sorting-with-prettier#how-classes-are-sorted

Regarding configuration. First let me disambiguate to avoid confusion. There are two separate concepts here:

• The Tailwind sorting options. This are strictly related to the sorting plugin. For example, one can indicate a list of functions whose string arguments (in function calls) will be interpreted as class names and sorted (e.g. clsx, cva, etc).
• The Tailwind CSS config. These are the options for Tailwind itself, like the theme, the files to process, the plugins, prefix, etc.

Sorting options are trivial, and just act as input for the formatting tool. What I'm talking about here is the latter, the involvement of the tailwind config in this process.

First, about this config: it is a JavaScript file that needs to run and be "resolved" (e.g. plugins are functions that need to call stuff like addUtility and such to register stuff for Tailwind to use. So, the final config is created by "resolving", a.k.a. executing a bunch of stuff like that.

Its role in sorting spans multiple things:

• General config like prefix (e.g. if the configured prefix is tw, classes will look like tw-m-4), the ! important strategy, etc. These affect how classes are interpreted.
• The available utilities and variants, and their order (I'm guessing any of these coming from custom plugins are ordered just as the plugins are ordered in the config file).

The prettier plugin seems to "hook" into all of the existing logic, essentially reusing the exact same mechanism that is used to order the output. This makes sense, because why wouldn't they?

But I would argue that such complexity is not necessary, and biome could go with a way simpler approach based on simple heuristics and basic parsing/regexp.

I've done custom "reimplementations" of tailwind-like parsing for two projects now:

• https://github.com/DaniGuardiola/classy-ink
• https://github.com/compi-ui/tw-merge (complete rewrote of tailwind-merge using plain regexp)

So I would propose an approach like this + extensive testing. Of course, only using actual tailwind can guarantee that there won't be any false positives, but I think it is a very good compromise.

Regarding tailwind config, plugins and such, I would suggest that those options are moved to the formatter options. I think this biome feature should be generalize as a "utility class sorting" thing, with a tailwind preset.

So, in line with that, it should be simple enough to just add the utilities and variants that a plugin might add through config.

Sorry if this got a bit long / chaotic, I'm just researching and brainstorming to get things rolling. I'd be happy to start playing with this in a PR.

[DaniGuardiola]

To expand on the pros/cons of my proposed approach:

Pros

• Simpler. Like tens of thousands of LOC simpler.
• Covers 99.8% of cases. Yes, I made this number up, but I'm strongly convinced of it. I will explain that missing 0.2% and why it largely doesn't matter.
• It is generalizable to utility classes in general, which should cover other projects like nativewind, UnoCSS, etc.

Cons

• Can't use tailwindcss config directly. The user would need to re-specify these settings for the biome feature. Honestly, I think options like prefix are largely unused so I don't think it's a big deal. Regarding plugin-provided utilities and variants, the simplest solution is to provide a way to define these in the config as well. All in all, not the worst thing imo.
• False positives. Tailwind can tell the difference between something like hover:px-4 and hover:px-8268. The first one is valid, and the second is not. This is because 4 is in the theme scale, and 8268 is not. The proposed approach would count both as valid, and sort them both. This is the 0.2% I was talking about. Anyone using hover:px-8268 as a manually defined class should consider changing careers anyway. It's a non-issue.

[estubmo]

Yet to begin, because of events in my personal life.

[DaniGuardiola]

Thanks for the update. I'm gonna give it a go then :)

[Reed-Anderson]

Hey @DaniGuardiola , thanks so much for taking this on, it will be a huge upgrade for me. I hope this is an appropriate place to ask, is there any interest in supporting this popular tailwind/prettier request that was never implemented?

tailwindlabs/tailwindcss#7763

[itsezc]

Cons

• Can't use tailwindcss config directly. The user would need to re-specify these settings for the biome feature. Honestly, I think options like prefix are largely unused so I don't think it's a big deal. Regarding plugin-provided utilities and variants, the simplest solution is to provide a way to define these in the config as well. All in all, not the worst thing imo.
• False positives. Tailwind can tell the difference between something like hover:px-4 and hover:px-8268. The first one is valid, and the second is not. This is because 4 is in the theme scale, and 8268 is not. The proposed approach would count both as valid, and sort them both. This is the 0.2% I was talking about. Anyone using hover:px-8268 as a manually defined class should consider changing careers anyway. It's a non-issue.

First issue, can cause some friction for DX, and repeating configs is not ideal especially when there may be several devs in a team / project with an evolving tailwind config, but you're right its not the worst thing either.

Second, is a non issue as you've said. But, many people use arbitrary values i.e. hover:px-[8rem] or hover:px-extra if they're using a custom setup theme within their tailwind config. As long as these scenarios are handled to how the existing prettier plugin does, I don't think that'll be a huge issue.

[DaniGuardiola]

@Reed-Anderson thanks for bringing this up. While I share your pain, and think some tooling could definitely help, I think that's out of scope for this task.

I did see some approaches I liked in that thread, like one that turned multi-line strings into a normal, single line string on build (iirc). I don't think this task is the place to try something like that though.

[DaniGuardiola]

@itsezc good call-out. While I'm not going for perfection, I do wanna consider all of these cases, and I have some ideas to solve this that I'll share soon here for public feedback.

I'm a heavy tailwind user myself so I definitely want something that works across all reasonable use-cases.

[DaniGuardiola]

Here's my current thinking. Read my earlier messages on this thread for context.

Tailwind CSS class sorting -> class sorting

While the main goal of this task is to provide a good replacement for the Prettier Tailwind CSS plugin, generalizing just makes sense to me, because other tools use the concept of utility classes as well. It also just seems like something that could be generally helpful, the ability to sort classes according to a configuration.

Approach

The main challenge to solve is how the order of the classes is decided. Tailwind relies on its internal logic that also decides how the output is ordered, but we can't do that here, so we need a different approach. My thinking so far has been along the lines of having a config like this:

// simplified example, obviously
{
  "class-patterns": [
      // some kind of pseudo-regex / templating way of specifying these
     "p{y|x}-${scale}", // "special" value types like scale, numeric, etc
     "p-${scale}",
     "m{y|x}-${scale}",
     "m-${scale}",
     "grow$", // match "grow" without a suffix first ("exact")
     "grow-${numeric}" // then match other with a suffix
  ]
}

"Special" value types could be extended/customized:

{
  "types": {
    // add values
    "scale": { "extend": ["extra"] },
    // replace values
    "screens": { "values": ["md", "lg"] }
  }
}

The sorting algorithm would use this config to decide the order. Some other configs can be specified as well:

{
  "prefix": "tw-",
  // etc...
}

Variants

Variants (hover:active:focus:<utility class>) also need to be taken into consideration, and they are ordered as well iirc. The order could be specified similarly. The separator (colon by default) could also be configurable.

Presets

Of course, having and maintaining all of this in a config JSON file is annoying, so Biome would ship with presets for Tailwind and any other libraries that are popular enough.

{
  "preset": "tailwind-css",
}

Manual configuration

As I described in a previous comment, a drawback of this approach is that there's a bunch of manual configuration to maintain, which has to be kept in sync with the Tailwind config. To alleviate this, it'd be doable to create a package that automatically reads the Tailwind config and syncs the Biome config to it. Doesn't necessarily need to be part of Biome itself, but it can be a simple npm package. E.g.

$ npm i -D sync-tailwind-biome
$ sync-tailwind-biome

I think this should make that pain much more manageable.

---

These are my thoughts so far. On the development side of things, my focus is going to be creating a minimal POC that works for a default tailwind config. This is the first time using Rust so it's enough to keep me busy for a while :P

Feedback is super welcome though, I'd like to polish these ideas so that I can be confident when it's time to implement the advanced features.

[ematipico]

Tailwind CSS class sorting -> class sorting

Unfortunately I can't venture an opinion because I don't know much of the logic we are about to implement. Surely, I am a big fan of consistency, so it's definitely a good start.

Approach

What are the JSON snippets that you shared? I miss some context even though I read the previous messages.

Variants

I don't understand the context of this, can you expand a bit please?

Manual configuration

I would suggest a different approach. I like having a separated package that does the work, and I think we can also have it under our organization, maintained by some volunteers.

The package should return a JSON file via stdout, and then we can use this package in our command biome migrate The command can read the result of this package via stdout, and use it to update the configuration file. Here's why:

• Biome has already a parser and deserialiser for biome.json, let's use it.
• By using our internal deserializer, we can catch errors from the package very early.
• The package stays slim, and doesn't require any parser/regex to update the biome.json.
• Other tools shouldn't mess with biome.json. Using Biome itself is more trustworthy.

[tcoopman]

• Honestly, I think options like prefix are largely unused so I don't think it's a big deal.

This comment is not completely clear to me. Does this mean that you won't provide support for prefixes or that they'll have to be specified in the biome config?

[DaniGuardiola]

@tcoopman the latter. In any case, the plan is to provide an automated way to update the config, and I'd expect that to be the most popular way to use this, so it's even less of a big deal.

[XiNiHa]

I wonder if it'd be possible to support UnoCSS transformer features like variant groups...

[johnpyp]

It might also be useful to look at https://github.com/avencera/rustywind, as this is a pure rust implementation of tailwind sorting which also doesn't look at the tailwind.config.js file afaict

an interesting approach it takes is optionally configuring the sort order based on the output css file of tailwind, not sure if that would really be applicable here though

[DaniGuardiola]

@XiNiHa it's possible, but it's a bit out of scope for now. Maybe in a future iteration.

@johnpyp thanks for the suggestion. I'm already very familiar with how Tailwind CSS sorting works, and an initial version is about to merge with only a couple of details missing, so there's no value in researching other projects anymore at this stage. Fwiw, I did take a look around that project but ended up using Tailwind CSS itself as the source of truth, which I believe is the best way to ensure correctness.

[GustavoBonfimS]

Could this rule be a safe action? Today we can only organize classes using --apply-unsafe. If it were a safe rule it could be automatically organized with the VS Code extension when the file is saved.

#1714

[vgseven]

add support for rules for un-supported or invalid class of tailwind, inspired by eslint-plugin-tailwind

[lobosan]

Hi, I'm migrating my Astro project to Biome 1.8.3, and I love the simple setup, the only thing remaining for me is Tailwind class sorting.

This is my biome.json

{
  "$schema": "./node_modules/@biomejs/biome/configuration_schema.json",
  "css": {
    "formatter": {
      "enabled": true
    },
    "linter": {
      "enabled": true
    },
    "parser": {
      "cssModules": true
    }
  },
  "files": {
    "ignore": [".astro", "dist", "node_modules"]
  },
  "formatter": {
    "formatWithErrors": true,
    "indentStyle": "space",
    "lineWidth": 100
  },
  "javascript": {
    "formatter": {
      "arrowParentheses": "asNeeded"
    }
  },
  "linter": {
    "rules": {
      "nursery": {
        "useSortedClasses": "error"
      }
    }
  }
}

This is my settings.json for VSCode

{
  "editor.codeActionsOnSave": {
    "quickfix.biome": "explicit",
    "source.organizeImports.biome": "explicit"
  },
  "editor.defaultFormatter": "biomejs.biome",
  "editor.formatOnSave": true
}

However, when I run
npx @biomejs/biome check --unsafe

I don't see any error in my .astro file that has the invalid example of the documentation
<div class="px-2 foo p-4 bar" />

Can someone please help me to fix the issue? Also, ideally I would love to sort the classes when saving.

[Trombach]

Hi, I'm migrating my Astro project to Biome 1.8.3, and I love the simple setup, the only thing remaining for me is Tailwind class sorting.

This is my biome.json

{
  "$schema": "./node_modules/@biomejs/biome/configuration_schema.json",
  "css": {
    "formatter": {
      "enabled": true
    },
    "linter": {
      "enabled": true
    },
    "parser": {
      "cssModules": true
    }
  },
  "files": {
    "ignore": [".astro", "dist", "node_modules"]
  },
  "formatter": {
    "formatWithErrors": true,
    "indentStyle": "space",
    "lineWidth": 100
  },
  "javascript": {
    "formatter": {
      "arrowParentheses": "asNeeded"
    }
  },
  "linter": {
    "rules": {
      "nursery": {
        "useSortedClasses": "error"
      }
    }
  }
}

This is my settings.json for VSCode

{
  "editor.codeActionsOnSave": {
    "quickfix.biome": "explicit",
    "source.organizeImports.biome": "explicit"
  },
  "editor.defaultFormatter": "biomejs.biome",
  "editor.formatOnSave": true
}

However, when I run npx @biomejs/biome check --unsafe

I don't see any error in my .astro file that has the invalid example of the documentation <div class="px-2 foo p-4 bar" />

Can someone please help me to fix the issue? Also, ideally I would love to sort the classes when saving.

Biome can't yet parse the html template section of Astro files, so nothing gets formatted/linted in there, including class names. THis will only work once biome has full support for Astro files

[MarkLyck]

After upgrading to biome 1.9.0 the Quick Fix for sorting the classes stopped working for me.

Downgrading back to 1.8.2 worked, and I can quick fix my classes sorting again.

[ematipico]

@MarkLyck update to 1.9.1. That issue was reported already and fixed.

[ematipico]

Hi all,

Implementing the issue is going slower than we wished, but that's open source, right? We're struggling to find people who have in-depth knowledge of the domain (tailwind) and coding skills (Rust)—of course, and time, too.

We want to try a different experiment this time. We are still determining if it will work, but at worst, we won't make any progress.

If you have in-depth knowledge of at least one of the missing features you require (check the first comment of the issue), and you have time and will to help the project, we would ask you the following:

• Create an issue that is linked to this one. In the issue, you will be able to explain to us maintainers the feature to implement, as much technical as possible, as extensive as possible. Ideally, you'd want to define a potential algorithm for implementing the feature. Spare no details.
• Add invalid use cases paired with the expectations of the rule. The more use cases you provide, the better. We will use these use cases inside our test suite. Here's an example:

   // use case 1
  - "class-1 class-3 class-4"
  + "class-4 class-3 class-1"
   // use case 2
  - "class-1 class-3 class-4"
  + "class-4 class-3 class-1"

• One of the maintainers will ask you questions, and pick up the task. If you want, you can also be involved in the review of the task, but it's not mandatory. As long as you match the expectations of the use cases you provide, we should be good.

Note

I increased the task pledge to 1k USD. This is a mastodontic task that requires a lot of work. Also, 70% of the bounty will be distributed to the contributors. Unfortunately, Polar seems buggy and can't update the issue badge, but you can check the link of the page to confirm.

Important

If you decide to help us, and you have extensive knowledge about a topic, you leave a comment here to notify possible other contributors who want to help with the same topic. We want to try to avoid double issues, so you can collaborate on the same issue.

[silvenon]

Regarding submitting test cases, will the initial goal be to pass prettier-plugin-tailwindcss's own test suite, or is the approach alternative to that?

Btw, once I donated more to the issue Polar updated the increased task pledge as well in the card 🥳

[ematipico]

Regarding submitting test cases, will the initial goal be to pass prettier-plugin-tailwindcss's own test suite, or is the approach alternative to that?

Btw, once I donated more to the issue Polar updated the increased task pledge as well in the card 🥳

@silvenon Yes. It's my understanding that the correct ordering of classes is crucial in certain cases, so yes, we should match their testing suite

[DaniGuardiola]

@ematipico I'd be happy to do this, fwiw. I had a call a while back with @lutaok where I basically did that, going very deep into the details of every item in the list. I think a format that would work is if I record a video while sharing my screen, so I can explain everything properly.

Typing would take me potentially weeks, but I can sit down and do a ~2 hour recording (what our call approximately took) going over everything. Would that help?

[ematipico]

@DaniGuardiola that's also another viable option, feel free to help. However, we still need to have valid and invalid cases for each feature that we must have, so we have some sort of harness.

[pvinis]

This rule is great, but it should also trim whitespace. So no spaces at the start of the line, no spaces at the end, and only one space between each classname.

[silvenon]

I'm guessing fixtures for handling whitespace are already included in prettier-plugin-tailwindcss' s test suite.

Note that this issue is for coordinating work on this rule, not reporting problems, read #1274 (comment) for info on how to submit a detailed issue about what this rule is currently not doing, but you believe should.

[DaniGuardiola]

@pvinis it already does this, whereas the original prettier plugin respects the original whitespace. This is something that might be worth reverting though, or making optional. I haven't given it that much thought, but there might be a good reason to leave whitespace intact.

[Axelb90]

@pvinis it already does this, whereas the original prettier plugin respects the original whitespace. This is something that might be worth reverting though, or making optional. I haven't given it that much thought, but there might be a good reason to leave whitespace intact.

Hey is not clear for me if you are planning to revert or to make it optional the white space functionality? Is it possible to know for when is this planned?

I'm doing a refactor to a project and there are a lot of literals that cause error when running biome because the space is removed and then all became a big string 😄 . Thanks in advice I love using this tool

[pvinis]

for what it's worth, I like whitespace being time automatically for me.