Stylelint の使い方完全ガイド — CSSリンターの決定版

一言でいうと

Stylelint は、CSSのエラー検出とコーディング規約の強制を行う強力なリンターです。100以上の組み込みルールを持ち、SCSS・Less・CSS-in-JSなどにも対応し、自動修正機能も備えています。

どんな時に使う？

• チーム開発でCSSの書き方を統一したい — プロパティの記述順序、命名規則、使用する単位などをルールとして定義し、CI/CDで自動チェックできます
• CSSの構文エラーや非推奨パターンを早期に検出したい — 不正なグリッド定義、重複セレクタ、存在しないプロパティ名などをコミット前に発見できます
• SCSS/Less/CSS-in-JSプロジェクトでも一貫したリント環境を構築したい — プラグインやカスタムシンタックスにより、さまざまなCSS系言語に対応できます

インストール

# npm
npm install --save-dev stylelint stylelint-config-standard

# yarn
yarn add --dev stylelint stylelint-config-standard

# pnpm
pnpm add --save-dev stylelint stylelint-config-standard

stylelint-config-standard は公式が提供する推奨ルールセットです。プロジェクトに合わせて他の共有設定を選択することもできます。

基本的な使い方

1. 設定ファイルの作成

プロジェクトルートに .stylelintrc.json を作成します。

{
  "extends": ["stylelint-config-standard"],
  "rules": {
    "color-named": "never",
    "selector-class-pattern": "^[a-z][a-zA-Z0-9]+$",
    "max-nesting-depth": 3
  }
}

2. CLIで実行

# すべてのCSSファイルをリント
npx stylelint "**/*.css"

# 自動修正を適用
npx stylelint "**/*.css" --fix

# SCSSファイルを対象にする場合
npx stylelint "**/*.scss"

3. package.json にスクリプトを追加

{
  "scripts": {
    "lint:css": "stylelint \"src/**/*.css\"",
    "lint:css:fix": "stylelint \"src/**/*.css\" --fix"
  }
}

4. Node.js API から使う（TypeScript）

import stylelint from "stylelint";

async function lintCSS() {
  const result = await stylelint.lint({
    files: "src/**/*.css",
    config: {
      extends: ["stylelint-config-standard"],
    },
  });

  if (result.errored) {
    console.error(result.report);
    // result.results には各ファイルの詳細な警告・エラー情報が含まれる
    for (const fileResult of result.results) {
      console.log(`${fileResult.source}: ${fileResult.warnings.length} issues`);
      for (const warning of fileResult.warnings) {
        console.log(
          `  Line ${warning.line}:${warning.column} - ${warning.text} (${warning.rule})`
        );
      }
    }
  } else {
    console.log("All CSS files are valid!");
  }
}

lintCSS();

よく使うAPI・機能

1. extends — 共有設定の継承

複数の共有設定を組み合わせて使えます。後に指定したものが優先されます。

{
  "extends": [
    "stylelint-config-standard",
    "stylelint-config-css-modules"
  ]
}

主要な共有設定パッケージ：

2. rules — 個別ルールの設定

ルールは true（有効）、null（無効）、または配列でオプション付き指定ができます。

{
  "extends": ["stylelint-config-standard"],
  "rules": {
    "color-no-invalid-hex": true,
    "declaration-block-no-duplicate-properties": [
      true,
      {
        "ignore": ["consecutive-duplicates-with-different-syntaxes"]
      }
    ],
    "unit-allowed-list": ["rem", "em", "%", "vw", "vh", "s", "ms", "deg"],
    "selector-id-pattern": null,
    "color-function-notation": ["modern", { "severity": "warning" }]
  }
}

3. overrides — ファイルパターンごとの設定上書き

特定のファイルやディレクトリに対して異なるルールを適用できます。

