Zenn
🤖

stylelintユーザガイドーオプション

に公開
CSS
Sass
Scss
tech

内容の目的

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

オプション

以下の共通オプションです：

これらのオプションの一部は、設定オブジェクトでも使用できます。

allowEmptyInput

CLIフラグ: --allow-empty-input, --aei

グロブパターンがファイルにマッチしなかった場合でも、Stylelintはエラーを投げません。

configFile

CLIフラグ: --config, -c

設定オブジェクトを含むJSON、YAML、またはJSファイルへのパス。

Stylelintに設定ファイルの検索をさせたくない場合にこのオプションを使用してください。

パスは絶対パスか、プロセスが実行されているディレクトリ（process.cwd()）からの相対パスである必要があります。

configBasedir

CLIフラグ: --config-basedir

"extends"、"plugins"、および "customSyntax" の相対パスが基準とするディレクトリの絶対パス。これらの値が相対パスの場合にのみ必要です。

fix

CLIフラグ: --fix

可能な限りルールによって報告された問題を自動修正します。

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

  • "lax"（デフォルト） - postcss-safe-parserを使い、構文エラーがあってもできる限り修正します
  • "strict" - PostCSS Parserを使い、構文エラーがない場合のみ問題を修正します

[!TIP]
厳密さにこだわらない場合は、将来的に "strict" がデフォルトになる可能性があるため、オプションなしで --fix を使うことを推奨します。

Node.js APIを使用する場合、自動修正されたコードは返されるオブジェクトの code プロパティの値として利用可能です。

ルールが非推奨の context.fix に依存している場合、ソースに以下が含まれていると：

  • スコープ付き無効化コメント（例: /* stylelint-disable color-named */）がある場合、そのルールによって報告された問題はソースのどこでも自動修正されません
  • スコープなし無効化コメント（例: /* stylelint-disable */）がある場合、そのルールに対してソース全体が自動修正されません

computeEditInfo

CLIフラグ: --compute-edit-info, --cei

自動修正可能なルールの編集情報を計算します。

編集情報は以下の場合に計算されません：

  • fix オプションが有効な場合
  • ルールの修正が無効化されている場合：
    • 設定オブジェクトで例："rule-name": [true, { disableFix: true }]
    • 設定コメントで例：/* stylelint-disable rule-name */
  • 同じコード領域に対して既に別の編集が計算されている場合

詳細は Node.js APIの警告詳細を参照してください。

customSyntax

CLIフラグ: --custom-syntax

コードに使用するカスタム構文を指定します。

SCSSのようなCSS言語拡張からCSS-in-JSオブジェクトのような全く異なる表記法まで、多くのスタイリング言語があります。

これらのスタイリング言語は他の言語内に埋め込まれていることもあります。例えば：

  • HTMLの <style> タグ
  • マークダウンのフェンス
  • JavaScriptのテンプレートリテラル

このオプションにより、StylelintはこれらをCSSに似たものに変換できます。CSSは以下の言語の基盤であり、Stylelintに組み込まれたルールが最も理解しやすい言語です。

このオプションは、PostCSS互換の構文をエクスポートするJSモジュールに解決される文字列である必要があります。文字列はモジュール名（例: my-module）またはJSファイルのパス（例: path/to/my-module.js）です。

複数の異なる言語をリントしたい場合は、customSyntax と overrides 設定プロパティを組み合わせて使用できます。

Node.js APIでは、customSyntax オプションは Syntaxオブジェクトも受け入れます。Stylelintは parse プロパティを必須値として扱います。また、ESMで書かれた構文モジュールもサポートしています。

[!NOTE]
Stylelintはコアルールがカスタム構文で動作することを保証しません。

formatter

CLIフラグ: --formatter, -f | --custom-formatter

結果をフォーマットするフォーマッターを指定します。

選択肢は以下の通りです：

  • compact - ESLintのcompactフォーマッターに似た出力を生成
  • github - GitHub Actionsのワークフローコマンドを使ってメッセージを生成（非推奨）
  • json（Node APIのデフォルト） - 他のツールで利用可能なJSONを生成
  • string（CLIのデフォルト） - 人間が読みやすい文字列を生成
  • tap - Test Anything Protocolの出力を生成
  • unix - Cコンパイラのようなメッセージを生成し、Emacsの_Compilation mode_のようなツールでハイパーリンク可能にする
  • verbose - string を拡張し、チェックしたファイル一覧と各ルールの集計を含む

formatter のNode.js APIオプションは関数または Promise 関数も受け入れますが、--custom-formatter CLIフラグはJSファイルをエクスポートするパス（ファイルシステムパスまたは依存関係）を受け入れます。どちらの場合も関数は開発者ガイドで説明されている署名に合致する必要があります。

cache

CLIフラグ: --cache

