@unlimitechcloud/devlink

A modern package management utility for npm projects and monorepos. Manage local library development with a namespace-isolated store, environment-based install modes for local and published registry workflows, and declarative configuration.

Why DevLink?

When developing multiple packages locally, you need a way to test changes across projects without publishing to npm. DevLink provides:

• Namespace isolation - Different projects can use different versions or variants of the same package without conflicts
• Multi-version support - Test multiple versions of the same package simultaneously across different projects
• Automatic consumer updates - Push changes to all dependent projects with one command
• Declarative configuration - Define dependencies in a config file, not CLI flags
• npm fallback - Packages not found in the local store automatically fall back to npm, and vice versa — bidirectional per-package fallback with clear warnings
• Synthetic packages - Stage packages to .devlink/ for tooling and build-time use without polluting package.json

Installation

# Global installation (recommended)
npm install -g @unlimitechcloud/devlink

# Or use with npx
npx @unlimitechcloud/devlink <command>

Quick Start

1. Publish Your Library

cd my-library
dev-link publish

This copies your package to the DevLink store (~/.devlink/namespaces/global/).

2. Configure Your Consumer Project

Create devlink.config.mjs in your project root:

export default {
  packages: {
    "@myorg/my-library": { version: { dev: "1.0.0" } },
    "@myorg/utils": { version: "2.0.0" },
  },
  dev: () => ({
    manager: "store",
    namespaces: ["global"],
  }),
};

3. Install from Store

cd my-project
dev-link install --mode dev

DevLink copies the packages from the store to your node_modules.

4. Push Updates

After making changes to your library:

cd my-library
dev-link push

This publishes the new version AND automatically updates all consumer projects.

Commands Reference

| Command | Description | Common Options | |---------|-------------|----------------| | publish | Publish package to the store | -n, --namespace | | push | Publish and update all consumers | -n, --namespace | | install | Install packages from store/registry | -m, --mode, --npm-ignore-scripts, --recursive | | list | List packages in store | -n, -p, --flat | | resolve | Debug package resolution | -n, --namespaces | | consumers | List/manage consumer projects | --prune | | remove | Remove packages or namespaces | -n, --namespace | | verify | Check store integrity | --fix | | prune | Remove orphaned packages | --dry-run | | tree | Display monorepo structure | --json, --depth | | docs | Display embedded documentation | <topic> |

Command Details

dev-link publish

Publishes the current package to the DevLink store.

dev-link publish                    # Publish to global namespace
dev-link publish -n feature-v2      # Publish to feature-v2 namespace
dev-link publish --repo ~/custom    # Use custom store location

dev-link push

Publishes and automatically updates all consumer projects that use this package.

dev-link push                       # Publish and update consumers
dev-link push -n feature-v2         # Push to specific namespace

dev-link install

Installs packages from the store or registry based on your devlink.config.mjs. Resolution uses bidirectional fallback: store-primary flows fall back to npm, and npm-primary flows fall back to the store — per-package, with clear warnings. When no mode is specified, universal packages are resolved with npm as primary and store (global) as fallback.

dev-link install                        # Universal packages + npm install
dev-link install --mode dev             # Dev mode (store primary)
dev-link install --mode remote          # Remote mode (registry resolution)
dev-link install @scope/core --mode dev # Selective install (specific packages only)
dev-link install -n feature,global      # Override namespace precedence
dev-link install --recursive            # Recursive install across monorepo
dev-link install --npm-ignore-scripts   # Skip npm lifecycle scripts

dev-link list

Lists all packages in the store.

dev-link list                       # Tree view by namespace
dev-link list --flat                # Flat output (for scripting)
dev-link list -n global             # Filter by namespace
dev-link list -p @myorg             # Filter by scope
dev-link list -p @myorg/core        # Filter by package

dev-link resolve

Shows how packages would be resolved given namespace precedence.

dev-link resolve @myorg/[email protected]
dev-link resolve @myorg/[email protected] -n feature,global

dev-link consumers

Lists projects that have installed packages from the store.

dev-link consumers                  # List all consumers
dev-link consumers -p @myorg/core   # Filter by package
dev-link consumers --prune          # Remove dead projects

dev-link remove

Removes packages, versions, or entire namespaces.

dev-link remove @myorg/[email protected]   # Remove specific version
dev-link remove @myorg/core         # Remove all versions
dev-link remove feature-v2          # Remove entire namespace

dev-link tree

Scans and displays the monorepo structure, detecting install levels, sub-monorepos, and isolated packages.

dev-link tree                       # Visual tree output
dev-link tree --json                # JSON output for tool consumption
dev-link tree --depth 3             # Limit scan depth

dev-link docs

Access embedded documentation from the CLI.

dev-link docs                       # Show documentation tree
dev-link docs agents.md             # AI agent guide (root)
dev-link docs store/namespaces.md   # Specific topic
dev-link docs store/agents.md       # Store section agent guide

Configuration

devlink.config.mjs

export default {
  // Packages to manage — versions per mode or universal
  packages: {
    "@myorg/core": { version: "1.0.0" },                              // universal — all modes
    "@myorg/utils": { version: { dev: "2.0.0", remote: "1.5.0" } },  // per-mode
    "@myorg/dev-tools": { version: { dev: "1.0.0" } },                // dev only — removed in remote mode
    "@myorg/sst": { version: { dev: "0.4.0" }, synthetic: true },     // synthetic — staged to .devlink/
    "@myorg/test-utils": { version: "1.0.0", dev: true },             // dev dependency — → devDependencies
    "@myorg/local-sdk": { version: "1.0.0", link: "../sdk" },         // link — resolved via npm link
  },
  
  // Dev mode — uses local DevLink store
  dev: () => ({
    manager: "store",
    namespaces: ["feature", "global"],
    peerOptional: ["@myorg/*"],
  }),
  
  // Remote mode — uses npm registry (e.g. GitHub Packages)
  remote: () => ({
    manager: "npm",
  }),

  // Auto-detect mode when no --mode flag is provided
  detectMode: (ctx) => {
    if (ctx.env.NODE_ENV === "development") return "dev";
    return "remote";
  },
};