{
  "extends": ["stylelint-config-standard"],
  "overrides": [
    {
      "files": ["**/*.scss"],
      "extends": ["stylelint-config-standard-scss"],
      "rules": {
        "scss/dollar-variable-pattern": "^[a-z][a-zA-Z0-9]+$"
      }
    },
    {
      "files": ["src/legacy/**/*.css"],
      "rules": {
        "selector-class-pattern": null
      }
    }
  ]
}

4. plugins — カスタムルールの追加

サードパーティのプラグインを導入して、組み込みルールにはない検証を追加できます。

{
  "extends": ["stylelint-config-standard"],
  "plugins": [
    "stylelint-order",
    "stylelint-declaration-block-no-ignored-properties"
  ],
  "rules": {
    "order/properties-alphabetical-order": true,
    "plugin/declaration-block-no-ignored-properties": true
  }
}

5. インラインコメントによる無効化

特定の行やブロックでルールを無効化できます。

/* stylelint-disable color-named */
.legacy-button {
  color: red; /* 通常なら color-named ルールで警告される */
  background: blue;
}
/* stylelint-enable color-named */

.icon {
  width: 20px; /* stylelint-disable-line unit-allowed-list */
}

/* stylelint-disable-next-line selector-class-pattern */
.legacy_class_name {
  display: flex;
}

Tip: reportNeedlessDisables オプションを有効にすると、不要な stylelint-disable コメントを検出できます。

{
  "reportNeedlessDisables": true
}

類似パッケージとの比較

ポイント: Stylelint と Prettier は競合ではなく補完関係です。Prettier はフォーマット（インデント、改行等）を担当し、Stylelint はロジカルなルール（不正な値、命名規則等）を担当します。併用する場合は stylelint-config-prettier（v15以降は不要な場合あり）で競合ルールを無効化してください。

注意点・Tips

v16 → v17 マイグレーション時の注意

Stylelint 17 では破壊的変更があります。主な変更点：

• Node.js 18.12.0 以上が必須です
• 一部の非推奨ルールが削除されています
• 設定ファイルの ESM 対応が改善されています

アップグレード前に 公式マイグレーションガイド を確認してください。

ESM設定ファイルの利用

v17 では stylelint.config.mjs を使った ESM 形式の設定が安定しています。

// stylelint.config.mjs
export default {
  extends: ["stylelint-config-standard"],
  rules: {
    "color-named": "never",
  },
};

CI/CDへの組み込み

GitHub Actions での設定例：

# .github/workflows/lint.yml
name: CSS Lint
on: [push, pull_request]
jobs:
  stylelint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: npm ci
      - run: npx stylelint "src/**/*.css"

エディタ連携

VS Code を使っている場合は、公式拡張機能を導入すると、保存時に自動修正が走るように設定できます。

// .vscode/settings.json
{
  "editor.codeActionsOnSave": {
    "source.fixAll.stylelint": "explicit"
  },
  "stylelint.validate": ["css", "scss", "less"],
  "css.validate": false,
  "scss.validate": false,
  "less.validate": false
}

VS Code 組み込みの CSS バリデーションと競合するため、css.validate 等を false にするのがベストプラクティスです。

パフォーマンスTips

• --cache オプションを使うと、変更されたファイルのみリントされ、大規模プロジェクトで大幅に高速化します
• ignoreFiles で node_modules やビルド成果物を除外しましょう

{
  "extends": ["stylelint-config-standard"],
  "ignoreFiles": [
    "node_modules/**",
    "dist/**",
    "coverage/**"
  ]
}

npx stylelint "src/**/*.css" --cache --cache-location .stylelintcache

.stylelintcache は .gitignore に追加しておきましょう。

まとめ

Stylelint は、CSS系言語のリンティングにおけるデファクトスタンダードです。100以上の組み込みルール、プラグインによる拡張性、自動修正機能を備え、チーム開発でのCSS品質を確実に向上させます。Prettier と併用し、エディタ連携とCI/CDを設定すれば、CSSのコード品質を自動的に維持できる堅牢な開発環境が構築できます。