✦ How to Create and Use a package.json File in Node.js

When you start developing a Node.js application, one of the first files you will encounter is package.json. This file plays an important role in organizing your project, managing dependencies, defining scripts, and storing project information.

Whether you are building a simple Node.js application, an Express.js website, or a REST API connected to MySQL, understanding package.json will help you manage your project more efficiently.

In this practical tutorial by Param Classes, you will learn what package.json is, how to create it, understand its important properties, install dependencies, configure scripts, and build a working Node.js example.

✦ What Is package.json in Node.js?

package.json is a JSON configuration file that describes a Node.js project. It contains information such as the project name, version, scripts, dependencies, and other configuration settings.

For example, when you install Express.js using npm, the package is normally recorded in the dependencies section of your project's package.json.

A typical Node.js project may have this structure:

my-node-project/
├── node_modules/
├── app.js
├── package.json
└── package-lock.json

Here:

• app.js contains your application code.

• package.json stores project configuration and dependency declarations.

• package-lock.json records the resolved dependency tree.

• node_modules/ contains installed packages.

✦ Why Is package.json Important?

The package.json file helps developers manage their applications in several ways.

❖ 1. Project Information

It stores details such as the project name, version, and description.

❖ 2. Dependency Management

It records the packages required by your application, such as Express.js or MySQL libraries.

❖ 3. npm Scripts

You can define commands for starting the application, running tests, or launching a development server.

❖ 4. Team Collaboration

Other developers can understand the project's configuration and install its dependencies.

❖ 5. Project Maintenance

It provides a central place to manage scripts, dependency declarations, and other project metadata.

✦ Step 1: Create a Node.js Project

First, make sure Node.js and npm are installed.

Open Command Prompt, PowerShell, or your terminal and check:

node -v
npm -v

Now create a project folder:

mkdir package-json-demo
cd package-json-demo

Initialize the project with npm:

npm init -y

This command creates a package.json file using default answers.

Your initial file will look similar to this:

{
  "name": "package-json-demo",
  "version": "1.0.0",
  "description": "",
  "main": "index.js",
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  "keywords": [],
  "author": "",
  "license": "ISC"
}

The exact generated fields may differ depending on your npm version and configuration.

You can edit this file using Visual Studio Code or another code editor.

✦ Step 2: Understand the Important Properties

Let's understand the commonly used properties in package.json.

❖ 1. name

The name property identifies your project or package.

"name": "package-json-demo"

Use a suitable name and follow npm's naming restrictions if you intend to publish the package.

❖ 2. version

The version property indicates the project's version.

"version": "1.0.0"

Many JavaScript projects use semantic versioning, commonly expressed as MAJOR.MINOR.PATCH.

For example, 1.2.3 represents major version 1, minor version 2, and patch version 3.

❖ 3. description

The description explains what your project does.

"description": "A beginner-friendly Node.js application"

This is useful for documenting a project and describing a package.

❖ 4. main

The main property traditionally identifies the entry point for a package when it is loaded through mechanisms that use this field.

"main": "app.js"

For a simple application, you can choose the filename that contains your main code. Note that main does not automatically start your application when you run npm start.

❖ 5. scripts

The scripts property defines reusable commands.

"scripts": {
  "start": "node app.js",
  "dev": "node --watch app.js"
}

You can execute the configured commands using npm:

npm start

For the development script, run:

npm run dev

The --watch option is available in modern Node.js versions and restarts the application when watched files change.

❖ 6. dependencies

The dependencies property lists packages required by the application at runtime.

"dependencies": {
  "express": "^5.1.0"
}

The version shown is an example. Your installed package version may differ.

❖ 7. devDependencies

The devDependencies property lists packages used during development, such as testing tools and code formatters.

"devDependencies": {
  "nodemon": "^3.1.0"
}

You can add a development dependency by running:

npm install --save-dev nodemon

❖ 8. keywords and author

These fields provide additional metadata.

"keywords": ["nodejs", "javascript", "backend"],
"author": "Param Classes"

They are optional for many private applications but can be useful when documenting or publishing packages.

