Add Node ESM loader hook for import styles from './x.css'#169
Merged
Conversation
madyankin
force-pushed
the
postcss-modules-js-import
branch
from
June 30, 2026 19:30
8b3806f to
af0a3c5
Compare
Ships an opt-in `postcss-modules/loader` entrypoint that registers a
Node module-customization hook. With `node --import postcss-modules/loader`,
JavaScript files can `import styles from './foo.css'` and receive the
class-name token map directly, mirroring the workflow `css-loader` and
similar bundler integrations provide.
The hook reads the CSS file, runs it through the existing plugin with a
synthetic `getJSON` callback that captures tokens, and returns a synthetic
ESM module whose default export is the token map. Options are resolved
from `postcss-modules.config.{js,cjs,mjs}` in cwd, the `POSTCSS_MODULES_CONFIG`
env var, or a `"postcss-modules"` key in `package.json`, and accept the
same shape as the PostCSS plugin.
Targeted at non-bundler use cases (SSR, Node scripts, Jest/Vitest in
node mode); bundler users keep using `css-loader`, Vite's built-in
support, etc. Requires Node >= 20.6 where `module.register` stabilized.
Closes #80.
madyankin
force-pushed
the
postcss-modules-js-import
branch
from
June 30, 2026 19:38
d929ed0 to
2de0d0c
Compare
Add a configuration sub-section with concrete examples (config file, package.json key, env var), Jest/Vitest setup snippet, an ambient TypeScript declaration, and an explicit limitations list (ESM-only, tokens-only output, no HMR, Node version).
madyankin
force-pushed
the
postcss-modules-js-import
branch
from
June 30, 2026 19:43
2de0d0c to
82da0e6
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
postcss-modules/loaderentrypoint — a Node module-customization hook that lets JavaScript files doimport styles from './foo.css'and receive the token map directly. Mirrors the workflowcss-loaderand Vite's built-in CSS-Modules handling already provide.postcss-modules.config.{js,cjs,mjs}in cwd,POSTCSS_MODULES_CONFIGenv var, or a"postcss-modules"key inpackage.json. Same shape as the PostCSS plugin options.Usage
Implementation notes
src/loader.mjs— entry; callsmodule.registeron the hooks module.src/loaderHooks.mjs—loadhook interceptsfile://*.cssURLs, runs them through the existing plugin with agetJSONcallback that captures tokens, returns a synthetic ESM source.src/processCSS.js— small helper that sets up the fs adapter and invokes the existingmakePluginpipeline (no new code path through the transformer).src/loadConfig.mjs— config resolver. Kept as.mjsso swc doesn't rewrite its dynamicimport()torequire().Makefilegets acompiletarget; swc ignores*.mjsand wecpthose verbatim intobuild/.package.jsonexports map adds"./loader".engines.nodebumped to>=20.6(wheremodule.registerstabilized).Limitations (called out in the README)
Test plan
make test— 42 passing (5 new loader cases + 37 existing), lint clean.postcss-modules.config.cjsdiscovery from cwd,POSTCSS_MODULES_CONFIGenv var override, missing-file error surfaces the source path.