Package.json File

Packages published to the registry must contain a package.json file.

A package.json file:

Required name and version fields

A package.json file must contain "name" and "version" fields. The "name" field contains your package’s name, and must be lowercase and one word, and may contain hyphens and underscores. The "version" field must be in the form x.x.x and follow the symantic versioning guideline.

{
	"name": "my-awesome-package",
	"version": "1.0.0"
}

author field

author field allows you to specify author's name and email address -

{
	"author": {
	  "name": "Fedor Indutny",
	  "email": "fedor@indutny.com"
	}
}

There are other information you can include which we will discuss later.

main field

The name of the file that will be loaded when your module is required by another application. The default name is index.js

{
	"main" : "index.js"
}

Creating package.json File

Create a new folder and cd to this directory. And then type the following command-

npm init

It will ask you for few basic information. Provide them. If you are not sure about the information right away you can skip them by pressing Enter key. You can always change them later.

If you don't want to go through the process of providing answers you can run the following command. The following command will generate package.json file with all the default values and information that can be extracted from the current directory.

npm init --yes

For example, let's say we have a package.json file with the default values which looks like the following -

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

Creating Main File

After creating package.json file, next we will create a file index.js. In package.json file there is a field called main, which tells what file will be loaded when our package is required by an application. So the main field points to a single js file which will be loaded when our application requires it. Create the file with the following content -

exports.printMsg = function() {
  console.log("This is a message from the demo package");
}

Publishing Package

As an npm user, you can create unscoped packages to use in your own projects and publish them to the npm public registry for others to use in theirs. Unscoped packages are always public and are referred to by the package name only:

package-name

You can only publish unscoped packages to the npm public registry. You cannot publish unscoped packages to an npm Enterprise registry.

To publish the package run the following -

npm publish

It will publish your package to the NPM registry.

Installing your Package

Now create another directory (say, test) outside of your package directory and cd to your directory then run the following command -

// Syntax --
npm install <YourPackageName>

// In our Case --
npm install demoforsantanu

It will install your package called demoforsantanu. You can see your package within node_modules directory which is within the test directory.

Using your Package

Within the test directory create another js file (say, main.js) which will require your package.

var demo = require("demoforsantanu");
demo.printMsg();

To test your file run node main.js on the command to see the output.

Readme File

To help others find your packages on npm and have a good experience using your code in their projects, we recommend including a README file in your package directory. Your README file may include directions for installing, configuring, and using the code in your package, as well as any other information a user may find helpful. The README file will be shown on the package page.

Currently your Readme page of the package is empty -

Now let's add a README file. An npm package README file must be in the root-level directory of the package.

Let's say your README file looks like this -

# Hey Shit Face !
Bullshit

The README file will only be updated on the package page when you publish a new version of your package. To update your README file:

npm version patch
npm publish

After successfully publishing your package your read me page of the package will be updated -

Updating and Publishing a Package

Updating a Package means updating its version and then publish it again.

To update your package as a patch release -

npm version patch
npm publish

In the first command we are updating the version. In this case we are incrementing the last number of the version which is called patch version.

After that the last command updates the previous version with the new one.

To change the minor version -

npm version minor

To change the major version -

npm version major

Publishing Scoped Public Packges

To share your code publicly in a user or Org namespace, you can publish public user-scoped or Org-scoped packages to the npm registry.

First run the following command to create package.json

npm init --scope@scopeName

Replace the scopeName with the desired scope name you want. The scopeName can either be your user username or Org name. After that go through the process of creating package.json file in the command prompt.

After that create a README.md file and main entry js file.

After you have created your package in your local, it is ready to be published. Now when you publish a scoped package, its visibility is private by default. To make it public run the following command -

npm publish --access public

Remember that everytime you make a change to the package and publish to the NPM registry, you must add --access public flag

Now when you want to install a scoped package you have to also mentioned the scopename before the package name. Here is the syntax -

npm install @scopeName/packageName

Now when you are requiring the package in your application, you must mention its scope name-

var demo = require("@scopeName/packageName");

How to Name your package?

When choosing a name for your package, choose a name that -

Downloading and Installing Packages

You can install a package locally if you want to depend on the package from your own module, using something like Node.js require. This is npm install’s default behavior.

Unscoped packages are always public, which means they can be searched for, downloaded, and installed by anyone. To install a public package, on the command line, run -

npm install packageName

This will create the node_modules directory in your current directory (if one doesn’t exist yet) and will download the package to that directory.

If there is no package.json file in the local directory, the latest version of the package is installed. If there is a package.json file, npm installs the latest version that satisfies the version rule declared in package.json.

Scoped public packages can be downloaded and installed by anyone, as long as the scope name is referenced during installation:

npm install @scopeName/packageName

Installing Flags

npm install packageName takes few flags -

Installing a Package Globally

Installing a package globally allows you to use the code in the package as a set of tools on your local computer. To download and install packages globally, on the command line, run the following command:

npm install -g packageName

Here -g stands for global.

Updating a Package

If you want to update all modules at once you can run -

npm update

This command first analyze the package.json file and check which modules are outdated. If it finds one, it updates it.

To update a single local package, run -

npm update packageName

To find out what modules are outdated, run -

// For local packages --
npm outdated


// For Global packages --
npm outdated -g --depth=0

It will give you all the packages which are outdated.

To update a global package, run -

npm update -g packageName

To update all the global packages at once -

npm update -g

How to use a Package

Once you have installed a package in node_modules, you can use it in your code.

Using require function you can require a package in your application.

For example, to use a lodash package, use -

var lodash = require('lodash');

var output = lodash.without([1, 2, 3], 1);
console.log(output);

To require a scoped package -

var projectName = require("@scope/packageName");

Uninstalling a Package

Uninstall a unscoped package -

npm uninstall packageName

// Example -
npm uninstall lodash

Uninstall a scoped package -

npm uninstall @scopeName/packageName

To uninstall a global package, run -

npm uninstall -g packageName
npm uninstall -g @scopeName/packageName

In older version of NPM, you will find some flag added in npm uninstall command. Like --save, --save-dev etc. These commands are not required in newer version of NPM as they both behaves same. Actually these flags are used to clean up package.json file accordingly. But in newer version, the package.json file is updated whenever you run npm uninstall.

Listing Packages

To know your all kind of dependencies you can run -

npm ls

It will list all the packages that your applications depends on.