Skip to content

feat(core): pair server previews with browser commits #524

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
Charles Hudson (phobetron) wants to merge 1 commit into
base: main
Choose a base branch
from
+5,871 −4,958
Open

feat(core): pair server previews with browser commits #524

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions .prettierignore
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,7 @@
docs
pnpm-lock.yaml
**/.angular/**
**/.cache/**
**/.next/**
**/next-env.d.ts
**/ios/Pods/**
Expand Down
174 changes: 66 additions & 108 deletions documentation/authoring/blueprints/nextjs-app-router.md
View file
Open in desktop

Large diffs are not rendered by default.

91 changes: 50 additions & 41 deletions documentation/authoring/blueprints/nextjs-pages-router.md
View file
Open in desktop

Large diffs are not rendered by default.

35 changes: 19 additions & 16 deletions documentation/authoring/blueprints/node.md
View file
Open in desktop

Large diffs are not rendered by default.

34 changes: 17 additions & 17 deletions documentation/authoring/blueprints/react-web.md
View file
Open in desktop

Large diffs are not rendered by default.

34 changes: 17 additions & 17 deletions documentation/authoring/blueprints/web.md
View file
Open in desktop

Large diffs are not rendered by default.

36 changes: 18 additions & 18 deletions documentation/authoring/migration-blueprints/experience-js-nextjs-app-router.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,32 +12,32 @@ guide: ../../guides/migrating-experience-js-next-to-nextjs-app-router.md
- **Use when:** A Next.js App Router app carries legacy Next.js, ESR, SSR plugin, or React
experience.js wiring.
- **Target result:** The app uses the App Router server binding's nested request family for request
context, server first paint, and page tracking, with the client binding only for bound Client
Components.
preview and first paint, plus its injected client request root to hydrate and stage the browser
continuation for ordinary route tracking.
- **Guide file:** `documentation/guides/migrating-experience-js-next-to-nextjs-app-router.md`
- **Write after:** `choosing-a-nextjs-migration-path-from-experience-js.md`.
- **First verification:** One dynamic App Router route renders an all-visitors variant and verifies
both accepted and denied-consent event paths.
- **First verification:** One dynamic App Router route renders an all-visitors variant, delivers its
private replay in the browser, and verifies denied-consent behavior.

## Migration route

| Legacy surface | Target route | Detail owner |
| -------------------------------- | ------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
| Legacy Next provider and tracker | App Router server request family and forwarding handler | [App Router blueprint](../blueprints/nextjs-app-router.md) |
| SSR/ESR profile helpers | App Router request context and profile cookie | [App Router identifiers](../../internal/sdk-knowledge/web/nextjs-app-router.md#identifier-ownership) |
| React render hooks/components | App Router `OptimizedEntry` and browser takeover | [App Router rendering](../../internal/sdk-knowledge/web/nextjs-app-router.md#render--entry-resolution) |
| Legacy plugins | Supplemental plugin migration | `migrating-experience-js-plugins-and-preview.md` |
| Legacy surface | Target route | Detail owner |
| -------------------------------- | ---------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
| Legacy Next provider and tracker | App Router request family and injected client request root | [App Router blueprint](../blueprints/nextjs-app-router.md) |
| SSR/ESR profile helpers | Server preview plus private browser replay | [App Router identifiers](../../internal/sdk-knowledge/web/nextjs-app-router.md#identifier-ownership) |
| React render hooks/components | App Router `OptimizedEntry` and browser takeover | [App Router rendering](../../internal/sdk-knowledge/web/nextjs-app-router.md#render--entry-resolution) |
| Legacy plugins | Supplemental plugin migration | `migrating-experience-js-plugins-and-preview.md` |

## Section plan

| Section | Purpose | Must route to | Fact sources |
| ----------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Remove legacy Next.js package assumptions | Prevent writers from treating ESR middleware/selector source as supported imports. | Legacy package mapping and unsupported boundaries. | [package mapping](../../internal/migration-knowledge/experience-js.md#package-mapping), [Next.js SSR ESR](../../internal/migration-knowledge/experience-js.md#nextjs-ssr-and-esr), [unsupported boundaries](../../internal/migration-knowledge/experience-js.md#unsupported-or-manual-migration-boundaries) |
| Install and bind the App Router SDK | Restore the explicit server binding, nested request family, and forwarding-only handler before replacing render calls. | App Router setup, package, and runtime sections. | [package](../../internal/sdk-knowledge/web/nextjs-app-router.md#package--entry-points), [setup](../../internal/sdk-knowledge/web/nextjs-app-router.md#setup--initialization-and-binding), [runtime](../../internal/sdk-knowledge/web/nextjs-app-router.md#version--runtime-quirks) |
| Replace SSR/ESR profile continuity | Move profile cookie and request evaluation to the SDK-owned request family while consent remains app-owned. | Request context, identifiers, consent, and first-event ownership. | [Next.js SSR ESR](../../internal/migration-knowledge/experience-js.md#nextjs-ssr-and-esr), [legacy identifiers](../../internal/migration-knowledge/experience-js.md#identifiers-and-persistence), [target identifiers](../../internal/sdk-knowledge/web/nextjs-app-router.md#identifier-ownership), [events](../../internal/sdk-knowledge/web/nextjs-app-router.md#events--tracking) |
| Replace server-rendered personalization | Route legacy mapped experiences and React wrappers to target entry resolution and server first paint. | App Router rendering and content-model migration. | [React legacy](../../internal/migration-knowledge/experience-js.md#react-render-and-hooks), [content model](../../internal/migration-knowledge/experience-js.md#contentful-model-and-mapper), [rendering](../../internal/sdk-knowledge/web/nextjs-app-router.md#render--entry-resolution), [entry resolution](../../internal/sdk-knowledge/shared/concepts.md#entry-resolution) |
| Replace browser takeover features | Move flags, analytics forwarding, preview, and live updates through the target client runtime. | App Router browser/client sections and supplemental plugin guide. | [plugins](../../internal/migration-knowledge/experience-js.md#plugins-and-preview), [flag views](../../internal/sdk-knowledge/shared/concepts.md#custom-flag-views), [event streams](../../internal/sdk-knowledge/shared/concepts.md#stateful-event-forwarding-streams), [preview](../../internal/sdk-knowledge/shared/concepts.md#preview-overrides), [live updates](../../internal/sdk-knowledge/shared/concepts.md#live-updates) |
| Validate App Router migration | Verify server HTML, hydration stability, profile continuity, event ownership, and cache safety. | App Router production checks and troubleshooting. | [runtime](../../internal/sdk-knowledge/web/nextjs-app-router.md#version--runtime-quirks), [fallback](../../internal/sdk-knowledge/web/nextjs-app-router.md#failure--fallback-behavior), [events](../../internal/sdk-knowledge/web/nextjs-app-router.md#events--tracking) |
| Section | Purpose | Must route to | Fact sources |
| ----------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Remove legacy Next.js package assumptions | Prevent writers from treating ESR middleware/selector source as supported imports. | Legacy package mapping and unsupported boundaries. | [package mapping](../../internal/migration-knowledge/experience-js.md#package-mapping), [Next.js SSR ESR](../../internal/migration-knowledge/experience-js.md#nextjs-ssr-and-esr), [unsupported boundaries](../../internal/migration-knowledge/experience-js.md#unsupported-or-manual-migration-boundaries) |
| Install and bind the App Router SDK | Restore the explicit server binding, nested request family, and forwarding-only handler before replacing render calls. | App Router setup, package, and runtime sections. | [package](../../internal/sdk-knowledge/web/nextjs-app-router.md#package--entry-points), [setup](../../internal/sdk-knowledge/web/nextjs-app-router.md#setup--initialization-and-binding), [runtime](../../internal/sdk-knowledge/web/nextjs-app-router.md#version--runtime-quirks) |
| Replace SSR/ESR profile continuity | Move request evaluation to zero or more optional commands plus the SDK page, forced server preview state, a continuation staged during full browser hydration, matching-route delivery, successful Experience commit/persistence, and a visible no-JavaScript consequence while consent remains app-owned. | Request context, identifiers, consent, replay, and route ownership. | [Next.js SSR ESR](../../internal/migration-knowledge/experience-js.md#nextjs-ssr-and-esr), [legacy identifiers](../../internal/migration-knowledge/experience-js.md#identifiers-and-persistence), [target identifiers](../../internal/sdk-knowledge/web/nextjs-app-router.md#identifier-ownership), [events](../../internal/sdk-knowledge/web/nextjs-app-router.md#events--tracking), [replay](../../internal/sdk-knowledge/shared/concepts.md#experience-preflight-and-private-replay) |
| Replace server-rendered personalization | Route legacy mapped experiences and React wrappers to target entry resolution and server first paint. | App Router rendering and content-model migration. | [React legacy](../../internal/migration-knowledge/experience-js.md#react-render-and-hooks), [content model](../../internal/migration-knowledge/experience-js.md#contentful-model-and-mapper), [rendering](../../internal/sdk-knowledge/web/nextjs-app-router.md#render--entry-resolution), [entry resolution](../../internal/sdk-knowledge/shared/concepts.md#entry-resolution) |
| Replace browser takeover features | Move flags, analytics forwarding, preview, and live updates through the target client runtime. | App Router browser/client sections and supplemental plugin guide. | [plugins](../../internal/migration-knowledge/experience-js.md#plugins-and-preview), [flag views](../../internal/sdk-knowledge/shared/concepts.md#custom-flag-views), [event streams](../../internal/sdk-knowledge/shared/concepts.md#stateful-event-forwarding-streams), [preview](../../internal/sdk-knowledge/shared/concepts.md#preview-overrides), [live updates](../../internal/sdk-knowledge/shared/concepts.md#live-updates) |
| Validate App Router migration | Verify server HTML, hydration stability, cache safety, and deep-link to the integration guide's exact browser commit, duplicate-route, and continuity-cookie checks. | App Router production checks and troubleshooting. | [runtime](../../internal/sdk-knowledge/web/nextjs-app-router.md#version--runtime-quirks), [fallback](../../internal/sdk-knowledge/web/nextjs-app-router.md#failure--fallback-behavior), [events](../../internal/sdk-knowledge/web/nextjs-app-router.md#events--tracking) |

## Handoffs

Expand Down
Loading
Loading