@koryla/next 0.1.0

package/README.md

@@ -0,0 +1,91 @@
+# @koryla/next
+
+A/B testing for Next.js with zero flicker. Runs on the Vercel Edge Network.
+
+## Installation
+
+```bash
+npm install @koryla/next
+```
+
+## Setup
+
+### 1. Add environment variables
+
+```bash
+# .env.local
+KORYLA_API_KEY=sk_live_...   # generated in Koryla → Settings → API Keys
+KORYLA_API_URL=https://your-koryla-app.vercel.app
+```
+
+### 2. Create middleware.ts
+
+```ts
+// middleware.ts  (project root, next to package.json)
+import { korylaMiddleware } from '@koryla/next'
+
+export default korylaMiddleware({
+  apiKey: process.env.KORYLA_API_KEY!,
+  apiUrl: process.env.KORYLA_API_URL!,
+})
+
+// Only run on the pages you're testing — keeps other routes fast
+export const config = {
+  matcher: ['/', '/pricing', '/landing'],
+}
+```
+
+### 3. Create your variant pages
+
+The middleware rewrites the URL server-side, so the variant page must exist in your app:
+
+```
+app/
+  page.tsx           ← control  (base_url: https://acme.com/)
+  variant-b/
+    page.tsx         ← variant  (target_url: https://acme.com/variant-b)
+```
+
+### 4. Create an experiment in Koryla
+
+Go to your Koryla dashboard → New experiment:
+
+| Field | Value |
+|-------|-------|
+| Base URL | `https://acme.com/` |
+| Variant A — Control | `https://acme.com/` · 50% |
+| Variant B | `https://acme.com/variant-b` · 50% |
+| Conversion URL | `https://acme.com/thank-you` |
+
+Set it to **Active** and you're done.
+
+## How it works
+
+```
+User visits /
+     │
+     ▼
+Next.js middleware (runs at Vercel edge, before rendering)
+     │
+     ├── calls Koryla API once every 60s to get experiment config
+     ├── reads sp_<experimentId> cookie
+     │     ├── cookie present → use existing variant (sticky)
+     │     └── no cookie → assign variant by traffic weight
+     │
+     ├── rewrites request to /variant-b (server-side, no redirect)
+     └── sets cookie for 30 days
+     │
+     ▼
+Next.js renders /variant-b
+Browser receives variant B HTML — never sees the rewrite
+```
+
+## Why this is better than VWO / Optimizely
+
+| | VWO / Optimizely | @koryla/next |
+|--|--|--|
+| When variant is decided | In the browser, after JS loads | At the edge, before any HTML |
+| Flicker | Yes (page hides while swapping) | No |
+| Extra JS | ~80–150 KB | 0 KB |
+| Blockable by ad blockers | Yes | No |
+| Works without JS | No | Yes |

package/dist/index.cjs

@@ -0,0 +1,52 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  korylaMiddleware: () => korylaMiddleware
+});
+module.exports = __toCommonJS(index_exports);
+var import_server = require("next/server");
+var import_core = require("@koryla/core");
+var engine = null;
+function korylaMiddleware(options) {
+  return async function middleware(request) {
+    if (!engine) engine = (0, import_core.createSplitEngine)(options);
+    const result = await engine.process(
+      request.url,
+      request.headers.get("cookie") ?? ""
+    );
+    if (!result) return import_server.NextResponse.next();
+    const response = import_server.NextResponse.rewrite(new URL(result.targetUrl));
+    if (result.isNewAssignment) {
+      response.cookies.set(result.cookieName, result.variantId, {
+        maxAge: 60 * 60 * 24 * 30,
+        // 30 days
+        sameSite: "lax",
+        path: "/"
+      });
+    }
+    return response;
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  korylaMiddleware
+});

package/dist/index.d.cts

