TailwindCSS SDK

[bstro]

tldr

provide a script that generates Typescript typings from a user's tailwind.config.js into a project. It is important for this type information to be provided by the tailwindcss project itself, for reasons described later. The typings could look something like this, for every category of Tailwind utility:

export type BackgroundOpacity =
  | 'bg-opacity-0'
  | 'bg-opacity-5'
  | 'bg-opacity-10'
  | …

Background

I've used TailwindCSS fairly extensively both professionally and personally and really enjoy using it. I think one thing that could help the community and developer tool ecosystem to flourish could involve some kind of Typescript SDK. This post is not intended to be prescriptive but rather to share some ideas I've had, and perhaps spark imagination/discussion.

Design systems that use a style props API have an advantage in typescript environments because style prop declarations can be proven correct at compile-time.

Tailwind's VSCode extension confers some of the benefits of type safety (by offering hints when providing classnames to components) but will not warn against incorrect tailwind strings (imo this choice makes sense in the context of a vscode extension). It looks difficult to add typesafety around tailwind classname strings, though there are valiant efforts:

• https://github.com/muhammadsammy/tailwindcss-classnames — This gets the closest to what I'm looking for. tailwindcss-classnames generates type information and runtime helpers (typed wrappers for the classnames library) for each TailwindCSS class. One major problem is that it does not support stacked pseudo states. TW.backgroundColor('focus:border-yellow-500') typechecks correctly, but attempting to use TW.backgroundColor('dark:focus:border-yellow-500') would yield a type error because tailwindcss-classnames generates classes for only one state. This makes sense: generating TS unions for every possible permutation of pseudo states is far too much for typescript to handle. I have an idea for a potential workaround and included it as a footnote at the end of this post.
• https://kimmo.blog/posts/6-advanced-typescript-the-ultimate-tailwind-typings/ — this is an interesting solution but it can only let the user know that they've used a valid tailwind classname. Moreover, the generated types don't have any information about what category the classname belongs to. In effect, it is really only useful at build/compile-time, which is more limiting in terms of the tooling that can be built on top of it.

The idea

I think it could be worthwhile to consider offering a first-party Typescript SDK that (like tailwindcss-classnames) generates type information as well as runtime helper functions for each category of utility classes that Tailwind exposes, as well as functions/utilities for making it easier to interact with Tailwind within a typescript stack. If it were offered as a first-party Tailwind library, it would likely be easier to keep it in sync with updates to the Tailwind system and it could help the community plugin ecosystem to flourish in interesting, emergent ways.

To illustrate, I've built one such tool based on tailwindcss-classnames that allows me to use Tailwind with a typesafe chained api built with a proxy object that passes arguments through to the previously mentioned typed classnames library:

const {className} = tw.backgroundColor(props.variant === 'primary' ? "bg-indigo-500" : "bg-zinc-800")
                      .padding("px-3", "py-2")
                      .textColor("text-white")                      
                      .borderRadius("rounded")

The strings passed to each method in this chain are typechecked. This proxy-based API allows me to store the classname strings in a data structure according to their associated css property. In my project, I was able to leverage this information and build out a style overrides system. Having access to this kind of information at build- and run-time has proven incredibly useful. I'd like to release this tool soon as an npm package. This API in particular also has a nice bonus in that, for new tailwind developers, it leverages existing knowledge about css properties/keywords and guides them by narrowing the possible values accepted by the type.

Why not just keep using tailwindcss-classnames?

As mentioned, the library tailwindcss-classnames accomplishes a lot of what I'm looking for. The main benefits of having something like this provided by the tailwindcss org might include the following:

• encourages a rich developer tooling ecosystem. by exposing types that match tailwind utility classes, and by organizing those types into unions by utility category, developers can build rich, typesafe tools on top of Tailwind to match the kinds of developer experiences offered by style-props api's.
• as nice as it is, tailwindcss-classnames doesn't have perfect coverage. It's missing types here and there. This kind of slippage could be avoided by a first party offering.
• as mentioned, it doesn't support stacked variants like dark:hover:…

Footnote: API idea

This idea uses the API of tailwindcss-classnames to help illustrate the idea. I'm including it here because I think its possible that any typed SDK for tailwind might possibly end up with the same "type explosion" problem when trying to generate types for all possible variants of tailwind classes. My idea:

I'll start with an example for how a potential workaround for the permutation explosion problem might look: TW.backgroundColor<'dark', 'focus'>('dark:focus:border-yellow-500') — the idea here is that typescript would generate the valid classes based on the generics provided to the helper function. The tricky thing here is that the helper function would likely need to validate all possible permutations of the generics provided, including a case in which no generics are used at all. So with the above usage example, the valid classnames would consist of the following:

  border-X-Y
  dark:border-X-Y
  dark:focus:border-X-Y

^ where X is all valid color values as defined in by tailwind.config.js and where Y is all valid color shades. Here's a more complicated example of the call signatures the type would need to allow:

  TW.backgroundColor<'dark', 'focus'>('border-zinc-900', 'dark:border-transparent', {
    'dark:focus:border-yellow-400': !isDisabled
  })

I'm not 100% in love with this idea because I think the TS ergonomics are a little weird/unexpected, but it's the best I've come up with so far.

Thanks for reading!

[sentience]

I'm not sure I understand the limitation you describe with the second solution. Are you saying that it correctly errors on invalid class names, but it cannot provide autocompletion for valid class names?

[bstro]

I'm not sure to which point you are referring—if its the part about the vscode extension limitations, then yeah, the vscode extension is only able to offer hints for valid tailwind classes, but won't tell you if you've made a typo while writing a tailwind class name. This is desirable in the context of a vscode extension, where one may not always be using tailwind classes in side a className declaration.

Let me know if you meant something else!