Сборка сложных Node.js проектов утилитой run-z

Есть несколько десятков взаимосвязанных пакетов в рабочем дереве (Yarn Workspaces).

Надо собирать несколько из них. Часто, быстро, и в правильном порядке.

Существующие инструменты либо собирают всё сразу и долго, либо собирают в произвольном порядке, что некорректно и не всегда возможно.

Решение — run-z

Установка

npm install run-z --save-dev  # Используя NPM
yarn add run-z --dev          # Используя Yarn

Теперь в package.json можно добавлять задачи

{
  "scripts": {
    "all": "run-z build lint,test",
    "build": "run-z --then tsc -p .",
    "clean": "run-z --then shx rm -rf ./dist",
    "lint": "run-z --then eslint .",
    "test": "run-z --then jest",
    "z": "run-z"
  }
}

И запускать их

npm run all               # Запуск одной задачи, используя NPM
yarn all                  # Запуск одной задачи, используя Yarn

yarn clean build          # Запуск нескольких задач, используя Yarn
npm run clean -- build    # Запуск нескольких задач, используя NPM

npm run z -- clean build  # Запуск через пустую задачу `z`

Рекомендую всегда добавлять пустую задачу, например z. Она позволит передать дополнительные параметры в run-z, а не в npm или yarn. Например, вот так можно вызвать справку:

yarn z --help
npm run z -- --help

Как видите, синтаксис вызова у Yarn проще, чем у NPM.

Ниже в тексте я буду использовать Yarn в примерах.

Задачи

Задачи записываются как обычные сценарии в разделе scripts файла package.json. Если такой сценарий запускает команду run-z, то последняя трактует все сценарии как свои задачи и может запустить сразу несколько.

Если перечислить несколько задач в командной строке run-z, то выполнение каждой из них станет предварительным условием для следующей:

run-z prerequisite1 prerequisite2 --then node ./my-script.js --arg

Такая задача запустит сначала prereqiusite1, затем, дождавшись её завершения — prerequisite2, и только по её окончании — запустит сценарий node ./my-script.js --arg.

Поддерживаются четыре типа задач:

• Команда содержит опцию --then. Всё, что следует за этой опцией — это команда с аргументами, которая будет выполнена.
• Сценарий NPM — это любой сценарий в разделе scripts файла package.json, отличный от run-z. run-z запускает такие сценарии через npm run или yarn run.
• Группа содержит список задач для запуска, но не содержит команды. Список задач может быть пустым.
• Неизвестная задача создаётся, если не соответствует ни одному сценарию в package.json. При попытке её запуска возникнет ошибка. Но задачи можно пропускать, тогда никакой ошибки не будет.

Параметры выполнения задач

Можно передавать дополнительные параметры в вызываемые задачи. Для этого предназначен особый синтаксис:

run-z test/--ci/--runInBand     # Передача `--ci` и `--runInBand`
                                # в команду или сценарий NPM,
                                # запущенный задачей `test`.
run-z test //--ci --runInBand// # Несколько параметров сразу.

Отдельный синтаксис нужен, чтобы передавать параметры конкретной задаче, а не команде run-z. Впрочем, неопознанные параметры будут переданы задаче и так, без знака /.

Одиночные параметры отделяются от задачи одиночным знаком /. Перед ним можно добавлять пробелы.

Много параметров можно заключать между ограничителями из нескольких (двух или более) знаков /.

Атрибуты задач

Атрибуты — это пары ключ/значение, которые можно передавать задачам примерно так же, как и параметры:

run-z test/attribute=value       # Атрибут `attribute` со значением `value`
                                 # для задачи `test`
run-z build test attribute=value # Атрибут `attribute` со значением `value`
                                 # для самой задачи и всех предварительных задач.
run-z test/=if-present           # Сокращённо `if-present=on`.

Атрибуты пока не очень полезны, но уже могут быть использованы в некоторых случаях:

• Когда установлен атрибут if-present для задачи, отсутствующей в package.json, то попытки выполнить такую задачу не будет предпринято и ошибка не возникнет.
  Может быть полезно, когда задача выполняется в нескольких пакетах одновременно, но в некоторых пакетах такая задача не определена.
• Когда для задачи установлен атрибут skip, то выполняться такая задача не будет.

