postcss-media-query-pruner

postcss-media-query-pruner is a PostCSS plugin that consolidates and cleans up media queries in your CSS. It merges identical media queries into single blocks, removes duplicate rules, and optionally sorts them in “mobile-first” or “desktop-first” order if enabled through options. It helps reduce CSS file size and improves maintainability by ensuring that media queries are organized and efficient.

📦 Installation

Install with npm:

1npm install postcss-media-query-pruner --save-dev

🔧 Usage

Configure in your PostCSS setup (e.g., postcss.config.js or your build tool):

1import mediaQueryPruner from 'postcss-media-query-pruner';
2
3module.exports = {
4  plugins: [
5    mediaQueryPruner({
6      include: ['*'],      
7      exclude: [],     
8      sortingEnabled: true,          
9      sort: 'mobileFirst', // or 'desktopFirst'
10      logger: {
11        info: msg => console.log('[Pruner]', msg),
12        error: msg => console.error('[Pruner]', msg),
13      },
14    }),
15  ],
16};

⚙️ Options

Option	Type	Default	Description
include	string[]	['*']	Glob patterns or substrings to include files.
exclude	string[]	[]	Glob patterns or substrings to exclude files.
sortingEnabled	boolean	false	Enable sorting of media queries by width.
sort	'mobileFirst' | 'desktopFirst'	'mobileFirst'	Sorting strategy: ascending or descending by min-width.
logger	{info, error}	console	Custom logger for info and error messages.

📋 Examples

1. Merge & Deduplicate

Input:

1@media (min-width: 600px) {
2  .btn { color: blue; }
3}
4@media (min-width: 600px) {
5  .btn { color: blue; }
6  .card { padding: 1rem; }
7}

Output:

1@media (min-width: 600px) {
2  .btn { color: blue; }
3  .card { padding: 1rem; }
4}

2. Sorting Enabled (Desktop-first)

Input:

1@media (min-width: 300px) { .a { font-size: 14px; } }
2@media (min-width: 800px) { .b { font-size: 16px; } }

Config:

1mediaQueryPruner({ sortingEnabled: true, sort: 'desktopFirst' });

Output:

1@media (min-width: 800px) { .b { font-size: 16px; } }
2@media (min-width: 300px) { .a { font-size: 14px; } }

3. Include/Exclude Patterns

1mediaQueryPruner({
2  include: ['src/components'],
3  exclude: ['legacy.css'],
4});

Only files in src/components will be pruned, skipping any path containing legacy.css.

🤝 Contributing

Contributions welcome! Please open issues or pull requests for bug fixes and features.

📄 License

This project is licensed under the 0BSD License. See LICENSE for details.