🤖

stylelintユーザガイドー構成

2025/04/27に公開

内容の目的

本内容は、Stylelintユーザガイドー構成を翻訳し、個人活用のために整理しています。

設定方法

Stylelintは設定オブジェクトを必要とします。

現在の作業ディレクトリから開始して、Stylelintは上位ディレクトリへ向かってstylelint.config.jsファイルを探し、エクスポートされた設定を見つけます。--config や configFile オプションを使うことで、この探索を省略できます。

エクスポートのスタイルは、Node.js のデフォルトのモジュールシステム設定（例: package.json内の"type": "module"）によって異なります。明示的にしたい場合は stylelint.config.mjs や stylelint.config.cjs というファイル名を使うこともできます。

stylelint.config.js ファイルの例:

/** @type {import('stylelint').Config} */
export default {
  rules: {
    "block-no-empty": true
  }
};

[!NOTE]
Stylelintは現在、他の場所やフォーマットでの設定ファイルもサポートしていますが、今後これらは削除される可能性があります:

export default または module.exports を使った .stylelintrc.js ファイル

export default を使った .stylelintrc.mjs ファイル

module.exports を使った .stylelintrc.cjs ファイル

YAML または JSON 形式の .stylelintrc ファイル

.stylelintrc.yml または .stylelintrc.yaml ファイル

.stylelintrc.json ファイル

package.json の stylelint プロパティ

設定オブジェクトは以下のプロパティを持ちます:

`rules`

ルールはリンターが何を検出し、何について警告するかを決めます。Stylelintには100以上のルールが組み込まれていますが、デフォルトではどのルールも有効になっていません。

rulesプロパティは、_キーがルール名、値がルール設定のオブジェクト_です。例:

{
  "rules": {
    "color-no-invalid-hex": true
  }
}

各ルールの設定は次のいずれかの形式になります:

null（ルールを無効化）
単一の値（主オプション）
2つの値の配列（[主オプション, 副オプション]）

主オプションを指定すると、そのルールは有効になります。

多くのルールはさらなるカスタマイズのための副オプションも提供しています。副オプションを設定するには2要素の配列を使います。例:

{
  "rules": {
    "selector-pseudo-class-no-unknown": [
      true,
      {
        "ignorePseudoClasses": ["global"]
      }
    ]
  }
}

オブジェクトにはいくつでもキーを追加できます。例えば、以下のようなことができます:

block-no-empty を無効化
unit-allowed-list を主オプションで有効化
alpha-value-notation を主・副オプション付きで有効化

{
  "rules": {
    "block-no-empty": null,
    "unit-allowed-list": ["em", "rem", "%", "s"],
    "alpha-value-notation": ["percentage", { "exceptProperties": ["opacity"] }]
  }
}

一部のルールやオプションは正規表現を受け付けます。よくあるケースを以下で強制できます:

ケバブケース: ^([a-z][a-z0-9]*)(-[a-z0-9]+)*$
lowerCamelCase: ^[a-z][a-zA-Z0-9]+$
スネークケース: ^([a-z][a-z0-9]*)(_[a-z0-9]+)*$
アッパーキャメルケース: ^[A-Z][a-zA-Z0-9]+$

また、肯定的な後読み正規表現を使ってプレフィックスを強制することもできます。例: (?<=foo-) で foo- をプレフィックスに指定。

`disableFix`

disableFix 副オプションを使うと、_ルールごとに_自動修正を無効化できます。

例:

{
  "rules": {
    "color-function-notation": ["modern", { "disableFix": true }]
  }
}

`message`

message 副オプションを使うと、ルール違反時にカスタムメッセージを表示できます。

例えば、次のような設定でカスタムメッセージを差し込めます:

{
  "rules": {
    "custom-property-pattern": [
      "^([a-z][a-z0-9]*)(-[a-z0-9]+)*$",
      {
        "message": "Expected custom property name to be kebab-case"
      }
    ]
  }
}

さらに高度なカスタマイズが必要な場合はカスタムフォーマッタを書くこともできます。

実験的機能: 一部のルールはメッセージ引数をサポートしています。例えば color-no-hex ルールでは、違反した16進カラー値をメッセージ文字列に使えます:

JavaScriptの場合:

export default {
  rules: {
    "color-no-hex": [
      true,
      {
        message: (hex) => `Don't use hex colors like "${hex}"`
      }
    ]
  }
};

Via JSON:

