npm scripts: настройка и лучшие практики

npm scripts объединяют набор команд терминала, которые можно запускать для автоматизации задач в JavaScript-проекте. Они обеспечивают единый способ запуска команд в разных окружениях и делают рабочие процессы воспроизводимыми.

Вы настраиваете npm scripts в файле package.json, запускаете их из терминала и используете дополнительные пакеты и параметры для совместимости и удобства.

Настройка npm scripts в файле package.json

Обычно npm scripts определяются в package.json в корне проекта. Это не строгое требование — можно запускать команды и из других мест — но package.json упрощает доступ и управление.

Минимальные шаги для настройки:

1. Перейдите в корень проекта:

cd /path/to/your/project

2. Инициализируйте package.json (если его ещё нет):

npm init

Команда задаст несколько вопросов о проекте и создаст package.json.

3. Откройте package.json и найдите поле “scripts”. Добавьте туда пары имя-скрипт.

Простой пример package.json со скриптом hello-world:

{
  "name": "npm-scripts-demo",
  "version": "1.0.0",
  "scripts": {
    "hello-world": "echo \"Hello world\""
  }
}

Запуск npm run hello-world выведет в терминал “Hello world”.

Важно: для работы с npm scripts требуется установленный Node.js и npm на вашей машине.

Часто используемые скрипты

Типичные скрипты, которые можно встретить в проектах:

• start — запускает dev-сервер (например, через nodemon или node).
• build — собирает продакшн-артефакты (webpack, rollup и т. п.).
• test — запускает тесты (Jest, Mocha).
• lint — проверяет код линтером (ESLint).
• watch — следит за изменениями и пересобирает/перезапускает задачу.
• deploy — запускает деплой на staging/production.

Эти имена привычны командам разработки и инструментам CI.

Pre и post скрипты

npm поддерживает pre и post хуки: скрипт с префиксом pre выполняется до соответствующего скрипта, а post — после.

Пример:

{
  "scripts": {
    "pretest": "npm run lint",
    "test": "jest",
    "posttest": "npm run build"
  }
}

При запуске npm test сначала выполнится pretest, затем test, затем posttest.

Запуск npm скриптов

Базовый синтаксис:

npm run 

Пример:

npm run start

Чтобы получить список доступных скриптов, достаточно запустить npm run без аргументов — npm выведет все скрипты и команды.

Сокращённые команды для встроенных скриптов

Для некоторых стандартных имён есть краткая форма: вместо npm run start можно выполнить npm start. То же применимо для test, stop, restart (если они определены как скрипты).

Последовательный и параллельный запуск

Есть два подхода к запуску нескольких скриптов: по очереди (последовательно) и одновременно (параллельно).

• Последовательно: используйте && в Unix-подобных системах или в скриптах npm:

npm run start && npm run test

• Параллельно: в Unix можно использовать & или запустить процессы в фоновом режиме, но это не кросс-платформенно.

Для кросс-платформенного параллельного запуска используют пакеты npm-run-all и concurrently.

Пример с npm-run-all:

npm install --save-dev npm-run-all
# в package.json
"scripts": {
  "server": "node server.js",
  "client": "webpack --watch",
  "dev": "npm-run-all --parallel server client"
}

Пример с concurrently:

npm install --save-dev concurrently
# в package.json
"scripts": {
  "dev": "concurrently \"npm run server\" \"npm run client\""
}

Важно: перед использованием установите соответствующие пакеты через npm.

Типичные ошибки и их устранение

• npm ERR! missing script — вы пытаетесь запустить несуществующий скрипт. Проверьте орфографию и поле “scripts” в package.json.
• Permission denied — недостаточно прав для выполнения команды; проверьте права на файлы и используйте корректного пользователя.
• Missing dependencies — скрипт требует пакет, который не установлен. Установите зависимости через npm install и проверьте package.json. Инструмент depcheck помогает найти неиспользуемые и отсутствующие зависимости.
• Unknown command — при запуске кастомного скрипта как встроенной команды забудьте npm run. Для пользовательских скриптов всегда используйте npm run .

Переменные окружения в скриптах

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

Установка:

npm install --save-dev cross-env

Пример использования:

{
  "scripts": {
    "build": "cross-env NODE_ENV=production webpack"
  }
}

cross-env гарантирует, что NODE_ENV будет установлен правильно и на Windows, и на Unix.

Передача аргументов в npm скрипты

Чтобы передать аргументы в npm-скрипт, используйте двойной дефис -- после имени скрипта. Всё что после -- попадёт в процесс.

