Develop NPM Packages Locally with Yalc: A Practical Guide

# Why Yalc instead of npm link

Many developers use npm link to avoid publishing while developing a library and its consumer app. npm link creates symbolic links, but those symlinks can break in real projects. Common symptoms include duplicate dependency instances or frameworks throwing "invalid hook" errors when working with UI libraries. Yalc takes a different approach: it acts as a tiny local npm registry. Instead of linking, it copies compiled files into a local store and installs them into consumers like a normal package.

# How Yalc works

Install Yalc globally with npm install -g yalc. In your library folder run yalc publish. That moves the package contents to a hidden local store (usually in your home directory) rather than publishing to the internet. In the consuming application run yalc add package-name. Yalc creates a.yalc folder in the project and updates package.json to point to a local file path so npm or yarn will install the package correctly.

# Commands you will use

• yalc publish: copy compiled output into Yalc's local store. It does not push to a remote registry.
• yalc add package-name: install the package into a consuming project and update package.json to reference the local copy.
• yalc push: compile the library, update Yalc's local store, and push changes directly into every application that currently uses that package. Useful for rapid iteration.

• yalc link package-name: inject files into node_modules without modifying package.json. Use this when you want to avoid changing package.json in the consumer.

# Workflow patterns

If you prefer tight control over when consumers receive new code, run yalc publish in the library and yalc update in each app that depends on it. If you are repeatedly editing the library and want near-instant updates, use yalc push so all consuming projects receive the compiled changes automatically.

# Working with monorepos and multiple packages

# Avoiding Git and CI disasters

yalc add modifies package.json to point at a local.yalc path. If you commit those changes, teammates or CI systems that don't have your local Yalc store will break. To prevent this, add.yalc and yalc.lock to.gitignore. If you need a temporary injection that doesn't change package.json, prefer yalc link which writes into node_modules only.

# When to use Yalc

# Final practical tips

Keep compiled output consistent before publishing to Yalc so consumers get the files they expect. Ignore Yalc artifacts in version control. When automating across multiple packages, run publishes sequentially to avoid collisions in the local store. These steps reduce noisy test publishes and speed up local development cycles.