@koryla/node 0.1.0

package/README.md

@@ -0,0 +1,80 @@
+# @koryla/node
+
+A/B testing middleware for Express and any Node.js server.
+Works on Railway, Render, Fly.io, Heroku, AWS EC2/ECS, or any Node host.
+
+## Installation
+
+```bash
+npm install @koryla/node
+```
+
+## Setup (Express)
+
+```ts
+import express from 'express'
+import { korylaMiddleware } from '@koryla/node'
+
+const app = express()
+
+// Add Koryla before your routes
+app.use(korylaMiddleware({
+  apiKey: process.env.KORYLA_API_KEY!,
+  apiUrl: process.env.KORYLA_API_URL!,   // your deployed Koryla app URL
+}))
+
+// Variant pages must exist as real routes in the same app
+app.get('/', (req, res) => res.render('home-control'))
+app.get('/variant-b', (req, res) => res.render('home-variant-b'))
+app.get('/pricing', (req, res) => res.render('pricing-control'))
+app.get('/pricing-b', (req, res) => res.render('pricing-variant-b'))
+```
+
+### Environment variables
+
+```bash
+KORYLA_API_KEY=sk_live_...
+KORYLA_API_URL=https://your-koryla-app.vercel.app
+```
+
+## Important: variant pages must be in the same app
+
+Unlike edge adapters that can proxy to any URL, the Node middleware rewrites
+`req.url` internally and calls `next()`. This means:
+
+- ✅ Your variant pages are routes in the same Express app
+- ❌ Your variants are on a different domain/server
+
+If your variants are on a different origin you'll need a reverse proxy
+(nginx, Caddy) in front of your app instead.
+
+## How it works
+
+```
+User visits /
+     │
+     ▼
+Express middleware (in-process, ~1ms overhead)
+     │
+     ├── fetches Koryla config once every 60s (cached in memory)
+     ├── reads sp_<experimentId> cookie
+     ├── assigns variant, rewrites req.url to /variant-b
+     └── sets Set-Cookie header on response
+     │
+     ▼
+Express routes /variant-b to its handler
+Browser sees original URL (/) — no redirect, no flicker
+```
+
+## Difference vs edge adapters
+
+| | @koryla/node | @koryla/next / @koryla/netlify |
+|--|--|--|
+| Runs at | Your app server | CDN edge node near the user |
+| Latency added | ~1ms (in-process) | ~1ms (in-process) |
+| Koryla API call | Cached 60s | Cached 60s |
+| Variants on different origin | ❌ (same app only) | ✅ |
+| Zero flicker | ✅ | ✅ |
+
+Both approaches are server-side — neither has the flicker problem of client-side tools.
+The only difference is where the server runs.

package/dist/index.cjs

@@ -0,0 +1,63 @@
+"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_core = require("@koryla/core");
+var engine = null;
+function korylaMiddleware(options) {
+  return async function middleware(req, res, next) {
+    if (!engine) engine = (0, import_core.createSplitEngine)(options);
+    try {
+      const protocol = req.protocol ?? "http";
+      const host = req.headers["x-forwarded-host"] ?? req.headers["host"] ?? "localhost";
+      const path = req.originalUrl ?? req.url ?? "/";
+      const fullUrl = `${protocol}://${host}${path}`;
+      const cookieHeader = req.headers["cookie"] ?? "";
+      const result = await engine.process(fullUrl, cookieHeader);
+      if (!result) return next();
+      const variantPath = new URL(result.targetUrl).pathname;
+      req.url = variantPath;
+      if (req.originalUrl) req.originalUrl = variantPath;
+      if (result.isNewAssignment) {
+        const maxAge = 60 * 60 * 24 * 30;
+        const cookie = `${result.cookieName}=${result.variantId}; Path=/; Max-Age=${maxAge}; SameSite=Lax`;
+        const existing = res.getHeader("Set-Cookie");
+        if (Array.isArray(existing)) {
+          res.setHeader("Set-Cookie", [...existing, cookie]);
+        } else if (existing) {
+          res.setHeader("Set-Cookie", [existing, cookie]);
+        } else {
+          res.setHeader("Set-Cookie", cookie);
+        }
+      }
+      next();
+    } catch {
+      next();
+    }
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  korylaMiddleware
+});

package/dist/index.d.cts

@@ -0,0 +1,55 @@
+import { SplitEngineOptions } from '@koryla/core';
+
+/**
+ * @koryla/node
+ *
+ * Express / Node.js middleware adapter for Koryla A/B testing.
+ * Works anywhere Node.js runs: Railway, Render, Fly.io, Heroku, AWS EC2/ECS,
+ * self-hosted servers, or any Express-compatible framework (Fastify via @fastify/express, etc).
+ *
+ * Usage (Express):
+ *   import express from 'express'
+ *   import { korylaMiddleware } from '@koryla/node'
+ *
+ *   const app = express()
+ *
+ *   app.use(korylaMiddleware({
+ *     apiKey: process.env.KORYLA_API_KEY!,
+ *     apiUrl: process.env.KORYLA_API_URL!,
+ *   }))
+ *
+ *   // Your routes come after — they receive the rewritten req.url
+ *   app.get('/', handler)
+ *   app.get('/variant-b', handler)
+ *
+ * How it works:
+ *   Unlike edge runtimes, Node.js middleware cannot transparently proxy to another
+ *   origin. Instead it rewrites req.url to the variant's pathname, then calls next()
+ *   so Express routes the request to the correct handler.
+ *
+ *   This means your variant pages must exist as routes in the SAME app:
+ *     Control:   GET /          → renders homepage v1
+ *     Variant B: GET /variant-b → renders homepage v2
+ *
+ *   The browser always sees the original URL (/) — the rewrite is internal.
+ *
+ * Note on latency:
+ *   Unlike CF Workers / Vercel Edge / Netlify Edge, this runs in your app server
+ *   process — not at the CDN edge. Variant assignment adds ~1ms of in-process work.
+ *   The Koryla API call is cached for 60s so it doesn't add per-request latency.
+ */
+
+interface NodeRequest {
+    url?: string;
+    originalUrl?: string;
+    protocol?: string;
+    headers: Record<string, string | string[] | undefined>;
+}
+interface NodeResponse {
+    setHeader(name: string, value: string | string[]): void;
+    getHeader(name: string): string | string[] | number | undefined;
+}
+type NextFunction = (err?: unknown) => void;
+declare function korylaMiddleware(options: SplitEngineOptions): (req: NodeRequest, res: NodeResponse, next: NextFunction) => Promise<void>;
+
+export { type NextFunction, type NodeRequest, type NodeResponse, korylaMiddleware };

