マイグレーター

使用方法使用方法パーマリンク

Sassマイグレーターを使用するには、実行するマイグレーションと、マイグレーションするSassファイルを指定します。

sass-migrator <migration> <entrypoint.scss...>

デフォルトでは、マイグレーターはコマンドラインで明示的に渡されたファイルのみを変更します。--migrate-depsオプションを渡すと、@useルール、@forwardルール、または@importルールを使用してロードされるすべてのスタイルシートも変更されます。実際に保存せずに変更内容を確認するテスト実行を行う場合は、--dry-run --verbose（または短縮形-nv）を渡すことができます。

$ cat style.scss
$body-bg: #000;
$body-color: #111;

@import "bootstrap";

@include media-breakpoint-up(sm) {
  .navbar {
    display: block;
  }
}
$ sass-migrator --migrate-deps module style.scss
$ cat style.scss
@use "bootstrap" with (
  $body-bg: #000,
  $body-color: #111
);

@include bootstrap.media-breakpoint-up(sm) {
  .navbar {
    display: block;
  }
}

インストールインストールパーマリンク

Sassマイグレーターは、Dart Sassをインストールするほとんどの場所からインストールできます。

スタンドアロンスタンドアロンパーマリンク

Windows、Mac、またはLinuxにSassマイグレーターをインストールするには、オペレーティングシステムのパッケージをGitHubからダウンロードし、PATHに追加します。

npmnpmパーマリンク

Node.jsを使用する場合は、npmを使用してSassマイグレーターをインストールすることもできます。実行方法は次のとおりです。

npm install -g sass-migrator

ChocolateyChocolateyパーマリンク

WindowsでChocolateyパッケージマネージャーを使用する場合は、次のように実行してSassマイグレーターをインストールできます。

choco install sass-migrator

HomebrewHomebrewパーマリンク

Mac OS XでHomebrewパッケージマネージャーを使用する場合は、次のように実行してDart Sassをインストールできます。

brew install sass/sass/migrator

グローバルオプショングローバルオプションパーマリンク

これらのオプションは、すべてのマイグレーターで使用できます。

--migrate-deps–migrate-depsパーマリンク

このオプション（省略形-d）は、コマンドラインで明示的に渡されたスタイルシートだけでなく、@useルール、@forwardルール、または@importルールを使用して依存しているすべてのスタイルシートも変更するようにマイグレーターに指示します。

$ sass-migrator module --verbose style.scss
Migrating style.scss
$ sass-migrator module --verbose --migrate-deps style.scss
Migrating style.scss
Migrating _theme.scss
Migrating _fonts.scss
Migrating _grid.scss

--load-path–load-pathパーマリンク

このオプション（省略形-I）は、スタイルシートを検索するロードパスをマイグレーターに指示します。複数のロードパスを提供するために複数回渡すことができます。前のロードパスは後のロードパスよりも優先されます。

ロードパスからロードされた依存関係はサードパーティライブラリであると想定されているため、--migrate-depsオプションが渡されていても、マイグレーターはそれらをマイグレーションしません。

--dry-run–dry-runパーマリンク

このフラグ（省略形-n）は、マイグレーターに変更をディスクに保存しないように指示します。代わりに、変更されたファイルのリストを出力します。これは、--verboseオプションと組み合わせて、行われた変更の内容も出力する場合によく使用されます。

$ sass-migrator module --dry-run --migrate-deps style.scss
Dry run. Logging migrated files instead of overwriting...

style.scss
_theme.scss
_fonts.scss
_grid.scss

--no-unicode–no-unicodeパーマリンク

このフラグは、Sassマイグレーターがエラーメッセージの一部としてターミナルにASCII文字のみを出力するように指示します。デフォルトでは、または--unicodeが渡された場合、マイグレーターはこれらのメッセージに非ASCII文字を出力します。このフラグはCSS出力には影響しません。

$ sass-migrator --no-unicode module style.scss
line 1, column 9 of style.scss: Error: Could not find Sass file at 'typography'.
  ,
1 | @import "typography";
  |         ^^^^^^^^^^^^
  '
Migration failed!
$ sass-migrator --unicode module style.scss
line 1, column 9 of style.scss: Error: Could not find Sass file at 'typography'.
  ╷
1 │ @import "typography";
  │         ^^^^^^^^^^^^
  ╵
Migration failed!

--verbose–verboseパーマリンク

このフラグ（省略形-v）は、マイグレーターにコンソールに追加情報を表示するように指示します。デフォルトでは、変更されたファイルの名前のみを出力しますが、--dry-runオプションと組み合わせると、それらのファイルの新しい内容も出力します。

$ sass-migrator module --verbose --dry-run style.scss
Dry run. Logging migrated files instead of overwriting...
<==> style.scss
@use "bootstrap" with (
  $body-bg: #000,
  $body-color: #111
);

