typescript-plugin-css-modules

TypeScript Plugin CSS Modules

About This Plugin

The "typescript-plugin-css-modules" is a TypeScript language service plugin designed to enhance development with CSS Modules. It helps developers by providing type information in integrated development environments (IDEs) that support TypeScript language service plugins. This means developers can get better code suggestions, error detection, and autocomplete features specifically for CSS Modules while developing their applications.

Installation

To use the plugin, it can be installed via package managers. Use Yarn or npm for installation:

yarn add -D typescript-plugin-css-modules

or

npm install -D typescript-plugin-css-modules

After installation, the plugin should be added to the tsconfig.json file under the compilerOptions section:

{
  "compilerOptions": {
    "plugins": [{ "name": "typescript-plugin-css-modules" }]
  }
}

If you are using Visual Studio Code as your IDE, additional configuration may be required.

Using the Plugin

When using CSS Modules in TypeScript, styles can be imported like this:

import styles from 'my.module.css';

const className = styles.myClass;

The plugin supports both default and named exports. Named exports are available for class names without special characters such as hyphens or underscores.

import styles, { myClass } from 'my.module.css';

const className = myClass;

Configuration Options

The plugin offers various configurations to fine-tune its behavior according to specific project needs. Some of the available options include:

• classnameTransform: Alters how CSS class names are accessed (options include "asIs", "camelCase", etc.).
• customRenderer: Allows for a custom CSS renderer.
• customTemplate: Enables defining a custom template for TypeScript declarations.
• postcssOptions: Integrates with PostCSS, allowing loading from PostCSS config and excluding async plugins.
• rendererOptions: Provides options for Less, Sass, and Stylus renderers.

These configurations are added to the tsconfig.json under the plugin options:

{
  "compilerOptions": {
    "plugins": [
      {
        "name": "typescript-plugin-css-modules",
        "options": {
          "classnameTransform": "dashes",
          "customRenderer": "./myRenderer.js",
          "postcssOptions": {},
          "rendererOptions": {}
        }
      }
    ]
  }
}

Visual Studio Code Integration

For smooth integration with Visual Studio Code, it is recommended to use the workspace version of TypeScript, which will leverage the custom plugins and settings from tsconfig.json. Alternatively, the plugin can be referenced in the typescript.tsserver.pluginPaths setting without additional options.

Custom Definitions

Projects that do not come with global CSS Module declarations must add these manually to ensure TypeScript understands the imported CSS. A typical configuration involves creating a declaration file (e.g., custom.d.ts) encompassing all the module types used in the project.

Troubleshooting

Users can troubleshoot or debug issues by accessing the TypeScript Server Log in Visual Studio Code or using environment variables like TSS_LOG for logging outside the IDE. This information is vital when creating issues or seeking support for the plugin.

About This Project

The motivation for creating the "typescript-plugin-css-modules" stemmed from community needs expressed through platforms such as the Create React App repository. The project benefits from previous efforts, especially from projects like css-module-types, offering a more robust integration of CSS Modules within TypeScript environments.