Restart a Node.js Application upon Changing a File

This tutorial will explain how to restart a Node.js application after changing a file using an npm Script and Nodemon. We can create a custom npm script to run our project during development. We will create a start script, and a dev script. Using an npm module called nodemon (named from the words node and monitor), we can restart our application automatically upon file changes.

By the end of this tutorial, you’ll be able to:

• Understand how to create an npm script
• Describe how devDependencies are handled from npm scripts
• Describe why we might want nodemon to ignore files

Goal

Run a node application in development mode that restarts on file changes.

Prerequisites

• What Are NPM Scripts?

Watch: Create a Script to Restart Application on Save

Restarting a project on file changes

When developing a Node.js project, you need to restart the application each time changes are made to a file in order to see the changes reflected in the application. You can do this manually by stopping the running process and running it again from the command line, but that gets old real quick.

Instead, we can use a command line tool called nodemon to help us restart the project whenever a js file within the project has changed. Nodemon can be installed globally, or it can be installed locally into your project as a devDependency.

To use nodemon in your project, I recommend you create an npm script specifically for running the application during development. We will call this a dev script.

Creating a dev script is a nice touch, because we often use special tools or settings during development which aren’t needed in production. The nodemon script is a great example of something you wouldn’t want to run in production. Having a specific script to run to start the development environment is useful for not only recording how to start the project for development, but also in separating the commands used to run the app in production from the commands needed only during development.

Add nodemon to your project

In this tutorial, we’ll create two scripts:

• start — script containing the commands to run our application.
• dev — the script which we will use during development to run the application and restart it on file changes. This script will use nodemon to call our start script, and then on file changes, restart the application by running the start script again.

Create a start script

First, let’s create a start script which will run the application. To do so, we create an entry in package.json under the "scripts" field. It should look like this, assuming the file index.js starts your application:

"scripts": {
  "start": "node index.js"
}

Creating a start script ensures that any changes to how the application should be started can be recorded in a single place. To run your project using the start script, execute npm start in the project’s directory.

Install `nodemon` as a devDependency

You could install nodemon globally and skip creating a dev script at all by running nodemon from the command line, but we want to make sure that everyone running or working on the application has all the tools they need to get started. Globally-installed packages aren’t distributed with your project, so if someone doesn’t have nodemon installed globally they wouldn’t be able to use it with the project.

Let’s install nodemon as a devDependency:

npm install --save-dev nodemon

Installing nodemon as a devDependency will make sure the package is tracked with the application, so that anyone can run the dev script to get started working with the project without having to globally install nodemon.

Create a `dev` script

Now that we have nodemon installed, let’s create the dev script which will reload our application on file changes during development. We will use nodemon’s --exec flag to tell nodemon to run an npm script whenever files in the project have changed.

Create a new "dev" entry in the scripts field of your package.json:

"scripts": {
  "start": "node index.js",
  "dev": "nodemon --exec 'npm start'"
}

Here we’ve told nodemon to execute the start script, instead of just running a file. Running nodemon without any commands would also start our index.js file, because nodemon will look for an index.js file by default and run that. We are telling nodemon to run the start script so that if we need to change how the application is started at any point, we only have to make the change to the start script.

One of the benefits of npm scripts is that they are able to run devDependencies without having to use the full path to the executable in the node_modules/ directory. Outside of an npm script, you would have to run nodemon (or any other devDependency) like this:

./node_modules/.bin/nodemon

However, using an npm script allows us to run nodemon just by executing the name of the package — similar to how we would run a globally-installed package.

Run the `dev` script

Now that our scripts are all set up, run the dev script by typing the following into your terminal:

npm run dev

You should see nodemon start the application. If you edit and save a file in the project, you will see nodemon restart the application. To manually restart the application, type rs into the terminal window nodemon is running in and hit enter.

That’s basically it! Now you have a dev script which will make sure that your application restarts whenever you save file changes. Your days of manually stopping and restarting your application during development are over.

The following last step is optional, but will come in handy if your application makes changes to files while running, such as writing to JSON files.

Ignore changes to files (optional)

Nodemon will restart the application when it detects changes to .js and .json files. But if your application itself writes to a .js or .json file, like for updating a config file or storing data in a JSON file, nodemon will prematurely restart the application.

Luckily, nodemon lets you specify files and folders to ignore. Let’s assume that we are using JSON files as a flat database, and have them stored in a directory at the root of the project called data/.

Edit the dev script to ignore all json files present in the data/ directory:

"scripts": {
  "start": "node index.js",
  "dev": "nodemon --exec 'npm start' --ignore './data/*.json'"
}

We’re using a wildcard to ignore all files ending in .json inside the data/ directory. Now whenever a change is made to these files, nodemon will ignore the change and our application won’t restart prematurely. This is important whenever you’re using nodemon with an application that edits JSON files. Otherwise, your application will constantly restart at the wrong time.

Recap

Creating npm scripts with unique purposes is a useful way to organize the tasks you use in your project. In this tutorial we created an all-purpose start script to codify how to start the application, and then created a dev script which uses nodemon to run the start script. You can create different npm scripts to help out with repetitive tasks during your development workflow.

Using nodemon you created an npm script to restart your project on file changes. By installing nodemon as a devDependency instead of globally, you ensured that anyone who runs your project will be able to start it for development in the same way you do, using the same dependencies. You also learned how to ignore files when using nodemon, which prevents premature restarts of the application due to the application running as normal.

Further your understanding

• How is running your application with nodemon different from running it with the Node executable?
• What happens if you make changes to a file but don’t save it?
• How does nodemon behave if your application crashes?
• If you have nodemon installed globally on your system and as a devDependency, which one will the script run?

Additional resources

• nodemon Documentation (npmjs.com)