next-evolve 0.3.3 → 0.3.4

package/README.md

@@ -1,137 +1,164 @@
 # next-evolve
 
-Self-improving Next.js sites: server-side variants with no flicker, measured in your own Postgres. Needs an Evolve Cloud account.
+A/B tests and bandits for Next.js App Router sites. Variants are chosen on the server, so there is no flicker. Raw events stay in your own Postgres; Evolve Cloud only receives aggregate counts and does the statistics.
 
-> Alpha.
+> Alpha. Needs an Evolve Cloud account (sign-up is invite-only for now). Without one the SDK serves your normal pages and records nothing; see [docs/without-an-account.md](docs/without-an-account.md).
 
-## Setup
+**Requirements:** Next.js 15.5 or newer with the App Router, Node 22.12 or newer, a Postgres 14+ database, and a host that runs a Node server (not `output: "export"`).
 
-```sh
-npx next-evolve init --routes "/ /pricing"   # add --dry-run to see the diff first
-npx next-evolve doctor                       # checks env, key, DB, bundle, proxy, pages, cloud → app
-```
+## Quickstart (about 10 minutes)
 
-`init` installs the package, connects to your site (secret key and webhook secret from the dashboard), sets up the database, and writes the config, route handler, proxy, layout script, instrumentation and `prebuild` hook. Static-mode pages move under `app/[evolve]/` and get wrapped with `withEvolve()`; when that isn't safe (a top-level `[slug]`, `force-dynamic`, a `"use client"` page…) the route stays in dynamic mode and `init` says why. It never overwrites your `.env.local` lines, and a re-run changes nothing. `--yes` skips every prompt.
+This gets you from an existing Next.js app to a running experiment in local development.
 
-Other commands: `migrate`, `pull`, `push`, `connect --test [--app-url]`, `aggregate`. The sections below describe what `init` writes.
+### 1. Create a site
 
