Miłosz Orzeł

.net, js, html, arduino, java... no rants or clickbaits.

Controlling CSS Module Class Names in Vite

INTRO

A couple of months ago, I've migrated my vim.morzel.net hobby project from Create React App to Vite and noted down a few things that required attention. Recently, while adding dark mode to the same project, I've spotted another difference between CRA and Vite: class names for CSS modules were build differently.

For example, this is what I had in CRA for file named DrillChoiceScreen.module.css and a class named Content:

Class names with CRA... Click to enlarge...

 

and this is what I got for the same thing in Vite:

Class names with Vite... Click to enlarge...

 

Notice that the file name prefix is missing. I preferred having it as it makes it obvious which .module.css contains the styling.

I've spent some time experimenting with Vite config for CSS modules, and logged few observations in case I need to tweak it again in the future, or you need to do it now :)

 

CONFIG FILE

As usual with Vite, the configuration happens in vite.config.ts, which is automatically added when you start a new project with npm create vite@latest command. This is how the fresh file looks like (at least for React/TypeScript+SWC in Vite 5.2.0, with semicolons added - cause I like 'em):

import { defineConfig } from "vite";
import react from "@vitejs/plugin-react-swc";

// https://vitejs.dev/config/
export default defineConfig({
  plugins: [react()],
});

And this is how it looks after adding a css.modules configuration to make the file name appear in generated CSS module class names:

import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react-swc';

// https://vitejs.dev/config/
export default defineConfig({
  plugins: [react()],
  css: {
    modules: {
      generateScopedName: '[name]_[local]_[hash:base64:5]'
    }
  }
});

 

STRING PATTERN

Providing string pattern to generateScopedName property (as shown above) is the easiest way to affect generated class names. Vite uses postcss-modules (by default, but there's experimental support for Lightning CSS, configured differently). The interpolated string supports multiple placeholders which are described here.

While using the string was easy, the [name] pattern produces full name of the file. I name my CSS modules in this way: for component Example.tsx the styling goes to Example.module.css. Having "module" in class name was a bit annoying...

Fortunately, the generateScopedName can also take a function that gives a lot of control over the generated names.


CUSTOM FUNCTION

Below you can see an example of generateScopedName function config that creates class names containing: custom prefix _m, file name, class name and a line number.

This is based on example from postcss-modules docs but tweaked slightly to give more descriptive parameter names and to handle both Unix (LF) and Windows (CRLF) line endings.

For Example.module.css file and a MyClass class from line 10, it produces: m_Example_MyClass_10 as generated class name. 

import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react-swc';
import path from 'path';

// https://vitejs.dev/config/
export default defineConfig({
  plugins: [react()],
  css: {
    modules: {
      generateScopedName: (className, filePath, css) => {
        const classNameIndex = css.indexOf(`.${className}`);
        const lineNumber = css.substr(0, classNameIndex).split(/\r?\n/).length;
        const fileName = path.basename(filePath, '.module.css');
        const prefix = 'm_';

        return `${prefix}${fileName}_${className}_${lineNumber}`;
      },
    }
  }
});

When deciding on a class name, it's important to remember that it should not start with a digit. Best to always include some prefix (can be as simple as an underscore). Watch out especially if you would like to have the name started with content hash (nothing worse than a flaky issues caused by some hashes starting with a digit).

Speaking of prefixes and hashes: the css.modules has a hashPrefix property, but mind that it doesn't control what's prepended to the class name. It affects the computed hash value which you can include in the string version of generateScopedName with the [hash] pattern. 

This is how a function that includes hash of CSS (full module file content) could look like (provided that import crypto from 'crypto'; is added):

generateScopedName: (className, filePath, css) => {
  const classNameIndex = css.indexOf(`.${className}`);
  const lineNumber = css.substr(0, classNameIndex).split(/\r?\n/).length;
  const fileName = path.basename(filePath, '.module.css');
  const prefix = 'm_';

  const hash = crypto.createHash('sha1').update(css).digest('hex').substring(0, 4);

  return `${prefix}${fileName}_${className}_${lineNumber}_${hash}`;
}

The crypto module contains tones of options, but for the purpose of content hash suffix simply taking a few characters from SHA-1 hex representation should be ok.

 

DEV AND RELEASE NAMES

As show earlier in this post, the defineConfig function can take an object that describes the configuration, but it can also take a function. Vite docs call it conditional config. The function receives and object with a couple of properties, one of them is command. Using this property you can distinguish between running the app locally while developing (npm run dev) and building for release (npm run build).

Here's an example of conditional config that uses hashes for class names for build and much longer and more descriptive names for development:

export default defineConfig(({ command }) => {
  return {
    plugins: [
      react(),
    ],
    css: {
      modules: {
        generateScopedName: (className, file, css) => {
          const classNameIndex = css.indexOf(`.${className}`);
          const lineNumber = css.substr(0, classNameIndex).split(/\r?\n/).length;
          const fileName = path.basename(file, '.module.css');
          const prefix = 'm_';

          let result;

          if (command === 'build') {
            const hash = crypto
              .createHash('sha1')
              .update(className + lineNumber + css)
              .digest('hex')
              .substring(0, 8);

            result = `${prefix}${hash}`;
          } else {
            const hash = crypto.createHash('sha1').update(css).digest('hex').substring(0, 4);
            const combined = `${prefix}${fileName}_${className}_${lineNumber}_${hash}`;

            result = combined.replace(/(?<=^.+_)Top_\d+_/, '');
          }

          return result;
        }
      }
    }
  };
});

Notice that the hashed value for command === 'build' combines the class name, line number and CSS. In the else branch (development) just the CSS is hashed, but there the hash is only an addon on much more informative name.

In the development mode you can also notice a replace call with a regular expression. It may look a bit complicated because it uses lookbehind assertion, but it's there to shorten names such as Example_Top_1_Something_5 to Example_Something_5 (I'm using Top as the "main" class name for a component that uses CSS module).

CSS Grid - Site for Rapid Experimentation

 

PAGE LAYOUT

Making website layout used to be hard... Frames, tables, floats, display: table, vertical-align, negative margins, absolute positioning... you name it! People & frameworks had to abuse HTML/CSS features just to center a div (let alone do a responsive page setup)... Fortunately the dark ages are over, Flexbox is supported for quite a while and about two years ago mayor browsers implemented Grid. It took 30 years, but website layout problem is solved (almost, still waiting for Subgrid).

If you haven't heard about CSS Grid here's a couple of great resources:

 

QUICK EXPERIMENTS

Above sites (and myriad of others) are doing a great job of describing grid features, so I'm not going to do that here. Instead I will share the page I made while learning grid: https://morzel85.github.io/css-grid-playground (ups, I've just noticed that https://www.cssgridplayground.com exists, the more playgrounds the better?)

My site is not a grid generator but rather a place were you can quickly test effects of various CSS Grid properties. Play with properties and immediately see the result (you may also want to open browser devtools to see how styles are actually applied to container and items)... If you are lost don't worry, just reload the page to get to initial state.

Here's how the site looks:

CSS Grid Playground - Rapid Experimentation... Click to enlarge...

On left-hand side you can control properties of grid container (div with grid-container class). In the middle you can set the amount of grid items (divs with grid-item class) and see the resulting grid. If you click an item, and additional panel opens where you can control specific grid item properties. If you are not sure what a property does, hover over it to see a brief description and example values.

I've tested the page in Chrome 75, Firefox 68 and Edge 44.

 

SUPPORTED PROPERTIES

CSS Grid is quite complex, but if think that my tool does a decent job of demonstrating its most important features. These are the supported properties:

grid-template-rows
Defines the amount and sizes of explicit grid rows.

grid-template-columns
Defines the amount and sizes of explicit grid columns.

grid-auto-rows
Defines sizes of implicit grid rows. Implicit rows are created when amount of items exceeds the amount of explicit rows (rows defined by template) or when an item placement goes outside the range of explicit rows.

grid-template-areas
Defines named grid areas which can be associated with particular grid items by using placement properties: grid-row-start, grid-row-end, grid-column-startgrid-column-end (or their shorthands: grid-row, grid-column and grid-area). Areas for each row are specified between quotes, white-space might be added to increase readability.

grid-auto-columns
Defines sizes of implicit grid columns. Implicit columns are created when amount of items exceeds the amount of explicit columns (columns defined by template) or when an item placement goes outside the range of explicit columns.

grid-auto-flow
Defines placement algorithm for items which are not specifically positioned (for example by using grid-column or grid-area).

row-gap
Defines space (gutter) size between grid rows. Older implementations used grid-row-gap name. gap shorthand property can be used to specify row and column gutters at the same time.

column-gap
Defines space (gutter) size between grid columns. Older implementations used grid-column-gap name. gap shorthand property can be used to specify row and column gutters at the same time.

justify-items
Defines placement of items in grid cells along inline (main) axis (horizontally, except for vertical writing mode). Value set on a container can be overridden by justify-self on an item. place-items shorthand property can be used to specify both align and justify at the same time.

align-items
Defines placement of items in grid cells along block (cross) axis (vertically, except for vertical writing mode). Value set on a container can be overridden by aling-self on an item. place-items shorthand property can be used to specify both align and justify at the same time.

justify-content
Defines placement of grid cells along inline (main) axis (horizontally, except for vertical writing mode). The setting will not have any effect if there is no space left on inline axis (for example when some column is defined as 1fr)! place-content shorthand property can be used to specify both align and justify at the same time.

align-content
Defines placement of grid cells along block (cross) axis (vertically, except for vertical writing mode). The setting will not have any effect if there is no space left on block axis (for example when some row is defined as 1fr)! place-content shorthand property can be used to specify both align and justify at the same time.

grid-row
A shorthand property that controls item row placement by setting grid-row-start, and grid-row-end values respectively. If placement goes outside of explicitly defined grid rows, implicit rows will be created.

grid-column
A shorthand property that controls item column placement by setting grid-column-start, and grid-column-end values respectively. If placement goes outside of explicitly defined grid columns, implicit columns will be created.

grid-area
A shorthand property that controls item placement by setting grid-row-startgrid-column-start, grid-row-end and grid-column-end values respectively. The setting is especially helpful when grid-template-areas "ascii-art" is used. If placement goes outside of explicitly defined grid, implicit row or columns will be created.

justify-self
Places the item inside grid cell along inline (main) axis (horizontally, except for vertical writing mode). The setting takes precedence over justify-items specified on container.

align-self
Places the item inside grid cell along block (cross) axis (vertically, except for vertical writing mode). The setting takes precedence over align-items specified on container.

order
Allows reordering of automatically placed item. By default items have order 0. The higher the order the later the item will appear. If other items have default order, setting to 1 will move the item to the end, and setting to -1 will move the item to the beginning.