@lume-io/local-linker NPM

@lume-io/local-linker

A magical tool for managing local package dependencies in Node.js projects. Built with TypeScript for reliability and maintainability.

The Problem

Working with local package dependencies in Node.js projects can be frustrating. Existing solutions like monorepos, Docker, or tools like yalc often require complex setup or multiple manual steps.

The Solution

Local Linker provides a simple, magical experience for managing local dependencies:

Create a .localpackages file in your project
Run local-linker
That's it! Your local packages are linked and ready to use

Installation

# Install globally
npm install -g @lume-io/local-linker

# Or use with npx
npx @lume-io/local-linker

Usage

1. Create a `.localpackages` file

Create a .localpackages file in your project root with the following format:

# Basic format
ui-library = ../path/to/ui-library

# With custom build command
api-client = /absolute/path/to/api-client [npm run build:dev]

# With custom watch patterns
utils = ../common/utils [watch:src/**/*.ts,test/**/*.ts]

# With both custom build and watch patterns
components = ../components [pnpm run compile] [watch:src/**/*.{ts,tsx}]

2. Run the tool

# Link all packages
local-linker

# Link and watch for changes
local-linker --watch

# Resolve dependencies and build packages in the correct order
local-linker --deps

# Watch with dependency resolution
local-linker --watch --deps

# Disable spinners for CI environments
local-linker --no-spinner

# Recursively link dependencies in nested packages
local-linker --recursive

# All options can be combined
local-linker --deps --recursive --watch

Features

Zero Configuration: Just create the .localpackages file and run the tool
Auto Package Manager Detection: Works with npm, yarn, or pnpm
Watch Mode: Automatically rebuilds and relinks when source files change
Build Support: Runs the package's build script before linking if available
Simple CLI: Just run local-linker to link everything (after installing @lume-io/local-linker)
Custom Build Commands: Specify custom build commands per package
Custom Watch Patterns: Define exactly which files to watch per package
Dependency Resolution: Build packages in the correct order based on their dependencies
Progress Spinners: Visual feedback during long operations
Recursive Dependency Linking: Automatically link dependencies in all linked packages
TypeScript Support: Built with TypeScript for better maintainability

How It Works

Local Linker:

Reads your .localpackages file to find local dependencies
Detects your package manager (npm, yarn, or pnpm)
Builds each local package (if it has a build script)
Links the packages to your project using your package manager's link feature
In watch mode, it monitors the packages for changes and automatically rebuilds/relinks

Benefits Over Existing Solutions

No complex configuration files
No need to manually run linking commands in multiple directories
No need to understand the intricacies of each package manager's linking system
Works seamlessly with existing projects without changing their structure
The watch mode eliminates the need to manually rebuild and relink after changes
Custom build commands allow for different build processes per package
Dependency resolution ensures packages are built in the correct order
Progress spinners provide clear visual feedback on what's happening

About lume-io

@lume-io/local-linker is part of the lume-io organization, focused on creating developer tools that simplify workflows and enhance productivity. Our goal is to build tools that feel magical - they just work without complex configuration or steep learning curves.

Best Practices

Managing Dependencies

When using local-linker, we recommend adding your local packages to both places:

// package.json
{
  "dependencies": {
    "ui-library": "^1.0.0"
  }
}

# .localpackages
ui-library = ../path/to/ui-library

This dual approach provides several benefits:

Development: The local version is used during development (via local-linker)
Production: The published version is used in production builds
Collaboration: Team members without local copies can still run the project
CI/CD: Build pipelines will use the published version automatically

This pattern creates a seamless workflow between development and production environments.

Advanced Configuration

You can configure additional options in your project's package.json:

{
  "localLinker": {
    "useSpinner": true,
    "resolveDependencies": true,
    "recursiveLinks": true
  }
}

Available Options

useSpinner: Enable or disable progress spinners (default: true)
resolveDependencies: Automatically resolve and order packages by their dependencies (default: false)
recursiveLinks: Automatically link dependencies in nested packages (default: false)