Debugging with Multiple Repo Changes

The cad-viewer repository depends on packages from the realdwg-web, mtext-renderer repository.

Example:

• Repo cad-viewer

  • package: @mlightcad/cad-simple-viewer

• Repo realdwg-web

  • package: @mlightcad/data-model

@mlightcad/cad-simple-viewer  --->  @mlightcad/data-model

During development, bugs may exist in realdwg-web that must be fixed and tested immediately inside cad-viewer.

Problem with pnpm link

Using pnpm link across multiple monorepos introduces several issues:

• Complex setup and teardown
• Easy to forget unlink steps
• node_modules state becomes hard to reason about
• Breaks CI / reproducibility
• Hard for new developers to follow

To simplify local debugging, we adopt a local directory dependency approach with pnpm overrides.

Solution: Use Local Directory Dependencies with pnpm overrides

Instead of publishing or linking packages, we use pnpm overrides in the root package.json to directly reference the local filesystem path of realdwg-web packages.

This approach:

✅ Works naturally with pnpm
✅ Requires no global linking
✅ Is explicit and easy to revert
✅ Is suitable for short-term debugging
✅ Keeps dependency resolution predictable
✅ Applies to all packages in the monorepo

Directory Layout (Recommended)

Place the two repositories side by side:

workspace/
├── cad-viewer/
│   ├── packages/
│   │   └── cad-simple-viewer/
│   ├── package.json
│   └── pnpm-workspace.yaml
│
└── realdwg-web/
    ├── packages/
    │   ├── data-model/
    │   └── libredwg-converter/
    └── pnpm-workspace.yaml

⚠️ This layout is not mandatory, but relative paths will be easier to manage.

Step-by-Step Guide

1. Add pnpm overrides to root package.json

In cad-viewer/package.json (root directory):

{
  "name": "cad-viewer",
  "private": true,
  "pnpm": {
    "overrides": {
      "@mlightcad/data-model": "file:../realdwg-web/packages/data-model",
      "@mlightcad/libredwg-converter": "file:../realdwg-web/packages/libredwg-converter"
    }
  }
}

Adjust the relative paths if your directory structure is different.

2. Install Dependencies

From the root of cad-viewer:

pnpm install

pnpm will:

• Resolve data-model from the local directory
• Create a symlink inside node_modules
• Track it as a file-based dependency

---

3. Build dependencies (If Required)

If data-model requires a build step (TypeScript, bundling, etc.):

cd realdwg-web
pnpm install
pnpm build

For active development, you may also run:

pnpm dev

or a watch mode if supported.

---

4. Debug Normally

Now you can:

• Modify code inside realdwg-web/packages/data-model
• Rebuild (or let watch mode rebuild)
• Instantly test changes in cad-viewer

No linking, no publishing, no reinstall needed.

Reverting Back to Published Packages

After debugging is complete:

1. Remove the pnpm.overrides section from cad-viewer/package.json (root directory):

{
  "name": "cad-viewer",
  "private": true
  // Remove the pnpm overrides section
}

2. Reinstall dependencies:

pnpm install

This ensures:

• CI consistency
• Clean dependency graph
• No accidental local paths committed

---

⚠️ Important Notes

Do NOT Commit Local Paths

Local file dependencies are developer-only.

Before committing:

• Ensure package.json does not contain file: paths
• Use published versions for PRs and releases

---

When to Use This Approach

✅ Fixing bugs across repos
✅ Debugging integration issues
✅ Rapid iteration without publishing
❌ Long-term dependency management
❌ CI / production builds

Comparison: pnpm link vs Local Path with pnpm overrides

Aspect	pnpm link	Local path with pnpm overrides
Setup complexity	High	Low
Explicitness	Implicit	Explicit
Easy to revert	❌	✅
CI-safe	❌	❌ (dev-only)
Team-friendly	❌	✅

Summary

For debugging issues that span cad-viewer and realdwg-web, using local directory dependencies with pnpm overrides is the recommended approach.

It is:

• Simple
• Transparent
• Easy to teach
• Easy to undo
• Applies to all packages in the monorepo