@@ -0,0 +1,38 @@
+import { NextRequest, NextResponse } from 'next/server';
+import { SplitEngineOptions } from '@koryla/core';
+
+/**
+ * @koryla/next
+ *
+ * Next.js middleware adapter for Koryla A/B testing.
+ * Runs on the Vercel Edge Network — zero latency, zero flicker.
+ *
+ * Usage:
+ *   // middleware.ts (project root)
+ *   import { korylaMiddleware } from '@koryla/next'
+ *
+ *   export default korylaMiddleware({
+ *     apiKey: process.env.KORYLA_API_KEY!,
+ *     apiUrl: process.env.KORYLA_API_URL!,   // e.g. https://your-app.koryla.com
+ *   })
+ *
+ *   export const config = {
+ *     matcher: ['/', '/pricing', '/landing'],  // pages to A/B test
+ *   }
+ *
+ * How it works:
+ *   1. Middleware intercepts the request before Next.js renders anything
+ *   2. Calls Koryla API to get active experiments (cached 60s in memory)
+ *   3. Checks for an existing variant cookie — if found, sticks with it
+ *   4. If no cookie, randomly assigns a variant by traffic weight
+ *   5. Rewrites the request URL to the variant's target_url (server-side, no redirect)
+ *   6. Sets a 30-day cookie so the user always sees the same variant
+ *
+ * The browser never sees the rewrite — it only ever receives the assigned variant.
+ * This eliminates the flash of original content (FOOC) that client-side tools like
+ * VWO or Optimizely cause.
+ */
+
+declare function korylaMiddleware(options: SplitEngineOptions): (request: NextRequest) => Promise<NextResponse>;
+
+export { korylaMiddleware };

package/dist/index.d.ts

@@ -0,0 +1,38 @@
+import { NextRequest, NextResponse } from 'next/server';
+import { SplitEngineOptions } from '@koryla/core';
+
+/**
+ * @koryla/next
+ *
+ * Next.js middleware adapter for Koryla A/B testing.
+ * Runs on the Vercel Edge Network — zero latency, zero flicker.
+ *
+ * Usage:
+ *   // middleware.ts (project root)
+ *   import { korylaMiddleware } from '@koryla/next'
+ *
+ *   export default korylaMiddleware({
+ *     apiKey: process.env.KORYLA_API_KEY!,
+ *     apiUrl: process.env.KORYLA_API_URL!,   // e.g. https://your-app.koryla.com
+ *   })
+ *
+ *   export const config = {
+ *     matcher: ['/', '/pricing', '/landing'],  // pages to A/B test
+ *   }
+ *
+ * How it works:
+ *   1. Middleware intercepts the request before Next.js renders anything
+ *   2. Calls Koryla API to get active experiments (cached 60s in memory)
+ *   3. Checks for an existing variant cookie — if found, sticks with it
+ *   4. If no cookie, randomly assigns a variant by traffic weight
+ *   5. Rewrites the request URL to the variant's target_url (server-side, no redirect)
+ *   6. Sets a 30-day cookie so the user always sees the same variant
+ *
+ * The browser never sees the rewrite — it only ever receives the assigned variant.
+ * This eliminates the flash of original content (FOOC) that client-side tools like
+ * VWO or Optimizely cause.
+ */
+
+declare function korylaMiddleware(options: SplitEngineOptions): (request: NextRequest) => Promise<NextResponse>;
+
+export { korylaMiddleware };

package/dist/index.js

@@ -0,0 +1,27 @@
+// src/index.ts
+import { NextResponse } from "next/server";
+import { createSplitEngine } from "@koryla/core";
+var engine = null;
+function korylaMiddleware(options) {
+  return async function middleware(request) {
+    if (!engine) engine = createSplitEngine(options);
+    const result = await engine.process(
+      request.url,
+      request.headers.get("cookie") ?? ""
+    );
+    if (!result) return NextResponse.next();
+    const response = NextResponse.rewrite(new URL(result.targetUrl));
+    if (result.isNewAssignment) {
+      response.cookies.set(result.cookieName, result.variantId, {
+        maxAge: 60 * 60 * 24 * 30,
+        // 30 days
+        sameSite: "lax",
+        path: "/"
+      });
+    }
+    return response;
+  };
+}
+export {
+  korylaMiddleware
+};

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@koryla/next",
+  "version": "0.1.0",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": ["dist"],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format esm,cjs --dts --clean",
+    "dev": "tsup src/index.ts --format esm,cjs --dts --watch"
+  },
+  "peerDependencies": {
+    "next": ">=13"
+  },
+  "dependencies": {
+    "@koryla/core": "workspace:^"
+  },
+  "devDependencies": {
+    "next": "^15.0.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5"
+  }
+}