{
  "rules": {
    "color-no-hex": [
      true,
      {
        "message": "Don't use hex colors like \"%s\""
      }
    ]
  }
}

JSONのように関数をサポートしない形式では、printfのような書式（例: %s）を使えます。一方、JS形式では関数もprintf形式も両方使えます。

`url`

url 副オプションで外部ドキュメントへのカスタムリンクを指定できます。これらのURLはカスタムフォーマッタで表示できます。

例:

{
  "rules": {
    "color-no-hex": [true, { "url": "https://example.org/your-custom-doc" }]
  }
}

`reportDisables`

reportDisables 副オプションを設定すると、このルールに対する stylelint-disable コメントが報告され、実質的に回避を禁止できます。

例:

{
  "rules": {
    "color-no-invalid-hex": [true, { "reportDisables": true }]
  }
}

この報告はリンターエラーとして扱われます。

`severity`

severity 副オプションで特定ルールの重大度を調整できます。

severity の利用可能な値は次の通りです:

"warning"（警告）
"error"（エラー、デフォルト）

例:

{
  "rules": {
    "number-max-precision": [
      2,
      {
        "ignoreUnits": ["em"],
        "severity": "warning"
      }
    ]
  }
}

レポーターはこれらの重大度レベルを使って問題を表示したり、プロセスの終了方法を変えたりできます。

実験的機能: 一部のルールはメッセージ引数をサポートします。これらのルールでは、severityに関数を使うことで、引数に応じて重大度を動的に変更できます。

この関数は "error"、"warning"、または null を返す必要があります。null の場合は defaultSeverity が使われます。

例:

export default {
  rules: {
    "selector-disallowed-list": [
      ["a > .foo", "/\\[data-.+]/"],
      {
        severity: (selector) => {
          return selector.includes("a > .foo") ? "error" : "warning";
        }
      }
    ]
  }
};

次のパターンはエラーとして報告されます:

a > .foo {}

一方、次のパターンは警告として報告されます:

a[data-auto="1"] {}

`languageOptions`

atルール、プロパティ、型、CSSワイドキーワードの構文を定義・拡張できます。

`syntax`

デフォルトのCSS構文を拡張・変更し、以下の点をカスタマイズできます:

atRules: 独自のatルールを特定のpreludeやdescriptors構文で定義
cssWideKeywords: 独自の値でCSSワイドキーワードを拡張
properties: 特定プロパティの構文をカスタマイズ
types: プロパティ値で使われる型定義を拡張・変更

{
  "languageOptions": {
    "syntax": {
      "atRules": {
        "example": {
          "comment": "Example at-rule",
          "prelude": "<custom-ident>",
          "descriptors": {
            "foo": "<number>",
            "bar": "<color>"
          }
        }
      },
      "cssWideKeywords": ["my-global-value"],
      "properties": { "top": "| <--foo()>" },
      "types": { "--foo()": "--foo( <length-percentage> )" }
    }
  },
  "rules": {
    "at-rule-descriptor-no-unknown": true,
    "at-rule-descriptor-value-no-unknown": true,
    "at-rule-prelude-no-invalid": true,
    "declaration-property-value-no-unknown": true
  }
}

以下のルールは languageOptions プロパティで設定されます:

`AtRules`

atルールの期待されるpreludeやdescriptorsを定義することでカスタマイズできます。
例えば、新しいatルール@fooを特定のdescriptors付きでサポートする場合:

{
  "languageOptions": {
    "syntax": {
      "atRules": {
        "foo": {
          "prelude": "<custom-ident>",
          "descriptors": {
            "bar": "<number>",
            "baz": "<color>"
          }
        }
      }
    }
  }
}

at-rule-descriptor-no-unknown が有効な場合、次のパターンは問題とみなされます:

@foo custom-ident { qux: 10; }

at-rule-descriptor-value-no-unknown が有効な場合、次のパターンは問題とみなされます:

@foo custom-ident { bar: red; }

どちらの場合も、次のパターンは_問題とみなされません_:

@foo custom-ident { bar: 10; baz: red; }

`cssWideKeywords`

有効なプロパティ値として認められるグローバルキーワードを追加できます。
例えば、ワイドキーワードに -moz-initial を追加する場合:

{
  "languageOptions": {
    "syntax": {
      "cssWideKeywords": ["-moz-initial"]
    }
  }
}

declaration-property-value-no-unknown が有効な場合、次のパターンは問題とみなされます:

a { color: foo; }

次のパターンは_問題とみなされません_:

