@preprio/toolkit 0.2.0-beta.2 → 0.2.0-beta.4

package/README.md

@@ -80,6 +80,7 @@ Per-framework requirements:
 | Entry point | Peer dependencies |
 | --- | --- |
 | `@preprio/toolkit` (vanilla core) | none |
+| `@preprio/toolkit/react` | `react` >= 17, `react-dom` >= 17 |
 | `@preprio/toolkit/nextjs` | `next` >= 13, `react` >= 17, `react-dom` >= 17 |
 | `@preprio/toolkit/astro` | none (`.astro` components compile in your own pipeline) |
 | `@preprio/toolkit/sveltekit` | `svelte` (only for the `.svelte` components) |
@@ -535,6 +536,81 @@ const preprHeaders = getPreprHeadersFromEvent(event);
 
 See the runnable example at `examples/nuxt` for the full source of truth.
 
+## React (no framework)
+
+`@preprio/toolkit/react` carries the two components that need nothing but React — for Vite + React Router, TanStack Router, Remix SPA mode, or Create React App. Next.js users want the [Next.js section](#nextjs) instead; its `PreprToolbar` binds the App Router for you.
+
+```tsx
+import { PreprPreview, PreprTrackingPixel } from '@preprio/toolkit/react';
+
+export function App() {
+  return (
+    <>
+      <YourRoutes />
+      {import.meta.env.DEV && <PreprPreview />}
+      <PreprTrackingPixel id={import.meta.env.VITE_PREPR_TRACKING_ID} />
+    </>
+  );
+}
+```
+
+Mount `PreprPreview` once per page — two copies start two editor bridges.
+
+### Without personalization
+
+A client-rendered app with no segments and no A/B testing needs **no middleware and no server helpers at all**. The middleware exists to resolve segment and variant cookies into request headers; with both features off there are no headers to resolve. What remains is click-to-edit and the editor's scroll restore, which are pure client concerns:
+
+```tsx
+<PreprPreview options={{ features: { segments: false, abTesting: false } }} />
+```
+
+No `navigation` prop is needed here. The default adapter drives `window.location`, and with both features off the only reachable path is the preview-mode refresh — a full reload either way. `PreprPreview` also needs no router context in this configuration, so it can mount anywhere in the tree.
+
+### With personalization
+
+Segments and A/B testing need request headers, which need a server. A static SPA has none — so this requires either a framework with a server (React Router in framework mode, Next.js) or your own backend using the [vanilla core](#any-other-framework).
+
+Once there is a server, pass a `navigation` adapter so segment and variant switches route softly instead of reloading:
+
+```tsx
+import { useNavigate, useLocation } from 'react-router';
+
+const navigate = useNavigate();
+const location = useLocation();
+
+<PreprPreview
+  {...toolbarProps}
+  navigation={{
+    navigate: url => navigate(url),
+    currentPath: () => location.pathname + location.search,
+  }}
+/>;
+```
+
+`navigation.reload` is optional and defaults to `window.location.reload()`. React Router has no soft-refresh equivalent, so leaving it unset is usually right.
+
+### Tracking pageviews
+
+`loadTrackingPixel` queues one `pageload` event when it installs. Client-side route changes emit nothing on their own, so a SPA records a single pageview per session unless you fire them yourself:
+
+```tsx
+import { useEffect } from 'react';
+import { useLocation } from 'react-router';
+import { trackEvent } from '@preprio/toolkit';
+
+function usePreprPageviews() {
+  const { pathname } = useLocation();
+
+  useEffect(() => {
+    trackEvent('pageload');
+  }, [pathname]);
+}
+```
+
+This double-counts the first pageview, since the pixel's own install event fires too. Skip the initial run with a ref if the exact count matters.
+
+The `id` is your access token, and in a client-rendered app it is public — bundled into JS and visible in devtools. Use a tracking-only token; do not derive it from a browser-exposed GraphQL URL, which would also expose content read access.
+
 ## Any other framework
 
 The core is runtime-neutral: it works off a WHATWG `Request` and hands back the headers to forward to Prepr plus the cookies to persist. Adapting it to Express, Hono, Fastify, or a plain server is roughly twenty lines.
@@ -680,9 +756,25 @@ The toolbar. Takes the props returned by `getToolbarProps`, and renders nothing
 
 There is no provider to wrap your tree in; state lives in the toolbar's own store.
 
+#### `PreprPreview`
+
+From `@preprio/toolkit/react`. The framework-free equivalent of `PreprToolbar`: same preview runtime, with the router binding left to you. Renders nothing.
+
+```tsx
+<PreprPreview {...toolbarProps} navigation={adapter} />
+```
+
+| Prop | Type | Description |
+| --- | --- | --- |
+| `activeSegment` / `activeVariant` / `segments` | — | Toolbar data, as returned by `getToolbarProps`. Optional for a headless preview. |
+| `options` | `PreprPreviewOptions` | Feature flags, `ui`, locale, debug (see [Preview Options](#preview-options)). |
+| `navigation` | `PreprNavigationAdapter` | Optional router binding. Defaults to `window.location`, which is correct for any router that keeps the URL bar in sync. |
+
+Every prop is read once on mount; changing one afterwards has no effect, since a live update would have to tear down the editor bridge and re-announce the preview. Remount to change configuration.
+
 #### `PreprTrackingPixel`
 
-Loads Prepr's CDN tracking pixel on mount. Renders nothing.
+Loads Prepr's CDN tracking pixel on mount. Renders nothing. Exported from both `@preprio/toolkit/react` and `@preprio/toolkit/nextjs` — the same component, with nothing Next-specific about it.
 
 ```tsx
 <PreprTrackingPixel id={accessToken} config={{ destinations: { googleTagManager: true } }} />

package/dist/astro/index.cjs

@@ -30,7 +30,7 @@ __export(astro_exports, {
 module.exports = __toCommonJS(astro_exports);
 
 // src/version.ts
-var VERSION = "0.2.0-beta.2";
+var VERSION = "0.2.0-beta.4";
 
 // src/core/features.ts
 function isEnabled(config) {

package/dist/astro/index.d.cts

@@ -27,8 +27,18 @@ interface PreprFeatures {
     editMode?: PreprFeatureConfig;
 }
 interface PreprToolbarProps {
-    readonly activeSegment: string | null;
-    readonly activeVariant: string | null;
+    /**
+     * Server-resolved active segment. Optional: omit it with `segments`
+     * disabled, where there is nothing to resolve. When enabled and omitted,
+     * the persisted cookie is used.
+     */
+    readonly activeSegment?: string | null;
+    /**
+     * Server-resolved active A/B variant. Optional: omit it with `abTesting`
+     * disabled, where there is nothing to resolve. When enabled and omitted,
+     * the persisted cookie is used.
+     */
+    readonly activeVariant?: string | null;
     /** Available segments to personalize on. */
     readonly segments?: readonly PreprSegment[];
     /** @deprecated Alias for `segments`. */

package/dist/astro/index.d.ts

@@ -27,8 +27,18 @@ interface PreprFeatures {
     editMode?: PreprFeatureConfig;
 }
 interface PreprToolbarProps {
-    readonly activeSegment: string | null;
-    readonly activeVariant: string | null;
+    /**
+     * Server-resolved active segment. Optional: omit it with `segments`
+     * disabled, where there is nothing to resolve. When enabled and omitted,
+     * the persisted cookie is used.
+     */
+    readonly activeSegment?: string | null;
+    /**
+     * Server-resolved active A/B variant. Optional: omit it with `abTesting`
+     * disabled, where there is nothing to resolve. When enabled and omitted,
+     * the persisted cookie is used.
+     */
+    readonly activeVariant?: string | null;
     /** Available segments to personalize on. */
     readonly segments?: readonly PreprSegment[];
     /** @deprecated Alias for `segments`. */

package/dist/astro/index.js

@@ -1,5 +1,5 @@
 // src/version.ts
-var VERSION = "0.2.0-beta.2";
+var VERSION = "0.2.0-beta.4";
 
 // src/core/features.ts
 function isEnabled(config) {

package/dist/index.cjs

@@ -44,7 +44,7 @@ __export(src_exports, {
 module.exports = __toCommonJS(src_exports);
 
 // src/version.ts
-var VERSION = "0.2.0-beta.2";
+var VERSION = "0.2.0-beta.4";
 
 // src/core/features.ts
 function isEnabled(config) {

package/dist/index.d.cts

@@ -1,11 +1,11 @@
-import { P as PreprFeatures, R as ResolvedPreprFeatures, L as Locale, a as PreprSegment, b as PreprVariant, c as PreprToolbarProps, d as PreprPreviewOptions, e as PreprErrorCode, f as PreprHeaders } from './pixel-763p7m6A.cjs';
-export { g as PreprEnvironment, h as PreprEventType, i as PreprFeatureConfig, j as PreprHeaderName, k as PreprPixelConfig, l as PreprToolbarComponentProps, m as PreprToolbarOptions, n as loadTrackingPixel, s as setTrackingParam, t as trackEvent } from './pixel-763p7m6A.cjs';
+import { P as PreprFeatures, R as ResolvedPreprFeatures, L as Locale, a as PreprSegment, b as PreprVariant, c as PreprToolbarProps, d as PreprPreviewOptions, e as PreprErrorCode, f as PreprHeaders } from './pixel-Dd72wuJp.cjs';
+export { g as PreprEnvironment, h as PreprEventType, i as PreprFeatureConfig, j as PreprHeaderName, k as PreprPixelConfig, l as PreprToolbarComponentProps, m as PreprToolbarOptions, n as loadTrackingPixel, s as setTrackingParam, t as trackEvent } from './pixel-Dd72wuJp.cjs';
 
 /**
  * Package version; must match package.json. Lives in its own leaf module so
  * core can import it without cycling through the barrel.
  */
-declare const VERSION = "0.2.0-beta.2";
+declare const VERSION = "0.2.0-beta.4";
 
 /**
  * Resolve a `PreprFeatures` bag to plain booleans, defaulting every omitted key

package/dist/index.d.ts

@@ -1,11 +1,11 @@
-import { P as PreprFeatures, R as ResolvedPreprFeatures, L as Locale, a as PreprSegment, b as PreprVariant, c as PreprToolbarProps, d as PreprPreviewOptions, e as PreprErrorCode, f as PreprHeaders } from './pixel-763p7m6A.js';
-export { g as PreprEnvironment, h as PreprEventType, i as PreprFeatureConfig, j as PreprHeaderName, k as PreprPixelConfig, l as PreprToolbarComponentProps, m as PreprToolbarOptions, n as loadTrackingPixel, s as setTrackingParam, t as trackEvent } from './pixel-763p7m6A.js';
+import { P as PreprFeatures, R as ResolvedPreprFeatures, L as Locale, a as PreprSegment, b as PreprVariant, c as PreprToolbarProps, d as PreprPreviewOptions, e as PreprErrorCode, f as PreprHeaders } from './pixel-Dd72wuJp.js';
+export { g as PreprEnvironment, h as PreprEventType, i as PreprFeatureConfig, j as PreprHeaderName, k as PreprPixelConfig, l as PreprToolbarComponentProps, m as PreprToolbarOptions, n as loadTrackingPixel, s as setTrackingParam, t as trackEvent } from './pixel-Dd72wuJp.js';
 
 /**
  * Package version; must match package.json. Lives in its own leaf module so
  * core can import it without cycling through the barrel.
  */
-declare const VERSION = "0.2.0-beta.2";
+declare const VERSION = "0.2.0-beta.4";
 
 /**
  * Resolve a `PreprFeatures` bag to plain booleans, defaulting every omitted key

package/dist/index.js

@@ -20,7 +20,7 @@ import {
 } from "./chunk-6OOGNVJ4.js";
 
 // src/version.ts
-var VERSION = "0.2.0-beta.2";
+var VERSION = "0.2.0-beta.4";
 
 // src/core/server.ts
 var PreprError = class extends Error {

package/dist/nextjs/components.cjs

@@ -26,7 +26,7 @@ __export(components_exports, {
 });
 module.exports = __toCommonJS(components_exports);
 var import_navigation = require("next/navigation");
-var import_react = require("react");
+var import_react2 = require("react");
 
 // src/core/constants.ts
 var COOKIE_PREVIEW_MODE = "Prepr-Preview-Mode";
@@ -2172,6 +2172,9 @@ function createPreprPreview(opts = {}) {
   return controller;
 }
 
+// src/react/components.ts
+var import_react = require("react");
+
 // src/core/pixel.ts
 var PIXEL_SCRIPT_URL = "https://cdn.tracking.prepr.io/js/prepr-v2.min.js";
 var CACHE_BUST_INTERVAL_MS = 24 * 60 * 60 * 1e3;
@@ -2210,6 +2213,17 @@ function loadTrackingPixel(trackingId, config) {
   queueFn("event", "pageload");
 }
 
+// src/react/components.ts
+function PreprTrackingPixel({
+  id,
+  config
+}) {
+  (0, import_react.useEffect)(() => {
+    loadTrackingPixel(id, config);
+  }, []);
+  return null;
+}
+
 // src/nextjs/components.ts
 function PreprToolbar({
   options,
@@ -2217,7 +2231,7 @@ function PreprToolbar({
 }) {
   const router = (0, import_navigation.useRouter)();
   const pathname = (0, import_navigation.usePathname)();
-  (0, import_react.useEffect)(() => {
+  (0, import_react2.useEffect)(() => {
     const toolbar = createPreprPreview({
       props,
       options,
@@ -2230,12 +2244,6 @@ function PreprToolbar({
   }, []);
   return null;
 }
-function PreprTrackingPixel({ id, config }) {
-  (0, import_react.useEffect)(() => {
-    loadTrackingPixel(id, config);
-  }, []);
-  return null;
-}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   PreprToolbar,

package/dist/nextjs/components.d.cts

@@ -1,4 +1,18 @@
-import { l as PreprToolbarComponentProps, k as PreprPixelConfig } from '../pixel-763p7m6A.cjs';
+import { k as PreprPixelConfig, l as PreprToolbarComponentProps } from '../pixel-Dd72wuJp.cjs';
+
+interface PreprTrackingPixelProps {
+    /** Prepr tracking/access token. */
+    id: string;
+    config?: PreprPixelConfig;
+}
+/**
+ * Loads Prepr's CDN tracking pixel on mount. Renders nothing.
+ *
+ * The pixel queues a single `pageload` event when it installs. Client-side
+ * route changes emit nothing on their own — call `trackEvent('pageload')` from
+ * the router to count them.
+ */
+declare function PreprTrackingPixel({ id, config, }: PreprTrackingPixelProps): null;
 
 /**
  * Mounts the Prepr toolbar and wires it to the Next.js router so segment/variant
@@ -6,12 +20,5 @@ import { l as PreprToolbarComponentProps, k as PreprPixelConfig } from '../pixel
  * `createPreprPreview` mounts imperatively.
  */
 declare function PreprToolbar({ options, ...props }: PreprToolbarComponentProps): null;
-interface PreprTrackingPixelProps {
-    /** Prepr tracking/access token. */
-    id: string;
-    config?: PreprPixelConfig;
-}
-/** Loads Prepr's CDN tracking pixel on mount. Renders nothing. */
-declare function PreprTrackingPixel({ id, config }: PreprTrackingPixelProps): null;
 
 export { PreprToolbar, PreprTrackingPixel, type PreprTrackingPixelProps };

package/dist/nextjs/components.d.ts

@@ -1,4 +1,18 @@
-import { l as PreprToolbarComponentProps, k as PreprPixelConfig } from '../pixel-763p7m6A.js';
+import { k as PreprPixelConfig, l as PreprToolbarComponentProps } from '../pixel-Dd72wuJp.js';
+
+interface PreprTrackingPixelProps {
+    /** Prepr tracking/access token. */
+    id: string;
+    config?: PreprPixelConfig;
+}
+/**
+ * Loads Prepr's CDN tracking pixel on mount. Renders nothing.
+ *
+ * The pixel queues a single `pageload` event when it installs. Client-side
+ * route changes emit nothing on their own — call `trackEvent('pageload')` from
+ * the router to count them.
+ */
+declare function PreprTrackingPixel({ id, config, }: PreprTrackingPixelProps): null;
 
 /**
  * Mounts the Prepr toolbar and wires it to the Next.js router so segment/variant
@@ -6,12 +20,5 @@ import { l as PreprToolbarComponentProps, k as PreprPixelConfig } from '../pixel
  * `createPreprPreview` mounts imperatively.
  */
 declare function PreprToolbar({ options, ...props }: PreprToolbarComponentProps): null;
-interface PreprTrackingPixelProps {
-    /** Prepr tracking/access token. */
-    id: string;
-    config?: PreprPixelConfig;
-}
-/** Loads Prepr's CDN tracking pixel on mount. Renders nothing. */
-declare function PreprTrackingPixel({ id, config }: PreprTrackingPixelProps): null;
 
 export { PreprToolbar, PreprTrackingPixel, type PreprTrackingPixelProps };

package/dist/nextjs/components.js

@@ -6,14 +6,28 @@ import {
 
 // src/nextjs/components.ts
 import { usePathname, useRouter } from "next/navigation";
+import { useEffect as useEffect2 } from "react";
+
+// src/react/components.ts
 import { useEffect } from "react";
+function PreprTrackingPixel({
+  id,
+  config
+}) {
+  useEffect(() => {
+    loadTrackingPixel(id, config);
+  }, []);
+  return null;
+}
+
+// src/nextjs/components.ts
 function PreprToolbar({
   options,
   ...props
 }) {
   const router = useRouter();
   const pathname = usePathname();
-  useEffect(() => {
+  useEffect2(() => {
     const toolbar = createPreprPreview({
       props,
       options,
@@ -26,12 +40,6 @@ function PreprToolbar({
   }, []);
   return null;
 }
-function PreprTrackingPixel({ id, config }) {
-  useEffect(() => {
-    loadTrackingPixel(id, config);
-  }, []);
-  return null;
-}
 export {
   PreprToolbar,
   PreprTrackingPixel

package/dist/nextjs/index.cjs

@@ -38,7 +38,7 @@ module.exports = __toCommonJS(nextjs_exports);
 var import_server = require("next/server");
 
 // src/version.ts
-var VERSION = "0.2.0-beta.2";
+var VERSION = "0.2.0-beta.4";
 
 // src/core/constants.ts
 var COOKIE_PREVIEW_MODE = "Prepr-Preview-Mode";

package/dist/nextjs/index.d.cts

@@ -30,8 +30,18 @@ interface PreprFeatures {
     editMode?: PreprFeatureConfig;
 }
 interface PreprToolbarProps {
-    readonly activeSegment: string | null;
-    readonly activeVariant: string | null;
+    /**
+     * Server-resolved active segment. Optional: omit it with `segments`
+     * disabled, where there is nothing to resolve. When enabled and omitted,
+     * the persisted cookie is used.
+     */
+    readonly activeSegment?: string | null;
+    /**
+     * Server-resolved active A/B variant. Optional: omit it with `abTesting`
+     * disabled, where there is nothing to resolve. When enabled and omitted,
+     * the persisted cookie is used.
+     */
+    readonly activeVariant?: string | null;
     /** Available segments to personalize on. */
     readonly segments?: readonly PreprSegment[];
     /** @deprecated Alias for `segments`. */

package/dist/nextjs/index.d.ts

@@ -30,8 +30,18 @@ interface PreprFeatures {
     editMode?: PreprFeatureConfig;
 }
 interface PreprToolbarProps {
-    readonly activeSegment: string | null;
-    readonly activeVariant: string | null;
+    /**
+     * Server-resolved active segment. Optional: omit it with `segments`
+     * disabled, where there is nothing to resolve. When enabled and omitted,
+     * the persisted cookie is used.
+     */
+    readonly activeSegment?: string | null;
+    /**
+     * Server-resolved active A/B variant. Optional: omit it with `abTesting`
+     * disabled, where there is nothing to resolve. When enabled and omitted,
+     * the persisted cookie is used.
+     */
+    readonly activeVariant?: string | null;
     /** Available segments to personalize on. */
     readonly segments?: readonly PreprSegment[];
     /** @deprecated Alias for `segments`. */

package/dist/nextjs/index.js

@@ -2,7 +2,7 @@
 import { NextResponse } from "next/server";
 
 // src/version.ts
-var VERSION = "0.2.0-beta.2";
+var VERSION = "0.2.0-beta.4";
 
 // src/core/constants.ts
 var COOKIE_PREVIEW_MODE = "Prepr-Preview-Mode";

package/dist/nuxt/index.cjs

@@ -35,7 +35,7 @@ __export(nuxt_exports, {
 module.exports = __toCommonJS(nuxt_exports);
 
 // src/version.ts
-var VERSION = "0.2.0-beta.2";
+var VERSION = "0.2.0-beta.4";
 
 // src/core/constants.ts
 var COOKIE_PREVIEW_MODE = "Prepr-Preview-Mode";

package/dist/nuxt/index.d.cts

@@ -27,8 +27,18 @@ interface PreprFeatures {
     editMode?: PreprFeatureConfig;
 }
 interface PreprToolbarProps {
-    readonly activeSegment: string | null;
-    readonly activeVariant: string | null;
+    /**
+     * Server-resolved active segment. Optional: omit it with `segments`
+     * disabled, where there is nothing to resolve. When enabled and omitted,
+     * the persisted cookie is used.
+     */
+    readonly activeSegment?: string | null;
+    /**
+     * Server-resolved active A/B variant. Optional: omit it with `abTesting`
+     * disabled, where there is nothing to resolve. When enabled and omitted,
+     * the persisted cookie is used.
+     */
+    readonly activeVariant?: string | null;
     /** Available segments to personalize on. */
     readonly segments?: readonly PreprSegment[];
     /** @deprecated Alias for `segments`. */

package/dist/nuxt/index.d.ts

@@ -27,8 +27,18 @@ interface PreprFeatures {
     editMode?: PreprFeatureConfig;
 }
 interface PreprToolbarProps {
-    readonly activeSegment: string | null;
-    readonly activeVariant: string | null;
+    /**
+     * Server-resolved active segment. Optional: omit it with `segments`
+     * disabled, where there is nothing to resolve. When enabled and omitted,
+     * the persisted cookie is used.
+     */
+    readonly activeSegment?: string | null;
+    /**
+     * Server-resolved active A/B variant. Optional: omit it with `abTesting`
+     * disabled, where there is nothing to resolve. When enabled and omitted,
+     * the persisted cookie is used.
+     */
+    readonly activeVariant?: string | null;
     /** Available segments to personalize on. */
     readonly segments?: readonly PreprSegment[];
     /** @deprecated Alias for `segments`. */

package/dist/nuxt/index.js

@@ -1,5 +1,5 @@
 // src/version.ts
-var VERSION = "0.2.0-beta.2";
+var VERSION = "0.2.0-beta.4";
 
 // src/core/constants.ts
 var COOKIE_PREVIEW_MODE = "Prepr-Preview-Mode";

package/dist/{pixel-763p7m6A.d.cts → pixel-Dd72wuJp.d.cts}

@@ -70,8 +70,18 @@ interface PreprPreviewOptions extends PreprToolbarOptions {
     allowedEditorOrigins?: string[];
 }
 interface PreprToolbarProps {
-    readonly activeSegment: string | null;
-    readonly activeVariant: string | null;
+    /**
+     * Server-resolved active segment. Optional: omit it with `segments`
+     * disabled, where there is nothing to resolve. When enabled and omitted,
+     * the persisted cookie is used.
+     */
+    readonly activeSegment?: string | null;
+    /**
+     * Server-resolved active A/B variant. Optional: omit it with `abTesting`
+     * disabled, where there is nothing to resolve. When enabled and omitted,
+     * the persisted cookie is used.
+     */
+    readonly activeVariant?: string | null;
     /** Available segments to personalize on. */
     readonly segments?: readonly PreprSegment[];
     /** @deprecated Alias for `segments`. */

package/dist/{pixel-763p7m6A.d.ts → pixel-Dd72wuJp.d.ts}

@@ -70,8 +70,18 @@ interface PreprPreviewOptions extends PreprToolbarOptions {
     allowedEditorOrigins?: string[];
 }
 interface PreprToolbarProps {
-    readonly activeSegment: string | null;
-    readonly activeVariant: string | null;
+    /**
+     * Server-resolved active segment. Optional: omit it with `segments`
+     * disabled, where there is nothing to resolve. When enabled and omitted,
+     * the persisted cookie is used.
+     */
+    readonly activeSegment?: string | null;
+    /**
+     * Server-resolved active A/B variant. Optional: omit it with `abTesting`
+     * disabled, where there is nothing to resolve. When enabled and omitted,
+     * the persisted cookie is used.
+     */
+    readonly activeVariant?: string | null;
     /** Available segments to personalize on. */
     readonly segments?: readonly PreprSegment[];
     /** @deprecated Alias for `segments`. */