NPM scripts memo

S.P. — Sat, 24 Dec 2022 23:32:22 +0000

There is an extremely brief but too informative summary about such convenient feature of npm as scripts. So few words, only grouped and classified facts.

Disclamer

Information is relevant for npm v9.2.0

Main purposes of this post

to introduce classification of scripts
to summarize important things about npm scripts
to act as a quick reminder about npm scripts

Prerequisites

The readers should already be familiar with npm scripts feature at least at elementary level. It can be learned from scratch using some other sources:

Classification

Natively supported scripts
- Lifecycle
- Action-specific
- Command-specific
Arbitrary scripts

1 Natively supported

Purpose

To include developer-defined actions into npm command's flow (e.g., npm pack, npm install)

Where defined

package.json, "scripts" object

When executed

As a part of certain npm command - before or after the main action that performed by this command

How to run

npm <command-name>

Native scripts can be classified into Lifecycle, Action-specific, Command-specific scripts.

1-1 Lifecycle scripts

Description

Wide specific scripts. Run in the flow of several npm commands.

Scripts

preprepare/prepare/postprepare
dependencies

Example

prepare script is run in the flow of...
...next commands:

npm cache add
npm ci
npm diff
npm install
npm pack
npm publish
npm rebuild

See more here.

1-2 Action-specific scripts

Description

Run in the flow of one npm command along with command's main action. Some scripts run in more than one commands those perform related actions.

Scripts

prepublish - in flow of npm ci, npm install
prepublishOnly - in flow of npm publish
prepack/postpack - in flow of npm pack, npm publish
preinstall/install/postinstall - in flow of npm ci, npm install, npm rebuild
preversion/version/postversion - in flow of npm version

Example

npm version commands run the flow that includes its main action and predefined scripts. Execution order:

preversion script
npm version command's action
version script
postversion script

See more here.

1-3 Command-specific scripts

Description

Run in response of exactly one built-in npm command. These commands don't have their own actions and only run predefined scripts

Scripts

prestart/start/poststart - in response of npm start
prerestart/restart/postrestart - in response of npm restart
prestop/stop/poststop - in response of npm stop
pretest/test/posttest - in response of npm test

Example

npm start performs the next operations in order:

prestart script
start script
poststart script

This command doesn't have its own action other than scripts running.

2 Arbitrary

Purpose

To perform developer-defined tasks using npm ecosystem

Motivation

There may be other ways to perform developer-defined tasks, but it's handy to use npm ecosystem for them

How to define:

package.json, "scripts" object

When executed

In response of npm run command that runs exactly certain script named script-name

How to run

npm run[-script] <script-name>

Important

Arbitrary scripts can have pre/post versions

Example

Given we have precompress, compress and postcompress scripts in package.json.

npm run[-script] compress performs the next:

precompress script
compress script
postcompress script

So arbitrary scripts are similar to Command-specific native scripts. But they don't have a specific built-in npm command for running them.

This was a brief summary about npm scripts. I'm glad to receive a feedback!

DEV Community: S.P.

NPM scripts memo

Disclamer

Main purposes of this post

Prerequisites

Classification

1 Natively supported

Purpose

Where defined

When executed

How to run

1-1 Lifecycle scripts

Description

Scripts

Example

1-2 Action-specific scripts

Description

Scripts

Example

1-3 Command-specific scripts

Description

Scripts

Example

2 Arbitrary

Purpose

Motivation

How to define:

When executed

How to run

Important

Example