repository-linking-lib

Dependency-graph driven tooling for working on a set of local npm libraries side by side. Given a graph of repositories and their inter-dependencies, it can npm link / npm unlink them in the correct topological order, and build / unbuild the ones that publish a compiled entry point.

The library ships only the engine. Each consuming repository provides its own graph definition (the config) and a tiny entry point that runs it.

Operations

| Operation | What it does | | --- | --- | | info | Prints the graph and, per edge, whether the link is currently active. | | link | npm links every repository that has dependents globally, then links each repo's local dependencies. | | unlink | Reverts links: npm unlink -g for shared repos and npm install to restore published deps. | | build | Runs npm run build + npm run prepack on repos that declare a publishConfig.main. | | unbuild | Runs npm run postpack to revert a build. |

Usage in a consuming repository

Add the dependency (local, unpublished libraries are typically consumed via npm link or a file: reference) and create two files.

scripts/repository-linking/main.ts — the entry point (operation is read from the CLI argument):

import { Repository, RepositoryLinking, type RepositoryLinkingOperation } from 'repository-linking-lib';

let helpers = new Repository('../../../Libraries/Your-Library');

let framework = new Repository('../../Framework/Your-Framework');
framework.addDependency(helpers);

let root = new Repository('.');
root.addDependency(helpers);
root.addDependency(framework);

runRepositoryLinking(process.argv.slice(2)[0] as RepositoryLinkingOperation);

Wire up npm scripts that pass the operation as the argument:

{
  "scripts": {
    "info-repos": "tsx scripts/repository-linking/main.ts info",
    "link-repos": "tsx scripts/repository-linking/main.ts link",
    "unlink-repos": "tsx scripts/repository-linking/main.ts unlink",
    "build-repos": "tsx scripts/repository-linking/main.ts build",
    "unbuild-repos": "tsx scripts/repository-linking/main.ts unbuild"
  }
}

API

• Repository — a node in the graph. new Repository(relativePath) and .addDependency(other).
• runRepositoryLinking(options?) — runs an operation. options.operation defaults to process.argv[2]; options.rootPath defaults to process.cwd().
• RepositoryGraph / RepositoryStatus — the resolved graph, exposed for custom tooling.