Переход с @import на @use
Старые проекты и учебники подключают файлы через @import. Это правило устарело: Dart Sass выводит предупреждение на каждый @import, а Dart Sass 3 его удалит. Рано или поздно такой проект придётся перевести на @use и @forward. Здесь — что меняется и как сделать это с минимумом ручной работы.
Что было не так с @import
С @import каждая переменная, миксин и функция становились глобальными — видимыми во всех файлах, подключённых после:
// styles/main.scss
// Старый стиль
@import "variables";
@import "mixins";
@import "buttons";Внутри _buttons.scss можно было писать $primary без всякого @use, но понять, откуда взялась переменная, было нельзя. Две библиотеки со своим $primary молча перезаписывали друг друга. А файл, подключённый дважды, дважды попадал в результат.
@import | @use |
|---|---|
| Все имена глобальные | Имена через пространство имён |
| Файл может попасть в результат несколько раз | Модуль загружается один раз |
| Зависимости скрыты | Каждый файл перечисляет, что использует |
| Устарел | Современный способ |
Тот же код на модулях
Каждый файл загружает то, что ему нужно:
// styles/abstracts/_variables.scss
$primary: #2563eb;// styles/components/_buttons.scss
@use "../abstracts/variables" as v;
.btn {
background: v.$primary;
}// styles/main.scss
@use "components/buttons";.btn {
background: #2563eb;
}Встроенные функции
Старые глобальные функции переехали в модули. О старых именах Sass тоже предупреждает:
| Было | Стало |
|---|---|
darken($c, 10%) | color.adjust($c, $lightness: -10%) |
lighten($c, 10%) | color.adjust($c, $lightness: 10%) |
map-get($m, $k) | map.get($m, $k) |
nth($list, 2) | list.nth($list, 2) |
percentage(0.5) | math.percentage(0.5) |
$a / $b | math.div($a, $b) |
Инструмент миграции
Команда Sass выпускает sass-migrator, который переписывает файлы автоматически. Установите его и запустите миграцию module для главного файла:
npm install --save-dev sass-migrator
npx sass-migrator module --migrate-deps styles/main.scss--migrate-deps переводит заодно все файлы, которые импортирует main.scss. Инструмент заменяет @import на @use, добавляет пространства имён к переменным и миксинам и подключает встроенные модули. Отдельная миграция division заменяет / на math.div():
npx sass-migrator division --migrate-deps styles/main.scssПеред запуском закоммитьте работу в Git, чтобы потом просмотреть изменения как diff.
Переход по шагам
В большом проекте не обязательно переводить всё сразу. Файл, загруженный через @use, может внутри ещё содержать @import, и на время перехода старые и новые правила работают вместе. Начните с abstracts/, затем переводите компоненты по одному, компилируя после каждого шага.
Частая ошибка
Механическая замена @import на @use без пространств имён ломает сборку: компоненты по-прежнему обращаются к $primary, и Sass сообщает Undefined variable. Либо добавьте пространство имён (v.$primary), либо загрузите файл с as *. Мигратор делает это за вас — ещё одна причина начать с него.