JS API for using @apply in Plugins

[alexlafroscia]

I am working on building out my company's style guide using Tailwind CSS. For abstractions like buttons and inputs, rather than authoring CSS, I am writing a set of Tailwind plugins and a configuration file that our applications can extend from that supplies them. This works better for our application's architecture than writing "normal" CSS to define these custom classes. In case it's relevant, that work can be found here.

One issue that I often run into is that I would like to be able to use @apply when authoring components using the addComponent plugin API. I would be really nice to be able to access the classes that are already defined by Tailwind, rather than manually having to look up values using the theme() function. Especially as our designers get more familiar with Tailwind, they are starting to communicate in terms of the specific classes needed to achieve a design. Without being able to use @apply to access those, a level of manual translation back to the styles behind the class needs to be applied manually before using that as a reference when actually building out our component classes.

Proposal

An idea that I had would be an apply function that is passed as one of the properties on the argument to each plugin function. This apply function would take the name (or names?) of a class and return a JavaScript representation of the styles included when that class is applied.

Example Without Proposal (Current API)

module.exports = function buttonComponentsPlugin({ addComponents, theme }) {
  addComponents({
    '.fluid-button': {
      color: theme('colors.gray.400')
    }
  });
};

Example With Proposed API

module.exports = function buttonComponentsPlugin({ addComponents, apply }) {
  addComponents({
    '.fluid-button': {
      ...apply('text-gray-400')
    }
  });
};

---

For the above examples using text color as an example, the different is minimal. For other, more complex utilities -- like box shadows, for example -- being able to use apply() as a shortcut would be a really considerable clean-up!

Ideally, apply returns an object that matches the same CSS-in-JS syntax that Tailwind Plugins already use when authoring styles. This becomes quite handy, as the spread operator makes composing multiple usages of apply together fairly ergonomic.

addComponents({
  '.fluid-button': {
    ...apply('text-gray-400',
    ...apply('bg-blue-600')
    ...apply('rounded')
  }
})

Why Not Use CSS?

Naturally, a case like ours could be solved by just writing some custom CSS that is processed by PostCSS and itself uses @apply

@tailwind base;
@tailwind components;

.fluid-button {
  @apply text-gray-400;
  @apply bg-blue-600;
  @apply rounded;
}

@tailwind utilities;

However, that leaves this CSS file as an artifact that has to make it's way into the CSS build pipeline for each of our applications, imported from somewhere, etc.

Since Tailwind is already easy to extend with plugins that can add components through the addComponent API, this is a good candidate for a means for us to author our own custom component classes. This JS API for apply just makes this process a lot easier!

Potential Issues

Utility Resolution

It might be challenging to resolve classes within apply if the class being applied is itself inserted by a plugin.

This might not be so bad, however, if classes applied by a "previous" plugin are available to the "next" one. Plugin order might suddenly matter more than before, but I don't know that that would really cause an issue in practice.

It would be impossible to have a kind of "circular dependency" between plugins that apply classes from each other; you would need to extract shared styling to an additional plugin that precedes both of them.

[alexlafroscia]

After a little bit of playing around with the idea to see how it might be implemented, a problem is pretty quickly encountered: there's no real way to exchange a Tailwind configuration for the list of classes that are generated by that configuration, much less the styles themselves applied by each of those classes.

The definition for each style (say, turning your color config and the presence of the backgroundColor plugin) into the actual classes (.bg-blue-400 and friends) happens, itself, as a plugin to Tailwind, within the PostCSS build process. Because the only real artifact of processing the Tailwind configuration is the PostCSS output itself, having an apply syntax as suggested would need to have access to the whole PostCSS style tree up to that point, which does not seem possible in the current plugin architecture.

Thinking about other options, I am wondering if it would be worthwhile to split things up a bit, so that there was

1. A tool that takes a Tailwind configuration and generates the classes (with their CSS output definitions)
2. Another tool that takes this intermediate representation and turns that into an actual output CSS file

(By tools, here, I really just mean JavaScript functions; not whole, unique packages or anything).

I think that something like that would be helpful in many contexts, such as editor auto-complete (which, last time I dug into it, generates and then parses a CSS file internally to read a list of classes to power the auto-complete behavior) or class auto-sorting (which I tried to build, then realized that getting the class list requires compiling the whole PostCSS plugin in a pseudo-file and subsequently gave up on).

[praveenjuge]

Not sure if this is exactly what you want but you can use apply directly with this syntax:

module.exports = function buttonComponentsPlugin({ addComponents }) {
  addComponents({
    '.fluid-button': {
      "@apply text-gray-400": {},
    }
  });
};

But you can't update it from the tailwind.config.js user config which is important for changing plugin styles. So I would also love to see first class support for this.

You can see my button component here.

[nanorepublica]

Thanks for this! This enabled me to create this plugin which allows a declarative approach to CSS class creation within a tailwind config file.

[awebcode]

Not sure if this is exactly what you want but you can use apply directly with this syntax:

module.exports = function buttonComponentsPlugin({ addComponents }) {
  addComponents({
    '.fluid-button': {
      "@apply text-gray-400": {},
    }
  });
};

But you can't update it from the tailwind.config.js user config which is important for changing plugin styles. So I would also love to see first class support for this.

You can see my button component here.

Thanks

[alexlafroscia]

Oh, that's interesting @praveenjuge! Thanks for calling that out!

But you can't update it from the tailwind.config.js user config

What do you mean by this? I interpret that as the plugin not respecting changes to the default Tailwind configuration -- is that the case?

[praveenjuge]

Yes that's what I meant but I just created a new project to check and everything seems to work fine now, whenever I change the color scheme in the tailwind config, the @apply color in the plugin also changes in the latest version.

So I guess there is no problems.

[alexlafroscia]

Huh, cool! It's great that this can be a work-around for the time being!

[irg1008]

Hi!
Do we know if dark: and light: selectors can be used with @apply?
It seems they are not getting recognized has they are not integrated as hover: or focus: are.

[praveenjuge]

@irg1008 The dark selector should work with apply, make sure darkMode is enabled in the tailwind config file.

[minimit]

@praveenjuge thanks for the input. I've a question, does the "@apply text-gray-400": {}, gets purged by purgecss?

[praveenjuge]

yes, point the content option on purgecss to plugin js files and it will purge properly in the production builds

[LarsArtmann]

Thx, it's working awesome! Just finishing my first tailwind plugin

[Coleman453]

Thanks for the information, I will try to figure it out for more. Keep sharing such informative post keep suggesting such post.

Omegle

[asotog]

Is this still not possible in 2023? I faced the same not sure if there is any official alternative

[wongjn]

It is possible in 2023, use @apply as you would in CSS:

addComponents({
  '.my-class': {
    '@apply text-red-500': {},
  },
});

Though Adam Wathan, the creator of Tailwind, does not recommend this: #11012 (reply in thread).

[asotog]

thanks @wongjn will try that, yeah would be nice to see an official alternative

[dennis-NS]

Rather have a way to make it possible then nothing at all. But i wish something was exposed more officially like this proposal

[cabello]

Undocumented but useful, confirmed to also work with addUtilities, example in tailwind.config.cjs

/** @type {import('tailwindcss').Config} */
module.exports = {
  plugins: [
    function ({ addUtilities }) {
      addUtilities({
        ".absolute-center": {
          "@apply -translate-y-1/2 -translate-x-1/2": "",
          position: "absolute",
          top: "50%",
          left: "50%",
        },
      })
    },
  ],
}

Thank you for this thread. 🙇