[MVP] Bundle CSS modules

[evanw]

I want esbuild to demonstrate that it's possible for a normal web development workflow to have high-performance tools. I consider bundling CSS modules a part of my initial MVP feature set for esbuild since some form of CSS modularity is essential for a large-scale web app and I find CSS modules an elegant solution. This issue tracks the CSS module bundling part of my MVP.

At the bare minimum, importing a CSS file should ensure it's included in the bundle. I plan to also implement CSS modules, which makes CSS selector names local to the file and allows JavaScript to import the selector names as strings.

There are interesting extensions to think about once I get everything working. Tree shaking of unused CSS is an optimization that seems worth exploring, for example. That should be possible with CSS modules since unused imports correspond to unused CSS.

[eberkund]

Would this include font files, or is that a separate task?

[evanw]

Binary resources that don't need to be parsed such as PNG, JPEG, and font files are all the same to a bundler. Fonts don't need to be special cased as far as I'm aware. I think the existing loaders such as dataurl and file should cover fonts.

[evanw]

I'm starting to work on CSS support. I just landed a basic parser and AST, and will be working on integrating it into the build system next.

Note that I'm not planning to support the full CSS ecosystem with this feature. Today's CSS is a very diverse ecosystem with many non-standard language variants. This is possible in part due to the fault-tolerant nature of CSS. I'm imagining this feature as mainly a "CSS linker" that is responsible for the critical parts of joining CSS files together and removing unused CSS code. The CSS parser will be expecting real CSS for use with browsers. Non-standard extensions may still be parsed without syntax errors but may be passed through unmodified (e.g. not properly minified or renamed) since they aren't fully understood by the parser. It should be possible to use syntax extensions (e.g. SASS) with a plugin that transforms the source code before esbuild reads it.

[LarsDenBakker]

@evanw that's great to hear! There are different kinds of CSS modules out there, and there is also ongoing for a web standard for CSS modules (see whatwg/html#4898 and https://github.com/tc39/proposal-import-assertions). WIll esbuild allow specifying which variant to use?

[nitsky]

@evanw will the CSS feature inline the minified CSS in the javascript bundle or emit it as a separate file? While inlining is a good fit for client rendered applications, it is not ideal for server or static rendered applications. Ideally, esbuild would emit a number of CSS chunks, and the metafile would detail which CSS chunks correspond to each javascript entrypoint. A server or build tool would then be able to add references to the CSS for each page using <link> tags in the HTML it generates.

[evanw]

https://github.com/tc39/proposal-import-assertions

Import assertions seem unrelated to CSS to me. They just look like a way to tell the runtime what the file type is. Bundlers already have a way of doing this: they just use the file extension without needing an inline annotation, so this information is not necessary for bundlers.

whatwg/html#4898

This seems like an API to inject normal CSS inside a shadow DOM element? It looks like it would just be normal CSS as far as the bundler is concerned.

The CSS module implementation I'm thinking of adopting is the original one: https://github.com/css-modules/css-modules. Specifically, the use of local-by-default names, the :local and :global selectors, the composes declarations, and being able to import local names as strings in JavaScript.

will the CSS feature inline the minified CSS in the javascript bundle or emit it as a separate file?

It will be in a separate file. I believe this is the current expected behavior. It's how Parcel works, for example. I was not considering inlining it in the JavaScript code. I am also planning on having code splitting work the same way across JavaScript and CSS files.

[LarsDenBakker]

I listed import assertions just to indicate that there will be a standard way to import non-JS files.

The idea for the standard CSS modules is that they will return an instance of CSSStyleSheet (https://developer.mozilla.org/en-US/docs/Web/API/CSSStyleSheet and https://developers.google.com/web/updates/2019/02/constructable-stylesheets). So a "polyfill" would instantiate it with the css text. Shadow roots have a nice API for using those stylesheets, but they're not necessarily coupled to it. Hope fully it will be adopted more broadly.

My main concern is about what's enabled by default in esbuild, so far most (all?) things require an explicit opt-in which I think is important.