Windows: Rewrites stop working if run from a shell with cwd with a lowercase disk letter

[rhorenov]

Describe the bug

First, I want to say I'm really glad VitePress exists and I like it a lot! However, as a first-time user, I encountered a very frustrating bug that took me several hours to debug.

VitePress rewrites stop working on Windows when the dev server is run from a shell with a current working directory that has a lowercase drive letter (e.g., c:\path). The same configuration works correctly when the drive letter is uppercase (e.g., C:\path).

This appears to be caused by a case sensitivity mismatch: the rewrites map stores paths with lowercase drive letters, but Vite/Node returns file paths with uppercase drive letters, causing the lookup to fail.

This bug is particularly problematic for beginners because the symptoms are subtle and confusing - the site partially works, but internationalization breaks in unexpected ways. It's not immediately obvious that the shell's current directory case is the culprit.

Possibly related to: vitejs/vite#18468

Reproduction

Minimal reproduction project: vitepress_windows_bug.zip

In this project the en version of the site shall be served at the root / using rewrites option in the config.

Installation:

1. Extract the zip file

2. Install dependencies:

   npm install

3. Run the dev server:

   npm run docs:dev

The config file is very simple: (.vitepress/config.js):

import { defineConfig } from 'vitepress';

export default defineConfig({
  rewrites: {
    "en/:rest*": ":rest*",
  },

  locales: {
    root: {
      label: 'English',
      lang: 'en',
    },
    cs: {
      label: 'Čeština',
      lang: 'cs',
    },
  },
});

Steps to reproduce:

1. On Windows, open cmd.exe

2. Navigate to your VitePress project with a lowercase drive letter:

   cd \
   cd c:\vitepress_windows_bug

   (The prompt should show c:\... with lowercase)

3. Run the dev server:

   npm run docs:dev

4. Try to access / route and test language switching

Observed behavior (lowercase c:):

• The site redirects from / → /en/ automatically - it shall not happen
• Language change control, when 'Czech' is selected, sets the wrong path: /cs/en/ instead of /cs/
• Reason - routes are not properly rewritten

I've added logging to createMarkdownToVueRenderFn shows:

Console output (from the manually instrumented to createMarkdownToVueRenderFn method):

***** rewrites {
  'c:/vitepress_windows_bug/docs/en/index.md': 'c:/vitepress_windows_bug/docs/index.md'
}
***** file (before rewrites): C:/vitepress_windows_bug/docs/en/index.md
***** file (after rewrites): C:/vitepress_windows_bug/docs/en/index.md

❌ Rewrite NOT applied - notice the case mismatch between the rewrites map (c:) and the incoming file path (C:).

Working behavior (uppercase C:):

1. Navigate with uppercase drive letter:

   cd \
   cd C:\vitepress_windows_bug

2. Run npm run docs:dev

Console output:

***** rewrites {
  'C:/vitepress_windows_bug/docs/en/index.md': 'C:/vitepress_windows_bug/docs/index.md'
}
***** file (before rewrites): C:/vitepress_windows_bug/docs/en/index.md
***** file (after  rewrites): C:/vitepress_windows_bug/docs/index.md

✅ Rewrite applied correctly - case matches, language switching works properly.

Expected behavior

Rewrites should work regardless of the drive letter case in the current working directory. VitePress should normalize path cases on Windows to ensure consistent behavior.

Correct behaviour:

• The site does not redirect from / → /en/ automatically
• Language change control, when 'Czech' is selected, sets path: cs/

System Info

System:
  OS: Windows 10 10.0.19045
  CPU: (8) x64 Intel(R) Core(TM) i7-7700HQ CPU @ 2.80GHz
  Memory: 2.08 GB / 15.84 GB
Binaries:
  Node: 22.20.0
  npm: 10.9.3
  pnpm: 10.18.1
Browsers:
  Chrome: 141.0.7390.56
  Edge: Chromium (140.0.3485.54)
  Firefox: 136.0.4
  Internet Explorer: 11.0.19041.5794
npmPackages:
  vitepress: ^2.0.0-alpha.12 => 2.0.0-alpha.12

Additional context

Tested versions: This issue affects both VitePress 2.0.0-alpha.12 and 1.6.4 with identical behavior.

Package manager note: The issue occurs with npm but does NOT occur with pnpm - pnpm handles this case correctly.

Workaround: Setting vite.resolve.preserveSymlinks = true resolves the issue:

export default defineConfig({
  // ... other config
  vite: {
    resolve: {
      preserveSymlinks: true,
    },
  },
});

Recommendations:

• This is Windows-specific and related to upstream Vite issue: Drive letter case is different from the process.cwd vitejs/vite#18468
• It would be good to patch VitePress before the Vite issue is resolved
• If this cannot be fixed immediately, please document this prominently in the Windows setup documentation - it can save beginners many hours of frustration

Validations

• Check if you're on the latest VitePress version.
• Follow our Code of Conduct
• Read the docs.
• Check that there isn't already an issue that reports the same bug to avoid creating a duplicate.