Externalize next/navigation and next/headers for SSR catalog search

[field123]

Parent

#553 — Spec: one session for Elastic Path identity

What to build

Removes the blocker that makes server-rendered catalog search impossible to build at all. The
library that does the server rendering loads two Next.js modules that neither build environment
knows about, so a bundle containing it fails outright.

Platform work only — no component changes, and nothing a shopper or designer sees until the
server-rendering work lands on top.

Spec stories 17, 18 — this makes them buildable.

Acceptance criteria

• A bundle containing the catalog-search server-rendering library builds successfully in both build environments, where today it fails to resolve.
• A browser loading that library gets a working stand-in for the Next module that exists only on a server, rather than failing on a module that cannot exist there.
• A consumer on an older loader is unaffected: the new module names sit behind a new loader-version gate, so an older loader is never handed a name it cannot resolve.
• A regression test pins that the Studio canvas never mounts the catalog-search provider's inner component — the canvas survives this change only because of that fact, and it must be asserted rather than reasoned from a code reading.
• Every fork edit made here is recorded in the customization registry, so an upstream merge cannot drop it silently.

Blocked by

None (can start immediately).

The tracker's dependency graph on this issue is authoritative; this list mirrors it.

---

Below is the original ticket, kept intact — it carries the research and decisions from #486, #495, #523 and #524.

In brief

This package gives designers drag-and-drop commerce components they assemble into a storefront inside Plasmic Studio, a visual web builder. Plasmic ships the package as a pre-built bundle, so every third-party library a component uses has to be resolvable when that bundle is built.

Search results are currently rendered only in the browser, which means search engines see an empty page. Fixing that needs a library that loads two Next.js modules (next/navigation and next/headers) the bundler does not know about, so today the build fails outright.

This issue teaches the two build environments about those modules and supplies a browser stand-in for the one that only exists on a server. It changes no component code — it removes the blocker so the server-rendering work can happen.

Part of the ADR-0003 token architecture. Decided on #524.

Why

react-instantsearch-nextjs is the only reachable SSR mechanism for catalog search (getServerState hard-fails next build in the App Router). It has unguarded top-level require("next/navigation") and require("next/headers"), and deriveExternals externalizes neither — next is installed in neither loader-bundle-env nor canvas-packages. So the require resolves on neither build and SSR catalog search is not a package-only change.

No package change in this issue. Fork platform code only.

Work

• deriveExternals: add next/navigation and next/headers behind a new loader-version gate. This is a protocol bump, not an edit to an existing gate — an externalized module works only because the loader hands it over at run time, so ungated a customer on an older @plasmicapp/loader-nextjs gets "Unknown module" instead of a page.
• Register a browser stub for next/headers in loader-nextjs. The library requires it at module top level, unguarded, but only calls it on server paths (an absolute URL from x-forwarded-proto/host, and x-nonce). next/headers does not exist in a browser. Precedent: loader-server.tsx already registers fake React/host/query modules.
• platform/canvas-packages esbuild externals.
• Regression test pinning that the Studio canvas never mounts EPCatalogSearchProviderInner. The canvas is not a Next app so next/navigation never resolves there; this is survivable only because the require sits inside a render body that never executes. That finding must not be left resting on a code reading.
• Customization-registry entries for all three fork edits.

No upstream pull request, notwithstanding that loader-nextjs already hands over next/navigation while deriveExternals refuses to allow it.

Notes

Blast radius is additive: nothing can use these names today, since next is absent from both bundle environments, so any package touching them already fails to build. This turns a hard failure into a working path.

Blocked by: nothing.

---

ADR-0003: plasmicpkgs/commerce-providers/elastic-path/docs/adr/0003-one-session-for-elastic-path-identity.md. Map: #486. Issue set: #496.