cloudflare / cloudflare/vinext
Normalize internal paths to forward slashes for Windows support
- Dominant language
- TypeScript
- Stars
- 8.8k
- Forks
- 406
- Avg merge
- 2d 6h
- Merged PRs (30d)
- 120
Description
## Background
Vite normalizes all internal paths to forward slashes. On Windows, Node.js APIs (`path.join`, `path.relative`, `fs.glob`, etc.) return backslash paths. When vinext stores or compares these paths without normalization, things break — cache misses, failed route lookups, wrong `startsWith`/`endsWith` results, etc.
#1578 fixed the first case (`StaticFileCache`). #1604 extracted the fix into a reusable `toSlash()` utility in `utils/path.ts`. The same problem exists in other parts of the codebase.
## Known affected areas
- **Routing** — `pagePath`, `layoutPath`, `errorPath` from `app-route-graph.ts` are OS-native paths. Downstream forward-slash comparisons silently mismatch on Windows.
- **File scanner** — `scanWithExtensions` yields `fs.glob` results which use backslashes on Windows.
- **Entry generators** — `entries/` files apply `normalizePathSeparators()` per-callsite; should migrate to the shared `utils/path.ts`.
- **Build & deploy** — `path.relative()` in prerender output, asset prefix, deploy packaging.
- **Tests** — Hardcoded forward-slash assertions and NTFS-illegal fixture filenames (`*`, `:`) cause failures on Windows.
## Proposal
1. **Normalize at filesystem boundaries** — apply `toSlash()` wherever `path.join`, `path.relative`, or `fs.glob` produces a path for internal use (#1604 provides the utility). For constructing internal-only paths that never touch the OS filesystem, prefer `path.posix.join` to produce forward slashes directly without a normalize step.
2. **Add Windows CI on `main` only** — catch regressions post-merge without blocking the current fast-paced PR workflow.
## References
- #1578 — `StaticFileCache` inline fix
- #1604 — `utils/path.ts` (`slash` / `toSlash`)
Contributor guide
Assessment
This issue has not been assessed yet.