[PR #689] [MERGED] fix: usePathname() returns "/" during SSR of "use client" page components #772

New issue

Closed

opened 2026-05-06 13:10:02 +02:00 by BreizhHardware · 0 comments

BreizhHardware commented

2026-05-06 13:10:02 +02:00

Owner

📋 Pull Request Information

Original PR: https://github.com/cloudflare/vinext/pull/689
Author: @Divkix
Created: 3/26/2026
Status: ✅ Merged
Merged: 3/26/2026
Merged by: @southpolesteve

Base: main ← Head: fix/usePathname-ssr-hydration-688

📝 Commits (2)

6f4272a fix: usePathname() returns "/" during SSR of "use client" page components (#688)
978c48c refactor: deduplicate global accessor key and tighten types

📊 Changes

6 files changed (+277 additions, -12 deletions)

View changed files

📝 packages/vinext/src/shims/navigation-state.ts (+14 -2)
📝 packages/vinext/src/shims/navigation.ts (+48 -10)
📝 tests/e2e/app-router/routes.spec.ts (+34 -0)
➕ tests/fixtures/app-basic/app/use-client-page-pathname/[slug]/page.tsx (+23 -0)
➕ tests/fixtures/app-basic/app/use-client-page-pathname/page.tsx (+28 -0)
➕ tests/nextjs-compat/use-client-page-pathname.test.ts (+130 -0)

📄 Description

Summary

Fixes #688.

usePathname() returns "/" during SSR when the page component itself is a "use client" component, causing a React hydration mismatch
Root cause: Vite multi-environment dev mode can create separate module instances of navigation.ts for the SSR entry vs "use client" components. The _registerStateAccessors() pattern only updates the SSR entry's instance — the "use client" instance falls back to _serverContext (null -> "/")
Fix: navigation-state.ts now also stores the ALS-backed accessor functions on globalThis via Symbol.for("vinext.navigation.globalAccessors"). The default accessors in navigation.ts check this global before falling back to module-level state, ensuring all module instances reach the ALS-backed state regardless of which instance was registered

On the browser (where navigation-state.ts is never imported), the global key doesn't exist, so the fallback to module-level _serverContext is preserved — correct behavior for client-side hydration.

Test plan

New vitest: tests/nextjs-compat/use-client-page-pathname.test.ts — 8 tests covering usePathname(), useSearchParams(), useParams() for "use client" page components (static + dynamic routes)
New Playwright E2E: tests/e2e/app-router/routes.spec.ts — 3 tests checking no hydration errors and correct rendering for "use client" pages
Existing tests all pass (984 tests in shims + nextjs-compat, 1013 in shims + app-router)
Format + lint + type check clean

_{🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.}

## 📋 Pull Request Information **Original PR:** https://github.com/cloudflare/vinext/pull/689 **Author:** [@Divkix](https://github.com/Divkix) **Created:** 3/26/2026 **Status:** ✅ Merged **Merged:** 3/26/2026 **Merged by:** [@southpolesteve](https://github.com/southpolesteve) **Base:** `main` ← **Head:** `fix/usePathname-ssr-hydration-688` --- ### 📝 Commits (2) - [`6f4272a`](https://github.com/cloudflare/vinext/commit/6f4272a1fbab0adf3088cc89799b258a84d0a395) fix: usePathname() returns "/" during SSR of "use client" page components (#688) - [`978c48c`](https://github.com/cloudflare/vinext/commit/978c48c2477b2bddec3a7bdab7488ed92f6d4e94) refactor: deduplicate global accessor key and tighten types ### 📊 Changes **6 files changed** (+277 additions, -12 deletions) <details> <summary>View changed files</summary> 📝 `packages/vinext/src/shims/navigation-state.ts` (+14 -2) 📝 `packages/vinext/src/shims/navigation.ts` (+48 -10) 📝 `tests/e2e/app-router/routes.spec.ts` (+34 -0) ➕ `tests/fixtures/app-basic/app/use-client-page-pathname/[slug]/page.tsx` (+23 -0) ➕ `tests/fixtures/app-basic/app/use-client-page-pathname/page.tsx` (+28 -0) ➕ `tests/nextjs-compat/use-client-page-pathname.test.ts` (+130 -0) </details> ### 📄 Description ## Summary Fixes #688. - `usePathname()` returns `"/"` during SSR when the **page component itself** is a `"use client"` component, causing a React hydration mismatch - Root cause: Vite multi-environment dev mode can create separate module instances of `navigation.ts` for the SSR entry vs `"use client"` components. The `_registerStateAccessors()` pattern only updates the SSR entry's instance — the `"use client"` instance falls back to `_serverContext` (null -> `"/"`) - Fix: `navigation-state.ts` now also stores the ALS-backed accessor functions on `globalThis` via `Symbol.for("vinext.navigation.globalAccessors")`. The default accessors in `navigation.ts` check this global before falling back to module-level state, ensuring all module instances reach the ALS-backed state regardless of which instance was registered On the browser (where `navigation-state.ts` is never imported), the global key doesn't exist, so the fallback to module-level `_serverContext` is preserved — correct behavior for client-side hydration. ## Test plan - [x] New vitest: `tests/nextjs-compat/use-client-page-pathname.test.ts` — 8 tests covering `usePathname()`, `useSearchParams()`, `useParams()` for `"use client"` page components (static + dynamic routes) - [x] New Playwright E2E: `tests/e2e/app-router/routes.spec.ts` — 3 tests checking no hydration errors and correct rendering for `"use client"` pages - [x] Existing tests all pass (984 tests in shims + nextjs-compat, 1013 in shims + app-router) - [x] Format + lint + type check clean --- <sub>🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.</sub>