npm - @preprio/prepr-nextjs - Versions diffs - 2.0.0-alpha.9 → 2.0.0 - Mend

@preprio/prepr-nextjs 2.0.0-alpha.9 → 2.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (32) hide show

package/README.md +728 -110
package/dist/chunk-QZTUT4DH.js +2 -0
package/dist/chunk-QZTUT4DH.js.map +1 -0
package/dist/metafile-cjs.json +1 -1
package/dist/metafile-esm.json +1 -1
package/dist/middleware/index.cjs +1 -1
package/dist/middleware/index.cjs.map +1 -1
package/dist/middleware/index.d.cts +20 -4
package/dist/middleware/index.d.ts +20 -4
package/dist/middleware/index.js +1 -1
package/dist/middleware/index.js.map +1 -1
package/dist/react/index.cjs +6 -1
package/dist/react/index.cjs.map +1 -1
package/dist/react/index.d.cts +57 -19
package/dist/react/index.d.ts +57 -19
package/dist/react/index.js +6 -1
package/dist/react/index.js.map +1 -1
package/dist/server/index.cjs +2 -2
package/dist/server/index.cjs.map +1 -1
package/dist/server/index.d.cts +50 -11
package/dist/server/index.d.ts +50 -11
package/dist/server/index.js +2 -2
package/dist/server/index.js.map +1 -1
package/dist/types/index.d.cts +33 -13
package/dist/types/index.d.ts +33 -13
package/dist/utils/index.cjs +1 -1
package/dist/utils/index.cjs.map +1 -1
package/dist/utils/index.d.cts +39 -9
package/dist/utils/index.d.ts +39 -9
package/dist/utils/index.js +1 -1
package/dist/utils/index.js.map +1 -1
package/package.json +13 -24

package/README.md CHANGED Viewed

