Add Node ESM loader hook for import styles from './x.css'

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.

Author: madyankin

Makefile

@@ -3,7 +3,7 @@ NODE_IMAGE	= node:22
 DOCKER		= docker run --rm -v "$(CURDIR)":/app -w /app $(NODE_IMAGE)
 EXEC		= $(DOCKER) npm exec --
 
-.PHONY: clean lint test build publish pack release-patch release-minor release-major
+.PHONY: clean lint compile test build publish pack release-patch release-minor release-major
 
 # Reinstall whenever package-lock.json is newer than the marker.
 node_modules/.installed: package-lock.json package.json
@@ -17,11 +17,14 @@ clean:
 lint: node_modules/.installed
 	$(EXEC) eslint src test
 
-test: lint
+compile: node_modules/.installed
+	$(EXEC) swc src -d $(BUILD_DIR) --strip-leading-paths --ignore 'src/*.mjs'
+	$(DOCKER) sh -c 'cp src/*.mjs $(BUILD_DIR)/'
+
+test: lint compile
 	$(EXEC) jest
 
 build: clean test
-	$(EXEC) swc src -d $(BUILD_DIR) --strip-leading-paths
 
 publish: build
 	npm publish ./

README.md

@@ -92,6 +92,35 @@ postcss([
 
 `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:
+
+- **webpack** — [`css-loader`](https://github.com/webpack-contrib/css-loader) with `{ modules: true }`
+- **Vite** — built-in, files named `*.module.css`
+- **esbuild** — [`esbuild-css-modules-plugin`](https://github.com/indooorsman/esbuild-css-modules-plugin)
+- **Rollup** — [`rollup-plugin-postcss`](https://github.com/egoist/rollup-plugin-postcss) with `modules: true`
+
+### Without a bundler (SSR, Node scripts, Jest/Vitest in node mode)
+
+For Node directly, install the loader hook:
+
+```sh
+node --import postcss-modules/loader app.mjs
+```
+
+```js
+// app.mjs
+import styles from "./button.css";
+console.log(styles.primary); // "_button__primary_xkpkl_5"
+```
+
+Options live in `postcss-modules.config.{js,cjs,mjs}` in your cwd, or set `POSTCSS_MODULES_CONFIG=/path/to/cfg.cjs`. The config object accepts the same options as the PostCSS plugin (`generateScopedName`, `localsConvention`, `scopeBehaviour`, `globalModulePaths`, `Loader`, `resolve`, …).
+
+Requires Node ≥ 20.6 (the version that stabilized `module.register`). The loader returns only the token map; the transformed CSS is not emitted. For HMR, watch mode, or CSS extraction, use a bundler instead.
+
 ### Generating scoped names
 
 By default, the plugin assumes that all the classes are local. You can change

index.d.ts

@@ -50,3 +50,5 @@ declare interface PostcssModulesPlugin {
 declare const PostcssModulesPlugin: PostcssModulesPlugin;
 
 export = PostcssModulesPlugin;
+
+declare module "postcss-modules/loader" {}

package.json

@@ -4,6 +4,14 @@
 	"description": "PostCSS plugin to use CSS Modules everywhere",
 	"main": "build/index.js",
 	"types": "index.d.ts",
+	"exports": {
+		".": {
+			"types": "./index.d.ts",
+			"default": "./build/index.js"
+		},
+		"./loader": "./build/loader.mjs",
+		"./package.json": "./package.json"
+	},
 	"keywords": [
 		"postcss",
 		"css",
@@ -48,7 +56,7 @@
 		"prettier": "^3.9.4"
 	},
 	"engines": {
-		"node": ">=20"
+		"node": ">=20.6"
 	},
 	"scripts": {
 		"test": "make test",

src/loadConfig.mjs

@@ -0,0 +1,43 @@
+import { existsSync } from "fs";
+import { readFile } from "fs/promises";
+import path from "path";
+import { pathToFileURL } from "url";
+
+const CONFIG_NAMES = [
+	"postcss-modules.config.js",
+	"postcss-modules.config.cjs",
+	"postcss-modules.config.mjs",
+];
+
+async function importConfig(filePath) {
+	const url = pathToFileURL(filePath).href;
+	const mod = await import(url);
+	return mod.default || mod;
+}
+
+export async function loadConfig(cwd = process.cwd()) {
+	const explicit = process.env.POSTCSS_MODULES_CONFIG;
+	if (explicit) {
+		const resolved = path.isAbsolute(explicit) ? explicit : path.resolve(cwd, explicit);
+		return importConfig(resolved);
+	}
+
+	for (const name of CONFIG_NAMES) {
+		const candidate = path.resolve(cwd, name);
+		if (existsSync(candidate)) {
+			return importConfig(candidate);
+		}
+	}
+
+	const pkgPath = path.resolve(cwd, "package.json");
+	if (existsSync(pkgPath)) {
+		try {
+			const pkg = JSON.parse(await readFile(pkgPath, "utf8"));
+			if (pkg["postcss-modules"]) return pkg["postcss-modules"];
+		} catch {
+			// ignore unreadable / malformed package.json
+		}
+	}
+
+	return {};
+}

src/loader.mjs

@@ -0,0 +1,3 @@
+import { register } from "node:module";
+
+register("./loaderHooks.mjs", import.meta.url);

src/loaderHooks.mjs

@@ -0,0 +1,25 @@
+import { readFile } from "node:fs/promises";
+import { fileURLToPath } from "node:url";
+import { processCSS } from "./processCSS.js";
+import { loadConfig } from "./loadConfig.mjs";
+
+let configPromise;
+function getConfig() {
+	if (!configPromise) configPromise = loadConfig();
+	return configPromise;
+}
+
+export async function load(url, context, nextLoad) {
+	if (!url.startsWith("file:") || !url.endsWith(".css")) {
+		return nextLoad(url, context);
+	}
+	const filename = fileURLToPath(url);
+	const source = await readFile(filename, "utf8");
+	const opts = await getConfig();
+	const tokens = await processCSS(source, filename, opts);
+	return {
+		format: "module",
+		source: `export default ${JSON.stringify(tokens)};\n`,
+		shortCircuit: true,
+	};
+}

src/processCSS.js

@@ -0,0 +1,18 @@
+import postcss from "postcss";
+import { readFile, writeFile } from "fs";
+import { setFileSystem } from "./fs";
+import { makePlugin } from "./pluginFactory";
+
+setFileSystem({ readFile, writeFile });
+
+export async function processCSS(source, filename, opts = {}) {
+	let tokens = {};
+	const plugin = makePlugin({
+		...opts,
+		getJSON: (_cssFile, json) => {
+			tokens = json;
+		},
+	});
+	await postcss([plugin]).process(source, { from: filename });
+	return tokens;
+}

test/loader.test.js

@@ -0,0 +1,98 @@
+import { execFileSync } from "node:child_process";
+import { existsSync, mkdtempSync, writeFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import path from "node:path";
+
+const repoRoot = path.resolve(__dirname, "..");
+const loaderPath = path.resolve(repoRoot, "build/loader.mjs");
+const fixturesIn = path.resolve(__dirname, "./fixtures/in");
+
+beforeAll(() => {
+	if (!existsSync(loaderPath)) {
+		throw new Error(
+			`Loader build artifact missing at ${loaderPath}. Run \`make compile\` first.`,
+		);
+	}
+});
+
+function runLoaderScript(script, options = {}) {
+	return execFileSync(
+		process.execPath,
+		["--import", loaderPath, "--input-type=module", "-e", script],
+		{
+			cwd: options.cwd || repoRoot,
+			encoding: "utf8",
+			env: { ...process.env, ...(options.env || {}) },
+		},
+	).trim();
+}
+
+it("returns the token map for a CSS file via JS import", () => {
+	const cssPath = path.join(fixturesIn, "classes.css");
+	const out = runLoaderScript(
+		`import s from ${JSON.stringify(cssPath)}; process.stdout.write(JSON.stringify(s));`,
+	);
+	const tokens = JSON.parse(out);
+	expect(Object.keys(tokens).sort()).toEqual(["article", "title"]);
+	expect(tokens.title).toMatch(/title/);
+});
+
+it("composes tokens across imported CSS files", () => {
+	const cssPath = path.join(fixturesIn, "composes.css");
+	const out = runLoaderScript(
+		`import s from ${JSON.stringify(cssPath)}; process.stdout.write(JSON.stringify(s));`,
+	);
+	const tokens = JSON.parse(out);
+	expect(tokens).toHaveProperty("title");
+	expect(tokens).toHaveProperty("figure");
+	expect(tokens.title.split(/\s+/).length).toBeGreaterThanOrEqual(2);
+	expect(tokens.figure.split(/\s+/).length).toBeGreaterThanOrEqual(2);
+});
+
+it("applies options from postcss-modules.config.cjs in cwd", () => {
+	const dir = mkdtempSync(path.join(tmpdir(), "pcm-loader-"));
+	try {
+		writeFileSync(
+			path.join(dir, "postcss-modules.config.cjs"),
+			'module.exports = { generateScopedName: (name) => "_test_" + name };\n',
+		);
+		const cssPath = path.join(dir, "x.css");
+		writeFileSync(cssPath, ".foo { color: red; }\n.bar { color: blue; }\n");
+		const out = runLoaderScript(
+			`import s from ${JSON.stringify(cssPath)}; process.stdout.write(JSON.stringify(s));`,
+			{ cwd: dir },
+		);
+		expect(JSON.parse(out)).toEqual({ foo: "_test_foo", bar: "_test_bar" });
+	} finally {
+		rmSync(dir, { recursive: true, force: true });
+	}
+});
+
+it("honors POSTCSS_MODULES_CONFIG env var", () => {
+	const dir = mkdtempSync(path.join(tmpdir(), "pcm-loader-env-"));
+	try {
+		const configPath = path.join(dir, "my-config.cjs");
+		writeFileSync(
+			configPath,
+			'module.exports = { generateScopedName: (name) => "_env_" + name };\n',
+		);
+		const cssPath = path.join(dir, "x.css");
+		writeFileSync(cssPath, ".a {}\n.b {}\n");
+		const out = runLoaderScript(
+			`import s from ${JSON.stringify(cssPath)}; process.stdout.write(JSON.stringify(s));`,
+			{ cwd: dir, env: { POSTCSS_MODULES_CONFIG: configPath } },
+		);
+		expect(JSON.parse(out)).toEqual({ a: "_env_a", b: "_env_b" });
+	} finally {
+		rmSync(dir, { recursive: true, force: true });
+	}
+});
+
+it("surfaces missing-file errors with the source path", () => {
+	const cssPath = path.join(fixturesIn, "does-not-exist.css");
+	expect(() => {
+		runLoaderScript(
+			`import s from ${JSON.stringify(cssPath)}; process.stdout.write(JSON.stringify(s));`,
+		);
+	}).toThrow(/does-not-exist\.css/);
+});