Node.js basic commands with practical examples: a hands-on guide

Intro

Node.js comes with a small set of commands that cover most daily work: running code, installing packages, executing scripts, and debugging. This guide shows the essential commands, when to use them, and safe, copy-paste examples you can run on macOS, Linux, or Windows terminals.

Who this is for:

• Developers shipping services and CLIs
• DevOps consultants standardizing workflows
• Startup teams building APIs with Express, data layers with MongoDB or Redis, and automating builds with Docker and GitLab CI/CD

What you will get:

• A minimal workflow from project setup to debugging
• Practical examples of node, npm, and npx
• A small local pilot you can complete in under 20 minutes

---

Workflow Overview

Use this sequence to keep work predictable and low-risk.

1. Verify versions

   node --version
   npm --version
   npx --version

Why: Confirms your toolchain and helps reproduce issues across machines.

1. Initialize a project

   mkdir my-app && cd my-app
   npm init -y

Why: Creates package.json so you can track scripts and dependencies.

1. Try quick one-liners

   node -e "console.log('hello world')"
   node -p "1 + 2"

Why: Validate runtime features or reproduce bugs fast without files.

1. Add dependencies

   npm install express
   npm install --save-dev nodemon

Why: Keep runtime deps separate from dev-only tools.

1. Wire npm scripts (package.json)

   {
     "scripts": {
       "start": "node index.js",
       "dev": "npx nodemon index.js",
       "test": "node test.js"
     }
   }

Why: Standard entry points make local runs and automation consistent.

1. Run and debug

   npm run start
   node --inspect index.js
   node --inspect-brk index.js

Why: Inspect variables and step through startup when needed.

1. Maintain the install

   npm list --depth=0
   npm uninstall <pkg>
   npm prune
   npm cache verify

Why: Keep the tree clean and dependency state predictable.

1. Reproducible installs for automation

   # Use when you have a lockfile (package-lock.json)
   npm ci

Why: Faster, clean install that matches the lockfile exactly.

---

Core Commands With Examples

Below are the commands you will reach for daily, grouped by task.

Check and explore the runtime

• Versions

  node -v
  npm -v

• REPL (interactive shell)

  node
  > 2 + 2
  4
  > .exit

• One-liners

  node -e "console.log(process.platform)"
  node -p "[1,2,3].map(x=>x*2)"

• Run a file

  node index.js

Debugging and diagnostics

• Inspect with a debugger port

  node --inspect index.js
  node --inspect-brk index.js # break on first line

• Trace warnings to source

  node --trace-warnings index.js

Tip: Use these flags only when investigating; remove them for normal runs.

Initialize and manage packages

• Create package.json quickly

  npm init -y

• Install runtime and dev dependencies

  npm install express
  npm install --save-dev nodemon eslint

• Remove dependencies and clean extras

  npm uninstall express
  npm prune

• List top-level packages

  npm list --depth=0

• Update within allowed semver ranges

  npm update

• Reproducible clean install (CI, containers)

  npm ci

Note: npm ci removes node_modules and installs exactly from package-lock.json.

Run project scripts

• Add scripts (example)

  {
    "scripts": {
      "start": "node index.js",
      "dev": "npx nodemon index.js",
      "lint": "npx eslint .",
      "test": "node test.js"
    }
  }

• List available scripts and run them

  npm run          # lists scripts
  npm run dev
  npm run lint
  npm test         # alias for npm run test

Use npx to execute project binaries

npx looks up executables in your project or downloads them if needed.

• Prefer local dev tools to keep versions consistent:

  # After installing eslint as a dev dependency
  npm install --save-dev eslint
  npx eslint .

• Run a locally installed nodemon without global install:

  npx nodemon index.js

Environment tips for daily operations

• Cross-platform port setting in code is safer than in shell:

  // index.js
  const port = process.env.PORT || 3000

• In Docker or CI, prefer:

  npm ci --omit=dev   # production-only install

• For monorepos or multiple services, run scripts from each package root to keep context clear.

---

Local Pilot Plan

Build a small, safe Express API locally. This pilot is narrow, measurable, and easy to inspect.

1. Pre-checks

   node --version
   npm --version

Success criteria: Node and npm respond with versions.

1. Initialize and install

   mkdir node-pilot && cd node-pilot
   npm init -y
   npm install express
   npm install --save-dev nodemon

1. Create a minimal API

   // index.js
   const express = require('express')
   const app = express()
   const port = process.env.PORT || 3000

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

   app.get('/time', (req, res) => {
     res.json({ now: new Date().toISOString() })
   })

   app.listen(port, () => {
     console.log(`API listening on http://localhost:${port}`)
   })

1. Add scripts

   {
     "scripts": {
       "start": "node index.js",
       "dev": "npx nodemon index.js",
       "test": "node test.js"
     }
   }

1. Run locally

   npm run start
   # or live-reload during development
   npm run dev

1. Validate behavior

   # In a separate terminal
   curl -s http://localhost:3000/health | jq .
   curl -s http://localhost:3000/time | jq .

Pass criteria:

• /health returns {"status":"ok"}
• /time returns an ISO timestamp

1. Optional diagnostics

   node --inspect index.js
   node --trace-warnings index.js

1. Clean up

Press Ctrl+C to stop the server, then:

   npm prune

Notes:

• Extend the pilot by adding a POST route and a simple in-memory store before introducing MongoDB or Redis.
• When containerizing, replace npm install with npm ci for consistent builds.

---

Conclusion

You now have a compact Node.js command set, a clear workflow, and a local pilot you can run today. Apply these habits to services that use Express, connect to MongoDB or Redis, and run inside Docker or GitLab CI/CD. Next steps:

• Standardize scripts: start, dev, test, lint
• Use npm ci in containers and automation for reproducible installs
• Keep debugging flags handy for quick diagnosis, but off in normal runs

With these commands and patterns, your team can move faster with fewer surprises.