css-modules-typing-loader

css-modules-typing-loader

Webpack loader to generate Typescript typings for your CSS modules on the fly. This does not replace your existing CSS loader.

Originally modified from css-modules-typing-loader-loader.

Installation

npm install --save-dev css-modules-typing-loader

Options

You can specify the following options as query parameters:

camelCase

Makes sure all classnames are transformed to valid variables (often used in combination with namedExport, as described below).

  { test: /\.css$/, loader: 'css-modules-typing-loader?camelCase' }

namedExport

Since class names with characters like dashes (-) are not valid characters for a Typescript variable, the default behaviour for this loader is to export an interface as the default export that contains the classnames as properties.

export interface IExampleCss {
  'foo': string;
  'bar-baz': string;
}
declare const styles: IExampleCss;

export default styles;

A cleaner way is to expose all classes as named exports. This can be done by enabling the namedExport option:

  { test: /\.css$/, loader: 'css-modules-typing-loader?namedExport' }

As mentioned above, this requires class names to only contain valid typescript characters, thus filtering out all classnames that do not match the regex /^\w+$/i. In order to make sure that even class names with non-legal characters are used it is highly recommended to use the camelCase option as well:

  { test: /\.css$/, loader: 'css-modules-typing-loader?namedExport&camelCase' }

Note: css-loader exports mappings to exports.locals which is incompatible with the namedExport-option unless paired with extract-text-webpack-plugin or style-loader. They move the exported properties from exports.locals to exports making them required for namedExport to work, and namedExport required for them to work. Always combine usage of extract-text-webpack-plugin or style-loader with the namedExport-option.

silent

To silence the loader because you get annoyed by its warnings or for other reasons, you can simply pass the "silent" query to the loader and it will shut up.

  { test: /\.css$/, loader: 'css-modules-typing-loader?silent' }

banner

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.

  { test: /\.css$/, loader: 'css-modules-typing-loader?banner="// This file is automatically generated by css-modules-typing-loader.\n// Please do not change this file!"' }

Usage

Modify your Webpack config to pass your CSS module files through css-modules-typing-loader.

before:

{
  ...webpackConfig,
  module: {
    rules: [
      { test: /\.css$/, loader: 'css?modules' }
    ]
  }
}

after:

{
  ...webpackConfig,
  module: {
    rules: [
      { test: /\.css$/, use: ['css?modules', 'css-modules-typing-loader'] }
    ]
  }
}

Example

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
  }
}

Using css-modules-typing-loader will generate ~/my-project/src/component/MyComponent/myComponent.scss.d.ts with the following content:

export interface IMyComponentScss {
  'some-class': string;
  'someOtherClass': string;
  'some-class-sayWhat': string;
}
declare const styles: IMyComponentScss;

export default styles;

If you are using the namedExport and camelCase options, the generated file will look something more like this:

export const someClass: string;
export const someOtherClass: string;
export const someClassSayWhat: string;

Known issues

Slow Webpack builds and/or rebuilds

Since this loader will be generating type definition files on the fly, it is recommended that tell Webpack you ignore these. This can be done using the built-in WatchIgnorePlugin:

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