🎨

Sass @importから@useへの移行ガイド - Dart Sass 3.0.0に向けて

に公開
CSS
Sass
Scss
migration
frontend
tech

はじめに

Dart Sass 3.0.0のリリースに向けて、@importルールが完全に削除される予定です。これは、Sassを使用している全てのプロジェクトに影響を与える大きな変更です。

本記事では、実際のプロジェクトで行った@importから@useへの移行作業を通じて、移行の必要性、手順、そして注意点について解説します。

なぜ移行が必要なのか

Sassプロジェクトをビルドする際、以下のような警告メッセージを見たことはありませんか？

Deprecation Warning [import]: Sass @import rules are deprecated and will be removed in Dart Sass 3.0.0.

More info and automated migrator: https://sass-lang.com/d/import

これは、@importルールが非推奨となり、将来的に削除されることを示しています。

@importの問題点

  1. グローバルスコープの汚染: @importで読み込まれた変数やミックスインは全てグローバルスコープに展開される
  2. 名前の衝突: 異なるファイルで同じ名前の変数を定義すると、後から読み込まれたものが優先される
  3. 依存関係の不明確さ: どのファイルがどの変数を提供しているか分かりにくい
  4. 重複読み込み: 同じファイルが複数回読み込まれる可能性がある

@useの利点

  1. 名前空間の導入: モジュールごとに名前空間を持ち、変数の衝突を防ぐ
  2. 明確な依存関係: どのファイルから何をインポートしているか明確
  3. 一度だけの読み込み: 同じファイルは一度だけ評価される
  4. プライベート変数: アンダースコアで始まる変数はファイル内でのみ有効

実際の移行例

24個のSCSSファイルを移行した実例を見てみましょう。

Before: @importを使用

// app.module.scss
@import 'src/common/styles/theme';
@import 'src/common/styles/shadow';

.container {
  background-color: $core-content-primaryA;
  box-shadow: $card-shadow;
}

After: @useを使用

// app.module.scss
@use 'src/common/styles/theme' as theme;
@use 'src/common/styles/shadow' as shadow;

.container {
  background-color: theme.$core-content-primaryA;
  box-shadow: shadow.$card-shadow;
}

移行手順

1. 対象ファイルの特定

まず、プロジェクト内で@importを使用しているファイルを特定します：

# @importを含むファイルを検索
grep -r "@import" --include="*.scss" --include="*.sass" .

2. 依存関係の整理

移行前に、どのファイルがどのファイルに依存しているか整理しておくことが重要です。

3. @importから@useへの変換

基本的な変換パターン：

// Before
@import 'path/to/file';

// After（デフォルトの名前空間を使用）
@use 'path/to/file';

// After（カスタム名前空間を指定）
@use 'path/to/file' as custom-name;

4. 変数参照の更新

名前空間を使用した変数参照に更新：

// Before
color: $primary-color;

// After（ファイル名が名前空間になる）
color: file.$primary-color;

// After（カスタム名前空間の場合）
color: custom-name.$primary-color;

実践的なTips

1. 段階的な移行

大規模プロジェクトでは、一度に全てを移行するのではなく、モジュールごとに段階的に移行することをお勧めします。

// 移行済みのファイルから未移行のファイルをインポートする場合
@use 'sass:meta';
@include meta.load-css('legacy-file');

2. よく使うファイルの名前空間

頻繁に使用するファイルには短い名前空間を設定：

// 長い名前空間は避ける
@use 'src/common/styles/theme' as theme;

// 非常に頻繁に使う場合は短縮形も検討
@use 'src/common/styles/theme' as t;

3. インデックスファイルの活用

関連するスタイルをまとめたインデックスファイルを作成：

// _index.scss
@forward 'variables';
@forward 'mixins';
@forward 'functions';

// 使用側
@use 'styles'; // styles/_index.scssを読み込む

4. @forwardの使用

公開APIを定義する際は@forwardを使用：

// styles/_index.scss
@forward 'theme' show $primary-color, $secondary-color;
@forward 'mixins' hide internal-*;

移行時の注意点

1. ビルドエラーの確認

移行後は必ずビルドを実行し、エラーがないことを確認：

npm run build

2. スタイルの視覚的確認

変数名の変更ミスなどでスタイルが崩れていないか、視覚的に確認することも重要です。

3. テストの実行

スタイルのテストがある場合は、必ず実行して正常に動作することを確認します。

自動移行ツール

Sass公式が提供する移行ツールも利用可能です：

npm install -g sass-migrator
sass-migrator module --migrate-deps path/to/style.scss

ただし、自動移行後も手動での確認と調整が必要な場合があります。

まとめ

@importから@useへの移行は、最初は手間がかかるように感じるかもしれませんが、長期的にはコードの保守性と可読性が大幅に向上します。

主なポイント：

  • Dart Sass 3.0.0に向けて早めの移行が重要
  • 名前空間により変数の衝突を防げる
  • 依存関係が明確になり、コードの理解が容易に
  • 段階的な移行でリスクを最小限に

今回の移行作業を通じて、Sassのモジュールシステムの利点を実感できました。まだ移行していないプロジェクトがある場合は、早めの対応をお勧めします。

参考リンク

Discussion