StepContainerV2: Migrate to CSS modules

[zaguiini]

Proposed Changes

Migrates StepContainerV2 to CSS modules instead of static CSS class names to prevent overrides.

On several occasions, we observed PRs trying to achieve visual goals by modifying the wireframe or container styles. This isn't supposed to be like that. If we let these changes in, then the whole purpose of StepContainerV2 (consistency, predictability, composability) goes down the drain.

This PR changes from static CSS to CSS modules to prevent class names and avoid such scenarios. It does so by modifying the Webpack configuration so it supports .module.scss files and generates class names, even on the server, as some wireframes (Loading and, very soon, CenteredContentLayout) are rendering styles on the server.

This will also make #102503 irrelevant, as the problem this PR solves will solve that one as a side effect.

Reviewing this PR

@Automattic/team-calypso, you can disregard all changes within packages/onboarding. The meat of this PR is within packages/calypso-build/webpack/sass.js and client.

Before, the server bundle processing completely ignored CSS. Now, both SSR and CSR modes include CSS processing and extraction. Why were we not doing that before? Is there anything we should do differently?

Testing Instructions

Ensure you see no layout shifts and that the steps are properly applied when entering /setup, including the centered loading bar and the WordPress logo at the top-left corner.

[github-actions]

Calypso Live (direct link)

https://calypso.live?image=registry.a8c.com/calypso/app:build-142833

Jetpack Cloud live (direct link)

https://calypso.live?image=registry.a8c.com/calypso/app:build-142833&env=jetpack

Automattic for Agencies live (direct link)

https://calypso.live?image=registry.a8c.com/calypso/app:build-142833&env=a8c-for-agencies

[matticbot]

Here is how your PR affects size of JS and CSS bundles shipped to the user's browser:

App Entrypoints (~543 bytes removed 📉 [gzipped])

name                    parsed_size           gzip_size
entry-stepper               +3595 B  (+0.2%)     +395 B  (+0.1%)
entry-login                 +1358 B  (+0.1%)     -886 B  (-0.1%)
entry-subscriptions          -101 B  (-0.0%)      -22 B  (-0.0%)
entry-domains-landing        -101 B  (-0.0%)      -22 B  (-0.0%)
entry-dashboard-dotcom       -101 B  (-0.0%)      -22 B  (-0.0%)
entry-dashboard-a4a          -101 B  (-0.0%)      -22 B  (-0.0%)
entry-browsehappy            -101 B  (-0.1%)      -22 B  (-0.0%)
entry-reauth-required         -38 B  (-0.0%)    -1154 B  (-0.2%)
entry-main                    -38 B  (-0.0%)    -1152 B  (-0.2%)

Common code that is always downloaded and parsed every time the app is loaded, no matter which route is used.

Sections (~4310 bytes added 📈 [gzipped])

name                        parsed_size           gzip_size
checkout                        +4211 B  (+0.2%)     +638 B  (+0.1%)
a8c-for-agencies-client         +4211 B  (+0.2%)     +622 B  (+0.1%)
async-step-unified-domains      +3620 B  (+0.2%)     +420 B  (+0.1%)
async-step-unified-plans        +3064 B  (+0.3%)     +150 B  (+0.1%)
marketplace                     +2136 B  (+0.3%)     +366 B  (+0.2%)
stepper-user-step               +1810 B  (+0.2%)     +355 B  (+0.2%)
async-step-use-my-domain        +1691 B  (+0.3%)     +322 B  (+0.2%)
signup                          +1648 B  (+0.6%)      +21 B  (+0.0%)
gutenberg-editor                 +108 B  (+0.0%)      +44 B  (+0.0%)

Sections contain code specific for a given set of routes. Is downloaded and parsed only when a particular route is navigated to.

Async-loaded Components (~9082 bytes removed 📉 [gzipped])

name                                             parsed_size           gzip_size
async-load-calypso-blocks-editor-checkout-modal      +4108 B  (+0.3%)     +582 B  (+0.2%)
async-load-signup-steps-domains                      +3632 B  (+0.3%)     +694 B  (+0.2%)
async-load-signup-steps-plans-theme-preselected      +3579 B  (+0.7%)     +833 B  (+0.5%)
async-load-signup-steps-plans                        +3444 B  (+0.7%)     +660 B  (+0.4%)

React components that are loaded lazily, when a certain part of UI is displayed for the first time.

Legend

What is parsed and gzip size?

Parsed Size: Uncompressed size of the JS and CSS files. This much code needs to be parsed and stored in memory.
Gzip Size: Compressed size of the JS and CSS files. This much data needs to be downloaded over network.

Generated by performance advisor bot at iscalypsofastyet.com.

[aduth]

Related effort to introduce CSS modules: #103004 (cc @mirka)

[aduth]

Could/should we still ignore everything except files suffixed with .module.scss ?

Why were we not doing [server-side CSS processing and extraction] before? Is there anything we should do differently?

