cloudflare / cloudflare/vinext

Normalize internal paths to forward slashes for Windows support

Open
#1,605 3 comments 0 reactions 0 assignees View on GitHub
good first issue help wanted
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

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.