Codectionary / Developer documentation / JavaScript

npm and your first JavaScript project

Learn what npm installs, what package.json records, and how to manage a small Node.js project.

When do you need npm?

npm is a package manager and command-line tool, not JavaScript itself. An official Node.js installation normally includes it. A single hello.js file can run with node hello.js and needs no package.json or third-party packages.

Use npm when a project has dependencies, development tools or named commands that should be shared with teammates. For browser-only JavaScript in a plain HTML page, npm and Node.js are optional until your chosen tools require them.

Create package.json

Create an empty project folder and run npm init -y inside it. npm writes a starter package.json with metadata and default values. Review and edit it rather than assuming it has a start command. A script called start runs only after you add a start entry.

The example below shows a small manifest you could edit in an editor. Its private flag prevents accidental publishing with npm publish. The start script invokes Node on app.js; create that file before running the script.

In a new project folder

npm init -y

Example package.json after editing the generated file

{
  "name": "javascript-start",
  "version": "1.0.0",
  "private": true,
  "scripts": { "start": "node app.js" }
}

Install and run packages

npm install PACKAGE adds a package to dependencies for runtime use; npm install --save-dev PACKAGE adds it to devDependencies for development tooling. Replace PACKAGE with a package you have chosen and checked. npm install without a name installs dependencies already declared by the current project.

npm creates node_modules for local installed packages and writes package-lock.json to record the resolved dependency tree. Keep package.json and package-lock.json with the project; normally do not commit node_modules. Read a package’s documentation, version and maintenance status before installing it because install scripts may run code on your machine.

npm run start reads the start script from package.json. If it says Missing script: start, add that script or run node app.js directly. If npm reports EBADENGINE, check the project’s engines field or a dependency’s requirements against node --version; repeatedly requesting an incompatible npm release cannot solve it.

Install existing project dependencies

npm install

Run a script only after it is defined

npm run start

Keep the tools in their roles

An editor stores the source, Node executes server or command-line JavaScript, and npm manages packages and project commands. Browser scripts run in a browser and can use the DOM. A Node program does not gain a webpage just because npm installed packages.

Syntax

npm init -y

Examples

Inspect a project manifest

Run this JavaScript to see the values of a small project manifest. The JSON version above belongs in package.json.

const manifest = {
  name: "javascript-start",
  private: true,
  scripts: { start: "node app.js" }
};
console.log(manifest.scripts.start);
  1. The manifest object represents the same kinds of fields stored in package.json; its name identifies the project and private prevents accidental publication when set in the actual JSON file.
  2. scripts.start is the command npm run start would execute if this field were in package.json. The program logs node app.js so you can inspect it without installing a package.
  3. JavaScript object syntax is close to JSON, but a real package.json must be valid JSON with quoted property names and no JavaScript statements. Use the JSON snippet in the section above for that file.

Best practices

  • Keep package.json and package-lock.json together.
  • Prefer project-local packages and review them before installing.
  • Check the Node engine range before upgrading npm.
  • Do not assume a script exists until you inspect package.json.

Runtime & versions

Browsers and JavaScript runtimes. Feature availability depends on the language and runtime version used by your project; consult the official reference below.

ECMAScript specification

Specifications & further reading