css-loader

css-loader is the webpack loader that teaches CSS files to behave like JavaScript modules. It parses @import at-rules and url()/image-set() references the same way webpack resolves require()/import statements, letting stylesheets pull in other stylesheets and reference images, fonts, and other assets that then flow through webpack’s own module graph and asset pipeline instead of needing separate copy steps.

Beyond raw resolution, css-loader is the engine behind CSS Modules support in webpack: it can scope class names locally per file, compose classes across stylesheets, and export the generated identifiers back into JavaScript so components can import styles as a simple object of class names. It sits at the base of nearly every CSS build in the webpack ecosystem, typically paired with style-loader for development or mini-css-extract-plugin for production, and works equally with plain CSS, Sass/Less/Stylus output, or PostCSS-transformed input via postcss-loader.

What You Get

• @import and url() resolution - Rewrites @import at-rules and url()/image-set() references into webpack module requests so referenced stylesheets and assets are tracked and bundled.
• CSS Modules and ICSS support - Locally scopes class/id selectors, supports :local/:global, class composition via composes, and exports generated identifiers to JavaScript.
• Configurable export formats - Emits CSS as a JS string, an array of [id, css, media] tuples, or a constructable CSSStyleSheet, depending on the exportType option.
• Source map passthrough - Optionally generates and forwards source maps so browser devtools can map compiled CSS back to original source files.
• PostCSS AST reuse - Detects and reuses an existing PostCSS AST from an upstream loader like postcss-loader, avoiding a redundant CSS re-parse.

Common Use Cases

• Importing CSS into JavaScript - import './button.css' in a component file, with css-loader turning that stylesheet into a webpack module dependency.
• CSS Modules-scoped components - Using styles.module.css files whose class names are hashed per-component to avoid global collisions in a component library or app.
• Referencing images and fonts from CSS - url('./logo.png') in a stylesheet automatically resolved and processed by webpack’s asset pipeline instead of hand-managed paths.
• Extracting production CSS bundles - Feeding css-loader’s output into mini-css-extract-plugin to produce separate .css files instead of inlining styles via style-loader.

Under The Hood

Architecture

css-loader’s execution is a single async loader function (src/index.js) that normalizes raw loader options against a JSON schema (src/options.json), conditionally assembles a PostCSS plugin pipeline from three purpose-built plugins in src/plugins/ (postcss-icss-parser, postcss-import-parser, postcss-url-parser), and runs postcss(plugins).process() over the stylesheet - reusing an already-parsed AST from an upstream loader like postcss-loader when the metadata indicates a compatible version, to avoid re-parsing. Collected imports/exports/replacements from each plugin are then merged and rendered into three code sections (import code, module code, export code) by helper functions in the large src/utils.js module, and a small runtime API (src/runtime/api.js, getUrl.js, sourceMaps.js) is injected into the emitted bundle to resolve URLs and stitch source maps at runtime. The design cleanly separates option normalization, static CSS transformation, and runtime helpers, so changing the core PostCSS pipeline would primarily touch src/plugins/ and src/utils.js without needing to alter the runtime contract.

Tech Stack

Written in plain JavaScript (no TypeScript), built with Babel into dist/cjs.js, and validated post-build with es-check to guarantee the emitted runtime stays ES5-compatible for older browser targets. Its real dependencies are the PostCSS ecosystem - postcss itself plus icss-utils, postcss-modules-extract-imports/local-by-default/scope/values, and postcss-value-parser - alongside semver for AST-compatibility checks; it peer-depends on webpack ^5.27 or @rspack/core, both marked optional so either host bundler can use it. Testing runs on Jest with jest-environment-jsdom, exercising real webpack compiles via memfs-backed in-memory builds against fixture CSS/JS files; linting combines ESLint, Prettier, and cspell, wired into commit hooks via Husky/lint-staged, with commitlint enforcing Conventional Commits and standard-version driving releases.

Code Quality

The test/ directory holds a wide set of dedicated spec files (loader, modules-option, url-option, import-option, esModule-option, exportType-option, camelCase, cjs, validate-options, sourceMap-option, plus shared runtime tests) that compile real fixture bundles through Jest snapshot assertions on module source, executed output, warnings, and errors - giving broad behavioral coverage across nearly every documented option combination rather than isolated unit tests. The pretest script runs the full lint suite before any test executes, and CI re-runs this on every push/PR. There is no static type system (plain JS, options validated only at runtime via the JSON schema), so type-level guarantees are weaker than a TypeScript codebase, but the schema-driven validation still produces clear, structured error messages for misconfigured options.

API Design As a webpack loader, css-loader’s public surface is a single options object validated against a documented JSON schema, so misconfiguration fails fast with a structured, human-readable error rather than a silent bad build. Its options (url, import, modules, sourceMap, importLoaders, esModule, exportType) are individually well-scoped and composable - modules alone spans a boolean, a named mode, or a full object for fine-grained CSS Modules control - letting simple setups stay a one-line loader entry while advanced setups stay in the same object rather than requiring separate plugins. It doesn’t introduce a new API paradigm beyond the standard webpack loader chain, which keeps developer experience familiar but unsurprising rather than innovative.