package/dist/index.d.ts

@@ -0,0 +1,55 @@
+import { SplitEngineOptions } from '@koryla/core';
+
+/**
+ * @koryla/node
+ *
+ * Express / Node.js middleware adapter for Koryla A/B testing.
+ * Works anywhere Node.js runs: Railway, Render, Fly.io, Heroku, AWS EC2/ECS,
+ * self-hosted servers, or any Express-compatible framework (Fastify via @fastify/express, etc).
+ *
+ * Usage (Express):
+ *   import express from 'express'
+ *   import { korylaMiddleware } from '@koryla/node'
+ *
+ *   const app = express()
+ *
+ *   app.use(korylaMiddleware({
+ *     apiKey: process.env.KORYLA_API_KEY!,
+ *     apiUrl: process.env.KORYLA_API_URL!,
+ *   }))
+ *
+ *   // Your routes come after — they receive the rewritten req.url
+ *   app.get('/', handler)
+ *   app.get('/variant-b', handler)
+ *
+ * How it works:
+ *   Unlike edge runtimes, Node.js middleware cannot transparently proxy to another
+ *   origin. Instead it rewrites req.url to the variant's pathname, then calls next()
+ *   so Express routes the request to the correct handler.
+ *
+ *   This means your variant pages must exist as routes in the SAME app:
+ *     Control:   GET /          → renders homepage v1
+ *     Variant B: GET /variant-b → renders homepage v2
+ *
+ *   The browser always sees the original URL (/) — the rewrite is internal.
+ *
+ * Note on latency:
+ *   Unlike CF Workers / Vercel Edge / Netlify Edge, this runs in your app server
+ *   process — not at the CDN edge. Variant assignment adds ~1ms of in-process work.
+ *   The Koryla API call is cached for 60s so it doesn't add per-request latency.
+ */
+
+interface NodeRequest {
+    url?: string;
+    originalUrl?: string;
+    protocol?: string;
+    headers: Record<string, string | string[] | undefined>;
+}
+interface NodeResponse {
+    setHeader(name: string, value: string | string[]): void;
+    getHeader(name: string): string | string[] | number | undefined;
+}
+type NextFunction = (err?: unknown) => void;
+declare function korylaMiddleware(options: SplitEngineOptions): (req: NodeRequest, res: NodeResponse, next: NextFunction) => Promise<void>;
+
+export { type NextFunction, type NodeRequest, type NodeResponse, korylaMiddleware };

package/dist/index.js

@@ -0,0 +1,38 @@
+// src/index.ts
+import { createSplitEngine } from "@koryla/core";
+var engine = null;
+function korylaMiddleware(options) {
+  return async function middleware(req, res, next) {
+    if (!engine) engine = createSplitEngine(options);
+    try {
+      const protocol = req.protocol ?? "http";
+      const host = req.headers["x-forwarded-host"] ?? req.headers["host"] ?? "localhost";
+      const path = req.originalUrl ?? req.url ?? "/";
+      const fullUrl = `${protocol}://${host}${path}`;
+      const cookieHeader = req.headers["cookie"] ?? "";
+      const result = await engine.process(fullUrl, cookieHeader);
+      if (!result) return next();
+      const variantPath = new URL(result.targetUrl).pathname;
+      req.url = variantPath;
+      if (req.originalUrl) req.originalUrl = variantPath;
+      if (result.isNewAssignment) {
+        const maxAge = 60 * 60 * 24 * 30;
+        const cookie = `${result.cookieName}=${result.variantId}; Path=/; Max-Age=${maxAge}; SameSite=Lax`;
+        const existing = res.getHeader("Set-Cookie");
+        if (Array.isArray(existing)) {
+          res.setHeader("Set-Cookie", [...existing, cookie]);
+        } else if (existing) {
+          res.setHeader("Set-Cookie", [existing, cookie]);
+        } else {
+          res.setHeader("Set-Cookie", cookie);
+        }
+      }
+      next();
+    } catch {
+      next();
+    }
+  };
+}
+export {
+  korylaMiddleware
+};

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@koryla/node",
+  "version": "0.1.0",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "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"
+  },
+  "dependencies": {
+    "@koryla/core": "^0.2.0"
+  },
+  "devDependencies": {
+    "tsup": "^8.0.0",
+    "typescript": "^5"
+  }
+}