@@ -1,177 +1,795 @@
-# The Prepr Next.js package
+# Prepr Next.js Package
-## Getting Started
-<hr>
-The Prepr Next.js package offers some helper functions and a preview toolbar component for an
-easier personalization & A/B testing implementation in your Next.js project.
+A powerful TypeScript library that provides preview functionality, visual editing capabilities, and A/B testing for [Prepr CMS](https://prepr.io) integrated with Next.js applications.
-## Installation
-<hr>
-To install the Prepr Next.js package, run the following command:
+## ⚡ Quick Start
 ```bash
+# Install the package
 npm install @preprio/prepr-nextjs
+# or
+pnpm add @preprio/prepr-nextjs
 ```
-Next, add the `PREPR_ENV` variable to the `.env` file. You can enable the Prepr preview toolbar for a staging environment by setting the value to `preview`.
+Add environment variables to your `.env`:
 ```bash
+PREPR_GRAPHQL_URL=https://graphql.prepr.io/{YOUR_ACCESS_TOKEN}
 PREPR_ENV=preview
 ```
-When you're launching your project to production, then set the `PREPR_ENV` environment variable to `production`.
+Set up middleware in `middleware.ts`:
-Next, implement the `PreprMiddleware` function. Go to your `middleware.js` or the `middleware.ts`
-file. If you don't have this file, you can create it in the root of your project.
+```typescript
+import type { NextRequest } from 'next/server'
+import createPreprMiddleware from '@preprio/prepr-nextjs/middleware'
-Then add the following code to the `middleware.ts` file:
-```javascript
+export function middleware(request: NextRequest) {
+  return createPreprMiddleware(request, { preview: true })
+}
+```
+Add toolbar and tracking to your layout:
+```typescript
+import { getToolbarProps, extractAccessToken } from '@preprio/prepr-nextjs/server'
+import { PreprToolbar, PreprToolbarProvider, PreprTrackingPixel } from '@preprio/prepr-nextjs/react'
+import '@preprio/prepr-nextjs/index.css'
+export default async function RootLayout({ children }: { children: React.ReactNode }) {
+  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>
+      <body>
+        <PreprToolbarProvider props={toolbarProps}>
+          <PreprToolbar />
+          {children}
+        </PreprToolbarProvider>
+      </body>
+    </html>
+  )
+}
+```
+## 📋 Prerequisites
+Before installing, ensure you have:
+- **Next.js 13.0.0 or later** (supports App Router)
+- **React 17.0.0 or later** (React 18+ recommended)
+- **Node.js 16.0.0 or later**
+- **A Prepr account**
+- **Prepr GraphQL URL** (found in Settings → Access tokens)
+### Prepr Account Setup
+1. **Create a Prepr account** at [prepr.io](https://prepr.io)
+2. **Get your GraphQL URL**:
+   - Go to Settings → Access tokens
+   - Find your GraphQL Preview access token
+       ![preview API URL](https://assets-site.prepr.io//35k5a4g45wuy-preview-access-token.png)
+   - Copy the full GraphQL URL (e.g., `https://graphql.prepr.io/e6f7a0521f11e5149ce65b0e9f372ced2dfc923490890e7f225da1db84cxxxxx`)
+   - The URL format is always `https://graphql.prepr.io/{YOUR_ACCESS_TOKEN}`
+3. **Enable edit mode** (for toolbar):
+   - Open your GraphQL Preview access token
+   - Check "Enable edit mode"
+   - Save the token
+     ![Preview access token](https://assets-site.prepr.io/229kaekn7m96//preview-access-token-enable-edit-mode.png)
+## 🔧 Installation & Setup
+### 1. Install the Package
+```bash
+npm install @preprio/prepr-nextjs
+# or
+pnpm add @preprio/prepr-nextjs
+# or
+yarn add @preprio/prepr-nextjs
+```
+### 2. Environment Configuration
+Create or update your `.env` file:
+```bash
+# Required: Your Prepr GraphQL endpoint
+PREPR_GRAPHQL_URL=https://graphql.prepr.io/{YOUR_ACCESS_TOKEN}
+# Required: Environment mode
+PREPR_ENV=preview    # Use 'preview' for staging/development
+# PREPR_ENV=production # Use 'production' for live sites
+# Optional: Enable debug logging (development only)
+# PREPR_DEBUG=true
+```
+> **Important**: Replace `{YOUR_ACCESS_TOKEN}` with your actual Prepr access token from Settings → Access tokens.
+### 3. Middleware Setup
+The middleware handles personalization headers, customer ID tracking, and preview mode functionality.
+#### TypeScript Setup
+Create or update `middleware.ts` in your project root:
+```typescript
 import type { NextRequest } from 'next/server'
 import createPreprMiddleware from '@preprio/prepr-nextjs/middleware'
 export function middleware(request: NextRequest) {
-    return createPreprMiddleware(request)
+  return createPreprMiddleware(request, {
+    preview: process.env.PREPR_ENV === 'preview'
+  })
+}
+export const config = {
+  matcher: [
+    /*
+     * Match all request paths except for the ones starting with:
+     * - api (API routes)
+     * - _next/static (static files)
+     * - _next/image (image optimization files)
+     * - favicon.ico (favicon file)
+     */
+    '/((?!api|_next/static|_next/image|favicon.ico).*)',
+  ],
 }
 ```
-Or add the following code to the `middleware.js` file:
+#### JavaScript Setup
+Create or update `middleware.js` in your project root:
 ```javascript
 import createPreprMiddleware from '@preprio/prepr-nextjs/middleware'
-export async function middleware(request: NextRequest) {
-    return createPreprMiddleware(request)
+export async function middleware(request) {
+  return createPreprMiddleware(request, {
+    preview: process.env.PREPR_ENV === 'preview'
+  })
+}
+export const config = {
+  matcher: [
+    '/((?!api|_next/static|_next/image|favicon.ico).*)',
+  ],
 }
 ```
-### Middleware functionality
-The `PreprMiddleware` accepts a request and optional response property and returns a `NextRequest` object.
-This is done so you are able to chain your own middleware to it.
+#### Chaining with Existing Middleware
-The `PreprMiddleware` function checks every request if the `__prepr_uid` cookie is set. If it isn't, the function generates a new UUID and sets it as a cookie. Then it returns a `Prepr-Customer-Id` header with the value of the `__prepr_uid` cookie to simplify your personalization and A/B testing implementation.
+##### Basic Chaining Pattern
-If the `PREPR_ENV` environment variable is set to `preview`, the `PreprMiddleware` function also checks for searchParams `segments` and `a-b-testing` in the URL.
-If these searchParams are set, the PreprMiddleware sets the `Prepr-Segments` and `Prepr-AB-Testing` headers with the values of the searchParams, and stores its value in a cookie.
+```typescript
+import type { NextRequest, NextResponse } from 'next/server'
+import createPreprMiddleware from '@preprio/prepr-nextjs/middleware'
-## Usage
-To set your API request headers to query adaptive content or A/B testing content, you can call the `getPreprHeaders()` helper function. It returns an array of headers that you can spread in your fetch call.
-See the example code below in the `page.tsx` file.
+export function middleware(request: NextRequest) {
+  // Start with your existing middleware
+  let response = NextResponse.next()
+  // Add your custom logic
+  if (request.nextUrl.pathname.startsWith('/admin')) {
+    response.headers.set('x-admin-route', 'true')
+  }
+  // Chain with Prepr middleware
+  return createPreprMiddleware(request, response, {
+    preview: process.env.PREPR_ENV === 'preview'
+  })
+}
+```
-```javascript
+##### With next-intl Integration
+```typescript
+import type { NextRequest } from 'next/server'
+import createIntlMiddleware from 'next-intl/middleware'
+import createPreprMiddleware from '@preprio/prepr-nextjs/middleware'
+const intlMiddleware = createIntlMiddleware({
+  locales: ['en', 'de', 'fr'],
+  defaultLocale: 'en'
+})
+export function middleware(request: NextRequest) {
+  // First run internationalization middleware
+  const intlResponse = intlMiddleware(request)
+  // If next-intl returns a redirect, return it immediately
+  if (intlResponse.status >= 300 && intlResponse.status < 400) {
+    return intlResponse
+  }
+  // Otherwise, chain with Prepr middleware
+  return createPreprMiddleware(request, intlResponse, {
+    preview: process.env.PREPR_ENV === 'preview'
+  })
+}
+export const config = {
+  matcher: [
+    '/((?!api|_next/static|_next/image|favicon.ico).*)',
+  ],
+}
+```
+##### Advanced Chaining with Multiple Middlewares
+```typescript
+import type { NextRequest, NextResponse } from 'next/server'
+import createPreprMiddleware from '@preprio/prepr-nextjs/middleware'
+import { authMiddleware } from '@/lib/auth'
+import { rateLimitMiddleware } from '@/lib/rate-limit'
+export function middleware(request: NextRequest) {
+  let response = NextResponse.next()
+  // 1. Rate limiting
+  response = rateLimitMiddleware(request, response)
+  // 2. Authentication (if needed)
+  if (request.nextUrl.pathname.startsWith('/dashboard')) {
+    response = authMiddleware(request, response)
+  }
+  // 3. Custom headers
+  response.headers.set('x-custom-header', 'my-value')
+  // 4. Finally, Prepr middleware
+  return createPreprMiddleware(request, response, {
+    preview: process.env.PREPR_ENV === 'preview'
+  })
+}
+```
+##### Conditional Chaining
+```typescript
+import type { NextRequest, NextResponse } from 'next/server'
+import createPreprMiddleware from '@preprio/prepr-nextjs/middleware'
+export function middleware(request: NextRequest) {
+  const { pathname } = request.nextUrl
+  // Skip Prepr middleware for API routes
+  if (pathname.startsWith('/api/')) {
+    return NextResponse.next()
+  }
+  // Apply different logic based on route
+  let response = NextResponse.next()
+  if (pathname.startsWith('/blog')) {
+    response.headers.set('x-content-type', 'blog')
+  } else if (pathname.startsWith('/product')) {
+    response.headers.set('x-content-type', 'product')
+  }
+  // Always apply Prepr middleware for content routes
+  return createPreprMiddleware(request, response, {
+    preview: process.env.PREPR_ENV === 'preview'
+  })
+}
+```
+### 4. Layout Integration
+#### App Router (Next.js 13+)
+The toolbar should only be rendered in preview environments to avoid showing development tools in production. Here are several approaches for conditional rendering:
+##### Basic Conditional Rendering
+Update your `app/layout.tsx`:
+```typescript
+import { getToolbarProps } from '@preprio/prepr-nextjs/server'
+import {
+  PreprToolbar,
+  PreprToolbarProvider
+} from '@preprio/prepr-nextjs/react'
+import '@preprio/prepr-nextjs/index.css'
+export default async function RootLayout({
+  children,
+}: {
+  children: React.ReactNode
+}) {
+  const isPreview = process.env.PREPR_ENV === 'preview'
+  const toolbarProps = isPreview ? await getToolbarProps(process.env.PREPR_GRAPHQL_URL!) : null
+  return (
+    <html lang="en">
+      <body>
+        {isPreview && toolbarProps ? (
+          <PreprToolbarProvider props={toolbarProps}>
+            <PreprToolbar />
+            {children}
+          </PreprToolbarProvider>
+        ) : (
+          children
+        )}
+      </body>
+    </html>
+  )
+}
+```
+##### Advanced Conditional Rendering with Error Handling
+For production applications, you may want more robust error handling:
+```typescript
+import { getToolbarProps } from '@preprio/prepr-nextjs/server'
+import {
+  PreprToolbar,
+  PreprToolbarProvider
+} from '@preprio/prepr-nextjs/react'
+import '@preprio/prepr-nextjs/index.css'
+export default async function RootLayout({
+  children,
+}: {
+  children: React.ReactNode
+}) {
+  const isPreview = process.env.PREPR_ENV === 'preview'
+  const graphqlUrl = process.env.PREPR_GRAPHQL_URL
+  // Only fetch toolbar props in preview mode with valid URL
+  let toolbarProps = null
+  if (isPreview && graphqlUrl) {
+    try {
+      toolbarProps = await getToolbarProps(graphqlUrl)
+    } catch (error) {
+      console.error('Failed to load toolbar:', error)
+      // Continue without toolbar instead of breaking the app
+    }
+  }
+  return (
+    <html lang="en">
+      <body>
+        {isPreview && toolbarProps ? (
+          <PreprToolbarProvider props={toolbarProps}>
+            <PreprToolbar />
+            {children}
+          </PreprToolbarProvider>
+        ) : (
+          children
+        )}
+      </body>
+    </html>
+  )
+}
+```
+##### Component-Level Conditional Rendering
+For better separation of concerns, create a dedicated component:
+```typescript
+// components/PreviewWrapper.tsx
+import { getToolbarProps } from '@preprio/prepr-nextjs/server'
+import {
+  PreprToolbar,
+  PreprToolbarProvider
+} from '@preprio/prepr-nextjs/react'
+interface PreviewWrapperProps {
+  children: React.ReactNode
+}
+export default async function PreviewWrapper({ children }: PreviewWrapperProps) {
+  const isPreview = process.env.PREPR_ENV === 'preview'
+  if (!isPreview) {
+    return <>{children}</>
+  }
+  const toolbarProps = await getToolbarProps(process.env.PREPR_GRAPHQL_URL!)
+  return (
+    <PreprToolbarProvider props={toolbarProps}>
+      <PreprToolbar />
+      {children}
+    </PreprToolbarProvider>
+  )
+}
+// app/layout.tsx
+import PreviewWrapper from '@/components/PreviewWrapper'
+import '@preprio/prepr-nextjs/index.css'
+export default function RootLayout({
+  children,
+}: {
+  children: React.ReactNode
+}) {
+  return (
+    <html lang="en">
+      <body>
+        <PreviewWrapper>
+          {children}
+        </PreviewWrapper>
+      </body>
+    </html>
+  )
+}
+```
+#### Why Conditional Rendering Matters
+1. **Performance**: Prevents unnecessary API calls in production
+2. **Security**: Avoids exposing preview functionality to end users
+3. **Bundle Size**: Excludes toolbar code from production builds
+4. **User Experience**: Ensures clean production UI without development tools
+#### Best Practices for Conditional Rendering
+- **Environment Variables**: Always use environment variables to control preview mode
+- **Error Boundaries**: Wrap preview components in error boundaries to prevent crashes
+- **Fallback UI**: Always provide a fallback when toolbar fails to load
+- **TypeScript Safety**: Use proper type guards when checking conditions
+- **Bundle Optimization**: Consider dynamic imports for preview-only code
+```typescript
+// Dynamic import example for advanced optimization
+const ToolbarDynamic = dynamic(
+  () => import('@preprio/prepr-nextjs/react').then(mod => mod.PreprToolbar),
+  {
+    ssr: false,
+    loading: () => <div>Loading preview tools...</div>
+  }
+)
+```
+### 5. User Tracking Setup
+The tracking pixel is essential for collecting user interaction data and enabling personalization features. It should be included in all environments (both preview and production).
+#### Basic Setup
+Add the tracking pixel to your layout's `<head>` section:
+```typescript
+import { extractAccessToken } from '@preprio/prepr-nextjs/server'
+import { PreprTrackingPixel } from '@preprio/prepr-nextjs/react'
+export default function RootLayout({ children }: { children: React.ReactNode }) {
+  const accessToken = extractAccessToken(process.env.PREPR_GRAPHQL_URL!)
+  return (
+    <html>
+      <head>
+        {accessToken && <PreprTrackingPixel accessToken={accessToken!} />}
+      </head>
+      <body>{children}</body>
+    </html>
+  )
+}
+```
+#### Alternative: Body Placement
+You can also place the tracking pixel in the body if needed:
+```typescript
+export default function RootLayout({ children }: { children: React.ReactNode }) {
+  const accessToken = extractAccessToken(process.env.PREPR_GRAPHQL_URL!)
+  return (
+    <html>
+      <body>
+        {accessToken && <PreprTrackingPixel accessToken={accessToken!} />}
+        {children}
+      </body>
+    </html>
+  )
+}
+```
+### 6. API Integration
+Use the `getPreprHeaders()` helper function in your data fetching to enable personalization and A/B testing:
+#### With Apollo Client
+```typescript
 import { getClient } from '@/lib/client'
-import { GetPageBySlugDocument, GetPageBySlugQuery } from '@/gql/graphql'
+import { GetPageBySlugDocument } from '@/gql/graphql'
 import { getPreprHeaders } from '@preprio/prepr-nextjs/server'
-const getData = async () => {
-    // Fetching the data using Apollo Client
-    const {data} = await getClient().query < GetPageBySlugQuery > ({
-        query: GetPageBySlugDocument,
-        variables: {
-            slug: '/',
-        },
-        context: {
-            // Call the getPreprHeaders function to get the appropriate headers
-            headers: getPreprHeaders(),
-        },
-        fetchPolicy: 'no-cache',
-    })
+const getData = async (slug: string) => {
+  const { data } = await getClient().query({
+    query: GetPageBySlugDocument,
+    variables: { slug },
+    context: {
+      headers: await getPreprHeaders(),
+    },
+    fetchPolicy: 'no-cache',
+  })
+  return data
 }
 ```
-See the JavaScript example code below in the `page.js`file.
-```javascript
-import { getClient } from '@/lib/client'
-import { GetPageBySlug } from '@/queries/get-page-by-slug';
+#### With Fetch API
+```typescript
 import { getPreprHeaders } from '@preprio/prepr-nextjs/server'
-const getData = async () => {
-    // Fetching the data using Apollo Client
-    const { data } = await client.query({
-    query: GetPageBySlug,
-    variables: {
-        slug: '/',
+const getData = async (slug: string) => {
+  const headers = await getPreprHeaders()
+  const response = await fetch(process.env.PREPR_GRAPHQL_URL!, {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+      ...headers,
     },
-    context: {
-            // Call the getPreprHeaders function to get the appropriate headers
-            headers: getPreprHeaders(),
-        },
-        fetchPolicy: 'no-cache',
-    })
-    return data;
+    body: JSON.stringify({
+      query: `
+        query GetPageBySlug($slug: String!) {
+          Page(slug: $slug) {
+            title
+            content
+          }
+        }
+      `,
+      variables: { slug },
+    }),
+  })
+  return response.json()
 }
 ```
-### Installing the Prepr preview toolbar component
+## 🎛️ API Reference
-The Prepr preview toolbar component fetches all segments from the Prepr API. So, you need to give it access to do this as follows:
+### Server Functions
-1. In your Prepr environment, go to the  **Settings → Access tokens** page to view all the access tokens.
-2. Click the *GraphQL Preview* access token to open it and tick the **Enable edit mode** checkbox and click the **Save** button.
+#### `getPreprHeaders()`
+Returns all Prepr headers for API requests.
-![Preview access token](https://assets-site.prepr.io/229kaekn7m96//preview-access-token-enable-edit-mode.png)
+```typescript
+import { getPreprHeaders } from '@preprio/prepr-nextjs/server'
-To implement the toolbar component, navigate to your root layout file, this is usually `layout.tsx`.
+const headers = await getPreprHeaders()
+// Returns: { 'prepr-customer-id': 'uuid', 'Prepr-Segments': 'segment-id', ... }
+```
-Then add the following code to the `layout.tsx` file:
+#### `getPreprUUID()`
+Returns the current customer ID from headers.
-```javascript
-// Helper function to get all the props for the PreviewBar component (this needs a server component)
-import { getPreviewBarProps } from '@preprio/prepr-nextjs/server'
+```typescript
+import { getPreprUUID } from '@preprio/prepr-nextjs/server'
-// Import the PreviewBar component & proivder
-import {
-  PreprPreviewBar,
-  PreprPreviewBarProvider,
-} from '@preprio/prepr-nextjs/react'
+const customerId = await getPreprUUID()
+// Returns: 'uuid-string' or null
+```
-// Import the PreviewBar CSS
-import '@preprio/prepr-nextjs/index.css'
+#### `getActiveSegment()`
+Returns the currently active segment.
+```typescript
+import { getActiveSegment } from '@preprio/prepr-nextjs/server'
+const segment = await getActiveSegment()
+// Returns: 'segment-id' or null
+```
+#### `getActiveVariant()`
+Returns the currently active A/B testing variant.
+```typescript
+import { getActiveVariant } from '@preprio/prepr-nextjs/server'
+const variant = await getActiveVariant()
+// Returns: 'A' | 'B' | null
+```
+#### `getToolbarProps()`
+Fetches all necessary props for the toolbar component.
+```typescript
+import { getToolbarProps } from '@preprio/prepr-nextjs/server'
+const props = await getToolbarProps(process.env.PREPR_GRAPHQL_URL!)
+// Returns: { activeSegment, activeVariant, data }
+```
+#### `validatePreprToken()`
+Validates a Prepr GraphQL URL format.
-export default async function RootLayout({children}: {children: React.ReactNode}) {
-    // Get the props for the PreviewBar component, pass the access token as an argument
-    const previewBarProps = await getPreviewBarProps(process.env.PREPR_GRAPHQL_URL!)
+```typescript
+import { validatePreprToken } from '@preprio/prepr-nextjs/server'
-    return (
-        <html>
-            <head>
-                {/*...*/}
-            </head>
-            <body>
-                <PreprPreviewBarProvider props={previewBarProps}>
-                    <PreprPreviewBar />
-                    {children}
-                </PreprPreviewBarProvider>
-            </body>
-        </html>
-    )
+const result = validatePreprToken('https://graphql.prepr.io/YOUR_ACCESS_TOKEN')
+// Returns: { valid: boolean, error?: string }
+```
+#### `isPreviewMode()`
+Checks if the current environment is in preview mode.
+```typescript
+import { isPreviewMode } from '@preprio/prepr-nextjs/server'
+const isPreview = isPreviewMode()
+// Returns: boolean
+```
+#### `extractAccessToken()`
+Extracts the access token from a Prepr GraphQL URL.
+```typescript
+import { extractAccessToken } from '@preprio/prepr-nextjs/server'
+const token = extractAccessToken('https://graphql.prepr.io/abc123')
+// Returns: 'abc123' or null
+```
+### React Components
+#### `PreprToolbarProvider`
+Context provider that wraps your app with toolbar functionality.
+```typescript
+import { PreprToolbarProvider } from '@preprio/prepr-nextjs/react'
+<PreprToolbarProvider props={toolbarProps}>
+  {children}
+</PreprToolbarProvider>
+```
+#### `PreprToolbar`
+The main toolbar component.
+```typescript
+import { PreprToolbar } from '@preprio/prepr-nextjs/react'
+<PreprToolbar />
+```
+#### `PreprTrackingPixel`
+User tracking component that loads the Prepr tracking script.
+```typescript
+import { PreprTrackingPixel } from '@preprio/prepr-nextjs/react'
+<PreprTrackingPixel accessToken="your-access-token" />
+```
+## 🔧 Configuration Options
+### Environment Variables
+| Variable | Required | Default | Description |
+|----------|----------|---------|-------------|
+| `PREPR_GRAPHQL_URL` | Yes | - | Your Prepr GraphQL endpoint URL |
+| `PREPR_ENV` | Yes | - | Environment mode (`preview` or `production`) |
+### Middleware Options
+```typescript
+// Simple usage (creates new NextResponse)
+createPreprMiddleware(request, {
+  preview: boolean // Enable preview mode functionality
+})
+// Chaining usage (uses existing NextResponse)
+createPreprMiddleware(request, response, {
+  preview: boolean // Enable preview mode functionality
+})
+```
+### Toolbar Options
+```typescript
+<PreprToolbarProvider
+  props={toolbarProps}
+  options={{
+    debug: true // Enable debug logging
+  }}
+>
+```
+## 🚨 Troubleshooting
+### Common Issues
+#### Toolbar Not Showing
+- **Check environment**: Ensure `PREPR_ENV=preview` is set
+- **Verify GraphQL URL**: Make sure `PREPR_GRAPHQL_URL` is correct and follows the format `https://graphql.prepr.io/YOUR_ACCESS_TOKEN`
+- **Check token permissions**: Ensure "Enable edit mode" is checked in Prepr
+#### Headers Not Working
+- **Middleware setup**: Verify middleware is properly configured
+- **API calls**: Ensure you're using `getPreprHeaders()` in your API calls
+- **Environment**: Check that environment variables are loaded
+#### TypeScript Errors
+- **Version compatibility**: Ensure you're using compatible versions of Next.js and React
+- **Type imports**: Import types from `@preprio/prepr-nextjs/types`
+#### Build Issues
+- **CSS imports**: Make sure to import the CSS file in your layout
+- **Server components**: Ensure server functions are only called in server components
+### Error Handling
+The package includes comprehensive error handling:
+```typescript
+import { PreprError } from '@preprio/prepr-nextjs/server'
+try {
+  const segments = await getPreprEnvironmentSegments(process.env.PREPR_GRAPHQL_URL!)
+} catch (error) {
+  if (error instanceof PreprError) {
+    console.log('Error code:', error.code)
+    console.log('Context:', error.context)
+  }
 }
 ```
-Now the Prepr preview toolbar is rendered on every page of your website. This component shows the segments in a dropdown list and a switch for A and B variants for an A/B test.  If you have added the `getPreprHeaders()` function to your API calls it automatically updates the segments and A/B testing variants when you select a new segment or variant.
+### Debug Mode
+Enable debug logging in development:
+```typescript
+<PreprToolbarProvider
+  props={toolbarProps}
+  options={{ debug: true }}
+>
+```
+## 📊 How It Works
+### Middleware Functionality
+The middleware automatically:
+1. **Generates customer IDs**: Creates unique visitor identifiers
+2. **Tracks UTM parameters**: Captures marketing campaign data
+3. **Manages segments**: Handles audience segmentation
+4. **Processes A/B tests**: Manages variant assignments
+5. **Sets headers**: Adds necessary headers for API calls
-### Helper functions
+### Toolbar Features
-#### getPreprUUID()
-The `getPreprUUID()` function will return the value of the `__prepr_uid` cookie. This can be useful if you want to store the `__prepr_uid` in a cookie or local storage.
+The toolbar provides:
+- **Segment selection**: Switch between different audience segments
+- **A/B testing**: Toggle between variants A and B
+- **Edit mode**: Visual content editing capabilities
+- **Reset functionality**: Clear personalization settings
-#### getActiveSegment()
-Returns the active segment from the `Prepr-Segments` header.
+### Visual Editing
-#### getActiveVariant()
-Returns the active variant from the `Prepr-ABTesting` header.
+When edit mode is enabled, the package:
+1. **Scans content**: Identifies editable content using Stega encoding
+2. **Highlights elements**: Shows proximity-based highlighting
+3. **Provides overlays**: Click-to-edit functionality
+4. **Syncs with Prepr**: Direct integration with Prepr's editing interface
-#### getPreviewHeaders()
-Helper function to only get the preview headers.
+## 🔄 Upgrading from v1 to v2
-#### getPreprHeaders()
-Helper function that will either return the customer id header or the preview headers depending on the `PREPR_ENV` environment variable.
+If you're upgrading from v1, please follow the [Upgrade Guide](./UPGRADE_GUIDE.md) for detailed migration instructions.
-#### getPreviewBarProps()
-Helper function to get the props for the PreviewBar component. Will return the segments and A/B testing variants aswell as an aray of all the segments.
+## 📜 License
-## 📌 Upgrade from v1 to v2
+MIT License - see the [LICENSE](./LICENSE) file for details.
-If you’re upgrading from **Prepr Next.js v1** to **v2**,
-please follow the [Upgrade Guide](./UPGRADE_GUIDE.mdx) for step-by-step instructions.
+## 🆘 Support
-This guide will help you update your middleware, helper imports, and preview toolbar usage.
+- **Documentation**: [Prepr Documentation](https://docs.prepr.io)
+- **Issues**: [GitHub Issues](https://github.com/preprio/prepr-nextjs/issues)
+- **Support**: [Prepr Support](https://prepr.io/support)