@uniformdev/next-app-router-upgrade 0.1.0 → 0.2.0

package/README.md

@@ -1,6 +1,6 @@
 # @uniformdev/next-app-router-upgrade
 
-This CLI helps you move a Next.js App Router app that uses `@uniformdev/next-app-router` to the developer preview of the SDK (`20.81.1-alpha.25.sha-f076f9b857`). The upgrade has two phases:
+This CLI helps you move a Next.js App Router app that uses `@uniformdev/next-app-router` to the developer preview of the SDK (`20.81.1-alpha.41.sha-adcf82dedd`). The app can use a stable version (20.82 to 20.85) or an earlier developer preview. The upgrade has two phases:
 
 - **Phase 1: upgrade the SDK.** The minimum changes. After phase 1, the app works in lite mode: the browser chooses the personalization and test variants after hydration.
 - **Phase 2: turn on edge mode.** The edge chooses the variants of each visitor, so the first paint is correct. The steps depend on the host of the app.
@@ -38,9 +38,9 @@ The guide uses the same safety checks as `migrate`. One difference: when a file
 | Host | Status |
 |---|---|
 | Vercel | Available: `--edge vercel` |
-| Cloudflare | Coming soon. Follow the docs for other hosts. |
+| Cloudflare | Available: `--edge cloudflare`. The app must run on Cloudflare Workers with vinext. |
 | Netlify | Coming soon. Follow the docs for other hosts. |
-| Akamai | Coming soon. Follow the docs for other hosts. |
+| Akamai | Available: `--edge akamai`. The CLI changes the app. You make the EdgeWorker. |
 
 ## Usage
 
@@ -111,14 +111,16 @@ The migration changes only code where the result has the same behavior:
 | Change | When |
 |---|---|
 | Set each `@uniformdev` package to the target version | The npm registry has the package at that version. `@uniformdev/toolbar-react` and `@uniformdev/context-edge` have their own version lines, so they do not change. |
-| Add `@vercel/functions` `^3.7.2` to `dependencies` | The app imports `@vercel/functions`, and `package.json` does not list it. Version 20.82 installed it for you. |
+| Add `@vercel/functions` `^3.7.2` to `dependencies` | The app imports `@vercel/functions`, and `package.json` does not list it. The stable SDK installs it for you. |
 | Add an override for `@uniformdev/context` | The target is a prerelease, and the app uses `@uniformdev/toolbar-react`. npm gets `overrides`, and yarn gets `resolutions`. For pnpm, the migration gives a manual step. |
 | Remove the `pathPatternsWithVariations` option | Always. The option has no effect in the developer preview. |
 | Remove `dataClient: new DefaultDataClient()` and the `dataClient={new DefaultDataClient()}` prop | Only for the default data client. A custom data client stays, and the migration lists it as a manual change. |
 | Remove `middlewareRuntimeCache` and `experimental.disableSwrMiddlewareCache` | In the server configuration: `uniform.server.config.*`, or an object of the type `UniformServerConfig`. |
+| Remove the `compositionMetadata` argument of `useInitUniformContext` | The argument is the `compositionMetadata` prop. The SDK now sends the composition metadata of the page composition to the Context. |
+| Remove the `compositionMetadata` prop of a custom client context component | No other code in the component uses it. |
 | Remove the import of a removed API | Only when no code uses it after the changes above. |
 
-All other findings of `check` are manual changes. Examples are a custom data client, `result.code`, `route.compositionApiResponse` without a type check, old page codes and the Next.js version. The migration shows each one with its file and line.
+All other findings of `check` are manual changes. Examples are a custom data client, `result.code`, `route.compositionApiResponse` without a type check, old page codes, the visitor data options of 20.85 and the Next.js version. The migration shows each one with its file and line.
 
 ### Phase 2 on Vercel (`--edge vercel`)
 
@@ -147,7 +149,43 @@ These cases are manual changes:
 - A matcher or options that are not literals.
 - An own `onRevalidateTags` function. Call `expireVercelRuntimeCacheTags(tags)` from it.
 