a { color: -moz-initial; }

`properties`

特定のプロパティの構文を拡張・変更できます。
例えば、カスタムプロパティfooが<color>値を受け入れるようにする場合:

{
  "languageOptions": {
    "syntax": {
      "properties": { "foo": "<color>" }
    }
  }
}

declaration-property-value-no-unknown が有効な場合、次のパターンは問題とみなされます:

a { foo: 10px; }

次のパターンは_問題とみなされません_:

a { foo: red; }

`types`

特定の型の構文を拡張・変更できます。
例えば、新しい関数--foo()が<length-percentage>値を受け入れ、topプロパティで使えるようにする場合:

{
  "languageOptions": {
    "syntax": {
      "types": { "--foo()": "--foo( <length-percentage> )" },
      "properties": { "top": "| <--foo()>" }
    }
  }
}

declaration-property-value-no-unknown が有効な場合、次のパターンは問題とみなされます:

a { top: --foo(red); }

次のパターンは_問題とみなされません_:

a { top: --foo(10px); }

`extends`

既存の設定（自作・サードパーティ問わず）を拡張できます。設定ファイルはプラグイン、カスタム構文、オプション、ルール設定などをバンドルでき、他の設定をさらに拡張することもできます。

例えば、stylelint-config-standard は公式の拡張可能な設定です。

ある設定が別の設定を拡張すると、まず拡張元のプロパティを引き継ぎ、その上で追加や上書きを行います。

例: stylelint-config-standard を拡張し、アルファ値を数値に変更、selector-class-patternルールを無効化:

{
  "extends": "stylelint-config-standard",
  "rules": {
    "alpha-value-notation": "number",
    "selector-class-pattern": null
  }
}

既存設定の配列を拡張することもでき、後ろのものほど優先されます（2番目が1番目を、3番目が1番目と2番目を… 最後がすべてを上書き）。

例: stylelint-config-standard、その上にmyExtendableConfig、さらにalpha-value-notationルールを上書き:

{
  "extends": ["stylelint-config-standard", "./myExtendableConfig"],
  "rules": {
    "alpha-value-notation": "number"
  }
}

"extends" の値は「ロケータ」（またはロケータの配列）で、最終的に require() されます。Nodeの require.resolve() アルゴリズムで解決できる形式なら何でもOKです。つまりロケータは以下のいずれかです:

node_modules 内のモジュール名（例: stylelint-config-standard。そのモジュールの main ファイルは有効なJSON設定である必要あり）
.jsまたは.json拡張子付きのファイルへの絶対パス（Node.jsでJSオブジェクトを作成して渡す場合など）
参照元設定ファイルからの相対パス（例: configAがextends: "../configB"を持つ場合はconfigAから見たconfigBを探す）

他の設定は Awesome Stylelint で見つかります。

`plugins`

プラグインは、手法・ツールセット・_非標準_のCSS機能・特殊な用途向けに作られたカスタムルールやそのセットです。

例えば stylelint-order は宣言ブロック内のプロパティの順序などを制御する人気プラグインです。

プラグインはよく拡張できる共通設定に含まれています。例: stylelint-config-standard-scss 設定には stylelint-scss プラグインが含まれています。

プラグインを直接使うには、設定ファイルに"plugins"配列を追加し、プラグインオブジェクトまたは使いたいプラグインを特定する「ロケータ」を指定します。extendsと同様、ロケータは以下のいずれかです:

npmモジュール名
絶対パス
設定ファイルからの相対パス

プラグインを宣言したら、"rules"オブジェクト内で_そのプラグインのルールにもオプションを追加_する必要があります（標準ルールと同じ）。ルール名はプラグインのドキュメントを参照してください。

{
  "plugins": ["../special-rule.js"],
  "rules": {
    "plugin-namespace/special-rule": "everything"
  }
}

「プラグイン」は単一ルールまたは複数ルールを提供できます。セットを提供するプラグインの場合、"plugins"でモジュールを指定し、"rules"でそのルール群を使います。例:

{
  "plugins": ["../some-rule-set.js"],
  "rules": {
    "some-rule-set/first-rule": "everything",
    "some-rule-set/second-rule": "nothing",
    "some-rule-set/third-rule": "everything"
  }
}

他のプラグインは Awesome Stylelint で見つかります。

`customSyntax`

独自の構文パーサーを指定できます。詳細はこちら。

`overrides`

overridesプロパティを使うと、設定を適用するファイルのサブセットを指定できます。

