css-module-typed README

Without writing .d.ts files, add TypeScript types to your css/less/scss modules files to keep your directory clean.

Features

The plugin can automatically enhance the css modules file type and provide the following features:

1. Auto complete.
2. Auto mark incorrect class names.
3. Go to definition.
4. Support css/less/scss module files.
5. Rich customization options for compilation.

Configuration

css-module-typed.pluginOptions

Quoted from https://github.com/mrmckeb/typescript-plugin-css-modules, and added some additional supported features.

classnameTransform

Implements the behaviour of the localsConvention css-loader option.

Options available are: 'asIs', 'camelCase', 'camelCaseOnly', 'dashes', and 'dashesOnly'.

customRenderer

The customRenderer is an advanced option, letting you provide the CSS renderer.

When a custom renderer is provided, not other renderers will be used.

The path to the customRenderer must be relative to the project root (i.e. ./myRenderer.js).

The custom renderer itself should be a JavaScript file. The function will be called with three arguments: a css string, an options object (see options.ts), and a compilerOptions object - which contains options as set in your tsconfig.json. It must be synchronous, and must return valid CSS.

module.exports = (css, { fileName, logger }) => {
  try {
    // ...process your css here.
    return renderedCss;
  } catch (error) {
    logger.error(error.message);
  }
};

You can find an example custom renderer in our test fixtures (customRenderer.js).

The internal logger is provided for debugging.

If you use Webpack, note that tilde (~) imports not supported by Less and Sass natively.

For Sass users: A custom importer has been implemented to resolve this as of v3.

For Less users: This package exports a customRenderer that enables tilde imports: less-plugin-aliases.

customTemplate

The customTemplate is an advanced option, letting you provide a template for the generated TypeScript declarations.

When a custom template is provided, its output is used as the virtual declaration (*.d.ts) file.

The path to the customTemplate must be relative to the project root (i.e. ./customTemplate.js).

The custom renderer itself should be a JavaScript file. The function will be called with two arguments: a dts string, and an options object (see options.ts). It must be synchronous, and must return a valid TypeScript declaration (as found in a .d.ts file).

module.exports = (dts, { classes, fileName, logger }) => {
  try {
    // ...generate your template here.
    return customTemplate;
  } catch (error) {
    logger.error(error.message);
  }
};

You can find an example custom template in our test fixtures (customTemplate.js).

The internal logger is provided for debugging.

The classes object represents all the classnames extracted from the CSS Module. They are available if you want to add a custom representation of the CSS classes.

goToDefinition

This allows an editor like Visual Studio Code to go to a classname's definition (file and line).

This is experimental, and may not always work as expected. It currently supports CSS/PostCSS, Less, and Sass. Please raise an issue if you find something isn't working.

postcssOptions

rendererOptions

For convenience, loadPaths for Sass are extended, not replaced. The defaults are the path of the current file, and 'node_modules'.

Configuration Priority

The priority of reading plugin configurations is as follows: user setting.json < workspace setting.json < .css-module.config.js (same dir with tsconfig.json)

QA

Q: I made changes to the plugin configurations but they didn't take effect?

A: reload vscode window make config work.

Q: Some of my less/scss files are not being recognized correctly?

A: Check if there are any less/scss variables that are not properly defined in the files. If so, you can try defining the unknown variables using additionalData.

Remark

Based on the usage of typescript-plugin-css-modules, we have discovered several issues with this plugin. Therefore, we have fixed them and released the fixes in this plugin.