16.0.0への移行
このリリースには、重要な変更または破壊的な変更が含まれています。
ソースコードをECMAScript modules (ESM) に移行しました。これは、ESMプラグイン、カスタム構文とフォーマッターを許可するための1年間の取り組みであり、pure ESM依存関係を更新するためのステップです。
コミュニティがESMに移行する時間を与えるため、次のメジャーリリースまで、（現在は非推奨の）CommonJS Node.js APIをサポートするハイブリッドパッケージを公開します。
重要な変更
私たちは
- ESMプラグインのサポートを追加しました
- ESMカスタム構文のサポートを追加しました
- ESMカスタムフォーマッターのサポートを追加しました
- CommonJS Node.js APIを非推奨にしました
- 内部で
.mjsおよび.cjs拡張子を使用するようにリファクタリングしました
ESMプラグインのサポートを追加
ESM pluginsを作成できるようになりました。
例えば
import stylelint from "stylelint";
const {
createPlugin,
utils: { report, ruleMessages, validateOptions }
} = stylelint;
const ruleName = "foo-org/foo-bar";
const messages = ruleMessages(ruleName, {
rejected: (selector) => `Unexpected "foo"`
});
const meta = {
url: "https://foo.org/foo-bar"
};
const ruleFunction = (primary, secondaryOptions) => {
return (root, result) => {
const validOptions = validateOptions(/* .. */);
if (!validOptions) return;
/* .. */
report({
/* .. */
});
};
};
ruleFunction.ruleName = ruleName;
ruleFunction.messages = messages;
ruleFunction.meta = meta;
export default createPlugin(ruleName, ruleFunction);
プラグイン開発者ガイドを更新し、ESM構文の例を追加しました。
ESMカスタム構文のサポートを追加
ESM カスタム構文を作成できるようになりました。
例えば
import postcss from "postcss";
function parse(css, opts) {
/* .. */
}
function stringify(node, builder) {
/* .. */
}
export default { parse, stringify };
詳細な例については、開発者ガイドのカスタム構文セクションを参照してください。
ESMカスタムフォーマッターのサポートを追加
ESM カスタムフォーマッターを作成できるようになりました。
例えば
export default function yourOwnFormatter(results) {
/* .. */
}
詳細な例については、開発者ガイドのカスタムフォーマッターセクションを参照してください。
CommonJS APIの非推奨化
pure ESM依存関係を更新できるように、CommonJS Node.js APIを非推奨とし、次のメジャーリリースで削除します。
プラグインの作成者である場合、または`stylelint.lint()`を使用してファイルをリントする場合、この非推奨化は影響します。カスタム構文とフォーマッターは、Node.js APIを使用しないため、影響を受けません。
ESMに移行するには、次の手順を実行する必要があります。
- すべての`require()/module.export`を`import/export`に置き換えます
- `.mjs`拡張子を使用していない場合は、`package.json`に`"type": "module"`を追加します
- インポートには完全な相対ファイルパスのみを使用します。例：`import x from '.';` → `import x from './index.js';`
また、以下のこともお勧めします。
- `package.json`の`"engines"`フィールドを`"node": ">=18.12.0"`に更新します
- すべてのファイルから`'use strict';`を削除します
- `package.json`に`"exports": "./index.js"`を追加します
- Node.js組み込みインポートには`node:`プロトコルを使用します
ESMの詳細については、Node.jsドキュメントを参照してください。
プラグイン
たとえば、プラグインが`import`と`export`を使用するように移行するには、
-const stylelint = require("stylelint");
+import stylelint from "stylelint";
const {
createPlugin,
utils: { report, validateOptions },
} = stylelint;
const ruleFunction = (primary, secondaryOptions) => { /* .. */ };
ruleFunction.ruleName = ruleName;
ruleFunction.messages = messages;
ruleFunction.meta = meta;
-module.exports = createPlugin(ruleName, ruleFunction);
+export default createPlugin(ruleName, ruleFunction);
`testRule`スキーマを使用してプラグインをテストする場合は、次のいずれかを実行できます。
- `jest-preset-stylelint`パッケージの最新バージョンに更新する
- `node:test|assert`を使用する新しい`stylelint-test-rule-node`パッケージを試す
`jest-preset-stylelint`
プリセットは、ESMをサポートするために`--experimental-vm-modules` Node.jsフラグが必要です。 `cross-env`パッケージを使用して、npm-run-scriptで`NODE_OPTIONS`環境変数を設定できます。
{
"scripts": {
- "test": "jest",
+ "test": "cross-env NODE_OPTIONS=\"--experimental-vm-modules --no-warnings\" jest --runInBand",
}
}
(`cross-env`は完成とみなされているため、メンテナンスモードになっています。)
エラーが発生した場合（例：Node.js 18でプリセットを実行中にセグメンテーション違反が発生した場合）、Jest設定で`jest-light-runner`を使用してみてください。
export default {
preset: "jest-preset-stylelint",
setupFiles: ["./jest.setup.js"],
+ runner: "jest-light-runner",
};
ランナーのカバレッジサポートは限定的です。
`stylelint-test-rule-node`
新しい`stylelint-test-rule-node`パッケージを試すには、テストファイルにインポートする必要があります。
+import { testRule } from "stylelint-test-rule-node";
testRule({
/* .. */
});
そして、npm-run-scriptを更新します
{
"scripts": {
- "test": "jest"
+ "test": "node --test"
}
}
このパッケージは、Node.js 18では実験的ですが、20では安定している`node:test`を使用しています。カバレッジのサポートも実験的です。
他のJestテストがある場合は、`node:test`を使用するように適応させる必要があります。たとえば、`expect()`は`assert()`になります。
`stylelint.lint()`
たとえば、`stylelint.lint()`を使用するコードを`import`とトップレベルの`await`を使用するように移行するには、
-const stylelint = require("stylelint");
+import stylelint from "stylelint";
-stylelint.lint(options).then((result) => { console.log(result); });
+const result = await stylelint.lint(options);
+console.log(result);
ユーザーガイドのESM Node.js APIの詳細をご覧ください。
CommonJS Node.js APIを使用すると、非推奨の警告が表示されます。ESMに移行する準備ができていない場合は、`quietDeprecationWarnings`オプションを使用して警告を非表示にすることができます。
const stylelint = require("stylelint");
const resultPromise = stylelint.lint({
/* .. */
+ quietDeprecationWarnings: true
});
内部で`.mjs`と`.cjs`拡張子を使用するようにリファクタリング
ハイブリッドパッケージをサポートするために、内部で`.mjs`と`.cjs`拡張子を使用するようになりました。この変更はパブリックAPIには影響しませんが、プラグインが内部ファイルを`require`する場合は影響します。
次のメジャーリリースでこれらのファイルへのアクセスを削除するため、インポートする代わりにプロジェクトにファイルをコピーすることをお勧めします。
ただし、次のメジャーリリースの前に、インポートを更新することで、安全ではない方法でファイルを`import`または`require`し続けることができます。
// ESM
-import('stylelint/lib/utils/typeGuards.js');
+import('stylelint/lib/utils/typeGuards.mjs');
// CommonJS
-require('stylelint/lib/utils/typeGuards.js');
+require('stylelint/lib/utils/typeGuards.cjs');
破壊的な変更
私たちは
- 非推奨のスタイルルールを削除しました
- 18.12.0未満のNode.jsのサポートを削除しました
- Node.js APIの返される解決済みオブジェクトを変更しました
- Node.js APIの`stylelint.formatters`オブジェクトを変更しました
- Node.js APIの`stylelint.rules`オブジェクトを変更しました
- Node.js APIの`stylelint.utils.checkAgainstRule()`関数を変更しました
- CLIが問題をstderrに出力するように変更しました
- フラグエラーのCLI終了コードを変更しました
- 拡張子に関係なく、`fix`で常にsafe-parserを使用するようにデフォルトの構文動作を変更しました
非推奨のスタイルルールを削除
15.0.0で非推奨としたスタイルルールを削除しました。
設定オブジェクトからルールを削除する必要があります。詳細については、15.0.0移行ガイドを参照してください。
18.12.0未満のNode.jsのサポートを削除
Node.js 14と16はサポート終了に達しました。依存関係の一部を更新するために、これらのサポートを削除しました。
18.12.0以降のバージョンのNode.jsを使用する必要があります。
Node.js APIの返される解決済みオブジェクトを変更
`stylelint.lint()`によって返されるPromiseの解決済みオブジェクトを変更し、新しい
`output`プロパティは、新しい`report`および`code`プロパティを支持して非推奨となり、次のメジャーバージョンで削除されます。
stylelint.lint() を使用してソース文字列を lint し、fix オプションが true の場合、report プロパティにはフォーマットされた問題が含まれ、code プロパティには修正されたコードが含まれます。
const result = await stylelint.lint({
code: "a {}",
fix: true
});
-const fixedCode = result.output;
+const formattedProblems = result.report;
+const fixedCode = result.code;
stylelint.lint() を使用してファイルを lint する場合、code プロパティは常に undefined になります。
変更された Node.js API stylelint.formatters オブジェクト
Node.js API の stylelint.formatters オブジェクトを変更し、すべてのフォーマッターが Promise 関数になるようにしました。
-const formatter = stylelint.formatters.json;
+const formatter = await stylelint.formatters.json;
変更された Node.js API stylelint.rules オブジェクト
Node.js API の stylelint.rules オブジェクトを変更し、すべてのルールが Promise 関数になるようにしました。
-const rule = stylelint.rules['block-no-empty'];
+const rule = await stylelint.rules['block-no-empty'];
変更された Node.js API stylelint.utils.checkAgainstRule() 関数
Node.js API の stylelint.utils.checkAgainstRule() 関数を変更し、非同期関数になるようにしました。
-checkAgainstRule({ /* .. */ });
+await checkAgainstRule({ /* .. */ });
CLI を変更して、問題を stderr に出力するようにしました
CLI を変更して、問題を stdout の代わりに stderr に出力するようにしました。
--fix オプションと --stdin オプションを使用する場合、CLI は修正されたコードを stdout に、問題を stderr に出力します。
カスタムフォーマッターなどから標準出力をリダイレクトするために > を使用する場合は、代わりに --output-file フラグを使用できます。
-npx stylelint "*.css" --custom-formatter custom-formatter.js > output.txt
+npx stylelint "*.css" --custom-formatter custom-formatter.js --output-file output.txt
フラグエラーの CLI 終了コードを変更しました
CLI フラグエラーの終了コードを 2 から 64 に変更し、2 を lint の問題用に予約しました。
CLI を使用するエディター統合の作成者の場合、フラグエラーと lint の問題を区別できるようになりました。
拡張子に関係なく、fix を使用して常に safe-parser を使用するようにデフォルトの構文動作を変更しました
CSS コードを自動修正する際に、ファイルの拡張子に関係なく、常に postcss-safe-parser を使用するようにデフォルトの構文動作を変更しました。以前は、.css、.pcss、または .postcss ファイルのみが postcss-safe-parser で自動修正されていました。