RFC: Bundle PostCSS Global Data Plugin with default configuration

[fabiankaegy]

We are more and more drifting away from having one main CSS bundle in favor of having multiple separate CSS files. In the WordPress context individual blocks may have their own stylesheets or templates have their own ones.

One issue that we manually have to solve on every project individually is how we share global stuff such as media queries, variables, mixins etc. across these different CSS entrypoints.

The @csstools/postcss-global-data plugin aims to solve just that. We should bundle this with toolkit and allow you to place any global shared postcss config files in a specified location in the root of the project. All these files would then automatically get loaded before each entrypoint so that mixins, custom breakpoints, selectors etc. can be shared without having to manually import things into every single file.

[fabiankaegy]

This is related to the conversation in #339 because these individual entrypoints would need this kind of setup to be possible.

[fabiankaegy]

I just ran into 3 separate projects running into issues because this isn't yet handled by toolkit. I think we need to prioritize this as more and more projects are transitioning to code-split CSS per block.

CC: @dainemawer @joesnellpdx @nicholasio @tlovett1

[nicholasio]

This feels like an easy change. Do we need a global folder where we include all of the css files from there or is a entrypoint enough (and other things can be importedfrom that entrypoint)?

[fabiankaegy]

Yeah on a few projects I've manually added a postcss.config.js file that looks something like this:

const baseConfig = require('10up-toolkit/config/postcss.config');

module.exports = (props) => {
	const config = baseConfig(props);

	const newConfig = JSON.parse(JSON.stringify(config));

	const { 'postcss-mixins': postcssMixins, ...otherPlugins } = config.plugins;

	newConfig.plugins = {
		// This ensures that the the media queries are available in the global scope
		// This is needed for the media queries to for example work in the separate CSS files
		// imported by blocks
		'@csstools/postcss-global-data': {
			files: [
				'../../themes/tenup-theme/assets/css/frontend/global/breakpoints.css',
				'../../themes/tenup-theme/assets/css/frontend/global/color.css',
			],
		},

		// This is needed to make the mixins available in the global scope
		// This is needed for the mixins to for example work in the separate CSS files
		// imported by blocks
		'postcss-mixins': {
			...postcssMixins,
			mixinsFiles: ['../../themes/tenup-theme/assets/css/frontend/global/mixins.css'],
		},
		...otherPlugins,
	};

	return newConfig;
};

The problem is that we somehow need to adjust for relative paths between the theme and plugins. If we can even support cross workspace sharing

[joesnellpdx]

@fabiankaegy

Something like this totally makes sense to me. We were struggling with a similar challenges in the initial phases of UI Kit.

I'm curios, though, in regards to this statement:

Please note that PostCSS Global Data does not add anything to the output of your CSS. It only injects data into PostCSS so that other plugins can actually use it.

I assume that means that it does "add" the actual files included in the global data to the head of your CSS - but it does not actually alter any of the CSS compiled as part of the CSS Module. In that case, I'm totally in.

In other words, if I declare a CSS custom property used via global data - I can reference and/or override the custom property in the CSS Module.

I assume @Antonio-Laguna is also on board with this enhancement.

[Antonio-Laguna]

I assume that means that it does "add" the actual files included in the global data to the head of your CSS - but it does not actually alter any of the CSS compiled as part of the CSS Module. In that case, I'm totally in.

No, it does not add any CSS output. You can see this fixture with this rule:

.foo {
	background-color: red;
}

That does not get into the expected result.

This is merely a plugin that aims to load all the needed context for any transformation such as media queries, custom properties, etc so when those plugins run, they can be picked up. They get injected into the AST very early in the process and then evicted right before the output is going to be made.

In other words, if I declare a CSS custom property used via global data - I can reference and/or override the custom property in the CSS Module.

Custom properties are, perhaps, a bad example since we've stopped preserving them and also they're affected by the cascade. In any case, you could have in a global this:

@custom-media --mq-a (max-width: 30em);

And then redefine it if you really wanted to but that would be a bit weird.

I assume @Antonio-Laguna is also on board with this enhancement.

I am!

[fabiankaegy]

My current plan for handling this is to define two new folders inside the assets/css/ directory.

1. globals
   The globals folder is meant to house any files that define custom post CSS features such as @custom-media or @custom-selector
2. mixins
   The mixins folder is meant to house any files that define mixins

As @Antonio-Laguna mentioned neither of these should produce any actual output. They should only define things. Also, the order in which the assets are loaded should not be important. All the files inside these folders get automatically added via a glob.

I initially tried to load an index.css entrypoint in either of these which then manages the importing of the various files. But the imports don't get resolved. Which is why I resorted to glob.