[Feature Proposal] A way for plugins to mutate the theme

[benface]

By "mutate the theme" I mean add utilities on top of the ones that are already defined by the user. You can already create utilities in the same "namespace" as a core plugin, like this:

addUtilities({
  '.w-container': { width: containerWidth, },
});

...but .w-container and its variants will be inserted in a completely different place as the other width utilities in the final CSS:

[user-defined width utilities]
[variants of user-defined width utilities such as hover, active, children, etc.]
[user-defined height utilities]
[variants of user-defined height utilities]
...
[plugin-defined width utilities]
[variants of plugin-defined width utilities]

...which matters if you're using variants that depend on the CSS order rather than specificity.

Having a way for a plugin to add a value to a core plugin (in this case, width) would maintain the expected CSS order for each property:

[all the width utilities]
[variants of all the width utilities]
[all the height utilities]
[variants of all the height utilities]
...

Another argument for this is if a core plugin ever changes its class names, say from w- to width-, plugins that add width values won't have to be updated. They will automatically follow the new format.

I suppose I don't have a strong use case for this, and it's possibly a lot of work to support something like this in the current architecture, so maybe it's not worth it. Just thought I'd throw the idea out there.

[bradlc]

I kind of like the idea of allowing plugins to mutate the config. Among other things, this would allow you to do what you’ve described above:

module.exports = {
  plugins: [
    // mutate directly?
    function({ config }) {
      config = {
        ...config,
        width: {
          ...config.width,
          container: '1280px'
        }
      }
    },
    // ... or use a function?
    function({ extendConfig }) {
      extendConfig('width', {
        container: '1280px'
      })
    },
    // ... or use the return value as a config merge?
    function() {
      return {
        width: {
          container: '1280px'
        }
      }
    }
  ]
}

These are just some ideas for how it could work. What do you think @benface?

A use-case that I was originally thinking of was something like a color palette plugin. You would give it some base values and it would add the resulting palette to config.colors for you (which would then be used across backgroundColors, borderColors etc. if you have some self-referencing set up)

[benface]

I hadn't thought about it this way @bradlc, but what you're suggesting makes a lot of sense. It's more flexible than what I had in mind, but I'm guessing easier to implement. I like your first two propositions; I'm not a fan of automatically merging whatever is returned because I don't think that's obvious enough (most plugins probably don't want to mutate the config). I think the first one would be a breaking change because config already exists and is a function to look up a value, but I really like it. It would allow a plugin to decide whether it wants to overwrite a utility if it's already defined by the user, or whether the user's utilities should have precedence, which I wasn't sure how Tailwind should handle. I don't know if it's too powerful, but I think it's a great idea.

[adamwathan]

I wonder if this problem would be solved pretty well by coincidence by implementing #677? The idea being that instead of adding a plugin to augment the default theme config, you would just extend that config, and it could be something you pull in from npm no problem.

We could even make it possible to extend multiple configs, so each one could only make a small amount of changes:

module.exports = {
  extends: [
    require('tailwindcss/default-config'),
    require('@benface/tailwind-extend-spacing'),
    require('@benface/tailwind-extend-cursors'),
  ],
  theme: {
    // ...
  }
}

Would this check all the boxes?

[benface]

@adamwathan I suppose it would! I guess my "plugin" would be something you add to the extends key rather than the plugins key, and it would return an object containing a plugin (in a plugins key) and some theme values haha. Does that make sense?

[adamwathan]

@benface Would you actually need a plugin at all? My understanding is you are just trying to add values to theme.extends yeah? Unless you are creating brand new utilities in a new namespace, you wouldn't need a plugin unless I'm misunderstanding 👍

[benface]

@adamwathan Oh, sorry, I thought I gave more details in my first post but I guess I removed all the superfluous stuff. This is for this plugin: https://github.com/benface/tailwindcss-fluid-container. First and foremost it adds a component, so it really needs to be a plugin, but it also adds some related utilities, so it will need to be added to the extends key, if that's implemented. To be clear, would having a plugins key in an object passed to extends be supported?

[adamwathan]

@benface Ah yeah with that example you're right I think it makes more sense to make it possible for plugins to mutate the theme. Not sure about the best way to do that because a plugin that mutates the theme would need to run before Tailwind's core plugins. I have some ideas but I don't think it'll be a 1.0 thing.

With the extends idea, in my head that would include plugins too, yeah 👍🏻

[benface]

Cool thanks @adamwathan :)

[benface]

As highlighted by a user of my tailwindcss-transitions plugin here, it is currently not possible for a user to extend a plugin's default theme with the extend key like one might expect. That's a different, and perhaps even more interesting use case for allowing plugins to mutate the theme. Something like @bradlc suggested would be awesome if possible:

function({ extendTheme }) {

  extendTheme('transitionProperty', {
    'none': 'none',
    'all': 'all',
    'color': 'color',
    'bg': 'background-color',
    'border': 'border-color',
    'colors': ['color', 'background-color', 'border-color'],
    'opacity': 'opacity',
    'transform': 'transform',
  });

  const propertyTheme = theme('transitionProperty');

  // propertyTheme would be set to the default properties defined above,
  // possibly replaced by the user's theme.transitionProperty if it exists,
  // and merged with the user's theme.extend.transitionProperty

  // ...
}

[adamwathan]

I think this is reasonable and shouldn't be too hard to implement. Off the top of my head it probably means doing one pass through all of the plugins to sort of "collect" all of the operations they want to perform, then executing those operations in the necessary order.

So for example we'd run all of the extendTheme calls together in the first batch, then we could run all of the addBase calls, then the addComponents calls, then the addUtilities calls, vs. right now where we run all of the operations from a single plugin, then all of the operations from the next plugin, etc.

Would accept a PR for this or I can look at trying to implement it in the coming months.