Дополнения к задачам

run-z запускает каждую задачу только раз, сколько бы раз она ни была вызвана. Даже если одна задача требуется для выполнения нескольких других. И каждый раз, как задача вызывается, ей можно передавать параметры и атрибуты. Параметры таких вызовов объединяются.

Также есть особый синтаксис вызова задачи, называемый дополнением. Если перед именем задачи поставить знак +, то параметры в задачу будут переданы, но вот выполнение задачи инициировано не будет.

Это можно использовать, например, для задания параметров задачи по умолчанию. Так что с таким package.json:

{
  "scripts": {
    "test": "run-z +z jest",
    "z": "run-z +test/--runInBand"
  }
}

при исполнении задачи test, jest всегда будет вызываться с опцией --runInBand.

Параллельное и последовательное выполнение

Любые две задачи выполняются последовательно, если только им не разрешено выполняться параллельно.

Запятая между именами задач разрешает их параллельное выполнение.

Например, задача

run-z clean build lint,test

Выполнит lint и test параллельно, но лишь когда build завершится. А задача build начнёт выполняться, только когда завершится clean.

Также можно выполнять команды параллельно с другими задачами. Для этого достаточно опцию --then заменить на опцию --and:

run-z copy-assets --and tsc -p .  # Копирует файлы и компилирует
                                  # TypeScript одновременно.

Число одновременно выполняемых задач ограничено. По умолчанию — числом процессоров. Но можно это исправить опцией --max-jobs (сокращённо -j):

run-z build,lint,test -j2          # Только две задачи одновременно.
run-z build,lint,test -max-jobs 1  # Отключает параллельное выполнение.
run-z build,lint,test -j0          # Убирает ограничение.

Пакетное выполнение

Можно выполнить задачу в другом пакете:

run-z ../package1 build test . build test

Эта задача выполнит build и test в пакете из директории ../package1, а затем — в текущем.

Опции командной строки ., .., а также начинающиеся с ./ и ../ — это URL указывающие на директории с пакетами. Задачи, перечисленные после них, будут найдены и выполнены в целевом пакете.

В общем случае такие опции — селекторы — могут выбрать сразу несколько пакетов. Тогда задача с одним и тем же именем будет выполнена во всех. Партией:

run-z ./packages//  build # Выполнит `build` в каждом пакете
                          # непосредственно внутри директории `./packages`.
run-z ./packages/// build # Выполнит `build` в директории `./packages`
                          # и в каждом пакете найденном как угодно глубже.

// выбирает непосредственно вложенные директории. /// выбирает директорию и её поддиректории на любую глубину. Скрытые директории и директории без файла package.json игнорируются.

Можно указать сразу несколько селекторов. Результаты выборок будет объединены:

run-z ./3rd-party// ./packages// build # Выполнит `build` в каждом пакете
                                       # из директорий `./3rd-party`
                                       # и `./packages`.

Порядок выполнения задач из партии определяется зависимостями между пакетами. То есть сначала задача выполняется для зависимости, а затем — для зависящего от него пакета. Задачи в независимых пакетах выполняются параллельно.

Можно разрешить всем задачам в партии выполняться параллельно опцией --batch-parallel, сокращённо --bap:

run-z --batch-parallel ./packages// lint # Выполнит `lint` в каждом пакете
                                         # внутри директории `./packages
                                         # параллельно.

Подзадачи

Задача типа "группа" не только выполняет перечисленные задачи. Она также может быть использована для запуска произвольных задач в выбранных пакетах.

Для этого группе можно передать параметры вызова. И первым параметром будет имя (под-)задачи, которую нужно выполнить. Остальные параметры будут переданы уже в эту подзадачу.

Так что с таким package.json:

{
  "scripts": {
    "each": "run-z ./3rd-party// ./packages//"
  }
}

можно выполнить задачи партией внутри директорий 3rd-party/ и packages/:

yarn each /build each /test  # Выполнит `build`, а затем `test` во всех пакетах.  

Именованные партии задач

Для удобства работы в рабочем дереве (например Yarn Workspaces) партии задач можно именовать.

Допустим, есть корневой пакет с таким package.json:

