Unlocking the Potential of CSS Modules with TypeScript

What are CSS Modules?

CSS Modules allow you to write modular and reusable CSS styles that are specific to your application’s components or modules. By using regular CSS syntax, you can define styles that are generated with unique class names at build time. This approach eliminates the need for manual effort in avoiding class name conflicts and unnecessary duplications.

/* example.module.css */
.container {
  width: 100%;
  max-width: 1200px;
  margin: 0 auto;
}

Adding CSS Modules to Your Project

To get started with CSS Modules, you can use modern build tools like Vite or Snowpack, which support CSS Modules out of the box. If you’re using webpack, you may need to include some minor configurations. Once set up, you can add CSS files with the .module.css extension and import them in your TypeScript files.

import styles from './example.module.css';

const ExampleComponent = () => {
  return (
    <div className={styles.container}>
      <h1>Example Component</h1>
    </div>
  );
};

The Problem with Manual Type Definitions

When using CSS Modules with TypeScript, you may encounter issues with type safety. Since class names are generated dynamically, it’s challenging to write type definitions manually. Updating type definitions manually can be tedious and prone to errors, especially when working with large codebases.

Automating Type Definitions with typed-css-modules

To overcome this challenge, you can use the typed-css-modules package, which generates type definitions automatically. By installing the package and adding a script to your package.json file, you can automate the process of generating type definitions and ensure that they are up-to-date.

{
  "scripts": {
    "generate-types": "typed-css-modules src/**/*.module.css"
  }
}

Integrating with Git Hooks

To take it a step further, you can integrate the automation process with Git Hooks using Husky. By setting up a pre-commit hook, you can run the type checking script before every commit, ensuring that your type definitions are always up-to-date.

{
  "husky": {
    "hooks": {
      "pre-commit": "npm run generate-types"
    }
  }
}