cssnano の使い方 — CSS を本番向けに最適化するモジュラーミニファイア

一言でいうと

cssnano は、PostCSS エコシステム上に構築された CSS ミニファイア（圧縮ツール）です。不要な空白・コメントの除去だけでなく、プロパティのマージや値の短縮など、多数の最適化をモジュラーに適用して CSS のファイルサイズを削減します。

---

どんな時に使う？

1. 本番ビルドで CSS を圧縮したいとき — Webpack・Vite・Gulp などのビルドパイプラインに組み込み、デプロイ前に CSS を最小化する定番ユースケースです。
2. PostCSS のプラグインチェーンに最適化ステップを追加したいとき — Autoprefixer や Tailwind CSS など、既に PostCSS を使っている環境にシームレスに統合できます。
3. 最適化の粒度を細かく制御したいとき — プリセット単位やプラグイン単位で最適化のオン・オフを切り替えられるため、「コメントだけ残したい」「calc() は最適化しない」といった要件にも対応できます。

---

インストール

# npm
npm install cssnano postcss --save-dev

# yarn
yarn add cssnano postcss --dev

# pnpm
pnpm add cssnano postcss -D

Note: cssnano v7 は PostCSS 8 をピア依存として要求します。postcss が未インストールの場合は一緒にインストールしてください。

---

基本的な使い方

PostCSS 設定ファイルで使う（最も一般的）

// postcss.config.ts
import type { Config } from 'postcss-load-config';

const config: Config = {
  plugins: [
    // 他のプラグイン（例: autoprefixer）をここに
    ['cssnano', { preset: 'default' }],
  ],
};

export default config;

Node.js スクリプトから直接使う

import postcss from 'postcss';
import cssnano from 'cssnano';
import { readFile, writeFile } from 'node:fs/promises';

async function minify() {
  const css = await readFile('src/styles.css', 'utf-8');

  const result = await postcss([
    cssnano({ preset: 'default' }),
  ]).process(css, { from: 'src/styles.css', to: 'dist/styles.css' });

  await writeFile('dist/styles.css', result.css);

  if (result.map) {
    await writeFile('dist/styles.css.map', result.map.toString());
  }
}

minify();

---

よく使う API・設定パターン

1. プリセットの指定

cssnano は プリセット という単位で最適化プラグインをまとめています。

import cssnano from 'cssnano';

// デフォルトプリセット（安全な最適化のみ）
cssnano({ preset: 'default' });

// 軽量プリセット（最小限の最適化）
// npm install cssnano-preset-lite -D が必要
cssnano({ preset: 'lite' });

// アドバンスドプリセット（より積極的な最適化）
// npm install cssnano-preset-advanced -D が必要
cssnano({ preset: 'advanced' });

2. 個別プラグインの無効化

プリセットの第2引数でプラグインごとにオン・オフを制御できます。

cssnano({
  preset: [
    'default',
    {
      // コメントを残す
      discardComments: false,
      // calc() の最適化を無効化
      calc: false,
      // カラー値の短縮を無効化
      colormin: false,
    },
  ],
});

3. 特定コメントの保持（! 付きコメント）

ライセンスコメントなど /*! で始まるコメントだけ残す設定です。

cssnano({
  preset: [
    'default',
    {
      discardComments: {
        removeAll: false,       // デフォルト
        // removeAllButFirst: true, // 先頭の重要コメントだけ残す場合
      },
    },
  ],
});

/*! で始まるコメントはデフォルトで保持されます。すべてのコメントを削除したい場合は removeAll: true を指定します。

cssnano({
  preset: [
    'default',
    {
      discardComments: { removeAll: true },
    },
  ],
});

4. Webpack（css-minimizer-webpack-plugin）との統合

// webpack.config.ts
import CssMinimizerPlugin from 'css-minimizer-webpack-plugin';

export default {
  // ...
  optimization: {
    minimizer: [
      '...', // デフォルトの JS ミニファイアを維持
      new CssMinimizerPlugin({
        // cssnano はデフォルトで使用される
        minimizerOptions: {
          preset: [
            'default',
            { discardComments: { removeAll: true } },
          ],
        },
      }),
    ],
  },
};

5. ソースマップの生成

PostCSS のオプションでソースマップを有効にします。

import postcss from 'postcss';
import cssnano from 'cssnano';

const result = await postcss([cssnano({ preset: 'default' })])
  .process(css, {
    from: 'src/styles.css',
    to: 'dist/styles.css',
    map: {
      inline: false, // 外部ファイルとして出力
    },
  });

console.log(result.css); // 圧縮された CSS
console.log(result.map); // ソースマップオブジェクト

---

類似パッケージとの比較

選定の目安:

• PostCSS ベースのビルド環境 → cssnano（最も自然に統合できる）
• ビルド速度が最優先 → lightningcss または esbuild
• PostCSS を使わないレガシー環境 → clean-css

---

注意点・Tips

⚠️ default プリセットでも意図しない変換が起きることがある

z-index のリベース（cssDeclarationSorter や zindex）など、一部の最適化はコンテキストによって副作用を生む場合があります。問題が起きたら個別プラグインを無効化して切り分けてください。

// z-index の最適化を無効化する例
cssnano({
  preset: ['default', { zindex: false }],
});

⚠️ 開発環境では無効にする

cssnano はファイルサイズ削減が目的なので、開発時に適用するとデバッグが困難になります。本番ビルドのみで有効にしましょう。

// postcss.config.ts
const isProduction = process.env.NODE_ENV === 'production';

export default {
  plugins: [
    ...(isProduction ? [['cssnano', { preset: 'default' }]] : []),
  ],
};

💡 Vite では組み込みの CSS 圧縮が優先される

Vite は本番ビルド時にデフォルトで lightningcss（または esbuild）による CSS 圧縮を行います。cssnano を使いたい場合は build.cssMinify の設定を確認してください。

💡 advanced プリセットは慎重に

cssnano-preset-advanced は未使用の @font-face や @keyframes の削除など、より積極的な最適化を行います。SPA で動的にクラスを付与するケースでは意図しない削除が起きる可能性があるため、十分にテストしてから導入してください。

💡 パフォーマンスが気になる場合

大規模プロジェクトでビルド時間が問題になる場合は、lite プリセットに切り替えるか、lightningcss への移行を検討してください。

---

まとめ

cssnano は PostCSS エコシステムにおける CSS 圧縮のデファクトスタンダードです。プリセットとプラグイン単位の細かな制御が可能で、既存の PostCSS ベースのビルド環境にはほぼゼロコストで導入できます。本番ビルドでの CSS 最適化に迷ったら、まず cssnano の default プリセットから始めるのがおすすめです。