例えば、以下のように:

すべての.scssファイルでpostcss-scss構文を使用
components・pagesディレクトリ内のすべての.cssファイルでアルファ値記法をpercentageに

{
  "rules": {
    "alpha-value-notation": "number"
  },
  "overrides": [
    {
      "files": ["*.scss", "**/*.scss"],
      "customSyntax": "postcss-scss"
    },
    {
      "files": ["components/**/*.css", "pages/**/*.css"],
      "rules": {
        "alpha-value-notation": "percentage"
      }
    }
  ]
}

overridesプロパティの値はオブジェクトの配列です。各オブジェクトは:

filesプロパティ（設定を適用するファイルを指定するグロブパターンの配列）を必ず含む必要があります
customSyntax、rules、extends など他の通常の設定プロパティを1つ以上含めるべきです
nameプロパティでオーバーライドの目的を説明することもできます

customSyntaxは上書きされますが、plugins、extends、rulesなどは追加されます。

パターンは設定ファイルのディレクトリからの相対パスで適用されます。例: 設定ファイルが /project-foo/.stylelintrc.js、対象ファイルが /project-foo/components/bar.css の場合、.stylelintrc.jsで指定したパターンは components/bar.css に対して評価されます。

オーバーライドは通常の設定よりも優先されます。同じ設定ファイル内で複数のオーバーライドがある場合、順番に適用され、最後のオーバーライドブロックが最も優先されます。

`processors`

[!WARNING]
これは実験的な機能です。APIは将来的に変更される可能性があります。

この processors プロパティはバージョン15.0.0で一度削除されましたが、ポストプロセッシング用に復活しました。以前の挙動とは異なりますのでご注意ください。

プロセッサはStylelintのパイプラインにフックする関数です。
現在、プロセッサは name（文字列）と postprocess（関数）の2つのプロパティのみ持ちます。postprocessはすべてのルール評価後に実行され、リンティング処理のresultオブジェクトを受け取り、変更できます。

