README.md

gatsby-plugin-dts-css-modules

GatsbyJS V4 plugin, which automatically creates TypeScript *.d.ts files for your CSS Modules, no matter which CSS preprocessor (Sass, LESS, Stylus etc.) you are using.

If you want to know more about CSS Modules, I recommend the article "Component-Scoped Styles with CSS Modules" on the GatsbyJS website.

This plugin utilizes the Webpack loader dts-css-modules-loader, which does not make any changes in content of styles, just creates *.d.ts file during the work.

If for some reason you need to stay with Gatsby V3, I recommend using version 2.2.0 of this plugin.

Installation

Ensure that you are using atleast Node.js v14.0.0.

npm install gatsby-plugin-dts-css-modules --save-dev
# or
yarn add gatsby-plugin-dts-css-modules --dev

Then, add the plugin to your gatsby-config.js …

module.exports = {
  // ...
  plugins: [
    // ...
    'gatsby-plugin-dts-css-modules',
    // ...
  ],
  // ...
}

It's also possible to change the dts-css-modules-loader options:

module.exports = {
  // ...
  plugins: [
    // ...
    {
      resolve: 'gatsby-plugin-dts-css-modules',
      options: {
        /** @default {true} */
        namedExport: false,

        /** @default {'// This file is automatically generated. Do not modify this file manually -- YOUR CHANGES WILL BE ERASED!'} */
        banner: '// My own banner',

        customTypings: (classes) => classes.map((className) => `export const ${className}: string;`).join('\n'),

        dropEmptyFile: true
      }
    },
    // ...
  ],
  // ...
}

Usage

For CSS files use the extension .module.css, for Sass/SCSS use .modules.sass or .module.scss and so on.

.container {
  margin: 3rem auto;
  max-width: 600px;
}

In TypeScript use:

import React from 'react';
import * as containerStyles from './container.module.css';

export const Container: React.FunctionComponent = ({ children }) => {
  return (
    <section className={containerStyles.container}>{children}</section>
  );
}

As soon as you use the Container component in your code, the plugin will create a container.module.d.ts, which looks like this one:

// This file is automatically generated. Do not modify this file manually -- YOUR CHANGES WILL BE ERASED!
export const container: string;

There will be one export const for each of your class names.

Replacing gatsby-plugin-scss-typescript / gatsby-plugin-typescript-css-modules

Since there are no further updates for gatsby-plugin-scss-typescript and gatsby-plugin-typescript-css-modules, you can simply replace them by gatsby-plugin-dts-css-modules (and gatsby-plugin-sass):

Just replace:

module.exports = {
  // ...
  plugins: [
    // ...
    'gatsby-plugin-scss-typescript',
    // or
    'gatsby-plugin-typescript-css-modules',
    // ...
  ],
  // ...
}

by:

module.exports = {
  // ...
  plugins: [
    // ...
    'gatsby-plugin-sass', // Required if you want to replace `gatsby-plugin-scss-typescript`
    'gatsby-plugin-dts-css-modules',
    // ...
  ],
  // ...
}

Don't forget to also install gatsby-plugin-sass, if you want to replace gatsby-plugin-scss-typescript!