{
  "scripts": {
    "all/*": "run-z ./packages//",
    "z": "run-z"
  }
}

Здесь сценарий с именем "all/*" — это описание именованной партии. С таким описанием становится возможным пакетное выполнение задач как находясь в корне, так и находясь во вложенных директориях:

yarn z build --all       # Выполняет `build` во всех пакетах.

Когда указана опция --all, run-z ищет самый верхний пакет, содержащий именованные партии задач, и выполняет задачи в этих партиях.

Имя именованной партии может быть "имя_партии/имя_задачи". Такая именованная партия используется вместо "имя_партии/*", когда выполняется задача "имя_задачи". Это полезно, например, когда нужно передать дополнительные опции в конкретную задачу:

{
  "scripts": {
    "all/*": "run-z ./packages//",
    "all/test": "run-z ./packages// +test/--runInBand",
    "z": "run-z"
  }
}

yarn z build --all  # Выполняет `build` партией.
yarn z test --all   # Выполняет `test` партией с опцией `--runInBand`.

Граф зависимостей

Именованные партии позволяют выполнять задачи в подмножестве графа зависимостей текущего пакета:

yarn build --with-deps        # Выполняет `build` в зависимостях
                              # и в самом пакете.
yarn build --only-deps        # Выполняет `build` только в зависимостях.
yarn build --with-dependants  # Выполняет `build` в пакете,
                              # а затем во всех зависимых пакетах.
yarn build --only-dependants  # Выполняет `build` только в зависимых пакетах.

Сравнение с npm-run-all

npm-run-all — это весьма популярный инструмент для сборки. Прежде я использовал именно его и могу сравнивать.

Вот так выглядели сценарии сборки типичного проекта, использующего TypeScript, Rollup, ESLint и Jest:

{
  "scripts": {
    "all": "run-p --aggregate-output build:all \"test {@}\" --",
    "build": "rollup --config ./rollup.config.js",
    "build:all": "run-p --aggregate-output rebuild lint",
    "ci:all": "run-p --aggregate-output build:all ci:test",
    "ci:test": "jest --ci --runInBand",
    "clean": "shx rm -rf d.ts dist target",
    "lint": "eslint .",
    "rebuild": "run-s clean build",
    "test": "jest",
  }
}

run-p здесь выполняет перечисленные задачи параллельно. run-s — последовательно.

И вот как это выглядит теперь:

{
  "scripts": {
    "all": "run-z build,lint,test",
    "build": "run-z +z rollup --config ./rollup.config.js",
    "ci:all": "run-z all +test/--ci/--runInBand",
    "clean": "run-z +z --then shx rm -rf d.ts dist target",
    "lint": "run-z +z --then eslint .",
    "test": "run-z +z --then jest",
    "z": "run-z +build,+doc,+lint,+test"
  }
}

1. Вспомогательная задача "ci:test" для запуска тестов в окружении CI больше не нужна. Все необходимые параметры можно передать прямо в задачу "test".
2. Вспомогательная задача "build:all" была нужна только чтобы выполнять задачи параллельно. Теперь их можно перечислить через запятую.
3. Задача "rebuild" тоже стала не нужна, поскольку можно вызывать несколько задач прямо из командной строки: yarn clean build.
4. Появилась задача "z". Она не просто для удобства, а ещё и разрешает параллельное выполнение некоторых задач. Так что yarn build lint test выполнит эти задачи параллельно. Не нужно каждый раз вспоминать, где поставить запятую.
5. Все сценарии теперь начинаются с run-z. Это необязательно для простых сценариев, но даёт возможность применить настройки по умолчанию, а также запустить несколько задач сразу, например yarn clean build.
6. Немаловажно также то, что run-z запускается единожды, сколько бы заданий не требовалось выполнить. А run-p или run-s запускаются каждым сценарием. Запуск V8 совсем не бесплатен.

Планы на будущее

В ближайших планах — добавить поддержку расширений. Основной замысел в том, чтобы уметь запускать не только внешние команды, но и использовать thread_workers. Хотя бы вместо некоторых команд. Это позволит как сэкономить ресурсы, так и существенно ускорить сборку. Особенно для быстрых утилит типа shx rm. Ведь последняя тратит на порядки больше времени на свой запуск, чем, собственно, на работу.