Prepr Toolkit upgrade guide

Learn how to upgrade your app to a newer Prepr Toolkit version.

We release new Prepr Toolkit versions regularly, and we add a version to this upgrade guide when it contains backwards-incompatible changes. The current version is 0.4.0. If you’re using an older version and you’re ready to upgrade, follow the instructions below.

How to upgrade to a newer Prepr Toolkit version

The Prepr Toolkit follows semantic versioning. Minor and patch releases (for example, 0.4.0 to 0.5.0) are backwards compatible. Only major releases (for example, 1.x.x to 2.0.0) contain breaking changes. When a major version is released, we encourage you to upgrade as soon as possible.

To upgrade to a newer Prepr Toolkit version, simply reinstall the latest version.


npm install @preprio/toolkit

For more specific implementations, check out the complete guides for your preferred front-end framework.

Released Prepr Toolkit versions

You can check out the previous Prepr Toolkit releases below.

Version	Release date	end-of-life on
0.4.0	2026-09-17	t.b.a

Version `0.4.0`

What’s new

The middleware and getPreprHeaders send a Prepr-Package request header with the toolkit version.
The tracking pixel reports the toolkit version before the pageload event.

What’s changed

The toolkit is no longer labeled beta and follows semantic versioning: breaking changes only ship in a major release.

Migrating from the Prepr Next.js package

The Prepr Toolkit @preprio/toolkit replaces the Prepr Next.js package @preprio/prepr-nextjs (last release 2.2.7).

Here are the key differences between the Prepr Next.js package and Prepr Toolkit.

Feature	Prepr Next.js package	Prepr Toolkit
Supported frameworks	Next.js	Next.js, Astro, Nuxt, SvelteKit, React, framework-free core
Included examples	No	Yes
Preview mode handling	Handled by the package, based on the `PREPR_ENV` environment variable	Handled by your front end: pass a `preview` flag and render the toolbar conditionally
Runtime dependencies	7 (including Headless UI, Zustand and Tailwind Merge)	2 (`@vercel/stega` and `preact`), so less code ships to your pages
Toolbar styling	Import css in front end	Styling in toolkit
Toolbar state handling	Renders with no props and reads state from wrapper	Takes state directly
Package imports	Separate entry points for middleware, server helpers and components	Single entry point per framework

For more technical details, check out the GitHub migration guide .

If you’ve installed the Prepr Next.js package and want to replace it with the latest Prepr Toolkit, follow the guide below.

Replace Prepr Next.js package installation


npm uninstall @preprio/prepr-nextjs
npm install @preprio/toolkit

Replace package imports

Update the following code by replacing the Prepr Next.js imports.

./src/middleware.ts


-import createPreprMiddleware from '@preprio/prepr-nextjs/middleware';
+import { createPreprMiddleware } from '@preprio/toolkit/nextjs';
 
 export function middleware(request: NextRequest) {
   return createPreprMiddleware(request, { preview: true });
 }

./src/app/layout.tsx


-import { getToolbarProps, extractAccessToken } from '@preprio/prepr-nextjs/server';
-import {
-  PreprToolbar,
-  PreprToolbarProvider,
-  PreprTrackingPixel,
-} from '@preprio/prepr-nextjs/react';
-import '@preprio/prepr-nextjs/index.css';
+import {
+  getToolbarProps,
+  extractAccessToken,
+  PreprToolbar,
+  PreprTrackingPixel,
+} from '@preprio/toolkit/nextjs';
 
 export default async function RootLayout({ children }) {
   const toolbarProps = await getToolbarProps(process.env.PREPR_GRAPHQL_URL!);
   const accessToken = extractAccessToken(process.env.PREPR_GRAPHQL_URL!);
 
   return (
     <html>
-      <head>{accessToken && <PreprTrackingPixel accessToken={accessToken} />}</head>
+      <head>{accessToken && <PreprTrackingPixel id={accessToken} />}</head>
       <body>
-        <PreprToolbarProvider props={toolbarProps}>
-          {children}
-          <PreprToolbar />
-        </PreprToolbarProvider>
+        {children}
+        <PreprToolbar {...toolbarProps} />
       </body>
     </html>
   );
 }


-import {
-  getPreprUUID,
-  getActiveSegment,
-  getActiveVariant,
-  getPreprHeaders,
-} from '@preprio/prepr-nextjs/server';
+import {
+  getPreprUUID,
+  getActiveSegment,
+  getActiveVariant,
+  getPreprHeaders,
+} from '@preprio/toolkit/nextjs';

The preview gate is yours

You decide when preview is on and pass it to the middleware, and you decide whether to call getToolbarProps and render <PreprToolbar /> at all.


// middleware.ts — resolve `preview` however your deployment already does.
const preview = process.env.VERCEL_ENV !== 'production';
return createPreprMiddleware(request, { preview });


// layout.tsx — skip the fetch and the toolbar entirely outside preview.
const preview = process.env.VERCEL_ENV !== 'production';
const toolbarProps = preview
  ? await getToolbarProps(process.env.PREPR_GRAPHQL_URL!)
  : null;
 
return (
  <body>
    {children}
    {toolbarProps && <PreprToolbar {...toolbarProps} />}
  </body>
);

<PreprToolbar /> doesn’t read the middleware’s preview flag, it mounts whenever it renders. Rendering it conditionally is what keeps the toolbar out of production.

The toolkit reads no environment variables of its own. Every value is passed in explicitly.

The getToolbarProps still swallows fetch failures and returns empty data rather than throwing, so a Prepr outage degrades to “no toolbar” instead of a broken page.

Optional: turn features off

New in the toolkit — segments, A/B testing and edit mode can each be disabled, in the middleware and on the component. Pass the same object to both.


const preprFeatures = { segments: true, abTesting: true, editMode: false };


createPreprMiddleware(request, { preview, features: preprFeatures });
const toolbarProps = await getToolbarProps(
  process.env.PREPR_GRAPHQL_URL!,
  preprFeatures
);


<PreprToolbar {...toolbarProps} options={{ features: preprFeatures }} />

Passing the object to getToolbarProps as well skips the segments request entirely when segments are disabled.

Verify your migration

You can make sure the migration is successful by running the following verification steps:

Log await getPreprHeaders() in a Server Component, switch a segment and a variant in the toolbar, and confirm Prepr-Segments / Prepr-ABtesting appear. These are request headers forwarded to your server code, so they don’t show up in the response (curl -I won’t list them).
Load a page with preview: true and confirm the toolbar mounts.
Switch a segment and a variant; the page should navigate and the content change.
Confirm the tracking pixel fires a pageload event.
Deploy with preview resolving to false and confirm no toolbar renders. This relies on the conditional render from the preview gate step.

Check out a working Next.js example in the Prepr Toolkit repo .