mint dev: full site rebuild on single file change — 30s+ reload, 500 errors, symlink resolution ignores workspace docs.json

[DeveloperAlly]

Summary

mint dev rebuilds the entire site on every single file save, causing 30+ second reload times even on minimal projects. Additionally, when running from a scoped workspace that uses symlinks to a subset of pages, mint dev follows symlink targets back to the repo root and discovers the full docs.json there instead of using the workspace's scoped docs.json.

Environment

• mint CLI version: 4.2.446
• Node: v23.11.0
• OS: macOS 14.4.1 (Darwin 23.4.0, Apple Silicon M3)

Issue 1: Full rebuild on every file change

Steps to reproduce

1. Project has ~750 MDX pages with a docs.json navigation config
2. Run mint dev
3. Edit a single MDX file and save
4. Observe 30+ second reload time

Expected

Incremental recompilation of only the changed page and its direct dependents. A single MDX edit on a project with fewer than 20 routes should reload in under 5 seconds.

Actual

Every save triggers what appears to be a full site rebuild. Even with a scoped workspace containing only 18 routes and 63 files (no OpenAPI spec, no redirects), reload takes 30+ seconds.

Issue 2: Frequent 500 errors and client-side exceptions

During normal mint dev usage we frequently see:

• 500 errors on page load in the browser
• "Application error: a client-side exception has occurred while loading localhost (see the browser console for more information)"

These occur during routine development with no invalid MDX — just editing content and saving.

Issue 3: Symlink resolution bypasses workspace docs.json

Context

We built a scoping tool that creates a minimal workspace with:

• A scoped docs.json containing only the routes for one tab (e.g. 18 routes)
• Symlinks from workspace/v2/solutions/page.mdx → repo/v2/solutions/page.mdx
• No OpenAPI config, no redirects

mint dev is launched with cwd set to this workspace directory.

Steps to reproduce

1. Create a workspace directory with a scoped docs.json (18 routes)
2. Symlink MDX files from the workspace back to the full repo
3. Run mint dev from the workspace directory
4. Observe that mint dev sometimes loads the full repo's docs.json (728 routes) instead of the workspace's scoped docs.json (18 routes)

Expected

mint dev should use the docs.json in its cwd — the workspace directory it was launched from.

Actual

mint dev appears to resolve symlink targets to their real paths, walk up the directory tree from the resolved path, and discover the repo root's docs.json. This causes it to load the full 728-route navigation instead of the scoped 18-route workspace.

Suggested fix

When resolving docs.json, mint dev should use the original cwd path, not the resolved real path of symlinked files. Alternatively, provide a --docs-config flag to explicitly specify which docs.json to use.

---

Any of these individually would be workable, but together they make mint dev very difficult to use on larger documentation projects. Happy to provide more details or test patches.