Пример:

npm run test -- --watch

Передача параметров конфигурации через npm config переменные:

npm run my-port --PORT=3000

И в scripts можно читать эту переменную как $npm_config_PORT (Unix) или %npm_config_PORT% (Windows):

Unix:

{
  "scripts": {
    "my-port": "echo \"Port: $npm_config_PORT\""
  }
}

Windows (cmd.exe):

{
  "scripts": {
    "my-port": "echo \"Port: %npm_config_PORT%\""
  }
}

Запуск npm run my-port --PORT=3000 выведет “Port: 3000”.

Когда npm scripts не подходят (контрпримеры)

• Сложные воркфлоу с длинными зависимостями и условной логикой: лучше использовать полноценные таск-раннеры (Gulp, Grunt) или build-системы.
• Проекты с большим числом параллельных задач и мониторинга ресурсов: подходы на уровне CI/CD или специализированные процессы дают больше контроля.
• Низкоуровневые системные операции, требующие сложных прав или контейнеризации: используйте shell-скрипты, systemd или контейнерные оркестраторы.

Альтернативные подходы

• Makefile — хорош для unix-среды и репродуцируемых целей, но менее удобен на Windows.
• Gulp / Grunt — task runner с потоковой обработкой и большим набором плагинов.
• npm task файлы с JavaScript — сложные задачи можно вынести в отдельные JS-файлы и запускать их из scripts.
• CI/CD pipelines — перенос логики в конвейер (GitHub Actions, GitLab CI) для более стабильного выполнения в окружениях.

Модель зрелости использования npm scripts

• Уровень 1 — базовые скрипты: start, test, build.
• Уровень 2 — составные скрипты: pre/post хуки, последовательные задачи.
• Уровень 3 — кросс-платформенность: использование cross-env, npm-run-all.
• Уровень 4 — интеграция с CI/CD и external tools: deploy, smoke tests, rollback.

Переходите на следующий уровень по мере роста проекта.

Чек-листы по ролям

Для разработчика:

• Убедиться, что npm run start запускает dev-сервер.
• Добавить test и lint в CI.
• Использовать переменные окружения через cross-env.

Для DevOps / инженер по интеграции:

• Автоматизировать сборку и деплой в CI.
• Проверить безопасность зависимостей.
• Настроить канареечный деплой и откат.

Для владельца проекта / мейнтейнера:

• Документировать доступные скрипты в README.
• Поддерживать краткие и понятные имена.
• Не дублировать логику между скриптами и CI.

Критерии приёмки для npm-сценариев

• Скрипт выполняется без ошибок на чистой машине после npm install.
• Выполняется как локально, так и в CI (учитывая переменные окружения).
• Имеет логирование и понятные сообщения об ошибках.
• Не содержит секретов или токенов в явном виде.

Безопасность и надёжность

• Не храните секреты в package.json и скриптах. Используйте менеджеры секретов или переменные окружения в CI.
• Выполняйте npm audit и обновляйте уязвимые зависимости.
• Ограничьте права исполняемых файлов и используйте непривилегированные учётные записи для CI.

Сравнение: concurrently vs npm-run-all

Быстрая шпаргалка (cheat sheet)

• Создать package.json: npm init
• Запустить скрипт: npm run или npm для start/test
• Параллельно (npm-run-all): npm-run-all --parallel a b
• Установить cross-env: npm install --save-dev cross-env
• Передать аргументы: npm run myscript -- --flag

Примеры шаблонов (snippet)

package.json с типовым набором скриптов:

{
  "scripts": {
    "start": "node server.js",
    "dev": "npm-run-all --parallel server client",
    "server": "nodemon server.js",
    "client": "webpack --watch",
    "lint": "eslint src",
    "test": "jest",
    "build": "cross-env NODE_ENV=production webpack",
    "prepublishOnly": "npm test && npm run build"
  }
}

Краткое резюме

npm scripts — удобный инструмент автоматизации повседневных задач в JavaScript-проектах. Они просты для начала, гибки в комбинации с утилитами (cross-env, npm-run-all, concurrently) и служат хорошим слоем абстракции для разработчиков и CI. Документируйте скрипты, избегайте хранения секретов в package.json и используйте пред- и пост-хуки для выстраивания воспроизводимых процессов.

Важно: тестируйте скрипты на чистой установке зависимостей и интегрируйте их в CI для стабильности.

Ключевые ссылки для установки и справки: в официальной документации Node.js и npm, а также в репозиториях cross-env, npm-run-all и concurrently на GitHub.