Stabilize Your npm Packages with ncc: Avoid Dependency Nightmares

Background

Whether you are doing front‑end development or Node development, many developers have already started reusing code by extracting npm packages. After extracting or using these packages, you may encounter problems like the following.

Example 1:

Project A depends on a utility package, which in turn depends on module xxx. One day xxx releases a new version that contains a bug. After cloning the code, deleting package‑lock.json, and reinstalling dependencies, the project behaves unexpectedly.

A project (unchanged)
    utility package (unchanged)
        xxx package (new buggy version)

Without a package‑lock.json, reinstalling can cause the whole project to break, forcing you to file an issue with the xxx package for a fix.

Example 2:

Using Lerna to manage a monorepo with multiple packages, after publishing we encounter a problem that requires a full rollback.

A (new ^1.2.0)
B (new ^1.2.0)
C (new ^1.2.0)

After the issue, we must revert all packages:

A (reverted to ^1.1.0)
B (reverted to ^1.1.0)
C (reverted to ^1.1.0)

If package A pins version 1.1.0, its dependency B (also ^1.1.0) may still be installed as 1.2.0, causing further errors.

Solution

To shield your project from uncertain third‑party changes, ensure your own code is protected by unit tests and other processes. The formula is:

[Certain self + [Uncertain third‑party]] = [versioned package]

[Versioned package] = Stability

The proposed solution is to use ncc, a Node CLI tool that can also be used as an API to compile a Node program into a single JavaScript file.

By bundling our npm package with ncc, we produce one JS file. The published npm package no longer needs to list its dependencies in package.json, so installing the package does not trigger installation of those dependencies.

Benefits of this approach:

All dependency code is fixed at the time of publishing, so later releases of those dependencies do not affect your package.

Installation speed improves because instead of pulling dozens or hundreds of packages, only one file is installed.

Disk usage drops dramatically; a node_modules folder that once occupied 50 MB may shrink to under 1 MB.

Startup time speeds up since the runtime no longer needs to resolve many require calls.

Related Questions

1. How does ncc differ from pkg?

ncc generates a JavaScript file (text) that still requires Node to run (e.g., node xxx.js), whereas pkg produces a binary executable that includes its own runtime, allowing it to run on a host without Node installed. Both have overlapping use cases but serve different scenarios.