The Node.js Handbook: From Initialization to Deployment

This handbook takes a Node.js project from an empty folder to a running deployment: creating package.json, managing dependencies safely, structuring code, testing with the built-in test runner, and choosing where to run it. It targets current Node.js long-term-support releases and modern npm, and drops the tools and habits that older tutorials still teach.

1. Install Node.js and pick a version

Use an LTS (long-term support) release for anything you'll deploy. In September 2026, Node.js 24 is the active LTS line and Node.js 22 is in maintenance; Node.js 20 and older no longer receive security fixes. Always check the schedule on nodejs.org.

A version manager such as fnm or nvm lets each project use its own version. Installation for Windows, macOS and Linux is covered in installing Node.js and npm on your local machine. Check the result:

node --version
npm --version

Pin the version for your project so everyone (and your server) uses the same one:

node --version > .nvmrc

For an editor, Visual Studio Code and WebStorm both have strong Node.js support, including debugging and ESLint integration.

2. Start a project

mkdir my-api && cd my-api
npm init -y
npm pkg set type=module

npm init -y creates package.json with default values; edit the name, description and licence afterwards. Setting "type": "module" lets you use modern import and export syntax in .js files.

The fields that matter most:

3. Manage dependencies safely

npm install express          # runtime dependency
npm install -D eslint        # development-only dependency
npm uninstall express        # remove a package
npm outdated                 # see what has newer versions
npm update                   # update within the ranges in package.json

Version ranges follow semantic versioning: ^5.1.0 accepts any 5.x release, ~5.1.0 accepts only 5.1.x patches. The exact versions actually installed are recorded in package-lock.json. Commit it, and use npm ci on servers and in CI; it installs exactly what the lock file says and fails if the two files disagree.

Supply-chain attacks through compromised npm packages are real, so keep dependencies few and reviewed:

• Run npm audit regularly and fix what it reports.
• Don't install packages you haven't checked, and be wary of names that look like popular packages with a typo.
• Install scripts can run code on your machine; npm install --ignore-scripts avoids that for packages that don't need them.

4. Structure the project

my-api/
├── src/
│   ├── routes/
│   ├── services/
│   └── server.js
├── test/
├── .env.example
├── .gitignore
├── package.json
└── package-lock.json

A minimal server in src/server.js:

import express from 'express';

const app = express();
app.use(express.json());

app.get('/health', (req, res) => res.json({ ok: true }));

const port = process.env.PORT || 3000;
app.listen(port, () => console.log(`Listening on ${port}`));

Add scripts to package.json:

{
  "scripts": {
    "start": "node src/server.js",
    "dev": "node --watch --env-file=.env src/server.js",
    "test": "node --test",
    "lint": "eslint ."
  }
}

node --watch restarts on file changes, so nodemon is no longer needed, and --env-file loads a .env file without the dotenv package.

5. Version control

git init
printf "node_modules/\n.env\ndist/\n.DS_Store\n" > .gitignore
git add .
git commit -m "Initial commit"

Never commit .env or any file with passwords or API keys. Commit a .env.example that lists the variable names with dummy values instead.

6. Test with the built-in runner

Node.js includes a stable test runner and assertion library, so small and medium projects don't need Mocha or Jest:

// test/math.test.js
import { test } from 'node:test';
import assert from 'node:assert/strict';
import { add } from '../src/math.js';

test('adds two numbers', () => {
  assert.equal(add(2, 3), 5);
});

Run npm test. Add ESLint for code style and common mistakes, and Prettier if you want automatic formatting.

7. TypeScript and build steps

Modern Node.js no longer needs Babel to run current JavaScript. For TypeScript you have two options:

• Run it directly. Recent Node.js releases can run .ts files that use only erasable type syntax, stripping the types at load time. Check the documentation for your Node.js version for what is supported.
• Compile it. Install typescript as a dev dependency, run npx tsc --init, add "build": "tsc" to your scripts, and run the compiled JavaScript from dist/ in production.

Front-end bundles (React, Vue and similar) are built with their own tools, such as Vite, and the output is served as static files.

8. Publish a package to npm (optional)

Most apps are never published. If you're sharing a library:

For monorepos, npm workspaces ("workspaces": ["packages/*"]) link local packages together and install them in one step.

9. Deploy to production

Whatever you deploy to, the same rules apply:

• Install with npm ci --omit=dev and set NODE_ENV=production.
• Read the port from process.env.PORT, and on container platforms bind to 0.0.0.0.
• Keep secrets in environment variables, never in the repository.
• Run the same Node.js major version as in development.
• Keep the process running with the platform's manager, or with PM2 or systemd on your own server.

Where to run it on Domain India

Guides: getting started with the App Platform, deploying a Node.js app on shared hosting, and PM2 process management for a VPS. App Platform plans are ₹100, ₹250 and ₹500 a month (Domain India list prices on 23 September 2026, excluding 18% GST).

10. Troubleshooting common problems

• npm ci fails because the lock file is out of sync: run npm install locally, commit the updated package-lock.json, and try again.
• Peer dependency conflicts: update the packages involved to compatible versions. Use --legacy-peer-deps only as a temporary workaround.
• EACCES errors on global installs: don't use sudo npm; use a version manager so Node.js lives in your home folder.
• "Cannot use import statement outside a module": add "type": "module" to package.json or rename the file to .mjs.
• Deprecated package warnings: check whether you depend on it directly (npm ls package-name) and replace or update it.

Ready to ship your app? See App Platform plans, read getting started with the App Platform, or choose a VPS if you want to manage the server yourself.