-The CLI also reminds you to check the Uniform webhook. It cannot see the webhook settings.
+The CLI also reminds you to check the Uniform webhook, and to turn on Protection Bypass for Automation if the deployment uses Vercel Deployment Protection. It cannot see these settings.
+
+### Phase 2 on Cloudflare (`--edge cloudflare`)
+
+```bash
+npx @uniformdev/next-app-router-upgrade migrate --edge cloudflare --dry-run
+```
+
+Edge mode on Cloudflare uses `cfVinextUniformEdgeMiddleware` from `@uniformdev/next-app-router/cf-vinext`. It needs vinext on Cloudflare Workers. If `package.json` does not list `vinext`, the CLI makes no changes, and tells you to move the app to vinext first.
+
+| Change | When |
+|---|---|
+| Replace `uniformMiddleware(...)` with `cfVinextUniformEdgeMiddleware(...)`, and import it from `@uniformdev/next-app-router/cf-vinext` | Each reference to `uniformMiddleware` is a call. |
+| Add `missing: [{ type: "header", key: "x-uniform-edge-origin" }]` to each matcher | The same as on Vercel. |
+| Add a config with the default matcher of the docs | The middleware file has no config. |
+| Add `edgeMode: [true, false]` to `createUniformStaticParams` | The options do not have `edgeMode`. |
+
+The CLI does not add a runtime, and it accepts `proxy.ts`. The preview route needs no change: its `revalidateTag` calls also expire the vinext data cache. The CLI reminds you that the Worker needs `@cloudflare/vite-plugin` and a vinext data cache, for example KV.
+
+### Phase 2 on Akamai (`--edge akamai`)
+
+```bash
+npx @uniformdev/next-app-router-upgrade migrate --edge akamai --dry-run
+```
+
+On Akamai, an EdgeWorker with `akamaiUniformEdgeWorker` from `@uniformdev/next-app-router/akamai` is in front of the app. The worker rewrites the routes and chooses the variants. The app keeps its middleware: `uniformMiddleware` and `handleUniformRoute` let the requests of the worker through, and handle draft mode.
+
+| Change | When |
+|---|---|
+| Add `edgeMode: [true, false]` to `createUniformStaticParams` | The options do not have `edgeMode`. |
+
+These are manual changes:
+
+- Make the EdgeWorker. The step goes away when a file in the app folder imports `@uniformdev/next-app-router/akamai`.
+- A middleware that does not use `uniformMiddleware` or `handleUniformRoute`. It must let requests with the `x-uniform-edge-origin` header through.
+
+The CLI also reminds you of the settings that it cannot see: the property variable `PMUSER_BYPASS_EW_RP_EVENT`, the external modules of the EdgeWorker bundle, the Akamai cache, and the Uniform webhook.
 
 ### Safety
 
@@ -176,7 +214,10 @@ Each of these fails the TypeScript build, or fails at runtime, with the develope
 | `result-code` | `.code` on the result of `resolveRouteFromCode` or `resolvePlaygroundRoute`. |
 | `old-page-code` | Hard-coded `/uniform/2~…` page codes. |
 | `next-version` | Next.js lower than 16.0.7. |
-| `vercel-functions-transitive` | Imports of `@vercel/functions` when `package.json` does not list it. Version 20.82 installed it for you. |
+| `context-composition-metadata` | The `compositionMetadata` prop of a custom client context component, and a second argument of `useInitUniformContext`. The docs and the starter for 20.82 use this pattern. |
+| `context-storage-options` | `cookieMaxBytes`, `pruneUnknownTests`, `pruneUnknownDimensions` and `pruneZeroScores`: in the `context` server configuration, as props of a custom client context component, or as options of `createClientUniformContext`. 20.85.0 added them. The developer preview does not have them. |
+| `uniform-context-props` | `UniformContext` with a `result` prop or with children. This is the API of `20.81.1-alpha.25`. Now, render the compositions, then `<UniformContext />`, and set `pageComposition` on the primary `UniformResolvedComposition`. |
+| `vercel-functions-transitive` | Imports of `@vercel/functions` when `package.json` does not list it. The stable SDK installs it for you. |
 
 ### Behavior changes (warnings)
 
