@se-studio/ab-testing

Server-side A/B testing framework for Next.js applications with Contentful CMS.

Features

- Server-side rendering: No flicker or layout shift - variants are rendered on the server
- Edge-optimized: Middleware runs at the edge for minimal latency
- CMS-driven: Test configuration managed entirely in Contentful
- Provider-agnostic: Bring your own blob storage (Vercel KV, Netlify Blobs, etc.)
- Flexible analytics: Use the useAbTestAssignments hook to integrate with any analytics platform

Architecture

``
┌─────────────────┐ ┌──────────────────┐ ┌─────────────────┐
│ Contentful │────▶│ Webhook Handler │────▶│ Blob Store │
│ PageTest │ │ (API Route) │ │ (Project- │
│ Entries │ │ │ │ specific) │
└─────────────────┘ └──────────────────┘ └────────┬────────┘
│
▼
┌─────────────────┐ ┌──────────────────┐ ┌─────────────────┐
│ User Request │────▶│ Middleware │────▶│ Variant Page │
│ /pricing │ │ (Edge) │ │ (SSR) │
└─────────────────┘ └──────────────────┘ └─────────────────┘
│
▼
┌──────────────────┐
│ Cookie Set │
│ ab-test-info │
└────────┬─────────┘
│
▼
┌──────────────────┐
│ useAbTestAssign- │
│ ments Hook │
│ → Your Analytics │
└──────────────────┘
`

Installation

`bash
pnpm add @se-studio/ab-testing
`

Quick Start

$3

The package requires you to implement the IBlobStore interface for your hosting platform.

Vercel KV Example:

`typescript
// src/server/abTestStore.ts
import { kv } from '@vercel/kv';
import type { IBlobStore, AbTest } from '@se-studio/ab-testing';

const STORE_KEY = 'ab-tests';

export function getAbTestStore(): IBlobStore {
return {
async get(key) {
const data = await kv.hget(STORE_KEY, key);
return data ?? undefined;
},
async set(key, value) {
await kv.hset(STORE_KEY, { [key]: value });
},
async bulkWrite(entries) {
await kv.del(STORE_KEY);
if (entries.length > 0) {
const data = Object.fromEntries(entries);
await kv.hset(STORE_KEY, data);
}
},
async size() {
return kv.hlen(STORE_KEY);
},
async values() {
const data = await kv.hgetall>(STORE_KEY);
return data ? Object.values(data) : [];
},
};
}
`

Netlify Blobs Example:

`typescript
// src/server/abTestStore.ts
import { getStore } from '@netlify/blobs';
import type { IBlobStore, AbTest } from '@se-studio/ab-testing';

export function getAbTestStore(): IBlobStore {
const store = getStore('ab-testing');
const BLOB_NAME = 'config';

return {
async get(key) {
const data = await store.get(BLOB_NAME, { type: 'json' });
return data?.[key];
},
async set(key, value) {
const data = (await store.get(BLOB_NAME, { type: 'json' })) ?? {};
data[key] = value;
await store.setJSON(BLOB_NAME, data);
},
async bulkWrite(entries) {
const data = Object.fromEntries(entries);
await store.setJSON(BLOB_NAME, data);
},
async size() {
const data = await store.get(BLOB_NAME, { type: 'json' });
return data ? Object.keys(data).length : 0;
},
async values() {
const data = await store.get(BLOB_NAME, { type: 'json' });
return data ? Object.values(data) : [];
},
};
}
`

$3

`typescript
// src/middleware.ts
import { createAbTestMiddleware } from '@se-studio/ab-testing/middleware';
import { getAbTestStore } from './server/abTestStore';
import { NextResponse } from 'next/server';
import type { NextRequest } from 'next/server';

const abTestHandler = createAbTestMiddleware({
getStore: getAbTestStore,
cacheTtlMs: 60000, // 60 second cache
});

export async function middleware(request: NextRequest) {
// Skip static assets, API routes, etc.
if (request.nextUrl.pathname.startsWith('/_next') ||
request.nextUrl.pathname.startsWith('/api')) {
return NextResponse.next();
}

// Process A/B tests
const abResponse = await abTestHandler(request);
if (abResponse) return abResponse;

return NextResponse.next();
}

export const config = {
matcher: ['/((?!api|_next/static|_next/image|favicon.ico).*)'],
};
`

$3

`typescript
// src/app/api/webhooks/ab-test/route.ts
import { createWebhookHandler } from '@se-studio/ab-testing/webhook';
import { getAbTestStore } from '@/server/abTestStore';
import { revalidateTag } from 'next/cache';

// Your Contentful fetch function
async function fetchPageTests() {
// Fetch all PageTest entries from Contentful
// Return array of RawPageTest objects
}

export const dynamic = 'force-dynamic';

