npm start Script Semantics in React

npm start Script Semantics in React

In today's post we will remind ourselves what the npm start script generally is and explore its conventional usage (or at least what is should be like) for React apps. It is assumed that you are familiar with the npm CLI and the concept of npm scripts.


npm start is one of predefined scripts of the npm CLI that can be called without run command (non-run scripts). The following two lines are identical:

$ npm start
$ npm run start

The npm start command consists of two short words (9 characters altogether including space), thus being very handy for common usage.

Common use cases

The npm start script usage may be different depending on type of target application. In this article we are considering the script use cases for front-end websites and web applications, in particular powered on React. These use cases may also apply to Node.js back-end apps.

In React, the npm start command is commonly used for either of two operations:

  • running development server, for development purposes, usually in watch mode;

  • launching optimized production build, including for deployment to production servers.

Different React development tools have different approaches of using the npm start. For example, popular create-react-app kit runs its dev server on npm start. Otherwise, Next.js - a React SSR framework - runs the app in production mode (super-hyper optimized), instead offering the npm run dev command for starting development mode.

In addition, some PaaS's, in particular Heroku, expect the npm start script of your application to run it in production mode, thus to use the script for deployment purposes. To override this behavior you often need to dive into heavy configuration, for example, in case of Heroku, to introduce a Procfile into your app codebase.

Let's have a convention

As we've mentioned above, every development tool has its own preferences about the npm start script usage. And I wouldn't urge you to break those rules: after all, it is already kinda conventional.

But what if you are going to compose a custom toolchain for your new React app, e.g. using Parcel (love this <3) bundler? If you are questioning whether to use the npm start script for development or production mode for your app - welcome to the pro club!

And as a pro you realize that you are setting up the handy npm start script primarily for people. For developers that will work (or already working) with your app codebase.

Developers run dev servers several times per day. They rarely launch an app in production mode. Not to mention that running the production mode often requires additional infrastructure, e.g. a static file server.

Thus, you will greatly improve developer experience by setting up the npm start script to start the app in development mode. (The create-react-app toolkit earns +1 from this point of view.)

After all, not everyone is familiar with your app codebase and infrastructure. It is a bit frustrating when a new person intends to run your app with simple npm start command and faces a nasty error like couldn't find a ./build directory (i.e. they were supposed to have run the npm run build command first).


Today we have explored common use cases of the npm start script for React apps and formulated a convention of how the script should be used in React app development. Have you thought about other reasons to follow this convention that I forgot to mention? Or maybe you disagree with something about it? Can't wait to see your comments on Twitter! Thanks for reading.

Photo by @thenewmalcolm from Unsplash