Webpack loader that generates TypeScript typings for CSS modules from css-loader on the fly

This repository is a fork of the unmaintained https://github.com/Jimdo/typings-for-css-modules-loader repository.

Install via npm npm install --save-dev @teamsupercell/typings-for-css-modules-loader

webpack.config.js

module.exports = {
  module: {
    rules: [
      {
        test: /\.css$/i,
        use: [
          "style-loader",
          "@teamsupercell/typings-for-css-modules-loader",
          {
            loader: "css-loader",
            options: { modules: true }
          }
        ]
      }
    ]
  }
};

To add a "banner" prefix to each generated *.d.ts file, you can pass a string to this option as shown below. The prefix is quite literally prefixed into the generated file, so please ensure it conforms to the type definition syntax.

module.exports = {
  module: {
    rules: [
      {
        test: /\.css$/i,
        use: [
          {
            loader: "@teamsupercell/typings-for-css-modules-loader",
            options: {
              banner:
                "// autogenerated by typings-for-css-modules-loader. \n// Please do not change this file!"
            }
          },
          {
            loader: "css-loader",
            options: { modules: true }
          }
        ]
      }
    ]
  }
};

Possible options: none and prettier (requires prettier package to be installed). Defaults to prettier if prettier module can be resolved.

module.exports = {
  module: {
    rules: [
      {
        test: /\.css$/i,
        use: [
          {
            loader: "@teamsupercell/typings-for-css-modules-loader",
            options: {
              formatter: "prettier"
            }
          },
          {
            loader: "css-loader",
            options: { modules: true }
          }
        ]
      }
    ]
  }
};

"Newline character to be used in generated d.ts files. By default a value from require('os').eol is used. This option is ignored when formatter prettier is used.

module.exports = {
  module: {
    rules: [
      {
        test: /\.css$/i,
        use: [
          {
            loader: "@teamsupercell/typings-for-css-modules-loader",
            options: {
              eol: "\r\n"
            }
          },
          {
            loader: "css-loader",
            options: { modules: true }
          }
        ]
      }
    ]
  }
};

Imagine you have a file ~/my-project/src/component/MyComponent/myComponent.scss in your project with the following content:

.some-class {
  // some styles
  &.someOtherClass {
    // some other styles
  }
  &-sayWhat {
    // more styles
  }
}

Adding the typings-for-css-modules-loader will generate a file ~/my-project/src/component/MyComponent/myComponent.scss.d.ts that has the following content:

export interface IMyComponentScss {
  "some-class": string;
  someOtherClass: string;
  "some-class-sayWhat": string;
}

export const locals: IExampleCss;
export default locals;

// using default export when used with style-loader or mini-css-extract-plugin
import styles from "./myComponent.scss";

console.log(styles["some-class"]);
console.log(styles.someOtherClass);

// using locals export when used without style-loader or mini-css-extract-plugin
import { locals } from "./myComponent.scss";

console.log(locals["some-class"]);
console.log(locals.someOtherClass);

• Update webpack config
  • This package no longer replaces css-loader, but it has to be added alongside css-loader:
  • css-loader is no longer a peer dependency due to the change above
  • css-loader will need to be configured to output CSS Modules (e.g. options: { modules: true; })

module.exports = {
  module: {
    rules: [
      {
        test: /\.css$/i,
        use: [
          "style-loader",
          {
            loader: "@teamsupercell/typings-for-css-modules-loader",
            options: {
              // pass all the options for `css-loader` to `css-loader`, eg.
-             namedExport: true,
-             modules: true
            }
          },
+         {
+           loader: "css-loader",
+           options: {
+             modules: true
+           }
+         },
        ]
      }
    ]
  }
};

• Ensure all the typescript files import styles as default

- import * as styles from './styles.css';
+ import styles from './styles.css';

• Add allowSyntheticDefaultImports TypeScript compiler option if there are type errors related to default imports

As the loader just acts as an intermediary it can handle all kind of css preprocessors (sass, scss, stylus, less, ...). The only requirement is that those preprocessors have proper webpack loaders defined - meaning they can already be loaded by webpack anyways.

The loader is supposed to be used with css-loader(https://github.com/webpack/css-loader). Thus it is a peer-dependency and the expected loader to create CSS Modules.

As the loader generates typing files, it is wise to tell webpack to ignore them. The fix is luckily very simple. Webpack ships with a "WatchIgnorePlugin" out of the box. Simply add this to your webpack plugins:

plugins: [
    new webpack.WatchIgnorePlugin([
      /css\.d\.ts$/
    ]),
    ...
  ]

where css is the file extension of your style files. If you use sass you need to put sass here instead. If you use less, stylus or any other style language use their file ending.

As the webpack process is independent from your typescript "runtime" it may take a while for typescript to pick up the typings.

It is possible to write a custom webpack plugin using the fork-ts-checker-service-before-start hook from https://github.com/TypeStrong/fork-ts-checker-webpack-plugin#plugin-hooks to delay the start of type checking until all the *.d.ts files are generated. Potentially, this plugin can be included in this repository.