By default, a JSON file with exported classes will be placed next to corresponding CSS.
But you have a freedom to make everything you want with exported classes, just
use the getJSON callback. For example, save data about classes into a corresponding JSON file:
postcss([ require("postcss-modules")({ getJSON: function (cssFileName, json, outputFileName) { var path = require("path"); var cssName = path.basename(cssFileName, ".css"); var jsonFileName = path.resolve("./build/" + cssName + ".json"); fs.writeFileSync(jsonFileName, JSON.stringify(json)); }, }),]);
getJSON may also return a Promise.
Using with JavaScript imports
With a bundler
import styles from "./x.css" is already supported by every major bundler — they invoke postcss-modules (or its building blocks) under the hood:
Without a bundler (SSR, Node scripts, Jest/Vitest in node mode)
postcss-modules ships a Node module-customization hook at the postcss-modules/loader subpath. Register it with --import and any import of a .css file is intercepted, run through the plugin, and exposed as a default-exported token map.
node --import postcss-modules/loader app.mjs
// app.mjsimport styles from "./button.css";const el = document.createElement("div");el.className = styles.primary; // "_button__primary_xkpkl_5"
Composing across files (composes: foo from "./other.css") works without extra configuration — the same FileSystemLoader the PostCSS plugin uses resolves siblings.
Configuring the loader
The hook accepts the same options object as the PostCSS plugin
(generateScopedName, localsConvention, scopeBehaviour, globalModulePaths, exportGlobals, hashPrefix, Loader, resolve, root). Options are discovered, in priority order:
process.env.POSTCSS_MODULES_CONFIG — absolute or cwd-relative path to a config file.
postcss-modules.config.{js,cjs,mjs} in process.cwd().
A "postcss-modules" key in the nearest package.json.
ESM only.require("./x.css") is not supported; the underlying transform is async and cannot be expressed through require.extensions. Use a .mjs entrypoint, or "type": "module" in package.json.
Tokens only, no CSS output. The loader returns the class-name map but does not emit the transformed CSS. SSR setups that need the stylesheet should use a bundler or call postcss([require("postcss-modules")(...)]).process(...) directly to capture both.
No HMR, no watch mode — by design. Use a bundler for those.
Node ≥ 20.6.module.register stabilized there.
Generating scoped names
By default, the plugin assumes that all the classes are local. You can change
this behaviour using the scopeBehaviour option:
postcss([ require("postcss-modules")({ scopeBehaviour: "global", // can be 'global', 'local' or 'pure', }),]);
Like local mode, pure mode localizes class and ID names, but it also requires
every comma-separated selector branch to contain at least one local class or ID.
For example, .button :global(.icon) is allowed, while :global(.page) is
rejected. Add /* cssmodules-pure-ignore */ immediately before a selector or
at-rule to skip this check once, or put
/* cssmodules-pure-no-check */ at the top of a file to disable the check for
the whole file.
To define paths for global modules, use the globalModulePaths option.
It is an array with regular expressions defining the paths. Matching files are
treated as global even when scopeBehaviour is "pure":
Style of exported classnames, the keys in your json.
Name
Type
Description
'camelCase'
{String}
Class names will be camelized, the original class name will not to be removed from the locals
'camelCaseOnly'
{String}
Class names will be camelized, the original class name will be removed from the locals
'dashes'
{String}
Only dashes in class names will be camelized
'dashesOnly'
{String}
Dashes in class names will be camelized, the original class name will be removed from the locals
'all'
{String}
Emit the original class name plus the camelCase and dashes-camelCase variants
'none'
{String}
Emit only the original class name (equivalent to leaving localsConvention unset)
For an input class foo-bar resolving to scoped name _a:
Mode
Emitted locals
camelCase
{ "foo-bar": "_a", "fooBar": "_a" }
camelCaseOnly
{ "fooBar": "_a" }
dashes
{ "foo-bar": "_a", "fooBar": "_a" }
dashesOnly
{ "fooBar": "_a" }
all
{ "foo-bar": "_a", "fooBar": "_a" } (camelCase + dashesCamelCase collapse for this input)
none
{ "foo-bar": "_a" }
In lieu of a string, a custom function can generate the exported class names. The function may return either a single string or an array of strings; when an array is returned every entry is added to the locals map and resolves to the same value:
The plugin only transforms CSS classes to CSS modules.
But you probably want to integrate these CSS modules with your templates.
Here are some examples.
Assume you've saved project's CSS modules in cssModules.json: