npm скрипты: настройка, запуск, отладка

Рука, держащая красный стикер npm

Что такое npm-скрипты

npm-скрипты — это пары “имя: команда” в поле scripts файла package.json. Они дают единый интерфейс для выполнения повторяющихся задач (запуск сервера, сборка, тесты, линтинг и т. п.). Определение: npm-скрипт — короткая оболочка для запуска команд оболочки (shell) или Node-инструментов из контекста проекта.

Коротко по терминам:

package.json — основной файл метаданных npm-проекта.
scripts — объект в package.json, где задаются команды.
pre/post хуки — скрипты, запускающиеся до/после основного скрипта.

Зачем использовать npm-скрипты

Упрощают запуск повторяющихся команд командной строки.
Абстрагируют платформенные различия (в сочетании с cross-env и подобными утилитами).
Делают процесс воспроизводимым для команды и CI.
Позволяют сочетать несколько шагов через pre/post хуки.

Important: npm-скрипты не заменяют полноценные таск-раннеры там, где требуется сложная логика. Они удобны для большинства dev-операций.

Настройка npm-скриптов в package.json

Перейдите в корень проекта.
Создайте package.json, если его нет:

npm init

В package.json добавьте поле scripts. Простой пример:

{
    "scripts": {
        "hello-world": "echo \"Hello world\""
    }
}

Когда вы добавите такой скрипт, команда npm run hello-world выведет Hello world в терминал.

Частые имена скриптов и их назначение

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

Pre и post скрипты

npm поддерживает префиксы pre и post. Скрипт с именем pre выполнится перед , post — после.

Пример:

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

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

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

Синтаксис базовой команды:

npm run

Примеры:

npm run start

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

npm run

Вывод покажет имена скриптов и команды, которые они выполняют.

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

Некоторые имена скриптов запускаются сокращённо:

npm start вместо npm run start
npm test вместо npm run test
npm stop, npm restart аналогично

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

Запуск нескольких npm-скриптов

Есть два основных подхода: последовательный и параллельный запуск.

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

npm run start && npm test

Параллельный запуск (в Unix):

npm run server & npm run client

Для кросс-платформенной поддержки используйте утилиты:

npm-run-all (позволяет –parallel и другие опции)
concurrently (удобно для запуска нескольких npm-скриптов)

Примеры:

npm-run-all --parallel server client

В package.json с concurrently:

"scripts": {
    "dev": "concurrently \"npm run server\" \"npm run client\""
}

Прежде чем использовать эти команды, установите пакеты:

npm i -D npm-run-all concurrently

Совет: объединяйте вывод в логи и давайте префиксы, чтобы легче отличать потоки.

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

Переменные окружения передают параметры в процесс сборки или запуска. Для кросс-платформенной установки удобно использовать cross-env.

Установка в качестве dev-зависимости:

npm i -D cross-env

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

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

cross-env гарантирует корректную установку переменных и в Windows, и в Unix.

Security note: не храните секреты (ключи, пароли) в package.json или в скриптах. Используйте защищённые хранилища CI и переменные окружения на уровне системы/платформы развертывания.

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

Чтобы передать аргументы, используйте двойной дефис – после имени скрипта:

npm run test -- --watch

Чтобы передать ключи в виде npmconfig:

npm run my-port --PORT=3000

В Unix-подобных системах доступ к переменной в скрипте:

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

В Windows (cmd.exe):

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

Проверяйте поведение платформенно-специфичных подстановок и документируйте, как запускать на CI.

Отладка частых ошибок

Ниже — типичные проблемы и быстрые решения:

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

Runbook при ошибках (быстрая последовательность действий)

Запустите скрипт вручную в терминале и скопируйте полный вывод.
Проверьте package.json на синтаксические ошибки (JSON валидатор).
Убедитесь, что все зависимости установлены: npm ci или npm install.
Если ошибка связана с путями — проверьте рабочую директорию (cwd) CI/сервер.
Для проблем с платформой — попытайтесь выполнить команду в контейнере Linux или через WSL.
При необходимости добавьте логирование в скрипт и выполните повторно.

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

Если требуется сложная оркестрация задач с ветвлениями и условиями — лучше использовать gulp, make или CI-конвейер.
Для тяжелых задач сборки, требующих параллелизма на уровне потоков/процессов, лучше отдельные инструменты сборки.
Если нужно управлять секретами и правами доступа — используйте специализированные решения CI/CD и секрет-менеджеры.

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

