@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:

1. Create a .localpackages file in your project
2. Run local-linker
3. 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:

1. Reads your .localpackages file to find local dependencies
2. Detects your package manager (npm, yarn, or pnpm)
3. Builds each local package (if it has a build script)
4. Links the packages to your project using your package manager's link feature
5. 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:

1. Development: The local version is used during development (via local-linker)
2. Production: The published version is used in production builds
3. Collaboration: Team members without local copies can still run the project
4. 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)

Contributing

This project is written in TypeScript. To contribute:

1. Fork the repository
2. Install dependencies: npm install
3. Make your changes in the src directory
4. Build the project: npm run build
5. Test your changes
6. Submit a pull request

License

MIT