typings-for-css-modules-loader

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

Disclaimer

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

Installation

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

Options

| Name | Type | Description | | :-----------------------------------------------: | :---------: | :----------------------------------------------------------: | | banner | {String} | To add a 'banner' prefix to each generated *.d.ts file | | formatter | {String} | Formats the generated *.d.ts file with specified formatter, eg. prettier | | eol | {String} | Newline character to be used in generated *.d.ts files | | verifyOnly | {Boolean} | Validate generated *.d.ts files and fail if an update is needed (useful in CI) | | disableLocalsExport | {Boolean} | Disable the use of locals export. | | prettierConfigFile | {String} | Path to prettier config file | | lazy | {boolean} | Emit 'use()' & 'unuse()' for *.lazy.css. Defaults to true |

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.

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

formatter

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

eol

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

verifyOnly

Validate generated *.d.ts files and fail if an update is needed (useful in CI).

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

disableLocalsExport

Disable the use of locals export. Defaults to false.

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

prettierConfigFile

Path to the prettier config file

module.exports = {
  module: {
    rules: [
      {
        test: /\.css$/i,
        use: [
          {
            loader: "@teamsupercell/typings-for-css-modules-loader",
            options: {
              prettierConfigFile: resolve(__dirname, '../.prettierrc'),
            }
          },
          {
            loader: "css-loader",
            options: { modules: true }
          }
        ]
      }
    ]
  }
};

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

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:

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

declare const MyComponentScssModule: MyComponentScssModule.IMyComponentScss & {
  /** WARNING: Only available when `css-loader` is used without `style-loader` or `mini-css-extract-plugin` */
  locals: MyComponentScssModule.IMyComponentScss;
};

export = MyComponentScssModule;

// using wildcard export when used with style-loader or mini-css-extract-plugin
// or default export only when typescript `esModuleInterop` enabled
import * as 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);

Example in Visual Studio Code

Upgrade from v1:

• 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
+           }
+         },
        ]
      }
    ]
  }
};

Support

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.

Requirements

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.

Known issues

Webpack rebuilds / builds slow

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.

Typescript does not find the typings

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.