I'm not sure exactly why we would have needed to do it previously. Am I correct in understanding that it's required now so that the server can generate the computed class names in the server-rendered markup? Since we would have previously had static class names, I would suppose that's the reason we wouldn't need to process the stylesheets. I'd imagine there's also a performance overhead in doing so, at least in contrast with ignoring them altogether.

[zaguiini]

Could/should we still ignore everything except files suffixed with .module.scss ?

Interesting. I think that would help with performance.

Am I correct in understanding that it's required now so that the server can generate the computed class names in the server-rendered markup?

Yes, that is exactly why. The class names must match both in the client and the server-generated markup.

[aduth]

What are we trying to achieve with this behavior?

[zaguiini]

This is needed for deterministic class name generation between the server and the client, since each Webpack entry processes its own chunk.

[aduth]

This is needed for deterministic class name generation between the server and the client, since each Webpack entry processes its own chunk.

Interesting. That makes sense to me, though I would have thought the default behavior would produce a deterministic identifier as well.

One of the concerns I had is whether this could enable someone to continue targeting external CSS styles at the generated name, and if that's something we'd want to be discouraging.

e.g.

[class^="StepContainerV2_style-module-scss__"] {
  // ...some override
}

Since the default behavior for CSS module class name generation doesn't have anything static to target, it would not be possible.

[aduth]

Do we have any guarantees that this will produce safe CSS names?

[zaguiini]

resourcePath are valid file names, so I'm guessing so.

However, I think we can go with the simpler solution following the hashing in this file:

require( 'crypto' )
    .createHash( 'md5' )
    .update( context.resourcePath + localName )
    .digest( 'hex' )

This seems to be enough.

[aduth]

There are some weird gotchas like not allowing to start with a number which could happen with a file name or a hash value.

Looks like the default behavior has some extra checks to handle this:

https://github.com/webpack-contrib/css-loader/blob/9d030151bb221888ecfb0163b10910a7a918fe31/src/utils.js#L349-L356

[jsnajdr]

Before, the server bundle processing completely ignored CSS. Now, both SSR and CSR modes include CSS processing and extraction. Why were we not doing that before?

The server doesn't need to know any CSS because it's not a part of the markup it outputs. The markup is only HTML/JSX elements, with class names.

The server only needs to know which CSS/JS assets are associated with a certain page (section) like /log-in or /themes. So that it can send the links in <link> and <script> tags in the generated markup. These assets are stored in the build/assets.json file, generated by webpack during the client build. That's where the server finds them when serving a page.

The only reason why the server needs to start caring about CSS now is that the CSS modules export the actual class names. The class name in the server-generated markup is no longer a hardcoded step-container-v2__content-row, but it's styles[ 'step-container-v2__content-row' ] where styles is the CSS module export.

The server continues to not care about the actual content of the CSS rules, it's interested only in the class names.

[zaguiini]

The server continues to not care about the actual content of the CSS rules, it's interested only in the class names.

@jsnajdr so you're saying we should be fine with loading the CSS and generating the class names, but instead of extracting the CSS (MiniCssExtractPlugin.loader), just ignore the output (ignore-loader)?

[jsnajdr]

instead of extracting the CSS (MiniCssExtractPlugin.loader), just ignore the output (ignore-loader)?

Yes, we certainly don't want the server build to output any CSS assets because it won't use them. CSS is built as part of the client build (which is isomorphic to server). And the server then embeds the client CSS assets as <link rel="stylesheet" href="client/url"> elements.

We want webpack to compile CSS modules into something like:

// this is the `style.scss` module transformed into JS:
const styles = {
  'step-container-v2__content-row': 'abcd123',
  'left': 'efgh456',
  'right': 'ijkl789',
}
export default styles;

I.e., export the classnames, but nothing else, particularly not the content of the CSS rules. I don't know right now which configuration of the various CSS loaders achieves this. ignore-loader is maybe too much, we don't want to ignore everything.

We also need to make sure that the generated class names (abdc123) are the same in the server and client build. These are two separate webpack configs and two webpack runs. The hashes and the seeds and whatever else is used to generate the names must be the same in both.

[ciampo]

We also need to make sure that the generated class names (abdc123) are the same in the server and client build.

I guess that would imply:

• using same exact webpack loader configs
• using same exact versions of webpack, loader, and node.js, same env variables
• using webpack deterministic hashing algorithms (ie. using something like [contenthash:base64:8], docs)

[jsnajdr]

I guess that would imply:

@ciampo The hashing algorithm in the css-loader uses three inputs:

• a hashSalt value which is either specified as css-loader option or uses the webpack's "global" value. We'll probably have to set this value explicitly for the server and client builds. Needs to be the same for both.
• a resourcePath value, i.e., the path of the CSS file. We need to ensure the same resource path in both builds. If there is any prefix, for example, specific for one of the builds, it needs to be fixed.
• the local CSS class name.

That means that with little care, we should be able to guarantee identical scrambling both for client and server. We don't need to replicate the entire environment to the last detail. Also, the css-loader hashing is heavily customizable, that works in our favor.