Мигратор

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

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

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

choco install sass-migrator

Homebrew

Если вы используете менеджер пакетов Homebrew для Mac OS X, вы можете установить 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) сообщает мигратору путь загрузки, где он должен искать стилизованные страницы. Он может передаваться несколько раз для предоставления нескольких путей загрузки. Более ранние пути загрузки будут иметь приоритет над более поздними.

Предполагается, что зависимости, загруженные из путей загрузки, являются сторонними библиотеками, поэтому мигратор не будет их мигрировать, даже если передан параметр --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

Этот флаг сообщает мигратору 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

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

По умолчанию мигратор преобразует / операции в 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';
// ...

Поскольку у всех этих URL будет пространство имён по умолчанию mixins при миграции в правила @use, мигратор модулей может сгенерировать что-то вроде этого:

@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 с тем же предпочтительным пространством имён будут дополнены числовым суффиксом.