export const POST = createWebhookHandler({
fetchPageTests,
getStore: getAbTestStore,
webhookSecret: process.env.CONTENTFUL_WEBHOOK_SECRET,
revalidate: () => revalidateTag('PageTests'),
});
`

$3

The package provides a useAbTestAssignments hook that returns test assignments for the current page. You create your own reporter component with your project's specific analytics integrations.

`tsx
// src/components/AbTestReporter.tsx (project-specific)
'use client';

import { useEffect } from 'react';
import { useAbTestAssignments } from '@se-studio/ab-testing';
import { sendEvent } from '@/lib/analytics';

export function AbTestReporter() {
const assignments = useAbTestAssignments();

useEffect(() => {
for (const assignment of assignments) {
// Send to GTM/GA4
sendEvent('experiment_impression', {
experiment_id: assignment.testId,
experiment_name: assignment.test_label,
variant_id: assignment.test_path,
});
}
}, [assignments]);

return null;
}
`

With HubSpot Integration (HSD-style):

`tsx
// src/components/AbTestReporter.tsx
'use client';

import { useEffect } from 'react';
import { useAbTestAssignments } from '@se-studio/ab-testing';
import { sendEvent } from '@/lib/analytics';
import { sendHubspotCustomEvent } from '@/lib/hubspotCustomEvents';

export function AbTestReporter() {
const assignments = useAbTestAssignments();

useEffect(() => {
for (const assignment of assignments) {
// Send to GTM/GA4
sendEvent('experiment_impression', {
experiment_id: assignment.testId,
experiment_name: assignment.test_label,
variant_id: assignment.test_path,
});

// Send to HubSpot (if configured)
if (assignment.hubspot_event) {
sendHubspotCustomEvent(assignment.hubspot_event, {
experiment_name: assignment.test_label,
experiment_id: assignment.testId,
});
}
}
}, [assignments]);

return null;
}
`

Add to your layout:

`tsx
// src/app/layout.tsx
import { AbTestReporter } from '@/components/AbTestReporter';

export default function RootLayout({ children }: { children: React.ReactNode }) {
return (


{children}



);
}
`

Contentful Content Model

$3

| Field | Type | Description |
|-------|------|-------------|
| cmsLabel | Symbol | Internal label for the test |
| control | Reference (Page/PageVariant) | The control page to test against |
| enabled | Boolean | Whether the test is active |
| trackingLabel | Symbol (optional) | Override for analytics label |
| searchParameters | Symbol (optional) | URL params to match (e.g., "utm_source=google") |
| configuration | JSON | Array of {weight, hubspot_event_name?} |
| variants | References (PageVariant[]) | Variants to test |

$3

Existing content type that references an original page and defines component swaps.

API Reference

$3

`typescript
interface AbTest {
id: string;
cmsLabel: string;
controlSlug: string;
searchParameters?: string;
trackingLabel?: string;
enabled: boolean;
configuration: AbTestVariantConfig[];
variants: AbTestVariant[];
}

interface IBlobStore {
get(key: string): Promise;
set(key: string, value: T): Promise;
bulkWrite(entries: [string, T][]): Promise;
size(): Promise;
values(): Promise;
}

interface ActiveAbTestAssignment {
testId: string;
test_label: string;
test_path: string;
hubspot_event?: string;
original_path?: string;
}
`

$3

`typescript
import { createAbTestMiddleware } from '@se-studio/ab-testing/middleware';

const handler = createAbTestMiddleware({
getStore: () => store, // Required: blob store factory
cacheTtlMs: 60000, // Optional: cache TTL (default: 60s)
cookieName: 'ab-test-info', // Optional: cookie name
cookieMaxAge: 2592000, // Optional: cookie max age (default: 30 days)
shouldProcess: (path) => true, // Optional: filter requests
devTestData: [], // Optional: test data for development
});
`

$3

`typescript
import { createWebhookHandler } from '@se-studio/ab-testing/webhook';

export const POST = createWebhookHandler({
fetchPageTests: () => Promise, // Required
getStore: () => store, // Required
webhookSecret: 'secret', // Optional
revalidate: () => void, // Optional
onSkippedTest: (id, reason) => void, // Optional
});
`

$3

`typescript
import { useAbTestAssignments } from '@se-studio/ab-testing';

// Returns array of assignments for the current page
const assignments = useAbTestAssignments({
cookieName: 'ab-test-info', // Optional: custom cookie name
});

// Each assignment contains:
// - testId: string
// - test_label: string
// - test_path: string (variant slug or "control")
// - hubspot_event?: string
// - original_path?: string
`

Analytics Integration

$3

Push events to window.dataLayer:

`typescript
window.dataLayer.push({
event: 'experiment_impression',
experiment_id: assignment.testId,
experiment_name: assignment.test_label,
variant_id: assignment.test_path,
});
`

$3

Register custom dimensions in GA4:
1. Go to Admin > Data display > Custom definitions
2. Create event-scoped dimensions for:
- experiment_id
- experiment_name
- variant_id`

License

MIT