@c15t/nextjs 2.2.0 → 3.0.0-alpha.0

package/docs/frameworks/next/optimization.md

@@ -1,235 +1,199 @@
 ---
 title: Optimization
-description: Improve c15t startup performance in Next.js with same-origin
-  rewrites, static prefetching, and dynamic-route SSR.
+description: Reuse cached policy data and optionally reduce browser connection
+  overhead without changing consent behavior.
 group: frameworks
 ---
-Use this guide when you care about banner visibility speed, route static-ness, and reducing backend round-trip cost.
 
-## Start Here
+## Reuse cached policy data
 
-Apply the optimizations in this order:
+The [App Router](./app-router.md) and
+[Pages Router](./pages-router.md) guides use cached manifests
+with Inth. A manifest contains public policy configuration that your app server
+can reuse across requests. Each visitor's consent is still resolved separately.
 
-|Situation|Use|Why|
-|--|--|--|
-|Any production Next.js app|Same-origin `/api/c15t` rewrite|Lowers browser startup overhead and keeps the backend origin out of client config|
-|Static route, but banner speed matters|`C15tPrefetch`|Starts `/init` before hydration without making the route dynamic|
-|Dynamic route, or you want the fastest first banner|`fetchInitialData()`|Starts `/init` on the server and streams the result into the provider|
-|You want the simplest setup|Client-only init|No extra moving parts, but the banner appears later on cold loads|
+A warm cache avoids repeated backend policy resolution. It does not eliminate
+all requests. Your app may read its local manifest route, cold caches fetch
+upstream data, and consent choices still reach Inth. IAB policies can also need
+a Global Vendor List fetch.
 
