@andyrmitchell/pm-link-auto

Are you consuming unpublished packages in your project?

It's probably a pain to maintain the dependencies across multiple team members or devices.

This solves it with with a single config file of just the package names you need.

• ✅ Declarative Single Source of Truth: Define all local dependencies in a configuration file.
• ✅ Auto-Discovery: If the package path is wrong or missing, the tool can search a root directory to find it.
• ✅ Conflict-Free: It symlinks the packages rather than adding their paths directly to package.json, avoiding conflicting developer's paths

How it Works

• You define the package names you need in pm-link-auto.config.ts. Treat it like dependencies in package.json and commit it to Git.
• It searches all packages.json on your machine for name matches, and uses their local paths
• It creates a directory in your project for holding the symlinks to the found packages' paths
• It adds that directory the workspaces of your package.json
• When you run npm i, npm automatically resolves package-paths in workspaces and integrates them into your project (as if you'd run npm i <package> or npm link <package>)

Installation

Install the tool as a development dependency in your project.

npm install -D @andyrmitchell/pm-link-auto

To create the config file automatically, run...

npm pm-link-auto

Usage

1. Create a configuration file in your project's root directory named pm-link-auto.config.ts. Using TypeScript gives you the best editor support and type safety.

   // pm-link-auto.config.ts
   
   import type { LinkerConfig } from '@andyrmitchell/pm-link-auto';
   
   const config: LinkerConfig = {
     // This is where the local packages will be symlinked from.
     // This directory will be added to your Git repo, and to your package.json workspaces.
     // But its **contents** will be added to .gitignore 
     // Do not add anything else to it, as it's cleared every time it runs.
     packageSymlinkDirectory: "./pm-link-auto-packages",
         
     // Optional: The root directory to search for packages if a path is missing.
     // Supports `~` for home directory. Defaults to your home directory.
     packageSearchRoot: '~/dev/projects',
   
         
   
     // A list of packages you need to link.
     packages: [
       {
         name: '@my-scope/shared-ui',
         // Optional: The tool will try to discover the path if you omit it.
         // Path is relative to this config file.
         path: '../../shared-ui',
       },
       {
         name: '@my-scope/auth-library',
         // Path is missing, so the tool will search for it in `packageSearchRoot`.
       },
     ],
   };
   
   export default config;

   (Note: You can also use a .js file if you prefer.)

2. Run the linker:

   npx pm-link-auto

   The tool will validate the paths, ask for permission to find any missing ones, update the config file, and perform the symlinks.

3. Run npm install

   npm i

   This will install the new packages added to your package.json workspaces

4. (Recommended) Add to preinstall

   To make this fully automatic, add it to your package.json scripts. This way, links are refreshed before every npm install.

   "scripts": {
     "preinstall": "pm-link-auto"
   }

License

MIT