Lesson 5 · Node.js on IBM i — From RPG Developer to Modern IBM i Developer

npm and package.json Explained

Turn your IBM i Node.js folder into a managed project and understand dependencies, scripts, package-lock.json, and node_modules.

Saurabh Arora

IBM i Solution Architect | Technical Lead | Modernization & Integration Specialist

Published September 4, 20263 min read

npm manages the packages a Node.js application uses, while package.json describes the application and provides repeatable commands for working with it.

Your hello.js file runs without a project definition because it only uses features built into Node.js.

Real applications usually need more structure. They may depend on a database connector, web framework, validation library, logger, or test tool.

That is where npm and package.json fit.

Initialize the project

Return to the directory created in the previous lesson:

cd "$HOME/eraofi-node"

Initialize a Node.js project:

npm init -y

The -y option accepts npm’s defaults and creates package.json without asking each setup question.

Open package.json. It will contain values similar to these:

{
  "name": "eraofi-node",
  "version": "1.0.0",
  "main": "hello.js",
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  "license": "ISC"
}

The exact defaults can vary with the npm version.

Think of package.json as project metadata

package.json does not contain your business logic. It describes the Node.js project.

Important fields include:

name          Project or package name
version       Application/package version
main          Conventional entry file
scripts       Named commands for development and operations
dependencies  Packages required when the application runs

For a private IBM i application that will not be published to the npm registry, add "private": true.

You can also replace the generated scripts with a useful start command:

{
  "name": "eraofi-node",
  "version": "1.0.0",
  "private": true,
  "main": "hello.js",
  "scripts": {
    "start": "node hello.js"
  }
}

JSON does not allow comments or trailing commas, so edit carefully.

Now run the named command:

npm run start

npm reads the start script and runs node hello.js.

A named script gives developers and deployment automation one consistent command. The implementation can change later without changing how everyone starts the application.

Install the Db2 connector

The next lessons use IBM’s promise-based Db2 for i connector:

npm install idb-pconnector

This package installs only on IBM i systems.

After installation, npm changes three things:

1. It adds idb-pconnector under dependencies in package.json.
2. It records the resolved dependency tree in package-lock.json.
3. It places installed package files under node_modules.

What should go into Git?

A typical .gitignore file includes:

node_modules/
.env

Normally commit:

• your JavaScript source
• package.json
• package-lock.json
• .gitignore

Normally do not commit:

• node_modules
• secrets or environment files
• generated logs

The lock file records exact resolved versions and helps make installations repeatable across environments. Keep it with application source.

Dependencies are part of the application

Installing a package is easy. Owning it is the real responsibility.

Before adopting a dependency, consider:

• Who maintains it?
• Is it still active?
• What license does it use?
• Does it support your Node.js version and IBM i?
• Does installation run native build scripts?
• How will you monitor and apply security updates?

Do not install packages globally just to avoid declaring them. Application dependencies belong in the project definition.

Common mistake: editing only node_modules

node_modules is generated installation output. Do not make permanent fixes directly inside it.

Update your source or dependency version, then recreate installed packages from the project files:

npm install

For controlled automated builds, teams commonly use npm ci with a committed lock file.

The project so far

The project now has a repeatable shape:

JavaScript source    What your application does
package.json         What the application needs and how to run it
package-lock.json    Exact dependency resolution
node_modules         Installed package files

In the next lesson, we will use idb-pconnector to connect a Node.js program to the local Db2 for i database.