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.

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

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

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

cd my-library
dev-link publish

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

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"],
  }),
};

cd my-project
dev-link install --dev --npm

DevLink copies the packages from the store to your node_modules.

After making changes to your library:

cd my-library
dev-link push

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

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

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

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                        # No resolution (no --npm)
dev-link install --npm                  # Universal packages + npm install
dev-link install --mode dev --npm       # Dev mode with npm integration
dev-link install --mode remote --npm    # Remote mode (registry resolution)
dev-link install --dev --npm            # Shorthand for --mode dev
dev-link install -n feature,global      # Override namespace precedence
dev-link install --recursive --npm      # Recursive npm install across monorepo

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

Shows how packages would be resolved given namespace precedence.

dev-link resolve @myorg/core@1.0.0
dev-link resolve @myorg/core@1.0.0 -n feature,global

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

Removes packages, versions, or entire namespaces.

dev-link remove @myorg/core@1.0.0   # Remove specific version
dev-link remove @myorg/core         # Remove all versions
dev-link remove feature-v2          # Remove entire namespace

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

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

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";
  },
};

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.

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

# 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

# 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

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

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

• 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.

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.

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

📚 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

• 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

• tree command now detects sub-packages under packages/ even without workspaces field

📄 Full Changelog

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.

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.

MIT © Unlimitech Cloud LLC