peerOptional

When your packages have internal dependencies (e.g., @myorg/core depends on @myorg/utils), npm will try to resolve them from the registry during npm install. If these packages aren't published yet, npm fails.

The peerOptional option solves this by transforming matching dependencies to optional peer dependencies in the copied packages. This tells npm not to resolve them from the registry.

dev: () => ({
  manager: "store",
  peerOptional: ["@myorg/*"],  // All @myorg packages become optional peers
})

Note: Only the copies in node_modules are modified. The original packages in the store remain unchanged.

Global Options

--repo <path>     # Use custom store location (default: ~/.devlink)
-h, --help        # Show help
-v, --version     # Show version

Environment variable: DEVLINK_REPO can also set the store location.

Namespaces

Namespaces allow different projects to use different variants of the same package without conflicts. Each namespace is an isolated context in the store:

# Feature branch development
dev-link publish -n feature-auth

# Team-specific packages
dev-link publish -n team-platform

# Environment-specific
dev-link publish -n staging

Use cases:

• Test experimental changes in one project while others use stable versions
• Multiple developers working on different features of the same package
• A/B testing different implementations

Resolution follows namespace precedence:

namespaces: ["feature-auth", "global"]
// First looks in feature-auth, falls back to global

Example Workflows

Feature Branch Development

# Developer A: Working on auth feature
cd packages/auth
dev-link publish -n feature-auth

# Developer B: Testing auth changes
# devlink.config.mjs: namespaces: ["feature-auth", "global"]
dev-link install --dev

# After feature is merged
dev-link publish                    # Publish to global
dev-link remove feature-auth        # Clean up

Monorepo Development

# Publish all packages
cd packages/core && dev-link publish
cd packages/utils && dev-link publish
cd packages/ui && dev-link publish

# Consumer app
cd apps/web
dev-link install --dev

# After changes to core
cd packages/core
dev-link push                       # Updates apps/web automatically

Using DevLink as Default Install Command

Replace npm install with DevLink during development using npm lifecycle hooks:

{
  "scripts": {
    "dev:install": "dev-link install --mode dev",
    "remote:install": "dev-link install --mode remote"
  }
}

• dev:install — resolves packages from the local DevLink store via staging + file: protocol. Packages not found in the store fall back to npm automatically.
• remote:install — resolves packages from npm registry, verified per-package via npm view. Packages not found in npm fall back to the local store.

Use with AI Agents

DevLink includes comprehensive, hierarchical documentation designed for AI coding assistants. The documentation is embedded in the CLI and organized by section, each with its own agent guide.

# View the root AI agent guide
dev-link docs agents.md

# Section-specific guides
dev-link docs store/agents.md
dev-link docs publishing/agents.md
dev-link docs installation/agents.md

AI agents can also read the development guide at AGENTS.md in the project root for codebase internals.

Store Structure

~/.devlink/
├── namespaces/
│   ├── global/
│   │   └── @myorg/
│   │       └── core/
│   │           └── 1.0.0/
│   │               ├── package.json
│   │               └── dist/
│   └── feature-v2/
│       └── ...
├── registry.json          # Package index
├── installations.json     # Consumer tracking
└── .lock                  # File locking

Documentation

📚 Access documentation directly from the CLI:

dev-link docs                       # Browse documentation tree
dev-link docs agents.md             # Complete AI agent guide
dev-link docs store                 # List store documents
dev-link docs store/namespaces.md   # Specific topic

Each section has its own agent guide (agents.md) with context for that area:

• store/ — Store structure, namespaces, locking
• publishing/ — Publish and push commands
• installation/ — Install command and configuration
• inspection/ — List, resolve, consumers
• maintenance/ — Remove, verify, prune

Full Index

• Store
  • Structure — Store directory layout and registry
  • Namespaces — Namespace isolation and precedence
  • Locking — File locking and concurrency
• Publishing
  • Publish — Publishing packages to the store
  • Push — Publishing and updating all consumers
• Installation
  • Install — Install command, flows, and bin linking
  • Configuration — devlink.config.mjs reference
• Inspection
  • List — Listing packages in the store
  • Resolve — Debugging package resolution
  • Consumers — Consumer project tracking
• Maintenance
  • Remove — Removing packages and namespaces
  • Verify — Verifying store integrity
  • Prune — Removing orphaned packages

Changelog

Latest: [2.6.0] - 2026-03-18

• Selective package install via positional arguments (dev-link install [packages...])
• Simplified CLI: --mode <name> is the only mode flag; --npm-ignore-scripts replaces --run-scripts
• Staging + npm install is now the only flow — legacy direct copy removed
• All documentation aligned with new CLI surface

📄 Full Changelog

Feedback

We welcome feedback, suggestions, and ideas for improvement. Please open an issue to share your thoughts.

Note: This project does not accept code contributions via pull requests.

About This Project

This tool was built following the principles defined in the whitepaper "A Formal Definition of AI-First" by Unlimitech Cloud LLC.

📄 Read the Whitepaper | More Whitepapers

The whitepaper provides a formal functional definition that enables seamless integration with AI coding assistants and autonomous agents—making tools like DevLink naturally AI-ready.

This project represents Unlimitech Cloud LLC's commitment to knowledge sharing: contributing frameworks and practical tools that help organizations navigate complex challenges. We believe sharing knowledge openly strengthens the broader ecosystem and creates value for everyone.

License

MIT © Unlimitech Cloud LLC