Type safety for CSS classes

Catching issues as early as possible is essential for the developer experience. But browsers and many popular tools will happily ignore invalid properties, usage of non-existing classes, etc. Let’s explore how you can improve that and create a better developer experience for your project.

⇣ Quick access ⇣

• CSS-in-JS
• CSS modules
• Sass/SCSS
• LESS

CSS-in-JS

The CSS-in-JS approach tends to be typesafe by default.

1
// This is type-safe CSS. It's a CSS object that you can use in your components.
2
const helloWorldStyle: React.CSSProperties = {
3
  color: "purple",
4
};
5

6
export function HelloWorld() {
7
  return <div style={helloWorldStyle}> Hello world! </div>;
8
}

1
export function HelloWorld() {
2
  return (
3
    <div
4
      style={{
5
        // This is also type-safe CSS.
6
        color: "purple",
7
      }}>
8
      Hello world!
9
    </div>
10
  );
11
}

CSS modules

CSS modules are regular CSS files with limited scope. However, they lack types when used in a component. It becomes a problem when classes are renamed or removed.

You could have a CSS module like this:

1
.helloWorld {
2
    color: purple
3
}

and use it (the wrong way) in a component like this:

1
import styles from "./HelloWorld.module.css";
2
export function HelloWorld() {
3
  return <div className={styles.helloWorld123}>Hello world!</div>;
4
}

The example uses wrong classname, but our IDE, the browser and all other tooling stays silent.

One of the ways to get a validation for the class names is to generate types with the help of typed-css-modules and get autocomplete in our IDE with typescript-plugin-css-modules.

Because these are CLI tools, I like to use npm-run-all and run them at development time.

Start by installing the dependencies:

npm install -D typed-css-modules typescript-plugin-css-modules npm-run-all

Next, update the scripts in your package.json file to start the development server and css modules watcher at the same time.

1
 "scripts": {
2
    "dev:start": "vite",
3
    "dev:css": "tcm src --watch",
4
    "dev": "run-p dev:**",
5
  }

TCM will run in the background and automatically generate types when it detects changes in the CSS module files.

This is the generated types file from my CSS modules example:

1
declare const styles: {
2
  readonly "helloWorld": string;
3
};
4
export = styles;

To enable autocomplete in your IDE add css modules plugin to tsconfig.json.

1
{
2
  "compilerOptions": {
3
    "plugins": [{ "name": "typescript-plugin-css-modules" }]
4
  }
5
}

Sass/SCSS

For SCSS we can use typed-scss-modules for type generation and npm-run-all to generate them during development time.

Start by installing the dependencies:

npm install -D typed-scss-modules npm-run-all

Next, update the scripts in your package.json file to start the development server and scss files watcher at the same time.

1
 "scripts": {
2
    "dev:start": "vite",
3
    "dev:scss": "typed-scss-modules src --watch --exportType default",
4
    "dev": "run-p dev:**",
5
  }

This is my sample scss file:

1
.helloWorld {
2
    color: purple;
3
  }

and these are the generated types:

1
export type Styles = {
2
  'helloWorld': string;
3
};
4

5
export type ClassNames = keyof Styles;
6

7
declare const styles: Styles;
8

9
export default styles;

When used in a component, you will get autocomplete for free.

1
import styles from "./HelloWorld.scss";
2
export function HelloWorld() {
3
  return <div className={styles.helloWorld}>Hello world!</div>;
4
}

LESS

When it comes to LESS we can use typed-less-modules to generate the types and npm-run-all to keep the file watcher running during development time.

Start by installing the dependencies:

npm install -D typed-less-modules npm-run-all

Next, update the scripts in your package.json file to start the development server and LESS files watcher at the same time.

1
 "scripts": {
2
    "dev:start": "vite",
3
     "dev:less": "tlm src --watch --exportType default",
4
    "dev": "run-p dev:**",
5
  }

This is my sample LESS file:

1
.helloWorld {
2
    color: purple
3
}

and these are the generated types:

1
export interface Styles {
2
  'helloWorld': string;
3
}
4

5
export type ClassNames = keyof Styles;
6

7
declare const styles: Styles;
8

9
export default styles;

When used in a component, you will get autocomplete for free.

1
import styles from "./HelloWorld.less";
2
export function HelloWorld() {
3
  return <div className={styles.helloWorld}>Hello world!</div>;
4
}

Next steps

If your project doesn’t have types for the CSS classes, now is the time to add them! It takes less than 15 minutes to implement and they go a long way in preventing all of the silly mistakes in the next code refactor.