Makefile или bash-скрипты для Unix-ориентированных проектов.
Gulp/Grunt для таск-ориентированных workflow.
Nx, Lerna, TurboRepo для монорепозиториев и кэширования сборок.
CI-системы (GitHub Actions, GitLab CI) для запуска этапов в пайплайне вне локальной машины.

Шаблоны / Cheat sheet (часто используемые сниппеты)

Примеры в package.json:

"scripts": {
  "start": "node server.js",
  "dev": "nodemon server.js",
  "build": "cross-env NODE_ENV=production webpack --config webpack.prod.js",
  "lint": "eslint src --fix",
  "test": "jest --coverage",
  "precommit": "npm run lint"
}

Параллельный dev-сценарий:

"scripts": {
  "server": "node ./server/index.js",
  "client": "cd client && npm start",
  "dev": "concurrently \"npm run server\" \"npm run client\""
}

Короткая подсказка:

npm run — запуск пользовательского скрипта
npm start — сокращение для start
npm test — сокращение для test
npm run –silent — запуск без лишних логов

SOP: как добавить новый скрипт в проект (простой процесс)

Описать цель скрипта в задаче/issue.
Добавить запись в package.json в поле scripts с понятным именем.
Прописать ожидаемый вывод и ошибки в описании коммита/PR.
Добавить тест/пример запуска в README проекта.
Если скрипт влияет на CI, обновить конфигурацию CI.
Просмотреть PR коллегой и задокументировать в CHANGELOG, при необходимости.

Ролевые чеклисты

Разработчик:

Добавил скрипт в package.json с документацией.
Убедился, что скрипт работает локально и на CI.

Тимлид:

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

DevOps:

Обновил пайплайн CI при необходимости.
Проверил совместимость с production-средой.

Критерии приёмки

Скрипт запускается командой npm run без дополнительных манипуляций.
Скрипт документирован в README или в отдельном разделе Contributing.
Наличие тестового выполнения в CI (если скрипт критичен для сборки).
Отсутствие секретов в кодовой базе.

Ментальные модели и эвристики

“Keep scripts small” — каждая команда должна делать одно действие, комбинируйте их через pre/post или через последовательность вызовов.
“Prefer declarative over imperative” — используйте пакеты и конфигурационные файлы (например, webpack.config.js) вместо длинных shell-команд в package.json.
“Document everything” — простое имя скрипта оправдано, если есть описание и назначение.

Совместимость и миграционные заметки

Windows vs Unix: проверьте подстановки переменных и синтаксис команд (используйте cross-env и утилиты, работающие кроссплатформенно).
Миграция монорепозитория: используйте инструменты типа Lerna или TurboRepo для координации скриптов по пакетам.
При переходе с npm 6 на npm 7+ убедитесь, что lock-файл и поведение peerDependencies соответствуют ожиданиям.

Пример диаграммы принятия решения

flowchart LR
  A[Есть готовая команда в package.json?] -->|Нет| B[Добавьте новую запись scripts]
  A -->|Да| C[Нужно ли параллельное выполнение?]
  C -->|Да| D[Используйте concurrently или npm-run-all]
  C -->|Нет| E[Запустите через && или поскриптовые хуки]
  D --> F[Добавьте в документацию и CI]
  E --> F

Короткое объявление (100–200 слов)

npm-скрипты — простой и мощный способ стандартизировать задачи в JavaScript-проектах. Вместо того, чтобы держать в голове длинные команды или ставить ad-hoc скрипты в CI, перенесите частоиспользуемые операции в package.json. В этом руководстве показано, как определять скрипты, использовать pre/post хуки, передавать аргументы и переменные окружения, а также как запускать несколько задач параллельно и отлаживать типичные ошибки. Следуйте SOP для добавления новых скриптов и используйте cross-env, concurrently или npm-run-all для кросс-платформенной совместимости. Документируйте скрипты и не храните секреты в кодовой базе — это ускорит onboarding и уменьшит число неожиданных проблем на CI.

Социальная превью-версия

OG title suggestion: npm-скрипты: настройка, запуск и отладка OG description suggestion: Научитесь добавлять и запускать npm-скрипты, работать с переменными окружения и решать типичные ошибки — быстро и практично.

Итог — основные выводы

npm-скрипты дают единый интерфейс для автоматизации задач.
Для кросс-платформенности используйте cross-env и специализированные утилиты.
Разделяйте и документируйте скрипты, применяйте pre/post хуки.
Если требуется сложная логика, рассмотрите альтернативы (Gulp, CI, Make).

Notes: храните секреты вне package.json и проверяйте поведение скриптов на CI перед слиянием.

Полное руководство по npm скриптам: настройка, запуск и отладка