【Stylelint】「ルールが効かない！」その原因、設定のせいかも？ "--print-config"で謎を解く方法

Web開発に携わっている皆さん、Stylelintは活用していますか？CSSやSCSSのコード品質を保つ上で、今や欠かせないリンターツールですよね。

しかし、時としてStylelintは私たちの言うことを聞いてくれなくなります。.stylelintrc.jsonを何度見直してもルールが適用されない… それどころか、「Unknown rule」なんてエラーに遭遇したことはありませんか？

この記事では、そんなStylelintの不可解な挙動に悩む開発者に向けて、問題の根源を特定し、解決に導くための方法をご紹介します。これは、先日私が携わったプロジェクトで実際に直面し、解決に至った実践的なノウハウです。

「Unknown rule」エラーの迷宮

「よし、SCSSに@importを禁止して、モダンな@useを強制するぞ！」

そう意気込んで.stylelintrc.jsonにルールを追加したものの、なぜかlintが全く機能しない。それどころか、コンソールにはこんな無慈悲なメッセージが…

1:1    Unknown rule max-empty-lines
1:1    Unknown rule string-quotes

max-empty-linesはStylelintの基本的なルールのはず。それを「知らない（Unknown）」と言われるのは、まさに怪奇現象。node_modulesを削除して再インストールしても、設定ファイルを書き換えても、このエラーは出続けます。

このエラーの正体、それは意図しない設定の上書きや、壊れた依存関係です。

多くのプロジェクトでは、extendsプロパティを使って、stylelint-config-standardのような標準的なルールセットを継承します。しかし、何らかの環境要因（ツールのバージョン互換性、パッケージマネージャーの癖など）でこの継承がうまく機能しないと、Stylelintはルール定義を正しく読み込めず、パニックに陥ってしまうのです。

解決への最終兵器：--print-config

もう設定ファイルと格闘するのはやめましょう。問題がファイルの中にあるのではなく、Stylelintが最終的にどんな設定を”認識”しているかを知ることが解決への近道です。

そこで登場するのが、StylelintのCLIが持つ診断用オプション--print-configです。

これは、Stylelintに「lintを実行する代わりに、指定したファイルをチェックする際に最終的に使用している設定をすべてJSON形式で出力して」と命令する、まさに最終兵器です。

使い方

プロジェクトのルートディレクトリで、以下のコマンドを実行します。

npx stylelint --print-config [対象のファイルパス] > stylelint-debug-output.json

例えば、src/scss/style.scssを対象にする場合はこうです。

npx stylelint --print-config src/scss/style.scss > stylelint-debug-output.json

npxを使うことで、プロジェクト内にインストールされたバージョンのStylelintを確実に使用できます。出力結果をstylelint-debug-output.jsonというファイルにリダイレクトすることで、長く複雑な設定内容をじっくりと確認できます。

デバッグ用JSONから”幽霊”の正体を暴く

コマンドを実行すると、stylelint-debug-output.jsonファイルが生成されます。この中身こそが、Stylelintの「頭の中」そのものです。

私が実際に遭遇したケースでは、このファイルの中に驚くべき記述がありました。

{
  "plugins": [
    "/path/to/your/project/node_modules/stylelint-scss/src/index.js"
  ],
  "rules": {
    "at-rule-disallowed-list": [["import"]],
    "max-empty-lines": [],
    "string-quotes": [],
    "number-leading-zero": []
  }
}

注目すべきは"max-empty-lines": []の部分です。

本来、ルールの設定値はtrueやnull、あるいは数値やオプションオブジェクトが入るべきです。しかし、ここには**無効な値である「空の配列 []」**が入ってしまっています。

これが「Unknown rule」エラーの直接的な原因でした。Stylelintは、この無効な設定値を解釈できず、エラーを吐き出していたのです。extendsで読み込んだ設定が、何らかの理由で壊れた形でマージされてしまった結果でした。

最終的な解決策：extendsからの脱却

原因が判明すれば、対策はシンプルです。問題を引き起こしているextends（設定の継承）を一切やめ、必要なルールだけを自分で定義するのです。

--print-configで出力された内容を参考に、本当に必要なルールだけをrulesセクションに書き写し、完全に自己完結した設定ファイルを作成します。

{
  "plugins": [
    "stylelint-scss"
  ],
  "rules": {
    // SCSSの基本的なエラー防止ルール
    "scss/at-rule-no-unknown": true,
    "scss/no-duplicate-mixins": true,

    // CSSの基本的なエラー防止ルール
    "color-no-invalid-hex": true,
    "block-no-empty": true,
    "property-no-unknown": true,
    "declaration-block-no-duplicate-properties": true,

    // 当初の目的だったルール
    "at-rule-disallowed-list": ["import"]
  }
}

この設定は、外部のルールセットに一切依存しないため、環境要因による不可解なエラーを完全に回避できます。遠回りに見えて、実は最も堅牢な解決策なのです。

まとめ

Stylelintが言うことを聞かない時、やみくもに設定ファイルをいじるのは得策ではありません。

1. npx stylelint --print-config [ファイルパス] を使って、Stylelintが最終的に何を考えているのかを可視化する。
2. 出力されたJSONを確認し、意図しない設定値（特に[]など）がないかを探す。
3. 問題の根源がextendsにあると判断したら、継承をやめて必要なルールだけをrulesに直接記述する。

このアプローチは、Stylelintに限らず、多くの設定ファイルベースのツール（ESLint, Prettierなど）のトラブルシューティングにも応用できる考え方です。

この記事が、あなたのプロジェクトから”幽霊”を追い出す手助けとなれば幸いです。Happy Linting!