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.

This method is inspired by this article (Section 3)

Solution: Use Local Directory Dependencies

Instead of publishing or linking packages, we directly reference the local filesystem path of realdwg-web.

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

Directory Layout (Recommended)

Place the two repositories side by side:

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

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

Step-by-Step Guide

1. Modify Dependency to Use Local Path

In cad-viewer/packages/cad-simple-viewer/package.json:

{
  "dependencies": {
    "@mlightcad/data-model": "file:../../../realdwg-web/packages/data-model/"
  }
}

Adjust the relative path 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 realdwg-web (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. Restore the original dependency version:

{
  "dependencies": {
    "@mlightcad/data-model": "^x.y.z"
  }
}

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

Aspect	pnpm link	Local path dependency
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 is the recommended approach.

It is:

• Simple
• Transparent
• Easy to teach
• Easy to undo

This should be the default debugging workflow when multiple repositories must be modified together.