Getting started with npm scripts

Node.js has been riding the wave of JavaScript's growing ubiquity. As the default package manager for Node.js, npm has seen a parallel rise in popularity. There is good reason for this. npm is well-built, well documented, and makes Node.js development more seamless. It's hard to imagine using Node.js without npm.

For Node.js based projects, developers often turn to technologies such as grunt and gulp. These tools help to simplify local development and front-end tooling. There is good reason for this: grunt, gulp and similar tools work well and are helpful.

npm scripts help you to move some of your front-end tooling and local development away from third party tools. There is a high probability that your Node.js based project leverages npm. If so, npm scripts offers potential for simplifying your setup.

To get started, clone the following git hub repository:

(Instructions on how to run the code are available in the Git hub page.)

A simple Gulp project

To explain npm scripts, I have created a simple project that leverages Gulp. This project has four features:

  • It compiles a coffeescript file to JavaScript.
  • It compiles a SASS file to CSS.
  • It uglifies a JavaScript file.
  • It starts a Node.js web server.

This is a simple example and there is not too much going on. I chose this scenario because it requires four manual steps. It is possible to automate these tasks using Gulp. But, what if you needed to swtich to Grunt, or Broccoli.js? Your commands would change. For example, gulp coffee would become grunt coffee. This is not fatal. But wouldn't it be nice if we could have a consistent set of commands? How can we build our local development assets and start the Node.js server with one command? Also, how can we ensure that this one command never changes?

We will solve this problem using npm scripts.


  "name": "npm-scripts-example",
  "version": "1.0.0",
  "devDependencies": {
    "gulp": "3.9.1",
    "gulp-coffee": "2.3.2",
    "gulp-sass": "2.3.2",
    "gulp-uglify": "2.0.0"

The package.json so far allows us to use Gulp. We also use the gulp-coffee module to compile coffeescript. We use the gulp-sass module to compile SASS. And we use the gulp-uglify module to uglify JavaScript.

Project folder structure

Example # 1:


In example # 1, we have the folder structure for our project. There is an src folder that contains three sub folders. The coffee folder has a coffeescript file. The js folder has a JavaScript file. the sass folder has a SASS file. These three files are used by our build. The built versions of these files are placed in the build/css and build/js folders accordingly.

At this point, we have the following commands available to us:

gulp sass
gulp coffee
gulp uglify
node index.js

gulp sass:

This command will compile the file src/sass/main.scss and create build/css/main.css

gulp coffee:

This command will compile the file src/coffee/ and create build/js/global.js

gulp uglify:

This command will uglify the file src/js/main.js and create build/js/main.js

node index.js:

This command will start the Node.js web server on port # 3000.

This is all fine. You can run each command and it will work just fine. The problem is that each time you change any of the files, you will want to build them again, and then re-start the web server.

We can use npm scripts to solve this problem.

Adding npm scripts to package.json

Example # 2:

  "name": "npm-scripts-example",
  "version": "1.0.0",
  "devDependencies": {
    "delete": "0.3.2 ",
    "gulp": "3.9.1",
    "gulp-coffee": "2.3.2",
    "gulp-sass": "2.3.2",
    "gulp-uglify": "2.0.0"
  "scripts" : {
      "build:sass": "gulp sass",
      "build:coffee": "gulp coffee",
      "build:js": "gulp uglify",
    "build": "npm run build:sass && npm run build:js && npm run build:coffee",
    "serve" : "node ./index.js",
      "start": "npm run build && npm run serve",
    "clean": "node ./clean.js"

In example # 2, we have added a scripts object to package.json.

build:sass :

This command is a shortcut to: gulp sass.

build:coffee :

This command is a shortcut to: gulp coffee.

build:js :

This command is a shortcut to: gulp uglify.

build :

This command will execute the previous three commands. It executes three steps in one command.

serve :

This command is a shortcut to: node ./index.js (it starts the Node.js web server).

start :

This command builds all three files, and then starts the web server.

clean :

This command will delete every the built file (these are files created by all previous commands).

What to expect when you run the example code locally

npm start - The build places the three built files in the build/css and build/js folders accordingly. And then, it starts the Node.js web server. You will see messages in your terminal that indicating these outcomes.

npm run clean - npm deletes the three built files in the build/css and build/js folders. (This is helpful if you want to "start from scratch" when running the npm start command. This way you see the built files created each time.)


In this article, we had a basic introduction to npm scripts. We learned how to specify npm commands in our package.json file. We also learned how to create npm script commands that in-turn execute more than one other npm script commands. This was a high-level overview, and there is much more detail available. A great place to start is: I hope that this article has pointed you in the right direction. There is a great deal of power in npm scripts. Depending on your needs, npm scripts can streamline your front-end tooling process.


Kevin Chisholm

Share This