cloudflare/vinext

Normalize internal paths to forward slashes for Windows support

Open

#1.605 aberto em 26 de mai. de 2026

Ver no GitHub
 (1 comment) (0 reactions) (0 assignees)TypeScript (329 forks)github user discovery
good first issuehelp wanted

Métricas do repositório

Stars
 (8.120 stars)
Métricas de merge de PR
 (Mesclagem média 1d 1h) (462 fundiu PRs em 30d)

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

  • RoutingpagePath, layoutPath, errorPath from app-route-graph.ts are OS-native paths. Downstream forward-slash comparisons silently mismatch on Windows.
  • File scannerscanWithExtensions yields fs.glob results which use backslashes on Windows.
  • Entry generatorsentries/ files apply normalizePathSeparators() per-callsite; should migrate to the shared utils/path.ts.
  • Build & deploypath.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)

Guia do colaborador