🤖

stylelintユーザガイドーNode.js API

に公開
CSS
Sass
Scss
tech

内容の目的

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

Node.js API

Stylelint モジュールには、Node.js API を提供する lint() 関数が含まれています。

const result = await stylelint.lint(options);

オプション

標準のオプションに加えて、Node API では以下のオプションを受け付けます：

config

設定オブジェクト。

このオプションを使用すると、Stylelint は設定ファイル（例：stylelint.config.js）を探しに行きません。

code

リントする文字列。

cwd

Stylelint がファイルを探す基準となるディレクトリ。デフォルトは process.cwd() が返すカレントワーキングディレクトリです。

files

ファイルのグロブ、または ファイルグロブの配列。

相対グロブは globbyOptions.cwd に対して相対的に解釈されます。

files と code はどちらも「省略可能」ですが、どちらか一方を必ず指定し、両方を同時に指定することはできません。

globbyOptions

files と一緒に渡されるオプション。

例えば、パスのグロブ時に使用する特定の cwd を設定できます。files 内の相対グロブはこのパスに対して相対的に解釈されます。デフォルトでは globbyOptions.cwd は cwd によって設定されます。

詳細な使用方法は Globby ガイド を参照してください。

戻り値の Promise

stylelint.lint() は、以下のプロパティを含むオブジェクトで解決される Promise を返します。

code

fix オプションが true に設定され、code オプションが提供された場合に、自動修正されたコードを含む文字列。それ以外の場合は undefined です。

cwd

リント処理の作業ディレクトリとして使用されたディレクトリ。

errored

真偽値。true の場合、少なくとも1つの「error」レベルのルールが問題を報告しています。

output

⚠️ 警告
このプロパティは非推奨であり、次のメジャーバージョンで削除されます。代わりに report または code を使用してください。詳細は 移行ガイド を参照してください。

  • フォーマットされた問題（デフォルトのフォーマッターまたは指定したフォーマッターを使用）
  • または fix オプションが true の場合の自動修正コード

のいずれかを含む文字列。

postcssResults

すべての蓄積された PostCSS LazyResults を含む配列。

report

フォーマットされた問題（デフォルトのフォーマッターまたは指定したフォーマッターを使用）を含む文字列。

results

すべての Stylelint 結果オブジェクト（フォーマッターが利用するオブジェクト）を含む配列。

maxWarningsExceeded

最大警告数と検出された警告数を含むオブジェクト。例：{ maxWarnings: 0, foundWarnings: 12 }。

結果オブジェクト

{
  "source": "path/to/file.css", // ファイルパスまたは <input css 1> のような PostCSS 識別子
  "errored": true, // 「error」レベルのルールが少なくとも1つ警告を発生させた場合は `true`
  "warnings": [
    // ルールの問題警告オブジェクトの配列。各要素は以下のような形です ...
    {
      "line": 3,
      "column": 12,
      "endLine": 4,
      "endColumn": 15,
      "rule": "block-no-empty",
      "severity": "error",
      "text": "空のブロックは避けるべきです (block-no-empty)"
    }
  ],
  "deprecations": [
    // 非推奨警告オブジェクトの配列。各要素は以下のような形です ...
    {
      "text": "機能Xは非推奨であり、次のメジャーバージョンで削除されます。",
      "reference": "https://stylelint.io/docs/feature-x.md"
    }
  ],
  "invalidOptionWarnings": [
    // 無効なオプション警告オブジェクトの配列。各要素は以下のような形です ...
    {
      "text": "ルールYに対する無効なオプションXです"
    }
  ],
  "ignored": false // ファイルパスが指定された無視パターンに一致する場合は `true`
}

編集情報

computeEditInfo オプションが有効な場合、警告に修正候補の情報を提供する fix プロパティが含まれることがあります：

  • range ([number, number]) - ソースコードテキスト内の削除すべき0ベースのインデックス範囲
  • text (string) - 追加すべきテキスト

例えば、a { opacity: 10%; } を a { opacity: 0.1; } に変更する場合、EditInfo は以下のようになります：

{
  // "line", "column", "rule", ...
  "fix": {
    "range": [13, 16], // "10%" のインデックス範囲
    "text": "0.1" // 置換テキスト
  }
}

この編集を適用するには、次のようにします：

const sourceCodeText = "a { opacity: 10%; }";
const result =
  sourceCodeText.slice(0, edit.range[0]) + // "a { opacity: "
  edit.text + // "0.1"
  sourceCodeText.slice(edit.range[1]); // "; }"
//=> "a { opacity: 0.1; }"

特定の範囲に対しては、単一の EditInfo のみが記録されます。複数の報告範囲が重複する場合、最初の範囲だけが EditInfo を含みます。

構文エラー

stylelint.lint() は、CSS に構文エラーがあっても Promise を拒否しません。
戻り値の Promise のオブジェクトで構文エラーの情報を含んで解決されます。

使用例

例 A

config に相対パスの extends や plugins が含まれていない場合、configBasedir を使う必要はありません：

try {
  const result = await stylelint.lint({
    config: { rules: "color-no-invalid-hex" },
    files: "all/my/stylesheets/*.css"
  });
  // result.report, result.errored, result.results を使った処理
} catch (err) {
  // err を使った処理例
  console.error(err.stack);
}

例 B

myConfig に相対パスの extends や plugins が含まれている場合は、configBasedir を使う必要があります：

const result = await stylelint.lint({
  config: myConfig,
  configBasedir: url.fileURLToPath(new URL("configs", import.meta.url)),
  files: "all/my/stylesheets/*.css"
});

例 C

ファイルグロブの代わりに文字列コードを使い、デフォルトの JSON ではなく verbose フォーマッターを使用する例：

const result = await stylelint.lint({
  code: "a { color: pink; }",
  config: myConfig,
  formatter: "verbose"
});

// result.report を使った処理

レポートは戻り値オブジェクトの report プロパティで取得できます。

例 D

独自のカスタムフォーマッター関数を使用する例：

const result = await stylelint.lint({
  config: myConfig,
  files: "all/my/stylesheets/*.css",
  formatter: (results) => {
    /* .. */
  }
});

例 E

カスタム構文を使う例：

const result = await stylelint.lint({
  config: myConfig,
  files: "all/my/stylesheets/*.css",
  customSyntax: {
    parse(css, opts) {
      /* .. */
    },
    stringify(node, builder) {
      /* .. */
    }
  }
});

💡 メモ
customSyntax オプションは文字列も受け付けます。オプションのドキュメントを参照してください。

例 F

文字列コードと fix オプションを使う例：

const result = await stylelint.lint({
  code: "a { color: pink; }",
  config: { rules: { "hue-degree-notation": "angle" } },
  fix: true
});

// result.code を使った処理

自動修正されたコードは戻り値オブジェクトの code プロパティで取得できます。

ファイルに対する有効な設定の解決

実際にリントを実行せずに、ファイルに対してどの設定が使われるかを知りたい場合は、resolveConfig() 関数を使えます。ファイルパスを渡すと、有効な設定オブジェクトを返す Promise を返します：

const config = await stylelint.resolveConfig(filePath);

// config => {
//   rules: {
//     'color-no-invalid-hex': true
//   },
//   extends: [
//     'stylelint-config-standard',
//     'stylelint-config-css-modules'
//   ],
//   plugins: [
//     'stylelint-scss'
//   ],
//   …
// }

ファイルに対して設定が見つからない場合、resolveConfig() は undefined を返す Promise を返します。

また、lint() に渡すオプションの一部も渡せます：

  • cwd
  • config
  • configBasedir
  • customSyntax

目次に戻る

Discussion