Мигратор

Использование

Чтобы использовать мигратор 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:

Автономная версия

Мигратор Sass можно установить в Windows, Mac или Linux: скачайте пакет для своей операционной системы с GitHub и добавьте его в PATH.

npm

Если вы используете Node.js, мигратор Sass также можно установить с помощью npm, выполнив команду

npm install -g sass-migrator

Chocolatey

Если в Windows вы используете менеджер пакетов Chocolatey, установите мигратор Sass, выполнив команду

choco install sass-migrator

Homebrew

Если на Mac OS X вы используете менеджер пакетов Homebrew, установите Dart Sass, выполнив команду

brew install sass/sass/migrator

Глобальные параметры

Эти параметры доступны для всех миграторов.

--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

Этот параметр (сокращённо -I) задаёт путь загрузки load path, в котором мигратор должен искать таблицы стилей. Его можно передать несколько раз, указав несколько путей загрузки. Более ранние пути загрузки имеют приоритет над последующими.

Зависимости, загруженные из путей загрузки, считаются сторонними библиотеками, поэтому мигратор не будет переносить их, даже если передан параметр --migrate-deps.

--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

Этот флаг указывает мигратору выводить в терминал в сообщениях об ошибках только символы 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

Этот флаг (сокращённо -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

Миграции

if()

Эта миграция преобразует устаревшую функцию if() в новый синтаксис if() CSS. Подробности см. в разделе /d/if-function.

Цвет

Эта миграция преобразует устаревшие функции работы с цветом в новые функции, совместимые с цветовыми пространствами.

Деление

Эта миграция преобразует таблицы стилей, в которых используется / в качестве деления, чтобы вместо этого использовать встроенную функцию math.div.

--pessimistic

По умолчанию мигратор преобразует операции / в math.div, даже если не уверен, что при вычислении это будет деление. Он оставляет их без изменений, только если может статически определить, что выполняется другая операция (например, если SassScript не используется или один из операндов является строкой). Функция math.div в настоящее время работает так же, как оператор /, поэтому это безопасно, однако при выполнении может появиться новое предупреждение, если один из аргументов math.div не является числом.

Чтобы избежать такого поведения, можно передать флаг --pessimistic. С этим флагом мигратор будет преобразовывать только те операции /, которые точно выполняют деление. Это позволит избежать ненужных преобразований math.div, но некоторые операции деления, вероятно, останутся неперенесёнными, если их нельзя определить статически.

Модуль

Эта миграция преобразует таблицы стилей, использующие старое правило @import для загрузки зависимостей, чтобы вместо него использовать модульную систему Sass с помощью правила @use. Она не просто наивно заменяет @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.

К сожалению, мигратор не поддерживает пользовательские импортёры, но в нём есть встроенная поддержка поиска URL-адресов, начинающихся с ~, в node_modules, как и в Webpack.

--remove-prefix

Этот параметр (сокращённо -p) задаёт префикс идентификатора, который нужно удалить в начале всех имён переменных, миксинов и функций при их переносе. Имена элементов, не начинающиеся с этого префикса, останутся без изменений.

Правило @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
@use "theme";

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

При передаче этого параметра мигратор также создаст таблицу стилей только для импорта, которая перенаправляет все элементы, добавляя к ним исходный префикс, чтобы сохранить обратную совместимость для пользователей, импортировавших библиотеку.

Этот параметр можно передавать несколько раз или указывать несколько значений через запятую. Каждый префикс будет удалён у всех элементов, содержащих его. Если элемент соответствует нескольким префиксам, будет удалён самый длинный подходящий префикс.

--forward

Этот параметр указывает мигратору, какие элементы нужно перенаправить с помощью правила @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";

Пространство имён

Эта миграция позволяет легко менять пространства имён правил @use в таблице стилей. Это полезно, если пространства имён, которые мигратор модулей создаёт для устранения конфликтов, не подходят или если вы не хотите использовать пространство имён по умолчанию, которое Sass определяет на основе URL правила.

--rename

Укажите, какие пространства имён нужно изменить, передав выражения параметру --rename.

Эти выражения имеют форму <old-namespace> to <new-namespace> или url <rule-url> to <new-namespace>. В этих выражениях <old-namespace> и <rule-url> — это регулярные выражения, которые сопоставляются со всем существующим пространством имён или со всем URL правила @use соответственно.

В простых случаях достаточно указать --rename 'old to new': это переименует правило @use с пространством имён old в правило с пространством имён new.

Однако этот способ можно использовать и для более сложного переименования. Например, предположим, что раньше у вас была таблица стилей такого вида:

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

Поскольку после переноса в правила @use все эти URL-адреса получили бы пространство имён по умолчанию 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;
// ...

Скрипт переименования здесь указывает найти все правила @use, URL-адреса которых соответствуют шаблону components/(\w+)/lib/mixins (\w+ в регулярном выражении означает любое слово из одного или нескольких символов). \1 в выходном выражении означает подставить содержимое первой группы скобок в регулярном выражении (называемой группой).

Чтобы выполнить несколько переименований, можно передать параметр --rename несколько раз или разделить значения точкой с запятой либо переносом строки. Для каждого правила будет применено только первое подходящее переименование, поэтому можно передать, например, --rename 'a to b; b to a', чтобы поменять местами пространства имён a и b.

--force

По умолчанию, если после миграции у двух или более правил @use оказывается одно и то же пространство имён, мигратор завершает работу с ошибкой и не вносит никаких изменений.

В этом случае обычно следует изменить скрипт --rename, чтобы избежать конфликтов. Но если вы предпочитаете принудительно выполнить миграцию, вместо этого можно передать --force.

При использовании --force, если возникнут конфликты, первое правило @use получит предпочтительное пространство имён, а к последующим правилам @use с таким же предпочтительным пространством имён будет добавлен числовой суффикс.