fix(cli): dev server reads symlinked deps so npx dev isn't blank - #29
Conversation
…lank `lectio dev` symlinks the site's deps in from wherever the package was installed (npx cache, pnpm store), whose realpaths sit outside the materialized site dir. Vite's dev server refused to serve them, so React Router's default client entry failed to load and the page rendered blank. Allow the dev server to read them (server.fs.strict: false — dev-server only, the static build is unaffected). Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
There was a problem hiding this comment.
Pull request overview
Fixes a lectio dev failure mode when the CLI is run via npx (or other installs that place dependency realpaths outside the materialized site directory), which caused Vite to reject serving React Router’s client entry and render a blank page.
Changes:
- Loosens Vite dev server filesystem restrictions in the materialized
vite.config.tsso symlinked dependency realpaths can be served. - Adds a changeset documenting the patch-level fix for the
lectio-docspackage.
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated 1 comment.
| File | Description |
|---|---|
| apps/site-builder/vite.config.ts | Allows the dev server to serve symlinked dependencies by disabling Vite’s fs strict allowlist. |
| .changeset/dev-vite-fs-allow.md | Declares a patch release and documents the blank-page fix for npx lectio-docs dev. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| // outside the materialized site dir. Let the dev server read them — otherwise | ||
| // React Router's default client entry can't load and the page renders blank. | ||
| // Dev-server only; the static build is unaffected. | ||
| server: { fs: { strict: false } }, |
There was a problem hiding this comment.
Fair flag, but the exposure this describes needs the dev server reachable off-localhost — which the CLI never enables. The materialized server is react-router dev bound to localhost by default, and the bin runs it with no --host passthrough, so @fs paths are only reachable from the local machine.
A precise server.fs.allow list is the "correct" alternative, but it's brittle here: the deps are symlinked in and their realpaths live in different roots per install (npx cache, pnpm store, workspace root), so an allowlist would be layout-dependent and isn't exercised in CI (dev has no CI coverage). Keeping fs.strict: false for this localhost-only dev tool.
Running
npx lectio-docs devin another repo rendered a blank page:lectio devsymlinks the site's dependencies in from wherever the package wasinstalled (npx cache, pnpm store), whose realpaths sit outside the
materialized site dir. Vite's dev server refused to serve them, so React
Router's default client entry failed to load → blank page.
Fix: the materialized
vite.config.tssetsserver.fs.strict: false, so the devserver can read the symlinked deps. Dev-server only — the static build is
unaffected. Safe for a local dev server on your own machine.
Surfaced by testing
npx lectio-docs devin an external repo — the same classof "only shows up when installed elsewhere" bug as the materialized tsconfig fix.