例えば、プロセッサを使って警告の位置情報を再マップできます。下記プロセッサは color-no-hex ルールの警告位置をCSS宣言全体に拡張します。a { color: #111; } のような場合、元の警告位置は16進カラー自体（例: 1行目12-16列）ですが、処理後は宣言全体（例: 1行目5-16列）になります。

{
  "rules": { "color-no-hex": true },
  "processors": ["path/to/my-processor.js"]
}

// my-processor.js

/** @type {import("stylelint").Processor} */
export default function myProcessor() {
  return {
    name: "remap-color-no-hex",

    postprocess(result, root) {
      // 'color-no-hex'ルールの警告位置を宣言全体に拡張
      const updatedWarnings = result.warnings.map((warning) => {
        if (warning.rule !== "color-no-hex") {
          return warning;
        }

        let updatedWarning = { ...warning };

        root?.walk((node) => {
          const { start, end } = node.source;

          if (
            node.type === "decl" &&
            start.line <= warning.line &&
            end.line >= warning.endLine &&
            start.column <= warning.column &&
            end.column >= warning.endColumn
          ) {
            updatedWarning = {
              ...updatedWarning,
              line: start.line,
              endLine: end.line,
              column: start.column,
              endColumn: end.column
            };

            return false;
          }
        });

        return updatedWarning;
      });

      result.warnings = updatedWarnings;
    }
  };
}

`defaultSeverity`

副オプションで重大度が指定されていないすべてのルールのデフォルト重大度を設定できます。例: デフォルト重大度を "warning" に設定

{
  "defaultSeverity": "warning"
}

`report*`

これらのreport*プロパティは、stylelint-disableコメントの追加検証を提供します。これにより、有用で適切に記述された無効化を強制できます。

利用可能なレポートは次のとおりです:

reportDescriptionlessDisables
reportInvalidScopeDisables
reportNeedlessDisables
reportUnscopedDisables

これらはルールと同じように設定できます。値は以下のいずれかです:

null（無効化）
true または false（主オプション）
2要素配列（[主オプション, 副オプション]）

副オプションとしては以下が利用可能です:

"except": 主オプションを反転させるルール名配列
"severity": エラーの重大度（前述参照）

例: すべてのルール（selector-max-typeを除く）に対する不要な無効化をエラーにする:

{
  "reportNeedlessDisables": [true, { "except": ["selector-max-type"] }]
}

また、unit-allowed-listの説明なし無効化を警告として出力:

{
  "reportDescriptionlessDisables": [
    false,
    {
      "except": ["unit-allowed-list"],
      "severity": "warning"
    }
  ]
}

`reportDescriptionlessDisables`

説明のない stylelint-disable コメントを報告します。report* プロパティの一つです。

例:

{
  "reportDescriptionlessDisables": true
}

詳細はこちら。

`reportInvalidScopeDisables`

設定オブジェクトで指定されたルールに一致しない stylelint-disable コメントを報告します。report* プロパティの一つです。

例:

{
  "reportInvalidScopeDisables": true
}

詳細はこちら。

`reportNeedlessDisables`

無効化する必要のないリントに対する stylelint-disable コメントを報告します。report* プロパティの一つです。

例:

{
  "reportNeedlessDisables": true
}

詳細はこちら。

`reportUnscopedDisables`

少なくとも1つのルールにスコープされていない設定コメントを報告します。report* プロパティの一つです。

例:

{
  "reportUnscopedDisables": true
}

詳細はこちら。

`configurationComment`

/* stylelint-disable */ のような設定コメントのプレフィックスを変更できます。異なる設定で複数のStylelintインスタンスを使う場合に便利です。

例: デフォルトの /* stylelint-disable */ の代わりに /* stylelint-foo-instance-disable */ でルールを無効化:

{
  "configurationComment": "stylelint-foo-instance"
}

`ignoreDisables`

stylelint-disable（例: /* stylelint-disable block-no-empty */）コメントを無視します。

例:

{
  "ignoreDisables": true
}

詳細はこちら。

`ignoreFiles`

グロブまたはグロブ配列を指定して特定のファイルを無視できます。

例: すべてのJavaScriptファイルを無視

{
  "ignoreFiles": ["**/*.js"]
}

Stylelintはデフォルトでnode_modulesディレクトリを無視しますが、ignoreFilesを設定するとこれが上書きされます。

グロブが絶対パスの場合はそのまま使われます。相対パスの場合は以下の順で基準が決まります:

configBasedir が指定されていればそれ
Stylelintが見つけて読み込んだ設定ファイルのパス
それ以外は process.cwd()

[!NOTE]
これは大量のファイルを無視する効率的な方法ではありません。大量のファイルを効率的に無視したい場合は.stylelintignoreを使うか、filesグロブを調整してください。

`allowEmptyInput`

グロブパターンがファイルに一致しない場合でもStylelintがエラーをスローしません。

例:

{
  "allowEmptyInput": true
}

[!NOTE]
この設定オプションはファイル単位で上書きすべきではありません。

詳細はこちら。

`cache`

処理済みファイルの結果を保存し、変更されたファイルのみStylelintが再処理します。

例:

{
  "cache": true
}

[!NOTE]
この設定オプションはファイル単位で上書きすべきではありません。

詳細はこちら。

`fix`

ルールで検出された問題を可能な限り自動修正します。

例:

{
  "fix": true
}

[!NOTE]
この設定オプションはファイル単位で上書きすべきではありません。

詳細はこちら。

`formatter`

結果を整形するフォーマッターを指定できます。

オプションは以下の通りです:

提供されているフォーマッター名
```
{
  "formatter": "string"
}
```

カスタムフォーマッター関数へのパス

{
  "formatter": "path/to/customformatter.js"
}

フォーマッター関数

export default {
  formatter: () => {
    /* ... */
  }
};

詳細はこちら。

目次に戻る

内容の目的

設定方法

rules

disableFix

message

url

reportDisables

severity

languageOptions

syntax

AtRules

cssWideKeywords

properties

types

extends

plugins

customSyntax

overrides

processors

defaultSeverity

report*

reportDescriptionlessDisables

reportInvalidScopeDisables

reportNeedlessDisables

reportUnscopedDisables

configurationComment

ignoreDisables

ignoreFiles

allowEmptyInput

cache

fix

formatter

Discussion

`rules`

`disableFix`

`message`

`url`

`reportDisables`

`severity`

`languageOptions`

`syntax`

`AtRules`

`cssWideKeywords`

`properties`

`types`

`extends`

`plugins`

`customSyntax`

`overrides`

`processors`

`defaultSeverity`

`report*`

`reportDescriptionlessDisables`

`reportInvalidScopeDisables`

`reportNeedlessDisables`

`reportUnscopedDisables`

`configurationComment`

`ignoreDisables`

`ignoreFiles`

`allowEmptyInput`

`cache`

`fix`

`formatter`