cute-npm-link v0.9.0

cute-npm-link

A small utility library to link package dependencies from your local file system to your Node.js project as if they were regular dependencies.

Features

• Develop npm packages locally and see the results in other local projects
• No monorepos
• No symlinks
• No file: protocol schemas in package.json
• Doesn't break node resolution like symlinks
• Works with any bundler
• Links only the files that npm would actually publish

Why

Because npm link doesn't work.

Getting Started

cute-npm-link can be used either as a local or a global utility depending on your workflow.

Installation

Install cute-npm-link.

npm install -g cute-npm-link

Option 1: Local configuration

1. Create a cute-npm-link.config.cjs file in your project root directory

   This config matches your dependency names to paths on your local system.

   Here's an example of what it might look like:

   module.exports = {
     manifest: {
       "my-dependency": "/my-dependency/path",
       "another-dependency": "../another-dependency",
     },
   };

   This will tell cute-npm-link to watch the specified directories for changes, and when they change, cute-npm-link will copy the whole folders to the node_modules folder of your project.

2. Run cute-npm-link command in your project root directory.

   cute-npm-link

Option 2: Global configuration

Choose this approach if you do not want to alter your project repository in any way or when you're managing multiple projects and want a global configuration for cute-npm-link.

1. Create a cute-npm-link.config.cjs file outside your project directory. You can place this anywhere you like.

   Here's an example cute-npm-link.config.cjs:

   module.exports = {
     manifest: {
       "global-dependency": "/global-dependency/path",
       "another-global-dependency": "/another-global-dependency/path",
     },
   };

2. From the root of your project run cute-npm-link command, specifying the path to your config file.

   cute-npm-link /path/to/your/global/config

   All the dependencies listed in your config file will be linked to your project.

Note

cute-npm-link will only watch packages listed in the manifest that are also found in the "dependencies" (or "devDependencies") of your project. (this note might be incorrect)

Motivation and Workflow

Let's imagine you're working on a project, we'll call it Project A. Project A has a dependency on a package, let's call it x-package.

Now, x-package is a package you're developing locally in another directory.

Normally, you'd have to publish x-package to the npm registry every time you make a change, then pull/update in Project A to get those changes. This can be a time-consuming process, especially when you're actively developing x-package and need to test changes in Project A frequently.

With cute-npm-link, you can drastically simplify this workflow. Here's how:

1. Set up your cute-npm-link.config.cjs: In your Project A directory, you set up a cute-npm-link.config.cjs with the following content:

   module.exports = {
     manifest: {
       "x-package": "/path/to/x-package",
       // ...other local packages you're developing
     },
   };

2. Run cute-npm-link: Run cute-npm-link in your Project A directory.

   cute-npm-link

3. Start Developing: Now, whenever you make changes to x-package in its local directory, cute-npm-link will automatically copy those changes to the node_modules folder of Project A. There's no need to manually update or reinstall the package. cute-npm-link takes care of copying only the files that npm would publish(would publish).

Why use cute-npm-link instead of npm link?

The npm link command allows you to use a package from your local file system in your project by creating a symbolic link in your node_modules folder. While this is a very handy feature, it has a couple of major downsides.

First, it can break Node.js module resolution algorithm where you end up with duplicate versions of dependencies. If your project has a dependency on React, and you symlink another module which also has a dependency on React, you might end up with two copies of React in your build. See more details by author of the Parcel Bundler

Second, some bundlers simply fail to watch changes in symlinked modules. Bundlers already do a lot of work that impacts perfomance and watching symlinked folders can impact the build times for your project significantly.

With cute-npm-link, you can develop and test your local packages within your project as if they were regular dependencies, without worrying about the issues that come with symbolic links.

History

cute-npm-link started as a fork of physical-link. Addressing issues and complexities.