eslint-plugin-postcss-modules
Like eslint-plugin-css-modules, this plugin helps you lint your css modules.
It adds a new eslint rule that detects if you are trying to use a class that is
not exported by your css module.
The major difference between this plugin and the aforementioned plugin is that
this plugin uses postcss to parse the css files and determine what classes
are exported. There are a couple of benefits to this:
- Under the hood, css-loader is also using postcss with a few plugins to
determine which classes are exported. This plugin uses the same group of
plugins to guarantee that the classes that are linted are the same as the
classes css-loader exports.
- Through plugins, postcss can handle a variety of complex input css files.
While eslint-plugin-css-modules has excellent support for most major css
grammars (such as sass), it does not support all of the inputs that postcss
can handle and probably never will. If you are using postcss for your
project, chances are good that eslint-plugin-css-modules will choke on your
files.
The downside is that, while postcss is very battle-tested and fast for
building css, it may be slower than eslint-plugin-css-modules for linting
purposes. I don't have benchmarks, but welcome them.
Installation
yarn add -D eslint-plugin-postcss-modules
npm install -D eslint-plugin-postcss-modules
Usage
In your eslint config:
{
"extends": [
"plugin:postcss-modules/recommended"
],
}
The recommended configuration will set no-undef-class to errors and
no-unused-class to warnings. The recommended configuration is equivalent to:
{
"plugins": ["postcss-modules"],
"rules": {
"postcss-modules/no-undef-class": "error",
"postcss-modules/no-unused-class": "warn"
}
}
Settings
There are a couple settings you can tweak in your eslint config. Below are
examples of the options and their default values:
{
"settings": {
"postcss-modules": {
"postcssConfigDir": "cwd",
"baseDir": "cwd",
"camelCase": false,
"defaultScope": "local",
"include": "**/*.css",
"exclude": "**/node_modules/**/*"
}
}
}
-
postcssConfigDir (default: cwd)
postcssConfigDir sets the starting point to search for the postcss config
file, as determined by postcss-load-config. Searching will start with
this directory and work its way up recursively until it finds a config file
or hits your home directory. See cosmiconfig for more info.
I recommend that you create a pared down version of your postcss config
that only includes plugins that could affect the structure of the file and
the class names that might be exported in order to reduce the amount of
time linting takes. For example, postcss-preset-env is really a collection
of plugins under the hood. The only plugins that affect the structure and
classes that would be exported are probably postcss-custom-selectors and
postcss-nesting.
-
baseDir (default: cwd)
baseDir is used to resolve imports to your css files. If the import is
relative (ie, starts with ./), the path of the current file will be used
to resolve the import. However, if the import is not relative, this
baseDir will be used to resolve the path.
-
camelCase (default: false)
The camelCase option should match the camelCase option or
localsConvention option that you have set for css-loader, depending on
which version you are using. Here's a description of the options and what
they do:
| option | description |
|---|
false or "asIs" | Do not camelCase exported classes |
true or "camelCase" | Export both the original class name and the camelCased version |
"camelCaseOnly" or "only" | Export only the camelCased class names |
"dashes" | Convert dashed-names to camelCase and export both |
"dashesOnly" | Convert dashed-names to camelCase and only export the camelCased version |
-
defaultScope (default: "local")
The defaultScope option determines scope (global or local) of any css
classes which are not explicitly declared as being global or local using
:global or :local. The default is "local".
-
include (default: "**/*.css")
An anymatch matcher to determine what files should be parsed for
css-module exports. Any file which matches include but does not match
exclude will be parsed. Note that due to the way eslint combines
settings, you cannot use a regex here.
-
exclude (default: "**/node_modules/**/*")
An anymatch matcher to determine what files should not be parsed for
css-module exports. Any file which matches include but does not match
exclude will be parsed. Note that due to the way eslint combines
settings, you cannot use a regex here.