@include bootstrap.media-breakpoint-up(sm) {
  .navbar {
    display: block;
  }
}
$ sass-migrator module --verbose style.scss
Migrating style.scss

マイグレーションマイグレーションパーマリンク

カラーカラーパーマリンク

このマイグレーションは、レガシーカラー関数を新しいカラー空間互換関数に変換します。

除算除算パーマリンク

このマイグレーションは、/を除算として使用するスタイルシートを、代わりに組み込みのmath.div関数を使用するように変換します。

--pessimistic–pessimisticパーマリンク

デフォルトでは、マイグレーターは、評価時に除算であるかどうかが確実でない場合でも、/演算をmath.divに変換します。Sassスクリプトが含まれていない場合、またはオペランドのいずれかが文字列である場合など、静的に別の操作を行っていることを静的に判別できる場合のみ、そのまま残します。math.div関数は現在、/演算子と完全に同じように機能するため、これは安全に行うことができますが、ランタイムでmath.divの引数のいずれかが数値でない場合、新しい警告が表示される可能性があります。

この動作を回避するには、--pessimisticフラグを渡すことができます。このフラグを使用すると、マイグレーターは除算であることが確実にわかっている/演算のみを変換します。これにより、不要なmath.div変換を回避できますが、静的に判断できない場合、一部の除算がマイグレーションされないままになる可能性があります。

モジュールモジュールパーマリンク

このマイグレーションは、依存関係のロードに古い@importルールを使用するスタイルシートを、代わりに@useルールを使用してSassモジュールシステムを使用するように変換します。@importを@useに単純に変更するのではなく、以前と同じように動作するようにスタイルシートをインテリジェントに更新します。これには以下が含まれます。

• 他のモジュールからメンバー（変数、ミックスイン、関数）を使用する際に名前空間を追加すること。

• メンバーをインポートせずに使用していたスタイルシートに新しい@useルールを追加すること。

• 上書きされたデフォルト変数をwith句に変換すること。

• 他のファイルから使用されているメンバーの先頭の-と_プレフィックスを自動的に削除すること（それ以外の場合、プライベートと見なされ、宣言されているモジュールでのみ使用できるため）。

• ネストされたインポートを、代わりにmeta.load-css()ミックスインを使用するように変換すること。

$ cat style.scss
$body-bg: #000;
$body-color: #111;

@import "bootstrap";

@include media-breakpoint-up(sm) {
  .navbar {
    display: block;
  }
}
$ sass-migrator --migrate-deps module style.scss
$ cat style.scss
@use "bootstrap" with (
  $body-bg: #000,
  $body-color: #111
);

@include bootstrap.media-breakpoint-up(sm) {
  .navbar {
    display: block;
  }
}

依存関係の読み込み依存関係の読み込みパーマリンク

--migrate-depsオプションが渡されていない場合でも、モジュールマイグレーターは、マイグレーション対象のスタイルシートに依存するすべてのスタイルシートを読み取ることができる必要があります。マイグレーターが依存関係を見つけられない場合、エラーが発生します。

$ ls .
style.scss  node_modules
$ sass-migrator module style.scss
Error: Could not find Sass file at 'dependency'.
  ,
1 | @import "dependency";
  |         ^^^^^^^^^^^^
  '
  style.scss 1:9  root stylesheet
Migration failed!
$ sass-migrator --load-path node_modules module style.scss

スタイルシートをコンパイルするときにロードパスを使用する場合は、--load-pathオプションを使用してマイグレーターに渡してください。

残念ながら、マイグレーターはカスタムインポーターをサポートしていませんが、Webpackがサポートする内容と同様に、node_modulesで検索することにより、〜で始まるURLの解決を組み込みでサポートしています。

--remove-prefix–remove-prefixパーマリンク

このオプション（省略形-p）は、マイグレーション時にすべての変数、ミックスイン、関数名の先頭から削除する識別子プレフィックスを受け取ります。このプレフィックスで始まらないメンバーは変更されません。

@importルール@importルールは、最上位のメンバーをすべてグローバルスコープに配置するため、これがスタイルシートの読み込みの標準的な方法であった頃は、他のスタイルシートを誤って再定義することを避けるために、すべてのメンバー名にプレフィックスを追加することが奨励されていました。モジュールシステムはこの問題を解決するため、これらの古いプレフィックスは不要になった ので、自動的に削除することが役立ちます。

$ cat style.scss
@import "theme";

@mixin app-inverted {
  color: $app-bg-color;
  background-color: $app-color;
}
$ sass-migrator --migrate-deps module --remove-prefix=app- style.scss
$ cat style.scss
@import "theme";

@mixin inverted {
  color: theme.$bg-color;
  background-color: theme.$color;
}