@@ -195,7 +236,7 @@ Each of these fails the TypeScript build, or fails at runtime, with the develope
 
 ### Notes (info)
 
-`cached-resolver`, `static-params`, `context-edge-dependency` and `redirect-status` tell you about changes that need no code change.
+`cached-resolver`, `static-params`, `context-edge-dependency`, `playground-path` and `redirect-status` tell you about changes that need no code change. `playground-path` finds a `processPlaygroundPath` in `createPreviewGETRouteHandler`: the middleware now accepts the same option.
 
 ## Limits
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniformdev/next-app-router-upgrade",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Check and upgrade a Next.js App Router app to the developer preview of the Uniform SDK (@uniformdev/next-app-router), with edge mode.",
   "keywords": [
     "uniform",

package/src/client-context.js

@@ -0,0 +1,89 @@
+// Finds the code of a custom client context component that the developer preview does not accept.
+// The scan reports it, and the migration removes the parts that have the same behavior without them.
+
+import ts from "typescript";
+
+const CONTEXT_HOOK = "useInitUniformContext";
+const CONTEXT_FACTORIES = new Set(["createClientUniformContext", "createUniformContext"]);
+export const COMPOSITION_METADATA = "compositionMetadata";
+
+// 20.85.0 added these options. The developer preview does not have them.
+export const STABLE_CONTEXT_OPTIONS = {
+  cookieMaxBytes: "Without it, the visitor data cookie has no size limit.",
+  pruneUnknownTests: "Without it, the stored assignments of removed A/B tests stay.",
+  pruneUnknownDimensions: "Without it, the stored scores of removed dimensions stay.",
+  pruneZeroScores: "Without it, the stored dimensions with a score of zero stay.",
+};
+
+/**
+ * Returns { hookArguments, props, options } for the source file `sf`.
+ * `sdkLocals` maps local names to { imported } for the imports from the SDK packages.
+ * - `hookArguments`: { call, argument, removable } for each second argument of useInitUniformContext.
+ *   `removable` is true when the argument is the compositionMetadata prop.
+ * - `props`: { element, pattern, fn, name } for each destructured prop that ClientContextComponentProps
+ *   no longer has.
+ * - `options`: { property, name } for each 20.85 option of createClientUniformContext.
+ */
+export function findClientContextIssues(sf, sdkLocals) {
+  const hookArguments = [];
+  const props = [];
+  const options = [];
+  if (!sdkLocals.size) return { hookArguments, props, options };
+
+  const isSdkCall = (node, names) =>
+    ts.isCallExpression(node) && ts.isIdentifier(node.expression) && names.has(sdkLocals.get(node.expression.text)?.imported);
+  const hookNames = new Set([CONTEXT_HOOK]);
+
+  const visit = (node) => {
+    if (isSdkCall(node, hookNames) && node.arguments.length > 1) {
+      const argument = node.arguments[1];
+      const removable =
+        node.arguments.length === 2 &&
+        ((ts.isIdentifier(argument) && argument.text === COMPOSITION_METADATA) ||
+          (ts.isPropertyAccessExpression(argument) && argument.name.text === COMPOSITION_METADATA));
+      hookArguments.push({ call: node, argument, removable });
+    }
+
+    if (isSdkCall(node, CONTEXT_FACTORIES)) {
+      for (const argument of node.arguments) {
+        if (!ts.isObjectLiteralExpression(argument)) continue;
+        for (const property of argument.properties) {
+          const name = property.name && (ts.isIdentifier(property.name) || ts.isStringLiteral(property.name)) ? property.name.text : undefined;
+          if (name && STABLE_CONTEXT_OPTIONS[name]) options.push({ property, name });
+        }
+      }
+    }
+
+    if (ts.isFunctionLike(node) && isClientContextComponent(node, sf, (call) => isSdkCall(call, hookNames))) {
+      const pattern = node.parameters[0].name;
+      for (const element of pattern.elements) {
+        if (element.dotDotDotToken) continue;
+        const key = element.propertyName ?? element.name;
+        const name = ts.isIdentifier(key) || ts.isStringLiteral(key) ? key.text : undefined;
+        if (name === COMPOSITION_METADATA || STABLE_CONTEXT_OPTIONS[name]) props.push({ element, pattern, fn: node, name });
+      }
+    }
+
+    ts.forEachChild(node, visit);
+  };
+  visit(sf);
+  return { hookArguments, props, options };
+}
+
+// A function with a destructured first parameter that is a ClientContextComponent: by its type, by
+// the type of its props, or because it calls useInitUniformContext.
+function isClientContextComponent(fn, sf, isHookCall) {
+  const parameter = fn.parameters?.[0];
+  if (!parameter || !ts.isObjectBindingPattern(parameter.name)) return false;
+  if (parameter.type && /\bClientContextComponentProps\b/.test(parameter.type.getText(sf))) return true;
+  const declaration = fn.parent;
+  if (ts.isVariableDeclaration(declaration) && declaration.type && /\bClientContextComponent\b/.test(declaration.type.getText(sf))) return true;
+  let calls = false;
+  const visit = (node) => {
+    if (calls) return;
+    if (isHookCall(node)) calls = true;
+    else ts.forEachChild(node, visit);
+  };
+  if (fn.body) visit(fn.body);
+  return calls;
+}

package/src/edge/akamai.js

@@ -0,0 +1,62 @@
+// Phase 2 on Akamai: an EdgeWorker with akamaiUniformEdgeWorker in front of the app. The worker
+// rewrites the routes and chooses the variants. The app keeps its middleware for draft mode and for
+// the requests that the worker does not handle.
+
+import fs from "node:fs";
+import path from "node:path";
+
+import { listSourceFiles } from "../scan.js";
+import { EDGE_HEADER, findMiddlewareFile, migrateRouteFiles, parse, SDK, sdkImports, WEBHOOK_REMINDER } from "./common.js";
+
+const AKAMAI = `${SDK}/akamai`;
+// These functions let the requests of the worker through: they have the edge origin header.
+const PASS_THROUGH = new Set(["uniformMiddleware", "handleUniformRoute", "vercelUniformEdgeMiddleware", "cfVinextUniformEdgeMiddleware", "uniformEdgeMiddleware", "handleUniformEdgeRoute"]);
+
+const REMINDERS = [
+  "In the Akamai property, add the user-defined variable PMUSER_BYPASS_EW_RP_EVENT with the initial value false. Without it, responseProvider gets each request.",
+  "In the bundler of the EdgeWorker, mark the EdgeWorkers modules cookies, create-response, crypto, encoding, http-request, log, streams and url-search-params as external.",
+  "Akamai caches the pages. Make sure that the Akamai cache follows the cache headers of the app, or that publishing in Uniform purges it.",
+];
+
+/**
+ * Returns { changes, contents, manual, reminders } for phase 2 on Akamai.
+ * `base` maps absolute paths to the text after phase 1, so that the two phases make one plan.
+ */
+export function planAkamaiEdge(root, { base = new Map() } = {}) {
+  const read = (file) => base.get(file) ?? fs.readFileSync(file, "utf8");
+  const changes = [];
+  const contents = new Map();
+  const manual = [];
+
+  // Step 1: the app's middleware stays, and lets the requests of the worker through.
+  const middleware = findMiddlewareFile(root);
+  if (!middleware) {
+    manual.push("No middleware.ts was found. Add middleware.ts with uniformMiddleware: it handles draft mode and the requests that the EdgeWorker does not rewrite.");
+  } else {
+    const locals = sdkImports(parse(middleware, read(middleware)));
+    const passes = [...locals.values()].some((info) => PASS_THROUGH.has(info.imported));
+    if (!passes) {
+      manual.push(
+        `${path.relative(root, middleware)}: the middleware does not use uniformMiddleware or handleUniformRoute. Let requests with the ${EDGE_HEADER} header through (NextResponse.next()), because the EdgeWorker already rewrote them.`
+      );
+    }
+  }
+
+  // Step 2: static params for both edge mode values.
+  const routes = migrateRouteFiles(root, read, { skip: middleware });
+  for (const { file, text, changes: fileChanges } of routes.files) {
+    if (text !== read(file)) contents.set(file, text);
+    changes.push(...fileChanges);
+  }
+  manual.push(...routes.manual);
+
+  // Step 3: the EdgeWorker. It is a separate bundle, so the migration does not make it.
+  const hasWorker = listSourceFiles(root).some((file) => read(file).includes(AKAMAI));
+  if (!hasWorker) {
+    manual.push(
+      `Add the Akamai EdgeWorker. In its main.js, export the handlers of akamaiUniformEdgeWorker from ${AKAMAI}: export const { onClientRequest, responseProvider, onClientResponse } = akamaiUniformEdgeWorker({ config, manifest }). Give it the server config of the app (uniform.server.config), the Context manifest, and the rewrite options of the middleware. In the worker, rewriteRequestPath gets { request, path, query }. If the EdgeWorker is in a different folder, you can ignore this step.`
+    );
+  }
+
+  return { changes, contents, manual, reminders: [...REMINDERS, WEBHOOK_REMINDER] };
+}

package/src/edge/cloudflare.js

@@ -0,0 +1,45 @@
+// Phase 2 on Cloudflare: turn on edge mode with cfVinextUniformEdgeMiddleware. The app must run on
+// Cloudflare Workers with vinext.
+
+import fs from "node:fs";
+import path from "node:path";
+
+import { migrateEdgeMiddleware, planEdge, SDK } from "./common.js";
+
+const HOST = {
+  factory: "cfVinextUniformEdgeMiddleware",
+  module: `${SDK}/cf-vinext`,
+  // vinext accepts middleware.ts and proxy.ts, and has no edge runtime option.
+  runtime: false,
+  // The preview route expires the vinext data cache with revalidateTag. No extra call is necessary.
+  onRevalidateTags: undefined,
+  packages: [],
+  reminders: [
+    "cfVinextUniformEdgeMiddleware needs a Worker that @cloudflare/vite-plugin builds. It keeps the manifest and the route records in the vinext data cache, for example a KV namespace with kvDataAdapter(). Make sure that the Worker has a data cache.",
+  ],
+};
+
+/**
+ * Returns { changes, contents, manual, reminders } for phase 2 on Cloudflare.
+ * `base` maps absolute paths to the text after phase 1, so that the two phases make one plan.
+ */
+export function planCloudflareEdge(root, { base = new Map() } = {}) {
+  const pkgFile = path.join(root, "package.json");
+  const pkg = JSON.parse(base.get(pkgFile) ?? fs.readFileSync(pkgFile, "utf8"));
+  if (!pkg.dependencies?.vinext && !pkg.devDependencies?.vinext) {
+    // cfVinextUniformEdgeMiddleware imports vinext and cloudflare:workers, so the build fails without vinext.
+    return {
+      changes: [],
+      contents: new Map(),
+      manual: [
+        "Edge mode on Cloudflare needs vinext: package.json does not list it. Move the app to vinext on Cloudflare Workers first, and then run the migration again. On other runtimes, use uniformEdgeMiddleware from @uniformdev/next-app-router/edge, as in the docs.",
+      ],
+      reminders: [],
+    };
+  }
+  return planEdge(root, { base, host: HOST });
+}
+
+export function migrateMiddleware(root, file, text) {
+  return migrateEdgeMiddleware(root, file, text, HOST);
+}