Knowing the meaning of Tilde(~) and Caret(^) symbols, understanding the purpose of semantic versioning of Node packages, and knowing the difference between npm i and npm ci commands will help to efficiently manage dependencies in a Node project or any Node.js-based frontend application.

Let’s Begin

1. What is package.json?

All Node-based projects, npm packages — contain a package.json file usually in the root directory. This file is simply a JSON file containing the project's metadata. This metadata includes — name, homepage, keywords, dependencies, etc properties. To know more about the package.json file you can check its official documentation at this link: https://docs.npmjs.com/cli/v8/configuring-npm/package-json

2. What is Semantic Versioning?

The version number of npm packages has a specific format. The format is- MAJOR.MINOR.PATCH. According to the official documentation of semantic versioning (https://semver.org/) —

1. MAJOR version updates when any incompatible API changes happened

2. MINOR version updates when new functionality in a backward-compatible manner added

3. PATCH version updates when bug fixes in a backward-compatible manner

Another point to note is that when the MAJOR version updates it resets the MINOR and PATCH version numbers and when the MINOR version updates it resets the PATCH version number.

3. Meaning of Tilde(~) and Caret(^) Symbol

In the package.json file, there is a property called dependencies — it contains the name and the version number of different libraries (aka dependencies) used in the project. But before the version number, there may have a special symbol Tilde(~) or Caret(^), which controls the library version to install into the project. When using npm i to install project dependencies then the significance of these two symbols easily be understandable. In short, Caret(^) symbol tells the npm i command to install the latest MINOR update whereas Tilde(~) symbol tells the npm i command to install the library only till the latest PATCH update.

4. Node.js Project Example

Let's understand how Tilde(~) and Caret(^) symbol differs when using the npm i (or npm install) and the npm ci command to install dependencies into your project by taking an example.

We are going to create a simple node.js project.

Step 1: Initialize a Project

Create a folder named NODE-PROJECT-EXAMPLE (or give a name as you wish!) and run the command npm init --y into the folder to initiate a node project. Open the folder in VSCode (or any of your favorite IDE). Your NODE-PROJECT-EXAMPLE will look like this —

Image 2: Project Initiation

Step 2: Install Dependency

Install a library — history (or you can install any other library for this test) into the NODE-PROJECT-EXAMPLE. For this, run the command npm install history. This command will install the latest version of the history library and a node_modules folder, a package-lock.json file will be created in the root directory of the NODE-PROJECT-EXAMPLE, and the dependency property added to the package.json file.

Image 2: Library/Dependency Installation

Your package.json will contain dependencies property with dependency name and version. The file will look like this —

Step 3: Update Dependency Version

Till now this project contains the latest version of the history library. But for some reason, your project needs history version 5.0.0. So you downgrade the history version to 5.0.0. For this, you need to update the version number of the history library in the package.json file (write the exact version number without any ~ or ^ symbol), and remove the package-lock.json file and the node_modules folder. Now run the command npm install again and output like the below image -

Image 3: Downgrading Dependency

You can check the installed library version from the terminal by using the command npm list and you will get output like the below -

Image 4: List of Installed Dependency

So, our target is to install the exact 5.0.0 version of history is completed.

Step 4: Use of Tilde(~) and Caret(^) Symbol

Now this project will contain the history version exactly 5.0.0 as we are not adding the ~ or ^ symbol in front of the version number in the package.json file. So, the history library is never going to be updated according to the latest release in its npm repository. We will miss any bug-fix-related updates or new functionality-related updates made by the developers of the history library.

So, we will add Caret(^) sign in front of the version number to allow installing the latest MINOR with its latest PATCH update. Or, we will add Tilde(~) sign in front of the version number to allow installing only the latest PATCH update.

For example, ^5.0.0 version number allows to install 5.3.0 version (while writing this blog this is the latest minor update) and ~5.0.0 version number allows to install 5.0.3 (while writing this blog this is the latest patch update)

Please remember that every time you add/overwrite the version number in the package.json file remove the package-lock.json file and the node_modules folder before running the command npm i.

Hope it is clear to you how you can manage the different dependency versions in your project by the smart use of the Tilde(~) and the Caret(^) sign.

5. Use case of npm i and npm ci

npm i or npm install — this command installs the latest or updated dependencies depending on Tilde(~) or Caret(~) symbol in the package.json file and overwrites the package-lock.json file and the node-modules folder.

npm ci — this command installs the exact version of the dependencies mentioned in the package.json and package-lock.json file. This command doesn't care about Tilde(~) or Caret(~) symbol in the package.json file. This command requires the existence of the package-lock.json file in the project.

So, before using any of these two commands we need to decide on whether we want the latest updates of dependencies to be installed in the project or install only mentioned version in the project — if the first case is our decision then we must run npm i command else for the second case we must run npm ci command.

Happy Coding!

Hope this story will help you to clarify all the confusion regarding package.json, npm i vs npm ci command, and Tilde(~) vs Caret(~) symbol.

Bit: Build Better UI Component Libraries

Say hey to Bit. It’s the #1 tool for component-driven app development.

With Bit, you can create any part of your app as a “component” that’s composable and reusable. You and your team can share a toolbox of components to build more apps faster and consistently together.

• Create and compose “app building blocks”: UI elements, full features, pages, applications, serverless, or micro-services. With any JS stack.
• Easily share, and reuse components as a team.
• Quickly update components across projects.
• Make hard things simple: Monorepos, design systems & micro-frontends.

Try Bit open-source and free→