10up / 10up-toolkit

Official 10up asset building toolkit.
114 stars 19 forks source link

Bundle PostCSS Global Data Plugin with default configuration #389

Closed fabiankaegy closed 6 months ago

fabiankaegy commented 6 months ago

Related Issue/RFC: #340

Description of the Change

This change makes it possible to share one global configuration for things like custom breakpoints, selectors, mixins etc between all CSS entrypoints of a project.

Especially with the introduction of block specific stylesheets one common issue is that the global elements such as @custom-media definitions are not shared across all these individual entrypoints. This leads to unintended breakages when an engineer uses these variables thinking they will work just as expected from the main CSS file. But in reality this causes the styles to be broken because they cannot read the mixin that is only defined in the other entrpoint.

With this change both the custom media etc definitions, and any mixins get a new location in the theme located at ./assets/css/globals/ & ./assets/css/mixins/. All the .css files nested in that folder or any nested folders will now automatically get loaded and shared for all entrypoints.

These folders are configurable at the project level via either the paths.config.js file or the paths key in the 10up-toolkit object of package.json files. This flexibility to customize the paths also makes it possible to reference the folders of the theme in a plugin for example if you are developing a feature plugin that contains CSS and need to reference the themes media queries for example.

[!NOTE] This will require a change in the wp-scaffold once this has been released. I've created a draft PR for it https://github.com/10up/wp-scaffold/pull/228 However, this is not a breaking change :)

Alternate Designs

Initially, I wanted the globals to live outside of the theme folder at the monorepo root level to make it more clear that these elements are shared across all instances. But I think this here with the ability to customize it is the better experience.

Possible Drawbacks

This is a slight change in the development process that will need to be explained to the team. But it should be very nondisruptive.

Verification Process

The bundled sample theme project has been updated to use this new approach. Running the build in the theme directory will result in the mixins & globals getting applied both to the dist/css/frontend.css and the dist/blocks/example-block/style.css files.

Checklist:

changeset-bot[bot] commented 6 months ago

🦋 Changeset detected

Latest commit: 054ae44c3c95e40ca1caebd3b75b16fa204c8859

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package | Name | Type | | ------------ | ----- | | 10up-toolkit | Minor |

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR