StylelintでCSSをLintする方法

May 4, 2026 · 3 min read

雑なCSSは書くのは簡単ですが、メンテナンスが困難です。プロパティのスペルミス、重複したセレクタ、一貫性のない記法はコードレビューをすり抜け、技術的負債として蓄積されていきます。Stylelint は、本番環境に到達する前にエラーを検出し、標準を自動的に適用することでこの問題を解決します。

このガイドでは、StylelintによるCSSのLintを今日からプロジェクトで動作させるために必要な内容をすべて解説します。

主なポイント

Stylelintは静的解析によりCSSのエラーを検出し、規約を強制します。100以上の組み込みルールを備えています。
フォーマットではなくコード品質を扱うため、Prettierと競合せず、自然に併用できます。
最も簡単なセットアップは npm create stylelint@latest で、設定ファイルの雛形作成と stylelint-config-standard のインストールを自動で行います。
ルールは有効化、無効化、または警告レベルへの引き下げが可能で、既存のコードベースにStylelintを導入する際に役立ちます。
npmスクリプトとCIパイプラインに組み込み、Lintが確実に実行されるようにしましょう。

Stylelintとは何か、なぜワークフローに必要なのか?

Stylelintは100以上の組み込みルールを持つCSS Linterで、GoogleやGitHubのチームに信頼されています。CSSファイルを静的に解析し、無効な構文、未知のプロパティ、重複したセレクタ、規約違反などの問題を、コードを実行することなく報告します。

ここで重要な区別が一つあります: Stylelintはコード品質を扱うのであって、フォーマットは扱いません。スペースやセミコロンに関して Prettier と争うことはありません。両者は補完的なツールです。Prettierがフォーマットを担当し、Stylelintは正しさと一貫性を強制します。両方を使いましょう。

Stylelintのインストール: 始め方は2通り

Stylelintは最新のNode.jsバージョン(最近のリリースではNode 20.19.0以降)を必要とするため、環境が最新であることを確認してください。

オプション1: 自動セットアップ(推奨)

StylelintでCSSをLintする最も速い方法は create コマンドです:

npm create stylelint@latest

これにより設定ファイルの雛形が作成され、stylelint-config-standard が自動的にインストールされます。pnpm、Yarn、Bunでも動作します:

pnpm create stylelint
bun create stylelint

オプション2: 手動でのStylelintセットアップ

完全にコントロールしたい場合は、依存関係を自分でインストールします:

npm add -D stylelint stylelint-config-standard

次に、プロジェクトのルートに stylelint.config.mjs ファイルを作成します:

/** @type {import('stylelint').Config} */
export default {
  extends: ["stylelint-config-standard"]
};

.mjs 拡張子は最新のモジュール形式であるESMを使用します。StylelintはESM設定をサポートしており、現在のセットアップでは推奨されるアプローチです。

CSSファイルに対してStylelintを実行する

インストール後、すべてのCSSファイルに対してStylelintを実行します:

npx stylelint "**/*.css"

違反があれば、次のような出力が表示されます:

src/main.css
  12:3  ✖  Unexpected duplicate selector ".btn"   no-duplicate-selectors
  24:5  ✖  Unknown property "colour"              property-no-unknown

修正可能なものを自動的に修正するには、--fix フラグを追加します:

npx stylelint "**/*.css" --fix

すべてのルールが自動修正をサポートしているわけではありませんが、多くがサポートしています。--fix フラグは可能な限り安全な修正を適用しますが、すべての問題を解決するわけではありません。

Stylelint CSS Lintルールの設定

stylelint-config-standard は堅実なベースラインです。これを拡張し、設定で特定のルールを上書きできます:

/** @type {import('stylelint').Config} */
export default {
  extends: ["stylelint-config-standard"],
  rules: {
    "color-no-invalid-hex": true,
    "unit-no-unknown": true,
    "selector-id-pattern": null  // disable a rule
  }
};

ルールは有効化のための true、無効化のための null、または重大度を設定する配列を受け付けます:

"color-no-invalid-hex": [true, { severity: "warning" }]

これは、既存のコードベースにStylelintを導入する際に便利です。警告にすれば、ビルドを即座にブロックすることなく問題を監査できます。

package.jsonにLintスクリプトを追加する

npmスクリプトでStylelintをワークフローに組み込みます:

{
  "scripts": {
    "lint:css": "stylelint \"**/*.css\""
  }
}

npm run lint:css で実行します。ここから、lint-staged と Husky を使ってCIパイプラインやpre-commitフックに統合できます。

CSS Lintのベストプラクティス

stylelint-config-standard から始める — 現在のCSSベストプラクティスを反映し、活発にメンテナンスされています。
レガシーコードにStylelintを導入する場合は、エラーよりも先に警告を使用する。
.stylelintignore ファイル(.gitignore と同様)を追加して、生成されたファイルを無視する。
Prettierと併用する — Stylelintをフォーマットに使おうとしないでください。
CIで実行する — ローカルマシンだけでLintするとスキップされがちです。

まとめ

Stylelintのセットアップには約5分しかかからず、エラーの検出と一貫性のあるコードによってすぐに見返りが得られます。インストールして、stylelint-config-standard を拡張し、スクリプトを追加して実行しましょう。これがすべてのセットアップです。それ以外のすべて — カスタムルール、SCSSサポート、IDE統合 — はこの基盤の上に構築されます。

FAQ

はい。Stylelintは `postcss-scss` や `postcss-less` などのカスタム構文を介して、SCSS、Less、その他のCSS系構文をサポートしています。CSS-in-JSのサポートは特定のライブラリに依存し、`customSyntax` オプションで設定された適切なカスタム構文パッケージが必要です。

はい、両者は異なる問題を解決します。Prettierはコードをフォーマットし、空白、改行、引用符のスタイルを処理します。Stylelintは無効なプロパティ、重複したセレクタ、規約違反といったコード品質の問題を検出します。最新のStylelintは、Prettierとの重複を避けるためにスタイル系のルールを削除しているので、両者は競合なく協調して動作します。

lint-stagedとHuskyを使用します。package.jsonでlint-stagedを設定してステージングされたCSSファイルに対して stylelint --fix を実行するようにし、次にlint-stagedを呼び出すHuskyのpre-commitフックを追加します。これによりコミット直前のファイルのみをLintするため、大規模なリポジトリでもフックは高速に保たれ、問題のあるCSSがメインブランチに到達するのを防ぎます。

はい。VS Codeには公式のStylelint拡張機能があり、入力中に問題をハイライトし、保存時に修正できます。WebStormやその他のJetBrains IDEには組み込みのStylelintサポートが含まれています。その他のエディタにはコミュニティでサポートされている統合があるかもしれません。エディタ統合は、CLIを手動で実行するのに比べてフィードバックループを大幅に短縮します。

Complete picture for complete understanding

Capture every clue your frontend is leaving so you can instantly get to the root cause of any issue with OpenReplay — the open-source session replay tool for developers. Self-host it in minutes, and have complete control over your customer data.

Check our GitHub repo and join the thousands of developers in our community.