このオプションを渡すと、マイグレーションツールは、プレフィックスを再び追加したすべてのメンバーを転送するインポート専用のスタイルシートも生成します。これにより、ライブラリをインポートしていたユーザーとの後方互換性を維持できます 。

このオプションは複数回、またはコンマで区切られた複数の値で渡すことができます。各プレフィックスは、それを含むメンバーから削除されます。メンバーが複数のプレフィックスに一致する場合は、最も長い一致するプレフィックスが削除されます 。

--forward–forward permalink

このオプションは、@forwardルールを使用して転送するメンバーをマイグレーションツールに指示します。以下の設定をサポートします 。

• none（デフォルト）は、メンバーを転送しません 。

• allは、元のスタイルシートで-または_で始まっていたメンバーを除くすべてのメンバーを転送します。これは、モジュールシステムが導入される前に、パッケージプライベートメンバーをマークするために一般的に使用されていたためです 。

• prefixedは、--remove-prefixオプションに渡されたプレフィックスで始まるメンバーのみを転送します。このオプションは、--remove-prefixオプションと組み合わせてのみ使用できます。

コマンドラインで明示的に渡されたすべてのファイルは、@importルールを使用して推移的にロードされるメンバーを転送します。--migrate-depsオプションを使用してロードされたファイルは、新しいメンバーを転送しません。このオプションは、Sassライブラリのマイグレーション時に特に役立ちます。これにより、そのライブラリのユーザーは、ライブラリが定義するすべてのメンバーに引き続きアクセスできるようになります 。

$ cat _index.scss
@import "theme";
@import "typography";
@import "components";
$ sass-migrator --migrate-deps module --forward=all style.scss
$ cat _index.scss
@forward "theme";
@forward "typography";
@forward "components";

名前空間Namespace permalink

このマイグレーションにより、スタイルシートの@useルールの名前空間を簡単に変更できます。これは、モジュールマイグレーションツールが競合を解決するために生成する名前空間が理想的でない場合、またはSassがルールの URLに基づいて決定するデフォルトの名前空間を使用しない場合に役立ちます。

--rename–rename permalink

--renameオプションに式を渡すことで、マイグレーションツールに変更する名前空間を指定できます。

これらの式は、<old-namespace> to <new-namespace>またはurl <rule-url> to <new-namespace>の形式です。これらの式では、<old-namespace>と<rule-url>は、それぞれ既存の名前空間全体または@useルールのURL全体と一致する正規表現です 。

単純なユースケースでは、これは--rename 'old to new'のように見えます。これにより、名前空間oldを持つ@useルールがnewに名前変更されます。

ただし、これを使用して、より複雑な名前変更を行うこともできます。たとえば、以前に次のようなスタイルシートがあったとします 。

@import 'components/button/lib/mixins';
@import 'components/input/lib/mixins';
@import 'components/table/lib/mixins';
// ...

これらのURLはすべて、@useルールにマイグレーションされるとデフォルトの名前空間mixinsを持つため、モジュールマイグレーションツールは次のようなものを生成する可能性があります 。

@use 'components/button/lib/mixins' as button-lib-mixins;
@use 'components/input/lib/mixins' as input-lib-mixins;
@use 'components/table/lib/mixins' as table-lib-mixins;
// ...

これは、名前空間に競合がないため有効なコードですが、必要以上に複雑です。URLの関連部分はコンポーネント名であるため、名前空間マイグレーションツールを使用してその部分を抽出できます 。

--rename 'url components/(\w+)/lib/mixins to \1'を使用して名前空間マイグレーションツールを実行すると、次のようになります 。

@use 'components/button/lib/mixins' as button;
@use 'components/input/lib/mixins' as input;
@use 'components/table/lib/mixins' as table;
// ...

ここの名前変更スクリプトは、components/(\w+)/lib/mixinsのように見える@useルール（正規表現の\w+は、1文字以上の単語に一致することを意味します）をすべて検索します。出力句の\1は、正規表現の最初の括弧（グループと呼ばれる）の内容を代入することを意味します。

複数の名前変更を適用する場合は、--renameオプションを複数回渡すか、セミコロンまたは改行で区切ることができます。特定のルールに適用される最初の名前変更のみが使用されるため、aとbの名前空間を入れ替えるには、--rename 'a to b; b to a'のようなものを渡すことができます。

--force–force permalink

デフォルトでは、マイグレーション後の2つ以上の@useルールが同じ名前空間を持つ場合、マイグレーションツールは失敗し、変更は行われません 。

この場合は、通常、競合を避けるために--renameスクリプトを調整しますが、マイグレーションを強制する方が良い場合は、--forceを渡すことができます。

--forceを使用すると、競合が発生した場合、最初の@useルールが優先名前空間を取得し、同じ優先名前空間を持つ後続の@useルールには、数値サフィックスが追加されます 。