処理済みファイルの結果を保存し、変更されたファイルのみをStylelintが処理するようにします。デフォルトではキャッシュは process.cwd() の ./.stylelintcache に保存されます。

以下の値がキャッシュキーとして使用されます：

  • Stylelintのバージョン
  • オプション

このオプションを有効にすると、変更されたファイルのみをリントするため、Stylelintの速度が大幅に向上します。

[!WARNING]
プラグインのバージョンと実装はキャッシュキーに使用されません。プラグインを更新した場合はキャッシュを削除することを推奨します。

cache を使ってStylelintを実行し、その後 cache を使わずに実行すると、.stylelintcache が削除されます。これは2回目のコマンドが .stylelintcache を無効化したと見なすためです。

cacheLocation

CLIフラグ: --cache-location

キャッシュの保存場所としてファイルまたはディレクトリのパス。

ディレクトリが指定された場合、Stylelintは指定フォルダ内にキャッシュファイルを作成します。ファイル名は process.cwd() のハッシュに基づいており（例: .cache_hashOfCWD）、異なるプロジェクトのキャッシュを単一の場所で再利用できます。

cacheLocation のディレクトリが存在しない場合、*nixシステムでは末尾に / を、Windowsでは \ を付けてください。そうしないとStylelintはパスをファイルとみなします。

cacheStrategy

CLIフラグ: --cache-strategy

変更検出に使用するキャッシュ戦略。 "metadata" または "content" のいずれか。

"content" 戦略は、ファイルの内容は変わっていないのに修正日時が変わる場合に有用です。例えば、git clone のようなGit操作時にファイルの修正日時が追跡されない場合などです。

maxWarnings

CLIフラグ: --max-warnings, --mw

許容する警告の最大数を設定します。

defaultSeverityを "warning" に設定し、警告でプロセスを失敗させたい場合（例えばCIビルド）に便利です。

警告数がこの値を超えた場合：

  • CLIプロセスはコード 2 で終了します
  • Node.js APIは返されるデータに maxWarningsExceeded プロパティを追加します

disableDefaultIgnores

CLIフラグ: --disable-default-ignores, --di

デフォルトの無視設定を無効にします。Stylelintは node_modules の内容を自動的に無視しなくなります。

globbyOptions

CLIフラグ: --globby-options, --go

globby に渡されるオプション。詳細。

ignorePath

CLIフラグ: --ignore-path, -i

無視するファイルを記述したパターンを含むファイルへのパス。パスは絶対または process.cwd() からの相対パスです。複数回指定可能。デフォルトではStylelintは process.cwd() の .stylelintignore を探します。

ignoreDisables

CLIフラグ: --ignore-disables, --id

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

このオプションを使うと、これらの例外なしでリント結果がどうなるか確認できます。

reportDescriptionlessDisables

CLIフラグ: --report-descriptionless-disables, --rdd

説明のない設定コメントを報告します。

以下のパターンが報告されます：

/* stylelint-disable */
a {}


/* stylelint-disable-next-line block-no-empty */
a {}

しかし、以下のパターン（stylelint-disable -- <説明>）は報告されません：

/* stylelint-disable -- この問題は無視してよいです。 */
a {}


/* stylelint-disable-next-line block-no-empty -- この問題は無視してよいです。 */
a {}

reportInvalidScopeDisables

CLIフラグ: --report-invalid-scope-disables, --risd

設定コメント1のうち、設定オブジェクトで指定されていないルールにマッチしないものを報告します。

reportNeedlessDisables

CLIフラグ: --report-needless-disables, --rd

実際には無効化する必要のないリントにマッチしない設定コメント1を報告します。

reportUnscopedDisables

CLIフラグ: --report-unscoped-disables, --rud

1つ以上のルールにスコープされていない設定コメント1を報告します。

validate

CLIフラグ: --validate, --no-validate

ルールのオプション検証を強制的に有効化/無効化します。デフォルトは true。

例えば、rulesが変更されていなければCIを高速化するために検証をスキップすることができます。

export default {
  // …
  validate: process.env["CI"] !== "true"
};

codeFilename

CLIフラグ: --stdin-filename

入力に割り当てるファイル名。

code または stdin を使ってソース文字列を直接渡す場合に、そのコードに特定のファイル名を関連付けるために使用します。

quiet

CLIフラグ: --quiet

"警告" レベルを無視し、"エラー" レベルのルールの問題のみを登録します。

quietDeprecationWarnings

CLIフラグ: --quiet-deprecation-warnings

非推奨警告を無視します。

[!TIP]
Node.js 20.11.0以降では、Node.jsの --disable-warning 機能を使って個別の非推奨警告を無効化できます。例えば：

NODE_OPTIONS='--disable-warning=stylelint:005' npx stylelint "**/*.css"

目次に戻る

Discussion