Group CSS Media Queries Loader

4.3.0 verified Mon Apr 27 auth: no javascript

Webpack loader wrapping group-css-media-queries (v4.3.0) to combine identical @media queries from CSS files into a single block. Supports PostCSS 8+ and Webpack 2+. Unlike other media query merging tools, this loader integrates directly into webpack's build pipeline via standard rule configuration. Ships TypeScript definitions. Maintained with quarterly releases, used for optimizing CSS output size and performance.

Common errors

error Module not found: Error: Can't resolve 'group-css-media-queries-loader' ↓

cause The loader is not installed or the package name is misspelled.

fix

Run 'yarn add -D group-css-media-queries-loader' or 'npm install --save-dev group-css-media-queries-loader'.

error ValidationError: Invalid options object. group-css-media-queries-loader has been initialized using an options object that does not match the schema. ↓

cause Options were passed as query string or invalid object format.

fix

Use the object format: { loader: 'group-css-media-queries-loader', options: { ... } }.

error Error: PostCSS plugin group-css-media-queries requires PostCSS 8. ↓

cause Installed postcss version is below 8.1.0, but loader requires PostCSS 8+.

fix

Update postcss to version >=8.1.0: 'npm install postcss@latest'.

Warnings

breaking In v4.x, the loader now requires postcss >=8.1.0 as a peer dependency. Older versions of PostCSS are no longer compatible. ↓

fix Upgrade postcss to version 8.1.0 or later.

deprecated The 'sourceMap' option defaults to the value of 'compiler.devtool'. Using query string syntax for options (e.g., '?sourceMap=true') is deprecated in webpack 4+. ↓

fix Use object configuration format: { loader: 'group-css-media-queries-loader', options: { sourceMap: true } }.

gotcha Loader order matters: if used after postcss-loader, postcss-loader may have already combined media queries, causing the loader to have no effect. ↓

fix Place group-css-media-queries-loader after style-loader and css-loader, but before postcss-loader if postcss does not merge media queries.

gotcha The loader only works on CSS files processed by css-loader. It will not work on non-CSS files or when used without css-loader. ↓

fix Ensure css-loader is in the rule before group-css-media-queries-loader.

Install

npm install group-css-media-queries-loader

yarn add group-css-media-queries-loader

pnpm add group-css-media-queries-loader

Imports

GroupCssMediaQueriesLoader

wrong

const GroupCssMediaQueriesLoader = require('group-css-media-queries-loader'); module.exports.rules.push({ test: /\.css$/, loader: GroupCssMediaQueriesLoader })

correct

module.exports = { module: { rules: [ { test: /\.css$/, use: ['style-loader', 'css-loader', 'group-css-media-queries-loader'] } ] } }

Loader is used via string reference in webpack config, not imported. Using require() directly as a loader function may cause issues.

sourceMap option

wrong

module.exports = { module: { rules: [ { test: /\.css$/, use: [ 'style-loader', 'css-loader', 'group-css-media-queries-loader?sourceMap=true' ] } ] } }

correct

module.exports = { module: { rules: [ { test: /\.css$/, use: [ 'style-loader', 'css-loader', { loader: 'group-css-media-queries-loader', options: { sourceMap: true } } ] } ] } }

Options should be passed as object configuration, not query string. Query string format may not work reliably with webpack 4+.

Using with other PostCSS plugins

wrong

module.exports = { module: { rules: [ { test: /\.css$/, use: [ 'style-loader', 'css-loader', 'postcss-loader', 'group-css-media-queries-loader' ] } ] } }

correct

module.exports = { module: { rules: [ { test: /\.css$/, use: [ 'style-loader', 'css-loader', 'group-css-media-queries-loader', 'postcss-loader' ] } ] } }

Loader order matters: group-css-media-queries-loader should come after postcss-loader if postcss modifies media queries, or before to avoid conflicts.

Quickstart

Webpack configuration using group-css-media-queries-loader to merge identical media queries from CSS files.

// webpack.config.js
const path = require('path');

module.exports = {
  mode: 'development',
  entry: './src/index.js',
  output: {
    path: path.resolve(__dirname, 'dist'),
    filename: 'bundle.js'
  },
  module: {
    rules: [
      {
        test: /\.css$/,
        use: [
          'style-loader',
          'css-loader',
          'group-css-media-queries-loader'
        ]
      }
    ]
  }
};

// src/index.js
import './style.css';

// src/style.css
@media (max-width: 600px) { .a { color: red; } }
@media (max-width: 600px) { .b { color: blue; } }
// Output: single @media (max-width: 600px) { .a { color: red; } .b { color: blue; } }