-## Database
+Sign in at [app.evolveab.com](https://app.evolveab.com), enter a site name and click **Create site**. Copy the **secret key** (`evk_live_…`) and the **webhook secret** (`whsec_…`). They are shown only once. If you lose them, issue a new key on the site's **Connect** page.
 
-Raw events (exposures, goal events, identities) stay in **your** Postgres (≥ 14), in a separate `evolve` schema. Evolve Cloud only ever receives aggregate counts.
+### 2. Get a Postgres database
+
+Evolve writes events into its own `evolve` schema, so your app's existing database is fine. For local development, Docker works:
 
 ```sh
-EVOLVE_DATABASE_URL=postgres://… npx next-evolve migrate
+docker run -d --name evolve-pg -e POSTGRES_PASSWORD=postgres -p 54329:5432 postgres:17
 ```
 
-Use the pooled URL on serverless hosts (e.g. Neon's `-pooler` host).
+For production, any Postgres works (Neon, Supabase, RDS, your own). On serverless hosts use the pooled URL (for example Neon's `-pooler` host).
 
-## Goals
+### 3. Run init
 
-```ts
-// evolve.goals.ts
-import { defineGoals } from "next-evolve/config";
+In your app's directory:
 
-export default defineGoals({
-  cta_click: { event: "cta_click", window: "1d" },
-  signup_page: { pageview: "/signup", window: "1d" },
-  paid: {
-    event: "subscription_started",
-    source: "stripe",
-    window: "30d",
-    value: (e) => e.props.amount as number,
-  },
-});
+```sh
+npx next-evolve init \
+  --key evk_live_… \
+  --webhook-secret whsec_… \
+  --db postgres://postgres:postgres@localhost:54329/postgres \
+  --routes "/"
 ```
 
-Function values run in your app when the event is written; only `{ kind: "local-fn" }` is sent to the cloud.
+`--routes` lists the pages you want to test (exact paths, e.g. `"/ /pricing"`). Add `--dry-run` first to see the diff without changing anything. `init` is safe to re-run.
 
-## Routes and beacon
+It installs `next-evolve` and `zod`, checks the key, migrates the database and writes:
 
-```ts
-// app/api/evolve/[...evolve]/route.ts
-import { createEvolveHandler } from "next-evolve/server";
-import evolveConfig from "@/evolve.config";
-import goals from "@/evolve.goals";
+| File                                    | What it is                                                                                                                        |
+| --------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
+| `evolve.config.ts`                      | The routes Evolve may test, and their mode                                                                                        |
+| `evolve.goals.ts`                       | What counts as success (a sample `signed_up` goal)                                                                                |
+| `app/api/evolve/[...evolve]/route.ts`   | The routes the beacon and the cloud call                                                                                          |
+| `proxy.ts` (`middleware.ts` on Next 15) | Picks a variant per visitor; no network call                                                                                      |
+| `instrumentation.ts`                    | Registers goals and sends your config to the cloud on startup                                                                     |
+| `app/layout.tsx`                        | Adds `<EvolveScript />`, the beacon                                                                                               |
+| `package.json`                          | `"prebuild": "next-evolve pull"`                                                                                                  |
+| `.env.local`                            | `EVOLVE_SECRET_KEY`, `EVOLVE_WEBHOOK_SECRET`, `EVOLVE_DATABASE_URL`, `EVOLVE_TRACK_SECRET` (never overwrites a line that's there) |
 
-export const { GET, POST } = createEvolveHandler({ config: evolveConfig, goals });
-export const maxDuration = 60;
-```
+**Static or dynamic mode.** By default each tested page moves to `app/[evolve]/…` and is cached once per variant ("static mode"). `init` keeps a page where it is ("dynamic mode") when moving it isn't safe, and says why. If your `next.config` has `cacheComponents: true` (new `create-next-app` projects do), every route uses dynamic mode. See [docs/concepts.md](docs/concepts.md#static-and-dynamic-mode).
+
+If you already have a `proxy.ts`/`middleware.ts`, or `init` can't edit your layout, it prints the lines to add.
 
-Put `<EvolveScript />` (from `next-evolve/client`) in the root layout. It sends page views, exposures and clicks on `[data-evolve-goal]` elements (forms: on submit) to `/api/evolve/collect` on your own origin.
+### 4. Make a component optimizable
 
-## Tracking
+Declare which props Evolve may change with a Zod schema, next to the component:
 
-```ts
-import { evolve } from "next-evolve/server";
+```tsx
+// components/hero.tsx
+import { optimizable } from "next-evolve";
+import { z } from "zod";
 
-await evolve.track("project_created", { userId: user.id });
-await evolve.identify(user.id); // links the visitor's evolve_id cookie; first link wins
+const heroSchema = z.object({
+  title: z.string().min(3).max(60),
+  cta: z.string().min(2).max(24),
+});
+
+function Hero({ title, cta }: z.infer<typeof heroSchema>) {
+  return (
+    <section>
+      <h1>{title}</h1>
+      <a href="/signup" data-evolve-goal="signup">
+        {cta}
+      </a>
+    </section>
+  );
+}
+
+export default optimizable(Hero, heroSchema);
 ```
 
-In the browser: `import { track, identify } from "next-evolve/client"`.
+Render it with `<Optimizable>` on a tested page. The props you pass are the control:
 
-### Server-to-server events
+```tsx
+import { Optimizable } from "next-evolve";
+import Hero from "@/components/hero";
 
-`POST /api/evolve/track` with `Authorization: Bearer $EVOLVE_TRACK_SECRET` and `{ "events": [{ "name", "userId"?, "anonId"?, "value"?, "props"?, "source"?, "ts"?, "dedupeKey"? }] }` (≤ 500 events). Unset secret → 404; wrong bearer → 401.
+<Optimizable id="hero" component={Hero} props={{ title: "Ship faster", cta: "Start free" }} />;
+```
 
-### Stripe recipe
+With `cacheComponents: true`, wrap it in `<Suspense>` (from `react`); without it, `next build` fails with "uncached or runtime data … outside of `<Suspense>`":
 
-Call `evolve.track` from your own Stripe webhook handler, after you verify the signature:
+```tsx
+<Suspense>
+  <Optimizable id="hero" component={Hero} props={{ title: "Ship faster", cta: "Start free" }} />
+</Suspense>;
+```
 
-```ts
-// app/api/stripe/route.ts
-import { evolve } from "next-evolve/server";
+`data-evolve-goal="signup"` fires the `signup` event on click (forms: on submit). The sample goal `signed_up` in `evolve.goals.ts` counts that event.
 
-if (event.type === "invoice.paid") {
-  const invoice = event.data.object;
-  await evolve.track("subscription_started", {
-    userId: invoice.metadata.userId,
-    source: "stripe",
-    props: { amount: invoice.amount_paid / 100 },
-    dedupeKey: event.id, // Stripe retries: stored once
-  });
-}
+### 5. Start the app and open the page
+
+```sh
+npm run dev
 ```
 
-## Aggregation
+Open the page once. The region registers with the cloud and shows up under **Regions** in the dashboard within a few seconds.
+
+### 6. Create and start an experiment
+
+In the dashboard: **Regions → hero → New experiment**. Give it a name, change a prop for "Variant B" (for example the title), click **Save draft**, then **Start**.
+
+The dev server picks up the change within about 5 seconds (60 seconds in production, or at once through the sync webhook once deployed).
 
-Evolve Cloud never reads your database. It sends a signed request to `POST /api/evolve/aggregate` (verified with `EVOLVE_WEBHOOK_SECRET`), and your app answers with counts and sums per experiment × variant × goal × day, signed with the same secret. No visitor or user ids leave your app. Set `EVOLVE_SECRET_KEY`, `EVOLVE_WEBHOOK_SECRET` and `EVOLVE_DATABASE_URL`; the route needs `maxDuration = 60`.
+### 7. See the variant and the exposure
 
-In local development the cloud can't reach `localhost`. Run the same request yourself:
+Open the page in a private window: you get Control or Variant B (50/50) and keep it on reloads. Each new private window is a new visitor. The experiment page also has **Preview** links that force a variant without counting anything.
+
+The exposure is written to your database:
 
 ```sh
-npx next-evolve aggregate           # print the statistics
-npx next-evolve aggregate --upload  # and send them to Evolve Cloud
+docker exec evolve-pg psql -U postgres -c "select * from evolve.exposures"
 ```
 
-## Sync
+### 8. See it in the dashboard
+
+The cloud can't reach `localhost`, so in development you run the aggregation yourself. Aggregates only count data older than 2 minutes, so wait 2 minutes after the visit, then:
+
+```sh
+npx next-evolve aggregate --upload
+```
 
-Your app keeps a signed copy of its configuration (the bundle) in memory and serves from it with no network call on the request path. It gets new bundles three ways:
+The experiment page shows the visitor under **Results**. Once deployed, the cloud runs this on a schedule and you don't need the command.
 
-- **Polling:** every 60 s (5 s in dev), in the background.
-- **Webhook:** when you change an experiment, Evolve Cloud calls `POST /api/evolve/sync` (signed with `EVOLVE_WEBHOOK_SECRET`). The receiving instance pulls the new bundle within seconds. The webhook carries no configuration, so a forged call can at most cause one extra fetch.
-- **Build time:** add `"prebuild": "next-evolve pull"` to `package.json` and pass the result to the proxy, so a fresh instance serves the last bundle before its first fetch:
+### 9. Deploy
 
-```ts
-// proxy.ts
-import { createEvolveProxy } from "next-evolve/proxy";
-import buildBundle from "./.evolve/bundle.generated";
-import evolveConfig from "./evolve.config";
+Set the four `EVOLVE_*` variables from `.env.local` in your host's production environment, deploy, then tell the cloud where the app lives and test the connection:
 
-export const proxy = createEvolveProxy(evolveConfig, { buildBundle });
+```sh
+npx next-evolve connect --test --app-url https://your-app.com
+npx next-evolve doctor
 ```
 
-Add `.evolve/` to `.gitignore`. `pull` never fails the build: without a key or a reachable cloud it keeps the previous bundle or writes an empty one.
+More in [docs/production.md](docs/production.md).
 
-**Long-running Node (`next start`, Docker):** call `registerEvolve()` from `instrumentation.ts`. It polls in the background and keeps the last bundle on disk (`os.tmpdir()`, or `EVOLVE_CACHE_DIR`), so a restart serves it even when the cloud is unreachable.
+## Docs
 
-**Vercel + Global Config (recommended on Vercel):** without it, a webhook reaches only the instance that receives it and the others catch up within 60 s. With a [Global Config](https://vercel.com/docs/edge-config) store, the sync route writes the bundle there and every instance picks it up within ~10 s. Set:
+- [Concepts](docs/concepts.md): regions, variants, experiments, the bundle, static vs dynamic mode, cookies, bots
+- [API reference](docs/api.md): components, functions, CLI, HTTP routes
+- [Goals and attribution](docs/goals-and-attribution.md): defining goals, tracking events, how conversions are attributed
+- [Stripe recipe](docs/stripe.md): count paid subscriptions as a goal
+- [Going to production](docs/production.md): env, app URL, hosting (Vercel, Docker, Node), sync, firewalls
+- [What leaves your server](docs/what-leaves-your-server.md): every call the SDK makes, and what's in it
+- [Without an account](docs/without-an-account.md): what the SDK does when there's no cloud
+- [Configuration and environment variables](docs/configuration.md)
+- [Troubleshooting](docs/troubleshooting.md)
 
-| Var                       | Purpose                                 |
-| ------------------------- | --------------------------------------- |
-| `EVOLVE_GLOBAL_CONFIG`    | The store's connection string (read)    |
-| `EVOLVE_GLOBAL_CONFIG_ID` | The store id (`ecfg_…`), for writes     |
-| `EVOLVE_VERCEL_API_TOKEN` | A Vercel token that can write the store |
-| `EVOLVE_VERCEL_TEAM_ID`   | Optional, for team-owned stores         |
+## License
 
-Bundles read from Global Config are verified like any other. With an existing proxy that calls `applyEvolve`, `await evolveReady(evolveConfig)` first (a fresh instance waits ≤ 20 ms for one read).
+MIT

package/dist/cli/detect.js

@@ -75,7 +75,7 @@ function detectProject(root) {
 	});
 	if (cacheComponents) problems.push({
 		level: "warn",
-		message: "cacheComponents is on: static-mode pages are untested with it; prefer dynamic mode"
+		message: "cacheComponents is on: Evolve uses dynamic mode (static mode doesn't work with it); wrap <Optimizable> in <Suspense>"
 	});
 	return {
 		root,

package/dist/cli/files.js

@@ -107,12 +107,13 @@ function planLayout(plan, d) {
 	const src = plan.read(f);
 	if (src.includes("EvolveScript")) return;
 	const m = /^([ \t]*)<\/body>/m.exec(src);
-	if (!m) {
+	let withTag;
+	if (m) withTag = src.replace(m[0], `${m[1]}  <EvolveScript />\n${m[0]}`);
+	else if (src.split("</body>").length === 2) withTag = src.replace("</body>", "<EvolveScript /></body>");
+	else {
 		plan.manual.push(`Add <EvolveScript /> (from "next-evolve/client") inside <body> in ${f}.`);
 		return;
 	}
-	const indent = `${m[1]}  `;
-	const withTag = src.replace(m[0], `${indent}<EvolveScript />\n${m[0]}`);
 	plan.write(f, addImport(withTag, `import { EvolveScript } from "next-evolve/client";`));
 }
 function planInstrumentation(plan, d) {

package/dist/cli/init.js

@@ -51,11 +51,15 @@ async function initCommand(args, deps) {
 	for (const pr of d.problems) (pr.level === "error" ? err : out)(`${pr.level === "error" ? "✗" : "!"} ${pr.message}`);
 	if (d.problems.some((pr) => pr.level === "error")) return 1;
 	out(`✓ Next.js ${d.nextVersion} · ${d.appDir}/ · ${d.typescript ? "TypeScript" : "JavaScript"} · ${d.packageManager}`);
-	const mode = f.mode ?? "static";
+	const mode = f.mode ?? (d.cacheComponents ? "dynamic" : "static");
 	if (mode !== "static" && mode !== "dynamic") {
 		err("next-evolve init: --mode is \"static\" or \"dynamic\"");
 		return 1;
 	}
+	if (d.cacheComponents && mode === "static") {
+		err("✗ cacheComponents is on, and static mode doesn't work with it: use --mode dynamic (the default with cacheComponents)");
+		return 1;
+	}
 	const paths = (f.routes ?? "/").split(/[\s,]+/).filter(Boolean);
 	if (paths.some((r) => !r.startsWith("/") || /[[\]*?#]/.test(r))) {
 		err("next-evolve init: --routes are concrete paths like \"/ /pricing\"");
@@ -179,7 +183,7 @@ async function initCommand(args, deps) {
 	out(`\nNext:\n${[
 		...plan.manual,
 		...added.length && !dry ? [`In production, set ${added.join(", ")} (they're in .env.local now)`] : [],
-		`Wrap a component: <Optimizable id="hero" component={Hero} props={...} /> (from "next-evolve")`,
+		d.cacheComponents ? `Wrap a component: <Suspense><Optimizable id="hero" component={Hero} props={...} /></Suspense> (Optimizable from "next-evolve"; cacheComponents needs the <Suspense>)` : `Wrap a component: <Optimizable id="hero" component={Hero} props={...} /> (from "next-evolve")`,
 		"Visit the page once so the region registers, then open the dashboard",
 		...f["app-url"] ? ["After you deploy: npx next-evolve connect --test"] : ["After you deploy: npx next-evolve connect --test --app-url https://your-app.com"]
 	].map((s, i) => `  ${i + 1}. ${s}`).join("\n")}`);

package/dist/cli/load-app.js

@@ -55,7 +55,7 @@ function reexecWithTypes(command, args, cwd, env, quiet = false) {
 		stdio: [
 			"ignore",
 			quiet ? "ignore" : "inherit",
-			"inherit"
+			quiet ? "ignore" : "inherit"
 		],
 		cwd,
 		env: {

package/dist/client/beacon.d.ts

@@ -2,6 +2,13 @@ type BeaconEvent = Record<string, unknown>;
 export declare const COLLECT_URL = "/api/evolve/collect";
 export declare function push(e: BeaconEvent): void;
 export declare function flush(): void;
+/**
+ * Queues one exposure per counted region (`[data-evolve-e]` without
+ * `data-evolve-x`) on this page, now and again after 1 s and 4 s: regions
+ * inside <Suspense> (dynamic mode, cacheComponents) can stream in after the
+ * page's first effect. Returns the cleanup for a route change.
+ */
+export declare function watchExposures(p: string): () => void;
 /** Records a browser event (e.g. `track("cta_click", { plan: "pro" })`). */
 export declare function track(name: string, props?: Record<string, unknown>): void;
 /** Links this visitor to your user id. Prefer `evolve.identify()` on the server. */

package/dist/client/beacon.js

@@ -26,6 +26,33 @@ function flush() {
 		}).catch(() => {});
 	}
 }
+/**
+* Queues one exposure per counted region (`[data-evolve-e]` without
+* `data-evolve-x`) on this page, now and again after 1 s and 4 s: regions
+* inside <Suspense> (dynamic mode, cacheComponents) can stream in after the
+* page's first effect. Returns the cleanup for a route change.
+*/
+function watchExposures(p) {
+	const seen = /* @__PURE__ */ new Set();
+	const scan = () => {
+		for (const el of document.querySelectorAll("[data-evolve-e]:not([data-evolve-x])")) {
+			const e = el.getAttribute("data-evolve-e");
+			const v = el.getAttribute("data-evolve-v");
+			if (e && v && !seen.has(e)) {
+				seen.add(e);
+				push({
+					t: "exp",
+					e,
+					v,
+					p
+				});
+			}
+		}
+	};
+	scan();
+	const timers = [1e3, 4e3].map((ms) => setTimeout(scan, ms));
+	return () => timers.forEach(clearTimeout);
+}
 /** Records a browser event (e.g. `track("cta_click", { plan: "pro" })`). */
 function track(name, props) {
 	push({
@@ -48,4 +75,4 @@ function _reset() {
 	timer = void 0;
 	queue = [];
 }
-export { COLLECT_URL, _reset, flush, identify, push, track };
+export { COLLECT_URL, _reset, flush, identify, push, track, watchExposures };

package/dist/client/evolve-script.js

@@ -1,5 +1,5 @@
 "use client";
-import { flush, push } from "./beacon.js";
+import { flush, push, watchExposures } from "./beacon.js";
 import { useEffect } from "react";
 import { usePathname } from "next/navigation";
 // src/client/evolve-script.tsx
@@ -40,20 +40,7 @@ function EvolveScript() {
 			t: "pv",
 			p
 		});
-		const seen = /* @__PURE__ */ new Set();
-		for (const el of document.querySelectorAll("[data-evolve-e]:not([data-evolve-x])")) {
-			const e = el.getAttribute("data-evolve-e");
-			const v = el.getAttribute("data-evolve-v");
-			if (e && v && !seen.has(e)) {
-				seen.add(e);
-				push({
-					t: "exp",
-					e,
-					v,
-					p
-				});
-			}
-		}
+		return watchExposures(p);
 	}, [path]);
 	return null;
 }

package/dist/react/region.d.ts

@@ -10,6 +10,18 @@ export type OptimizableProps<P extends object, S extends z.ZodObject> = {
   /** Control props. Variant props are merged over these; schema defaults apply. */
   props: ControlProps<P, S>;
 };
+/**
+ * Region registration (spec §5.2): after the response, deduped per process,
+ * errors swallowed. `after()` is called from a timer, not during render: with
+ * `cacheComponents` on, Next flags the clock read inside `after()` as
+ * non-deterministic prerender I/O (a dev error overlay). Outside a request
+ * scope (tests, some build steps) the push runs directly, still in the
+ * background.
+ */
+export declare function scheduleRegistration(id: string, meta: {
+  jsonSchema: Record<string, unknown>;
+  schemaHash: string;
+}, controlProps: Record<string, unknown>, path: string | null): void;
 /**
  * Renders the variant of a region chosen by the proxy, or control. Never throws
  * because of Evolve: any problem renders control. Server component.

package/dist/react/region.js

@@ -32,18 +32,30 @@ async function currentPath() {
 		return null;
 	}
 }
-/** Region registration (spec §5.2): after the response, deduped per process, errors swallowed. */
+/**
+* Region registration (spec §5.2): after the response, deduped per process,
+* errors swallowed. `after()` is called from a timer, not during render: with
+* `cacheComponents` on, Next flags the clock read inside `after()` as
+* non-deterministic prerender I/O (a dev error overlay). Outside a request
+* scope (tests, some build steps) the push runs directly, still in the
+* background.
+*/
 function scheduleRegistration(id, meta, controlProps, path) {
 	if (!path) return;
-	try {
-		after(() => registerRegion({
-			id,
-			jsonSchema: meta.jsonSchema,
-			schemaHash: meta.schemaHash,
-			controlProps,
-			path
-		}));
-	} catch {}
+	const run = () => registerRegion({
+		id,
+		jsonSchema: meta.jsonSchema,
+		schemaHash: meta.schemaHash,
+		controlProps,
+		path
+	});
+	setTimeout(() => {
+		try {
+			after(run);
+		} catch {
+			run().catch(() => {});
+		}
+	}, 0);
 }
 function findPair(bundle, pairs, region) {
 	for (const p of pairs) {
@@ -124,4 +136,4 @@ async function Optimizable({ id, component, props }) {
 		...parsed.data
 	}));
 }
-export { Optimizable };
+export { Optimizable, scheduleRegistration };

package/dist/store/memory.js

@@ -43,6 +43,7 @@ function createMemoryStore(opts) {
 		schedule();
 		inflight = opts.fetcher(etag).then((res) => {
 			if (res.status === "ok") load(res.token);
+			else if (res.status === "error" && res.code === 404 && res.message?.includes("no_bundle")) logRateLimited("fetch:no_bundle", "no bundle yet (no experiment has started): serving control", void 0, 36e5);
 			else if (res.status === "error") logRateLimited(`fetch:${res.code}`, `bundle fetch failed (${res.code})`, res.message);
 		}).catch((e) => logRateLimited("fetch:throw", "bundle fetch failed", e)).finally(() => {
 			inflight = null;