Dependencies vs. DevDependencies: What's the Difference?

WHY IT EXISTS Node.js projects need a way to distinguish between packages required for the application to run for an end-user and packages only needed by developers to build and test it. This separation prevents shipping unnecessary code to production, which saves disk space, reduces installation time, and minimizes the potential security attack surface.

THE MENTAL MODEL Think of a restaurant kitchen. The dependencies are the ingredients that go into the final dish served to a customer, like flour, tomatoes, and cheese for a pizza. The devDependencies are the tools in the kitchen used to prepare the dish but not served to the customer, like the oven, mixing bowls, and pizza cutter. You need the tools to make the food, but you don't ship the oven with every pizza delivery.

HOW IT WORKS When you install a package via npm, you specify its purpose with a flag. Running npm install express (or npm i express --save-prod) adds express to the dependencies object in your package.json. Running npm install jest --save-dev adds jest to the devDependencies object. When you run a plain npm install in a project, it installs packages from both lists. However, build environments for deployment typically run npm install --production, which installs only the dependencies, correctly ignoring the development tools.

WHEN TO USE IT Use dependencies for any package your code require()s or imports that is necessary for the application to function in its deployed state. Examples include frameworks (Express), utility libraries (Lodash), and database drivers (pg). Use devDependencies for any package used during the development process but not at runtime. This includes test runners (Jest, Mocha), bundlers (Webpack, Vite), linters (ESLint), and type systems (TypeScript).

WHEN NOT TO USE IT The primary mistake is putting development tools in dependencies. This forces your production environment to install your entire testing and linting toolchain, which is wasteful. Conversely, never put a runtime package like express in devDependencies. If you do, your application will fail in production with a "module not found" error because the package wasn't installed.

ONE CANONICAL EXAMPLE Consider a simple API built with Express and written in TypeScript. Your package.json would list express in dependencies. Your devDependencies would include typescript (to compile TS to JS), nodemon (to auto-restart the server during development), and @types/express (for type definitions). A production deployment would correctly install only express, the single package needed to run the compiled server.