local-npm-registry

🚀 Supercharge your local development workflow! This CLI tool manages local npm package installations as if they were published, making it effortless to test changes across multiple projects without the hassle of publishing to npm or linking packages manually.

📦 Installation

Install as a dev dependency in both your library and consuming projects:

npm install -D @aneuhold/local-npm-registry
# or
pnpm add -D @aneuhold/local-npm-registry

🎯 Quick Start

1. Set up your library project for development

In your library project (the one you want to test changes from), set up a watch command using nodemon:

{
  "scripts": {
    "dev": "nodemon --ignore lib/ -e ts --exec \"npm run build && local-npm publish\""
  }
}

💡 Pro tip: You can pass any npm publish options to local-npm publish. For example, use local-npm publish --ignore-scripts if you want to skip pre/post-publish scripts.

Now when you run npm run dev, every time you save a TypeScript file, your library will rebuild and automatically update all consuming projects!

2. Subscribe your frontend project to the library

In your frontend/consuming project, first install the tool as a dev dependency, then add a convenient script:

{
  "scripts": {
    "sub:my-library": "local-npm subscribe @my-org/my-library",
    "unsub:my-library": "local-npm unsubscribe @my-org/my-library"
  }
}

Then subscribe to your library:

cd my-frontend-project
npm run sub:my-library

That's it! Your frontend project will now automatically receive updates whenever you make changes to your library.

🛠️ Core Commands

local-npm publish [npm-publish-options]

📤 Publishes your current package and automatically updates all projects that are subscribed to it.

• Creates a timestamped version (e.g., 1.2.3-20250528123456)
• Updates all subscriber projects with the new version
• Perfect for the watch command in your library
• Supports all npm publish options: Pass any npm publish options directly to the underlying npm publish command

# Basic publish
local-npm publish

# Publish without running scripts
local-npm publish --ignore-scripts

# Publish with verbose output for debugging
local-npm publish --verbose

local-npm subscribe <package-name>

🔔 Subscribe to a package to receive automatic updates when it's published locally.

• Adds your current project as a subscriber
• Installs the latest local version immediately
• Preserves publish arguments: Uses the same npm publish options that were used when the package was originally published
• Great for frontend projects consuming your libraries

local-npm unpublish [package-name]

🗑️ Removes a package from the local registry and resets all subscribers to original versions.

• Cleans up when you're done testing
• Resets all consuming projects back to their original package versions

local-npm unsubscribe [package-name]

🔕 Unsubscribe from packages and reset to original versions.

• Remove subscription from one package or all packages (if no name provided)
• Resets your project back to the original package versions

💡 Why Use This?

✅ No more npm link headaches - Works reliably across different package managers
✅ Automatic updates - Changes propagate instantly to all consuming projects
✅ Clean workflow - Easy to set up and tear down
✅ Version safety - Always keeps track of original versions to restore
✅ Multiple subscribers - One library can update many consuming projects at once
✅ True package installation behavior - Unlike local file paths, this tool installs packages the same way as remote registries, ensuring your local testing matches production behavior

🔧 Additional Commands

• local-npm list - See all packages in your local registry and their subscribers
• local-npm get-store - View the raw local package store data
• local-npm config - Show current configuration
• local-npm init-config - Create a configuration file
• local-npm clear-store - Reset everything and start fresh

⚙️ Configuration

The tool can be configured using a .local-npm-registry.json file. The configuration file is searched starting from the current working directory and traversing up the directory tree until found.

{
  "dataDirectory": "/path/to/data",
  "registryPort": 4873,
  "registryUrl": "http://localhost:4873",
  "verdaccioConfig": {}
}

local-npm init-config

📋 Technical Details

How It Works

This tool uses Verdaccio (a private npm registry) under the hood to simulate publishing packages locally. It maintains a JSON store that tracks package versions and subscriber relationships, ensuring clean workflows and easy cleanup.

Note: Verdaccio is only started for commands that need to publish packages (publish and subscribe). The unpublish and unsubscribe commands only modify package.json files and the local store, so they don't require Verdaccio to be running necessarily.

Why Not Use Local File Paths?

While npm supports local file paths as dependencies (e.g., "my-package": "file:../my-package"), this approach has significant limitations:

• Different installation behavior: Local paths don't install the package the same way as remote registries do
• Missing dependency resolution: The local package's own dependencies aren't automatically installed in the consuming project
• No build processes: Pre-publish scripts and build steps are often skipped
• Inconsistent testing: Your local testing environment differs from how the package will actually be consumed in production

This tool solves these issues by using a real npm registry (Verdaccio) locally, ensuring that packages are installed, built, and resolved exactly as they would be when published to the public npm registry.

Local JSON Store Structure

The local JSON store maintains the following structure:

{
  "packages": {
    "@aneuhold/core-ts-lib": {
      "originalVersion": "1.2.3",
      "currentVersion": "1.2.3-20250526123456",
      "subscribers": [
        {
          "subscriberPath": "/path/to/consumer-project-1",
          "originalSpecifier": "^1.2.3"
        },
        {
          "subscriberPath": "/path/to/consumer-project-2",
          "originalSpecifier": "~1.2.0"
        }
      ],
      "packageRootPath": "/path/to/core-ts-lib",
      "publishArgs": ["--ignore-scripts", "--verbose"]
    },
    "@aneuhold/be-ts-lib": {
      "originalVersion": "2.1.0",
      "currentVersion": "2.1.0-20250526134567",
      "subscribers": [
        {
          "subscriberPath": "/path/to/consumer-project-3",
          "originalSpecifier": "^2.1.0"
        }
      ],
      "packageRootPath": "/path/to/be-ts-lib"
    }
  }
}