✦ Step 3: Install Express.js and Update package.json

Let's create a small web application.

Inside your project directory, run:

npm install express

npm installs Express and updates the project's dependency information.

Your package.json will contain an entry similar to:

"dependencies": {
  "express": "^5.1.0"
}

The actual version depends on the package version installed.

Next, create a file named app.js:

const express = require('express');

const app = express();
const PORT = 3000;

app.get('/', (req, res) => {
    res.send('Welcome to Param Classes Node.js Tutorial!');
});

app.listen(PORT, () => {
    console.log(`Server running at http://localhost:${PORT}`);
});

This application creates a simple web server using Express.js.

✦ Step 4: Configure npm Scripts

You can configure scripts in package.json to avoid typing long commands repeatedly.

Update the scripts section:

"scripts": {
  "start": "node app.js"
}

Keep the other existing properties in your file. Only replace or add the relevant scripts section.

Now start the application:

npm start

You should see a message similar to:

Server running at http://localhost:3000

Open the URL in your browser. The page should display:

Welcome to Param Classes Node.js Tutorial!

This demonstrates how package.json connects npm commands with your application.

✦ Step 5: Understand package-lock.json

When npm installs packages, it usually creates or updates package-lock.json.

Although package.json declares dependency version ranges, the lockfile records the specific resolved versions and dependency tree used for the installation.

For example:

• package.json declares which packages your project needs.

• package-lock.json records the resolved dependency versions.

• node_modules/ contains the installed package files.

For an application, you should normally commit both package.json and package-lock.json to version control.

Other developers or deployment systems can then use:

npm ci

This command installs dependencies from the lockfile and is especially useful for automated builds.

✦ Step 6: Update and Remove Dependencies

You can manage project dependencies through npm commands.

Check for outdated packages:

npm outdated

Update packages within permitted version ranges:

npm update

Remove Express from the project:

npm uninstall express

When you remove a package, make sure your application no longer imports or relies on it. Otherwise, the application may stop working.

✦ Common Mistakes When Using package.json

❖ 1. Invalid JSON Syntax

JSON does not allow comments, and property names and string values must use double quotes.

Incorrect:

{
  name: 'my-project'
}

Correct:

{
  "name": "my-project"
}

❖ 2. Forgetting to Install Dependencies

If your project declares Express but its dependencies have not been installed, the application may show a module-not-found error.

Run:

npm install

❖ 3. Using the Wrong Script Command

If package.json does not define a start script, npm start may not behave as expected.

Add a suitable script before using the command.

❖ 4. Deleting the Lockfile Without a Reason

Deleting package-lock.json can cause npm to resolve different package versions during a later installation. Keep the lockfile unless you have a specific reason to regenerate it.

✦ Frequently Asked Questions (FAQs)

❖ 1. What is package.json in Node.js?

It is a JSON file that stores project metadata, scripts, dependencies, and other configuration information.

❖ 2. How do I create package.json?

Run npm init -y inside your project directory to generate a file with default values.

❖ 3. What is the difference between package.json and package-lock.json?

package.json declares project requirements and dependency ranges, while package-lock.json records the resolved dependency tree and versions.

❖ 4. What is the purpose of npm scripts?

Scripts allow you to run predefined commands using npm, such as npm start and npm run dev.

❖ 5. Do all Node.js projects need package.json?

Many Node.js projects use package.json to manage dependencies and configuration. It is particularly important for applications that use npm packages or project scripts.

❖ 6. Should package-lock.json be committed to Git?

For most applications, yes. Committing the lockfile helps teams and deployment systems install consistent dependency versions.

✦ Conclusion

The package.json file is an essential part of managing Node.js projects. It stores project information, tracks dependency declarations, defines npm scripts, and helps developers maintain their applications.

By learning how to create and configure this file, you can manage packages more effectively and prepare for advanced topics such as Express.js, REST APIs, database connections, and backend application development.

At Param Classes, learners can strengthen their development skills through practical programming tutorials and step-by-step examples.

Explore more programming resources at Param Classes and website development services at ParamWebInfo.