postcss-loader

postcss-loader integrates PostCSS into webpack’s module pipeline, letting any file matched by a CSS-type rule pass through a chain of PostCSS plugins before webpack’s built-in CSS support (or css-loader) processes it further. It resolves plugins and options either from loader options or from a standalone PostCSS config file, walking up the directory tree via cosmiconfig to find package.json’s postcss key, a postcss.config.js, or a .postcssrc variant, and it forwards PostCSS’s dependency, warning, and asset messages back into the webpack compilation so watch mode and caching stay accurate.

Because it sits directly ahead of tools like autoprefixer, postcss-preset-env, and CSS Modules processing, it’s the piece that makes those plugins run at build time rather than only at authoring time — most teams that use PostCSS inside a webpack project reach it through this loader rather than calling PostCSS’s own API directly.

What You Get

• Plugin pipeline integration — runs any PostCSS plugin chain against matched files inside a webpack use array, either as static options or an object built from a function of the loader context.
• Automatic config discovery — searches package.json, postcss.config.{js,mjs,cjs,ts,mts,cts}, and .postcssrc variants up the directory tree via cosmiconfig, so most projects need zero loader options.
• Source map passthrough — honors webpack’s devtool setting or an explicit sourceMap option, normalizing map source paths before and after PostCSS processing.
• CSS-in-JS support — the execute option runs JS-authored style modules through Node’s module system first, so the postcss-js parser can process them like ordinary CSS.
• Dependency and asset wiring — converts PostCSS’s own dependency, build-dependency, missing-dependency, context-dependency, and asset messages into webpack’s addDependency/emitFile calls automatically.

Common Use Cases

• Running autoprefixer or postcss-preset-env inside a webpack CSS pipeline for vendor prefixing and future-syntax support.
• Processing CSS Modules alongside PostCSS transforms using webpack’s built-in css/auto module type.
• Compiling SugarSS or other custom PostCSS syntaxes ahead of the rest of a webpack CSS build.
• Sharing a single postcss.config.js across multiple tools — webpack via this loader, and CI/scripts via postcss-cli.
• Styling with CSS-in-JS by pairing the execute option with the postcss-js parser.

Under The Hood

Architecture The project is a single-purpose webpack loader split cleanly into two files: src/index.js, the loader entry point that follows webpack’s async loader contract (this.async(), this.getOptions(schema), addDependency/emitFile) and orchestrates config loading, plugin resolution, PostCSS execution, and message translation; and src/utils.js, a set of pure/stateless helpers for config discovery, plugin normalization, source-map path rewriting, and error/warning formatting. The loader detects a compatible PostCSS AST already produced by an earlier loader in the chain (meta.ast, version-checked with semver) and reuses it instead of re-parsing, and it falls back to a one-time warning (guarded by module-level state in hasExplicitDependencyOnPostCSS) when it detects a PostCSS 7 processor without an explicit postcss dependency. The design is shallow and easy to reason about — one stateful entry point, one library of pure helpers.

Tech Stack Written in modern JavaScript (ES modules), built to CommonJS via Babel (@babel/cli/@babel/preset-env) for distribution as dist/cjs.js. Configuration discovery is delegated to cosmiconfig 9, with jiti 2 used to load TypeScript/ESM config files on the fly and semver 7 used for AST-version compatibility checks. postcss and webpack are peer dependencies (webpack optional, @rspack/core also supported as an optional peer), keeping the loader’s own dependency footprint deliberately small. Tests run under Jest with ts-jest/babel-jest transforms and a custom in-repo webpack-compile harness; releases are cut with standard-version.

Code Quality The repo has nine dedicated Jest test files (loader, config-autoload, execute, implementation, postcssOptions, sourceMap, validate-options, builtInCss, cjs) using snapshot assertions against a shared test/helpers webpack-compile harness, giving good coverage of the loader’s actual runtime behavior rather than just its exports. Errors are handled explicitly throughout — config loading, plugin loading, and PostCSS processing are each wrapped in try/catch and converted into loader callback errors, with a dedicated CssSyntaxError formatter for readable output. CI (GitHub Actions nodejs.yml) runs lint and test on every push, eslint-config-webpack plus cspell enforce style and spelling, and husky/lint-staged/commitlint gate commits. There are no TypeScript source files (options are validated at runtime via a JSON Schema in src/options.json), though src/config.d.ts ships hand-written types for consumers.

API Design The public surface is deliberately small: a single postcssOptions value that can be a static object or a function of the loader context, plus sourceMap, implementation, and execute. Config-file cascading (via cosmiconfig) means most projects need no loader options at all — use: ["postcss-loader"] and a postcss.config.js is enough — while defaults for source maps (inherited from webpack’s devtool) and config lookup keep everyday configuration close to zero. Escape hatches (implementation override for downstream tooling migrating PostCSS majors, execute for CSS-in-JS, string paths for parser/stringifier/syntax) are opt-in rather than required, which keeps the common path simple without limiting advanced use.