
Let's talk about version numbers in your `package.json`. You've probably seen versions like `1.2.3` or `^4.5.0`—but what
do they *actually* mean?

<Image src="semver.jpg" alt="but it works on *my* machine  joke" />

---

## **SemVer: The Three-Number System That Keeps Everyone Sane**

Semantic Versioning (SemVer) is just a fancy way of saying:  
**"Hey, let's use version numbers to tell people what *kind* of changes we made."**

Versions look like `x.y.z`:

- **Major (x)**: Big changes that might break your code. *Example:* Removing a feature your app relies on.
- **Minor (y)**: New stuff that won't wreck existing code. *Example:* Adding a cool new function.
- **Patch (z)**: Quiet fixes for bugs or security holes. *Example:* Fixing a crash when you type `null`.

Think of it like home renovations:

- **Major** = Tearing down a wall (big impact).
- **Minor** = Adding a new room (no harm done).
- **Patch** = Fixing a leaky faucet (everyone's happy).

---

## **Why Should You Care?**

Because npm uses these numbers to decide which updates are safe to install automatically. If everyone follows SemVer,
your app won't suddenly break when you run `npm update`.

---

## **The Secret Symbols in Your package.json**

Those weird characters like `^` and `~` in your dependencies? They're just rules for npm. Here's what they *really*
mean:

- **`^1.2.3`** = "New features and fixes are okay, but don't change anything big!"  
  *(Updates to 1.3.0 or 1.2.4 are fine. Won't jump to 2.0.0.)*

- **`~1.2.3`** = "Only tiny fixes, please."  
  *(Updates to 1.2.4 are okay. Won't go to 1.3.0.)*

- **`>` or `>=`** = "Give me anything newer than this."
- **`<` or `<=`** = "Nothing newer than this, thanks."
- **`1.2.3` - `1.5.0`** = "I'll take any version between these two."
- **`||`** = "Either version A *or* version B works."

**No symbol?** Example: `"lodash": "4.17.21"` means *"Only this exact version. Don't change a thing!"*

### **Watch Out for 0.x.x Versions**

The caret `^` behaves differently for versions below `1.0.0`:

- **`^0.2.3`** → allows only `0.2.x` (treats minor as major)
- **`^0.0.3`** → allows only `0.0.3` (most restrictive)

This is because pre-1.0 packages are considered unstable, so npm plays it safe.

---

## **But Wait... What About the Lock File?**

Great question! If you've ever wondered *"Why do I need `^` or `~` when `package-lock.json` already pins exact
versions?"*—you're not alone.

Here's the deal: **they serve different purposes**.

|                     | Lock File                      | Symbols (`^`, `~`)          |
|---------------------|--------------------------------|-----------------------------|
| **When it matters** | `npm install`                  | `npm update`                |
| **What it does**    | Freezes "what's installed now" | Defines "update boundaries" |
| **Purpose**         | Reproducibility                | Flexibility                 |

### **When Symbols Actually Matter**

**1. First install (no lock file yet)**

When you run `npm add react` on a fresh project, npm checks the registry for the latest version and writes:

- `package.json`: `"react": "^19.2.1"` (with caret by default)
- `package-lock.json`: `react: 19.2.1` (exact version)

**2. Running `npm update`**

This is where symbols shine:

| In package.json      | What happens on `npm update` |
|----------------------|------------------------------|
| `"react": "19.2.1"`  | ❌ Nothing changes            |
| `"react": "~19.2.1"` | Updates to latest `19.2.x`   |
| `"react": "^19.2.1"` | Updates to latest `19.x.x`   |

**3. Publishing a library**

If you're building an npm package, your lock file is **ignored** by consumers. They only see your `package.json` ranges.
This is why choosing the right symbols matters for library authors.

### **Think of It This Way**

- **Symbols** = the rules for *future* updates
- **Lock file** = a snapshot of *current* state

They work together: symbols say "what's allowed," the lock file says "what's installed." 🤝

---

## **Real-World Tips for Humans**

1. **Start with `^`** for most dependencies. It's the safest way to get bug fixes and new features without surprises.
2. **Use exact versions** for critical packages (like React or Vue) where unexpected changes could ruin your day.
3. **Check `npm outdated` weekly** to see which packages have updates. It's like a to-do list for your app's health.
4. **Commit `package-lock.json`** to avoid "but it works on *my* machine" moments. This file locks down every tiny
   detail.

<Image src="ops.jpg" alt="but it works on *my* machine  joke" />

## **When Things Go Sideways**

- **Broke after an update?** Check if a major version sneaked in. Temporarily pin the version <br/>`"package": "1.2.3"`
  until you fix things.
- **Confused by symbols?** Use [semver.org](https://semver.org/) to understand semantic versioning rules.

---

## **Quick Cheat Sheet**

| Symbol   | What It Means                             |  
|----------|-------------------------------------------|  
| `^1.2.3` | "Keep me up to date, but no big changes!" |  
| `~1.2.3` | "Only bug fixes, please."                 |  
| `1.2.x`  | "Any patch version for 1.2."              |  
| `1.2.3`  | "Only this exact version."                |

---

## **Wrapping Up**

SemVer isn't about memorizing rules—it's about communicating changes clearly. Use `^` for flexibility, `~` for caution,
and exact versions when stability matters. <br/>And always, *always* check your `package-lock.json` into Git.

**Try this now:**

```bash  
npm outdated  
```  

See what updates are waiting? Update one with `npm update package-name` and see if your app still works. You've got
this! 🛠️

---  

*P.S. Sharing is caring. Forward this to a teammate who still edits `package.json` versions by hand. 😉*

## Related Articles

- [Migrate to pnpm](/blog/pnpm) - faster package management with better disk efficiency
- [Conventional Commits](/blog/conventional-commits) - structured commit messages for automated versioning


A friendly, practical guide to SemVer in npm. Learn versioning rules, avoid dependency chaos, and manage updates with confidence.

Mastering npm and Semantic Versioning for Smarter Development


## Introduction

<Image src="pnpm-logo.png" alt="pnpm logo on gay background" />

I found article from Vercel
about [Projects using pnpm can now be deployed with zero configuration](https://vercel.com/changelog/projects-using-pnpm-can-now-be-deployed-with-zero-configuration)
and I wanted to try it.

## Why Migrate to pnpm?

Before diving into the migration process, it’s important to understand why pnpm is beneficial:

1. **Speed** 🚀: pnpm installs dependencies faster than npm by using a unique package linking mechanism.
2. **Disk Space** 🔎: It saves disk space by using a global store and hard links.
3. **Consistency** 💡: pnpm ensures that dependencies are installed in a way that is more consistent with the version
   specified in your `package.json`.

## Installation of pnpm

First, you need to install pnpm globally. Make sure you have the right Node.js version installed — if you manage multiple versions, [NVM](/blog/nvm) makes switching between them effortless. Then run:

```bash
brew install pnpm
```

## Migration Steps

### 1. Clean the Project

Remove the `node_modules` directory and the `package-lock.json` file. This step is crucial to ensure that there are no
leftover artifacts from npm that might interfere with pnpm.

```bash
rm -rf node_modules package-lock.json
```

### 2. Initialize pnpm

Run the following command to initialize pnpm in your project directory:

```bash
pnpm install
```

This command will create a `pnpm-lock.yaml` file and install all the dependencies listed in your `package.json`.
Understanding [how semantic versioning works in npm](/blog/npm-semantic-versioning) will help you predict exactly what gets installed.

### 3. Verify Dependency Installation

Check that all dependencies have been installed correctly by running:

```bash
pnpm list
```

This command lists all the installed dependencies and their versions. Make sure that there are no missing or outdated
packages.

<Image src="pnpm-list.png" alt="pnpm list command result in terminal" />

## Updating Scripts

### 1. Update npm Scripts

In your `package.json`, update any npm scripts to use pnpm where necessary. For example, if you have a script for
installing dependencies, change it from:

```json
"scripts": {
"install": "npm install"
}
```

to:

```json
"scripts": {
"install": "pnpm install"
}
```

### 2. Update CI/CD Pipelines

If your project uses CI/CD pipelines, ensure that the build scripts and installation commands are updated to use pnpm.
For example, in a [GitHub Actions  with pnpm](https://pnpm.io/continuous-integration) workflow, you might update the
step as follows:

```yaml
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: pnpm/action-setup@v4
        with:
          version: 9
      - uses: actions/setup-node@v4
        with:
          node-version: ${{ matrix.node-version }}
          cache: 'pnpm'
      - name: Install
        run: pnpm i
      - name: Run Tests // All your CI commands
        run: pnpm run test
```

## Handling Issues and Troubleshooting

During the migration, you might encounter some issues.

> Error: Unable to locate executable file: pnpm. Please verify either the file path exists or the file can be found
> within a directory specified by the PATH environment variable. Also check the file mode to verify the file is
> executable.

I stuck with this error when I tried to run the `pnpm` command in GitHub Actions.

The solution was to use the `pnpm/action-setup@v4` before `actions/setup-node@v4`.
So simply just copy the [above code](#2-update-cicd-pipelines) and paste it in your `.yml` file.

## Conclusion

This migration helped me to reduce the time of deployment by **44%** and the size of `node_modules` by **5%**.

<Image src="vercel-deployment.png" alt="Deployment time on vercel dashboard. Around 1 seccond" />

More info how my blog works you can find there [How my site works under the hood](/blog/introducing-the-new-shramko.dev)


Migrate from npm to pnpm and cut your deployment time by 44%. Step-by-step guide covering installation, lockfile conversion, and CI/CD configuration.

Migrate from npm to pnpm – Save Time with This Guide


<Image src="node-post.jpg" alt="Laptop with cone on screen with bloored background" />

[NVM](https://github.com/nvm-sh/nvm), or Node Version Manager, is essential for managing multiple versions of Node.js on
our development environment.
[Node.js](https://nodejs.org/en) is a JavaScript-based web technology, that allows developers to write server-side code
using JavaScript.

By using NVM to manage different versions with ease, developers can keep their environment up-to-date with the best
tools and achieve their desired results with ease.

In this article, we’ll be looking at how to install NVM with Brew and verify it worked properly. Additionally, we’ll
take a look at why we need NVM, a useful NVM cheatsheet, and how to install NVM on Windows, Linux, and MacOS.

## What is NVM?

Simply put, it is a software that allows you to install and manage different versions of Node.js on your system. You can
also switch easily between them, making it ideal for keeping your development environment updated.

## Why Do We Need NVM?

NVM is essential for managing multiple versions of Node.js on our systems. By using NVM to manage and switch between
different versions, we can make sure our environment is always up-to-date with the latest version. This allows us to
take advantage of the newest tools available in the Node.js ecosystem.

Additionally, NVM helps us become more efficient as developers. With NVM, we can quickly switch between different
versions of Node.js without having to reconfigure our environment and restart our terminal.

## How to Install NVM with Brew

Installing NVM with [Brew](https://brew.sh/) is a fairly straightforward process.

First, you’ll need to install Brew, which you can do simply by entering this on your terminal:

```shell
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
```

Once Brew is installed, you can install NVM by entering `brew install nvm` on your terminal.
This command will download the latest version of NVM for your system, including the necessary libraries and packages.

```shell
brew install nvm
```

### Verify It Worked

Once you’ve installed NVM with Brew, you can verify that it worked by entering `nvm —-v` on your terminal. This command
will show you the version of NVM you’re currently running.

```shell
nvm —-v

#Node Version Manager (v0.39.3) // It's my version of NVM
```

## NVM Cheatsheet

Using NVM can be intimidating at first. To help, here’s a helpful NVM cheatsheet:

```shell
- nvm install 8.0.0                     #Install a specific version number
- nvm use 8.0                           #Use the latest available 8.0.x release
- nvm run 6.10.3 app.js                 #Run app.js using node 6.10.3
- nvm exec 4.8.3 node app.js            #Run `node app.js` with the PATH pointing to node 4.8.3
- nvm alias default 8.1.0               #Set default node version on a shell
- nvm alias default node                #Always default to the latest available node version on a shell
- nvm uninstall [<version>]             #This command will uninstall a specific version of Node.js

- nvm install node                      #Install the latest available version
- nvm use node                          #Use the latest version
- nvm install --lts                     #Install the latest LTS version
- nvm use --lts                         #Use the latest LTS version
```

## How to Install NVM on Windows

Installing NVM on Windows is slightly more involved than with Linux or macOS. To do so, you’ll need to have the [Windows
Subsystem for Linux](https://learn.microsoft.com/en-us/windows/wsl/install) (WSL) installed. Once you have WSL
installed, you can use Brew to install NVM just as you would with Linux or macOS.

## How to Install NVM on Linux

The easiest way to install NVM on Linux is to use Brew. Simply open your terminal and then enter `brew install nvm`.

Before it install Brew 🍻

## Recap

Hopefully this article has helped you get a better understanding of NVM and how to install it on a variety of systems.
Installing and managing multiple versions of Node.js is essential for staying up-to-date with the best tools and
achieving better results.

With NVM, you’ll be able to easily switch between different versions and keep your development
environment updated.

## Further reading

- [pnpm — Fast, Disk Space Efficient Package Manager](/blog/pnpm) — a modern package manager that pairs well with NVM for Node.js projects
- [How to Create SSH Keys](/blog/how-to-create-ssh-keys) — another essential developer environment setup step


Learn how to install and use Node Version Manager (NVM) to switch between Node.js versions effortlessly. Manage multiple Node versions for different projects.

Node Version Manager (NVM): Install and Switch Versions


<Image src="es-module.png" alt="ES modules structure diagram" priority={true} />

## Problem

I ran into this error when using ```__dirname``` in an ES module.

```__dirname``` is an environment variable that tells you the absolute path of the directory containing the currently
executing file, and many Node.js projects use this.

But if you use it inside an ES module, you can't use it because of the infamous "__dirname is not defined in ES module
scope" an error appears.

## Solution

What can you do in this case?

To get the current file directory, we'll want to use a combination of a global variable and a few built-in methods:

- `import.meta.url` to get the current file's as a URL
- `url.fileURLToPath` to change the URL to a path
- `path.dirname` to get the directory name

Using these methods, we can reconstruct the global `__dirname` and `__filename` variables:

```js
import path from 'path';
import { fileURLToPath } from 'url';

const __filename = fileURLToPath(import.meta.url);

const __dirname = path.dirname(__filename);
```

Now you can use `__dirname` as usual:

```js
console.log(__dirname)
```

## Conclusion

Due to the different approaches to modularity in Node.js and EcmaScript, you may encounter such problems.

If you are working with file paths, you may also find it useful to know [how to check if a file exists in Node.js](/snippets/how-to-check-if-file-exists-node).

For further reading, check out
the [Node.js documentation for __dirname](https://nodejs.org/docs/latest/api/modules.html#modules_dirname).


Fix the "__dirname is not defined in ES module scope" error in Node.js. Recreate __dirname and __filename using import.meta.url.

Fix “__dirname Not Defined” in ES Modules – Quick Guide

Build scalable backend apps with Node.js. Explore modules, async programming, package management, and server-side best practices.

Node4 articles

Articles

Semantic Versioning in npm

How to decrease deployment time by 44% with pnpm

Node Version Manager

How to fix "__dirname is not defined in ES module scope"