-> ℹ️ **Info:**
-> C15tPrefetch is the only static-route prefetch step you need in @c15t/nextjs. Matching prefetched data is consumed automatically during first initialization.
->
-> ℹ️ **Info:**
-> Prefetched or SSR data is reused only when the request context still matches at runtime. That includes the backend URL, credentials, overrides, and the browser's ambient GPC signal.
+Server prefetch supplies the initial policy to the browser. For browser
+initialization that needs request geography, you can add an
+[optional local init route](./api-reference/data-fetching.md#do-i-need-the-local-init-route).
 
-In production benchmarks with a same-origin rewrite, prefetching strategies show measurable improvement over client-only init:
+## Compare manifests with backend initialization
 
-|Strategy|Scripts loaded|Data request starts|Banner visible|
-|--|--|--|--|
-|Client-only (no prefetch)|baseline|baseline|baseline|
-|Browser prefetch|\~1.3x faster|\~2.6x earlier|\~1.25x faster|
-|Server prefetch|\~2x faster|before page loads|\~1.9x faster|
+A warm manifest cache can reduce initialization latency by avoiding an upstream
+backend request. The saving depends on backend latency, cache hits and where
+consent resolution sits in rendering. It is not a fixed speedup for the whole
+page.
 
-## 1) Prefer Same-Origin Rewrites
+| Fetching path           | Work during initialization                                                                           |
+| ----------------------- | ---------------------------------------------------------------------------------------------------- |
+| Regular backend `/init` | Wait for the backend to resolve consent and return the result.                                       |
+| Cold manifest cache     | Fetch public policy from the backend, cache it and resolve consent locally.                          |
+| Warm manifest cache     | Reuse cached policy and resolve consent locally; local route requests and rendering still take time. |
 
-Proxy c15t requests through your Next.js app so the browser calls your own origin instead of a third-party domain.
+### How much faster is a warm manifest?
 
-```ts title="next.config.ts"
-import type { NextConfig } from 'next';
+In a local SSR benchmark with **150 ms of simulated backend latency**, a warm
+manifest reduced median time to first byte from **157.6 ms to 7.4 ms** across
+10 new-visitor samples per setup. Both setups waited for consent before rendering.
 
-const config: NextConfig = {
-  async rewrites() {
-    return [
-      {
-        source: '/api/c15t/:path*',
-        destination: `${process.env.NEXT_PUBLIC_C15T_URL}/:path*`,
-      },
-    ];
-  },
-};
+The warm cache skipped the upstream policy fetch. A cold cache still needs that
+fetch, so the benefit depends on your backend latency and cache hit rate.
 
-export default config;
-```
+See the [benchmark results](https://github.com/c15t/c15t/tree/ccfe906682ba06cef7b56a16cc8fd10728df77d3/benchmarks/reports/next-manifest-2026-09-10)
+for the measurements and test conditions.
 
-Then use:
+## Keep browser consent requests on your origin
 
-```tsx
-<ConsentManagerProvider options={{ backendURL: '/api/c15t', mode: 'hosted' }}>
-```
+A Next.js rewrite is an optional optimization. It can avoid a separate browser
+DNS lookup and TLS connection to the consent backend when that connection would
+otherwise be needed. Manifests and server rendering work without it.
 
-Why this helps:
+The app server still connects to Inth, and the rewrite adds a proxy hop. Measure
+your deployment to check the effect on latency. Vendor scripts, pixels and
+iframes keep their own URLs; this rewrite only forwards c15t HTTP requests.
+The same setup works with a self-hosted c15t backend.
 
-* Same-origin requests avoid extra DNS/TLS setup in many deployments
-* Ad blockers are less likely to block your init endpoint
-* You can change backend infrastructure without touching client code
+### Add the backend rewrite
 
-> ℹ️ **Info:**
-> Set NEXT\_PUBLIC\_C15T\_URL in .env to your backend URL, for example https\://your-project.inth.app.
->
-> ⚠️ **Warning:**
-> Use rewrites for browser-side calls (ConsentManagerProvider, C15tPrefetch). For server-side fetchInitialData(), prefer a direct backend URL (for example https\://your-project.inth.app) to avoid an extra server proxy hop.
+Set `C15T_BACKEND_URL` to the absolute endpoint supplied by your Inth project.
+The endpoint is public configuration. Merge this fallback into your existing
+Next.js configuration:
 
-## 2) Choose A Startup Strategy
-
-Start with a same-origin rewrite and the default client-side provider. Add one of the preloading strategies below only when the route behavior or performance target calls for it.
-
-### Client-Only Init
-
-Keep the default provider setup when you want the least complexity. This works on both static and dynamic routes, but the banner only appears after the client runtime starts and the initial `/init` request completes.
-
-### Dynamic Routes: Fetch On The Server And Stream
-
-Use `fetchInitialData()` when the route is already dynamic, or when you are willing to make it dynamic in exchange for the fastest first banner.
+```ts title="next.config.ts"
+import type { NextConfig } from 'next';
 
-Because it depends on `next/headers`, this opts the route into dynamic rendering.
+const upstreamURL = process.env.C15T_BACKEND_URL?.replace(/\/$/, '');
+if (!upstreamURL) throw new Error('Set C15T_BACKEND_URL to the absolute Inth endpoint');
 
-```tsx title="app/layout.tsx"
-import { fetchInitialData } from '@c15t/nextjs';
-import ConsentManager from '@/components/consent-manager';
+export default {
+  async rewrites() {
+    return {
+      fallback: [{
+        source: '/api/c15t/:path*',
+        destination: `${upstreamURL}/:path*`,
+      }],
+    };
+  },
+} satisfies NextConfig;
+```
 
-export default function RootLayout({ children }: { children: React.ReactNode }) {
-  const ssrData = fetchInitialData({
-    backendURL: process.env.NEXT_PUBLIC_C15T_URL!,
-  });
+Next.js serves the local manifest handler first. Other consent requests, such
+as `/api/c15t/subjects`, reach Inth through the rewrite. An optional local init
+handler also takes precedence over this fallback.
 
-  return (
-    <html lang="en">
-      <body>
-        <ConsentManager ssrData={ssrData}>{children}</ConsentManager>
-      </body>
-    </html>
-  );
-}
-```
+### Use the local prefix in browser configuration
 
-```tsx title="components/consent-manager/provider.tsx"
-'use client';
-
-import { type ReactNode } from 'react';
-import {
-  ConsentManagerProvider,
-  ConsentBanner,
-  ConsentDialog,
-  type InitialDataPromise,
-} from '@c15t/nextjs';
-
-export default function ConsentManager({
-  children,
-  ssrData,
-}: {
-  children: ReactNode;
-  ssrData?: InitialDataPromise;
-}) {
-  return (
-    <ConsentManagerProvider
-      options={{
-        mode: 'hosted',
-        backendURL: '/api/c15t',
-        ssrData,
-      }}
-    >
-      <ConsentBanner />
-      <ConsentDialog />
-      {children}
-    </ConsentManagerProvider>
-  );
-}
-```
+In the manifest setup from your router guide, change only `backendURL` to
+`'/api/c15t'`. The shared configuration then looks like this:
 
-> ⚠️ **Warning:**
-> Do not await fetchInitialData(). Pass the unresolved Promise to the provider so Next.js can stream the route while /init runs in parallel.
->
-> ℹ️ **Info:**
-> For fetchInitialData(), prefer a direct backend URL such as https\://your-project.inth.app instead of a rewrite to avoid an extra server-side proxy hop. See Server-Side Data Fetching for the full flow.
-
-### Static Routes: Start Fetch Early In The Browser
-
-Use `C15tPrefetch` when the route needs to stay static but you still want the `/init` request to start before hydration. Matching prefetched data is consumed automatically by the runtime during first store initialization.
-
-```tsx title="app/layout.tsx"
-import { C15tPrefetch } from '@c15t/nextjs';
-import { ConsentManager } from '@/components/consent-manager';
-
-export default function RootLayout({ children }: { children: React.ReactNode }) {
-  return (
-    <html lang="en">
-      <head>
-        <C15tPrefetch
-          backendURL="/api/c15t"
-          overrides={{ country: 'DE', region: 'BE', language: 'de' }}
-        />
-      </head>
-      <body>
-        <ConsentManager>{children}</ConsentManager>
-      </body>
-    </html>
-  );
-}
-```
+```ts title="c15t.config.ts"
+import { defineConsentConfig } from 'c15t/next';
 
-```tsx title="components/consent-manager/provider.tsx"
-'use client';
-
-import {
-  ConsentManagerProvider,
-  ConsentBanner,
-  ConsentDialog,
-} from '@c15t/nextjs';
-
-export default function ConsentManagerClient({ children }: { children: React.ReactNode }) {
-  return (
-    <ConsentManagerProvider
-      options={{
-        mode: 'hosted',
-        backendURL: '/api/c15t',
-        overrides: { country: 'DE', region: 'BE', language: 'de' },
-      }}
-    >
-      <ConsentBanner />
-      <ConsentDialog />
-      {children}
-    </ConsentManagerProvider>
-  );
-}
+export const consentConfig = defineConsentConfig({
+  backendURL: '/api/c15t',
+  manifestURL: '/api/c15t/manifest',
+});
 ```
 
-> ℹ️ **Info:**
-> C15tPrefetch uses Next.js beforeInteractive script loading, so the /init request can start before hydration.
->
-> ℹ️ **Info:**
-> If the request context changes between prefetch time and runtime, c15t falls back to a normal client /init. A common example is overrides.gpc conflicting with the browser's ambient GPC signal.
-
-## Keep The Provider Mounted Across Navigation
+The manifest URLs remain explicit in the current API. A configuration with only
+`backendURL` uses regular backend `/init` and can also use this rewrite. That
+setup must not have a local manifest init handler intercepting `/api/c15t/init`.
 
-Mount the consent provider at the app root so route transitions do not remount it.
+Keep using `consentConfig` for `resolveConsent` and `ConsentRoot`. Omit a
+separate `ConsentRoot` `backendURL` prop because it overrides the shared value.
 
-Why this helps:
+### Keep route handlers pointed upstream
 
-* Avoids re-running init work on client-side navigation
-* Prevents extra callback churn from remount cycles
-* Keeps banner/dialog state stable between route transitions
+The ready-made App Router handlers read the absolute upstream URL from
+`C15T_BACKEND_URL`. Keep these exports from the router guide:
 
-## Animation Performance
+```ts title="app/api/c15t/manifest/route.ts"
+export { manifestGET as GET } from 'c15t/next/api';
+```
 
-The default motion tokens are tuned for speed-first product UI:
+```ts title="app/api/c15t/init/route.ts"
+export { GET } from 'c15t/next/api';
+```
 
-|Token|Duration|Used for|
-|--|--|--|
-|`fast`|80ms|Banner slide + overlay, card scale, button hover, widget entry/exit|
-|`normal`|150ms|Accordion, switch toggle|
-|`slow`|200ms|Dialog trigger snap, tab indicator|
+Pages Router uses `createPagesApiHandlers()` with the same environment
+configuration. Export `.manifest` and `.init` from the respective API files as
+shown in the [Pages Router guide](./pages-router.md).
+
+If you configure handlers with `createNextConsentRouteHandlers({ backendURL })`,
+pass the absolute upstream URL. Passing the browser's local `consentConfig`
+would make the manifest handler fetch itself. An explicit `C15T_MANIFEST_URL`
+must also point upstream.
+
+### Check rewrite precedence
+
+An array-form rewrite or `afterFiles` runs after concrete routes; `fallback`
+runs after all application routes. A matching `beforeFiles` rewrite or
+middleware/proxy rewrite can intercept the local handlers instead. See
+[Next.js rewrite order](https://nextjs.org/docs/app/api-reference/config/next-config-js/rewrites).
+
+Use `/api/c15t/:path*` for the backend prefix. A bare `/api/c15t` source does not
+match nested endpoints. If a self-hosted backend catch-all already handles that
+prefix, it serves the remaining endpoints instead of the fallback rewrite.
+Keep the manifest resolver's upstream URL separate to avoid a request loop.
+
+A full [static export](./static-export.md) has no Next.js
+rewrites or API handlers. Use a hosting-level proxy or direct public Inth URL.
+
+## Configure manifest cache refresh
+
+`createNextConsentRouteHandlers` uses the Next.js Data Cache plus an in-process
+manifest cache. The in-process cache also covers Pages Router runtimes without
+the Data Cache. It supports ETag revalidation and respects upstream cache
+headers, including responses marked private.
+
+Once the upstream `s-maxage` has passed, the in-process cache keeps serving the
+cached manifest for as long as the upstream `stale-while-revalidate` allows
+(an explicit `s-maxage` is required for that window to apply),
+and refreshes it in the background. Requests do not wait for that refresh, and
+a refresh that fails or times out leaves the cached manifest in place, so a
+slow or unavailable backend does not delay rendering on a server that has
+already loaded the manifest. Inth sends `s-maxage=300` and a 24 hour
+`stale-while-revalidate` by default; lower the second value on a self-hosted
+backend if a policy change must reach servers sooner after an outage. A server
+with an empty cache still waits for the first upstream response.
+
+The background refresh is detached from the request. On runtimes that stop
+work once a response is sent, register it with the platform so it can finish.
+Pass `onBackgroundRevalidate` to the handler factory; it is called inside the
+handler with the refresh promise, which never rejects:
+
+```ts title="app/api/c15t/manifest/route.ts"
+import { createNextConsentRouteHandlers } from 'c15t/next/api';
+import { after } from 'next/server';
+
+export const { manifestGET: GET } = createNextConsentRouteHandlers({
+  onBackgroundRevalidate: (refresh) => after(() => refresh),
+});
+```
 
-These defaults follow the principle that product UI should be fast and purposeful — animations exist for spatial continuity, not decoration. In benchmarks, animation duration contributes a constant floor to "data fetched → banner visible" timing. The default tokens sit at the lower end of standard UI ranges (80-200ms) to minimize that floor.
+The same option applies to the init handler's `GET`. `after` is stable from
+Next 15.1; on Next 15.0 import `unstable_after` instead. Other hosts pass the
+promise to their equivalent, such as `waitUntil` on Vercel or Cloudflare.
+Without it the response still returns at once; only the refresh may be cut
+short, in which case the next request starts another.
 
-To customize motion durations and easing, see [Styling](/docs/frameworks/next/styling/overview).
+## Avoid repeating startup work
 
-## Reduce Network Overhead
+Keep one boundary in the App Router root layout or Pages Router `_app.tsx`.
+Remounting it during navigation creates another runtime and repeats startup
+work. Keep the stylesheet and consent UI in that shared root too.
 
-If you must use a cross-origin backend URL, add preconnect so the browser starts DNS/TLS early:
+Choose when to resolve consent according to your page. Use
+[server rendering](./server-side.md) for resolved initial HTML
+or streaming, and [client-side initialization](./client-side.md)
+when the browser should prepare consent.
 
-```tsx title="app/layout.tsx"
-<head>
-  <link rel="preconnect" href="https://your-project.inth.app" crossOrigin="" />
-</head>
-```
+Measure cold entry, a warm manifest cache and client navigation separately.
+Check server requests as well as the browser Network panel. Confirm that
+consent saves reach the backend and policy updates appear after the configured
+refresh window. If you add a rewrite, also confirm browser consent requests
+use your origin.