@avivbenhamo/polly-kit 0.1.0

package/README.md

@@ -0,0 +1,138 @@
+# @avivbenhamo/polly-kit
+
+Record a Vite app's real HTTP traffic to HAR files, then replay it so the app runs with no
+backends. Wraps Polly.JS, the recording store and the [polly-studio](https://www.npmjs.com/package/@avivbenhamo/polly-studio)
+editor into one plugin and one function.
+
+Nothing in here knows a hostname. You supply a policy; the package is the machinery.
+
+## Install
+
+```sh
+npm i -D @avivbenhamo/polly-kit
+```
+
+## Three steps
+
+**1. `vite.config.ts`** — one plugin, dev-server only (it registers in `configureServer`, so a
+production build never sees it):
+
+```ts
+import pollyKit from '@avivbenhamo/polly-kit/vite';
+
+export default defineConfig({
+    plugins: [react(), pollyKit({recordingsDir: 'recordings'})],
+});
+```
+
+**2. A config file** — the only file you write:
+
+```ts
+// src/polly/config.ts
+import type {PollyPolicyConfig} from '@avivbenhamo/polly-kit';
+
+export const pollyConfig: PollyPolicyConfig = {
+    recordingName: 'my-app',
+    policy: {kind: 'except', hosts: [import.meta.env.VITE_AUTH_URL]},
+};
+```
+
+**3. A bootstrap module, imported FIRST in your entry point:**
+
+```ts
+// src/polly/bootstrap.ts
+import {resolveMode, startPolly} from '@avivbenhamo/polly-kit';
+import {pollyConfig} from './config';
+
+const mode = import.meta.env.PROD ? 'off' : resolveMode(import.meta.env.VITE_POLLY_MODE);
+
+startPolly({...pollyConfig, mode});
+```
+
+```ts
+// src/index.tsx — FIRST import, above everything
+import './polly/bootstrap';
+```
+
+`bootstrap.ts` exists so that `startPolly()` runs before your component tree is evaluated. ES
+module imports are hoisted and fully evaluated before any statement in the importing module's
+body, so a bare `startPolly()` call in `index.tsx` runs *after* `./App` and everything it
+imports — and any module that fires a request at import time would escape interception,
+silently and only sometimes.
+
+Add `/recordings` to `.gitignore`. A HAR holds complete response bodies.
+
+## Running it
+
+Off unless `VITE_POLLY_MODE` is set, so the default behaviour of your app is unchanged.
+
+```powershell
+$env:VITE_POLLY_MODE='record'; npm run dev     # capture real traffic
+$env:VITE_POLLY_MODE='replay'; npm run dev     # serve from recordings
+```
+
+```sh
+VITE_POLLY_MODE=record npm run dev             # bash
+```
+
+Record once against reachable backends, then replay forever. Recordings land in
+`recordings/<recordingName>_<hash>/recording.har`, editable at **http://localhost:<port>/__polly**
+— the URL is printed on startup.
+
+## Policies
+
+```ts
+policy: {kind: 'all'}                    // mock every host
+policy: {kind: 'except', hosts: [...]}   // mock everything EXCEPT these
+policy: {kind: 'only',   hosts: [...]}   // mock ONLY these
+```
+
+Hosts match by origin, so a trailing slash or a path on the value is fine — they are `baseURL`s
+in practice, and `toOrigin` reduces them. An entry that resolves to `undefined` (an env var
+that was never set) is skipped rather than throwing at startup.
+
+The app's own origin is always passed through: it serves the HMR socket, the recording store
+and every static asset, so mocking it breaks the dev server.
+
+**Passed-through hosts still hit the real network in `replay` mode.** That is what passthrough
+means, but it has a sharp edge: the hosts you exclude are usually auth and analytics, which are
+also the least likely to be reachable from an isolated environment. Replaying off-network then
+gives you hanging calls to exactly those while everything else replays fine — which reads as
+"Polly is broken" and isn't. For true isolation use `{kind: 'all'}` and record them too.
+
+## API
+
+| Export | From | What |
+|---|---|---|
+| `startPolly(options)` | `.` | Starts Polly. Returns `null` when `mode` is `'off'`, having constructed nothing. |
+| `resolveMode(raw)` | `.` | Narrows an env value to `'off' \| 'record' \| 'replay'`. Anything unrecognised is `off`. |
+| `toOrigin` / `toOrigins` | `.` | The origin reduction the policy matcher uses. |
+| `pollyKit(options)` | `./vite` | The Vite plugin: recording store + studio. |
+| `recordingStore(options)` | `./store` | The store as a bare connect middleware, for mounting on something that isn't Vite. |
+
+`startPolly` options beyond the policy config: `mode` (required), `alwaysPassthrough`,
+`apiNamespace`, `saveDebounceMs`. `pollyKit` options: `recordingsDir`, `studioPath`,
+`apiNamespace`, `studio`. Change `apiNamespace` in one place and you must change it in both.
+
+## Notes on why it is built this way
+
+**The XHR adapter, not fetch.** axios resolves its adapter as `['xhr', 'http', 'fetch']`, so in
+a browser it uses `XMLHttpRequest`. `@pollyjs/adapter-fetch` would attach cleanly and then see
+no traffic at all. `adapter-xhr` patches `window.XMLHttpRequest`, which axios picks up with no
+awareness — so no axios instance in your app needs to change.
+
+**The `global` shim.** `@pollyjs/persister-rest` reads a bare, unbound `global` at module top
+level, which throws in a browser. `startPolly`'s module imports the shim as its own first
+import, so you cannot get the order wrong.
+
+**Recordings flush while you browse.** Polly only persists on `stop()`, which suits a test that
+ends; a dev server page stays open and would write nothing. The kit debounces a `persist()` per
+response instead.
+
+**Defaults that differ from Polly's.** `recordIfMissing: false` (a replay miss must fail loudly
+— the default quietly hits the network and records it, which looks identical to replay working),
+`recordFailedRequests: true`, `matchRequestsBy.order: false` (screens refetch) and
+`.headers: false` (bearer tokens would pin a recording to one session).
+
+**If you also run MSW, Polly wins.** It patches `XMLHttpRequest` in-page, so the request is
+answered before the service worker sees it. Run one or the other.

package/dist/browser.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Record and replay a browser app's HTTP calls with Polly.JS.
+ *
+ * Polly works by patching the transport, so `startPolly()` has to run before the
+ * first request goes out. Import the module that calls it FIRST in your entry
+ * point — see the README.
+ *
+ * WHY THE XHR ADAPTER. axios resolves its adapter in the order
+ * `['xhr', 'http', 'fetch']`, so in a browser it uses XMLHttpRequest. The fetch
+ * adapter would attach cleanly and then see no traffic at all. `adapter-xhr`
+ * patches `window.XMLHttpRequest`, which axios picks up with no awareness — so no
+ * axios instance in the host app needs to change.
+ *
+ * Nothing here reads the environment. The caller resolves the mode and passes it
+ * in, which is what keeps this file free of any bundler's env API.
+ */
+import './global-shim.js';
+import { Polly } from '@pollyjs/core';
+import { type PollyPolicyConfig } from './policy.js';
+export type { HostPolicy, PollyPolicyConfig } from './policy.js';
+export { toOrigin, toOrigins } from './policy.js';
+export type PollyMode = 'off' | 'record' | 'replay';
+/**
+ * Narrows whatever the host app read out of its environment to a mode.
+ *
+ * Anything unrecognised — including `undefined` from an unset variable — is
+ * `off`, so a typo in the variable disables Polly rather than half-enabling it.
+ */
+export declare function resolveMode(raw: unknown): PollyMode;
+export interface StartPollyOptions extends PollyPolicyConfig {
+    /** Resolve it with `resolveMode(import.meta.env.VITE_POLLY_MODE)`, or equivalent. */
+    mode: PollyMode;
+    /**
+     * Hosts that are never mocked, whatever the policy says. Defaults to the
+     * app's own origin, which serves the dev server's HMR socket, the recording
+     * store itself and every static asset — mocking it breaks the dev server.
+     */
+    alwaysPassthrough?: readonly (string | undefined | null)[];
+    /** Where the recording store is mounted. Must match the Vite plugin. */
+    apiNamespace?: string;
+    /** Debounce on flushing to disk while recording. */
+    saveDebounceMs?: number;
+}
+/** Returns null when the mode is `off`, having constructed nothing. */
+export declare function startPolly(options: StartPollyOptions): Polly | null;

package/dist/browser.js

@@ -0,0 +1,102 @@
+/**
+ * Record and replay a browser app's HTTP calls with Polly.JS.
+ *
+ * Polly works by patching the transport, so `startPolly()` has to run before the
+ * first request goes out. Import the module that calls it FIRST in your entry
+ * point — see the README.
+ *
+ * WHY THE XHR ADAPTER. axios resolves its adapter in the order
+ * `['xhr', 'http', 'fetch']`, so in a browser it uses XMLHttpRequest. The fetch
+ * adapter would attach cleanly and then see no traffic at all. `adapter-xhr`
+ * patches `window.XMLHttpRequest`, which axios picks up with no awareness — so no
+ * axios instance in the host app needs to change.
+ *
+ * Nothing here reads the environment. The caller resolves the mode and passes it
+ * in, which is what keeps this file free of any bundler's env API.
+ */
+// FIRST. Defines `global`, which @pollyjs/persister-rest reads unbound at module
+// top level. ES modules evaluate in import order, so this runs before the Polly
+// imports below. Moving it under them reintroduces the crash — and it lives here
+// rather than in the host app so the host app cannot get the order wrong.
+import './global-shim.js';
+import { Polly } from '@pollyjs/core';
+import XHRAdapter from '@pollyjs/adapter-xhr';
+import RestPersister from '@pollyjs/persister-rest';
+import { applyPolicy } from './policy.js';
+export { toOrigin, toOrigins } from './policy.js';
+const MODES = ['off', 'record', 'replay'];
+/** Matches the namespace the Vite plugin mounts the recording store on. */
+const API_NAMESPACE = '/api/polly';
+/** How long to wait for more responses before flushing a recording to disk. */
+const SAVE_DEBOUNCE_MS = 500;
+let registered = false;
+/**
+ * Narrows whatever the host app read out of its environment to a mode.
+ *
+ * Anything unrecognised — including `undefined` from an unset variable — is
+ * `off`, so a typo in the variable disables Polly rather than half-enabling it.
+ */
+export function resolveMode(raw) {
+    return MODES.includes(raw) ? raw : 'off';
+}
+/**
+ * Flush recordings to disk as they arrive.
+ *
+ * Polly only persists on `stop()`, which suits a test that ends. A dev server
+ * page stays open, so it would hold every recording in memory and write none of
+ * them. Debounced rather than per-response because a page load fires dozens of
+ * requests and each save rewrites the whole HAR.
+ */
+function autoSave(polly, debounceMs) {
+    let timer;
+    polly.server.any().on('response', () => {
+        clearTimeout(timer);
+        timer = setTimeout(() => {
+            void polly.persister?.persist();
+        }, debounceMs);
+    });
+}
+/** Returns null when the mode is `off`, having constructed nothing. */
+export function startPolly(options) {
+    const { mode, recordingName, policy, alwaysPassthrough = [window.location.origin], apiNamespace = API_NAMESPACE, saveDebounceMs = SAVE_DEBOUNCE_MS, } = options;
+    if (mode === 'off') {
+        return null;
+    }
+    if (!registered) {
+        Polly.register(XHRAdapter);
+        Polly.register(RestPersister);
+        registered = true;
+    }
+    const polly = new Polly(recordingName, {
+        mode,
+        adapters: ['xhr'],
+        persister: 'rest',
+        persisterOptions: {
+            // Without this, every save drops the entries that were not replayed
+            // this session. Exercising one screen would throw away every other
+            // screen's recording.
+            keepUnusedRequests: true,
+            rest: { host: window.location.origin, apiNamespace },
+        },
+        // A replay miss must fail loudly. The default `true` quietly goes to the
+        // network and records it, which looks identical to replay working.
+        recordIfMissing: false,
+        // A 401 or a 500 is worth having on disk. The default drops it, and the
+        // gap only surfaces later as a replay miss with no obvious cause.
+        recordFailedRequests: true,
+        matchRequestsBy: {
+            // Screens refetch, and the same request is issued many times. With
+            // `order: true` the second one looks for a second recording and misses.
+            order: false,
+            // Apps attach bearer tokens and per-session headers. Matching on
+            // headers would make a recording valid only for the session that
+            // produced it.
+            headers: false,
+        },
+    });
+    applyPolicy(polly.server, { policy, alwaysPassthrough });
+    if (mode === 'record') {
+        autoSave(polly, saveDebounceMs);
+    }
+    return polly;
+}

package/dist/global-shim.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Define `global` for Polly's CommonJS-era dependencies.
+ *
+ * `@pollyjs/persister-rest` reads a bare, unbound `global` at module top level:
+ *
+ *   const REQUEST_ASYNC = !('navigator' in global) || ...
+ *   const NativeXMLHttpRequest = global.XMLHttpRequest;
+ *
+ * Browsers have no `global`, so evaluating that module throws
+ * `ReferenceError: global is not defined` before any of our code runs.
+ *
+ * The file does contain `var global = module.exports = ...` further up, but that
+ * sits inside a `createCommonjsModule(function (module) {...})` wrapper, so it
+ * binds nothing at module scope and does not save the references above.
+ *
+ * THIS IS THE FALLBACK, NOT THE MECHANISM. Under Vite the real fix is the
+ * `define: {global: 'globalThis'}` pair contributed by `./vite.ts` — one for app
+ * code and one under `optimizeDeps.esbuildOptions` for pre-bundled dependencies,
+ * because persister-rest is one and the plain `define` does not reach it.
+ *
+ * A runtime assignment cannot do that job here. It was the mechanism while these
+ * files were app source, where being the first import in the entry point orders
+ * it before the Polly imports. Once this is a *dependency*, Vite pre-bundles it
+ * and esbuild concatenates the modules in its own dependency order, so the
+ * assignment below can land after persister-rest has already read `global` — and
+ * measurably does. Import order in `browser.ts` does not survive bundling.
+ *
+ * It stays for the paths that are not pre-bundled: a consumer who excludes this
+ * package from `optimizeDeps`, a non-Vite bundler, or `./global-shim` imported
+ * directly. Harmless when `define` already did the work — the guard below simply
+ * finds `global` defined and does nothing.
+ */
+declare global {
+    var global: typeof globalThis;
+}
+export {};

package/dist/global-shim.js

@@ -0,0 +1,4 @@
+if (typeof globalThis.global === 'undefined') {
+    globalThis.global = globalThis;
+}
+export {};

package/dist/policy.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Turns a host policy into Polly route registrations.
+ *
+ * Nothing here knows a hostname — the host app supplies those. This file is the
+ * generic machinery and should stay that way.
+ *
+ * Both mechanisms below were verified against @pollyjs/core 6.0.6 by probe, not
+ * read off the docs, because the obvious reading of the API is wrong twice:
+ *
+ * 1. `server.any()` is ALWAYS middleware, never a route, and it is only
+ *    *global* when called with NO argument. `_registerMiddleware` takes its
+ *    global branch only for `!route || route === '*'`; anything else — including
+ *    `'/*path'` — registers under host `'/'`, which `Middleware.match` compares
+ *    against the request's origin. It therefore matches nothing, with no error.
+ *
+ * 2. Precedence is last-writer-wins, not most-specific-wins. `Route._valueFor`
+ *    walks `[...middleware, route]` in registration order and keeps the last
+ *    handler that set a key. So a host-scoped middleware registered *after* the
+ *    global one overrides it — which is why order matters below.
+ */
+import type { PollyServer } from '@pollyjs/core';
+export type HostPolicy = {
+    kind: 'all';
+} | {
+    kind: 'except';
+    hosts: string[];
+} | {
+    kind: 'only';
+    hosts: string[];
+};
+export interface PollyPolicyConfig {
+    /** One HAR per name: `recordings/<name>_<hash>/recording.har`. */
+    recordingName: string;
+    policy: HostPolicy;
+}
+/**
+ * Reduce a base URL to the origin Polly matches on.
+ *
+ * The config values are axios `baseURL`s, so they arrive with trailing slashes
+ * (`https://gallery-statistics-dev.../`) and sometimes a path
+ * (`${SANHEDRIN}/louvre`). Polly compares `parsedUrl.origin`, so both must be
+ * reduced or the host never matches.
+ *
+ * Returns null for anything unusable — an env var that was never set resolves
+ * to `undefined` here, and silently skipping it beats throwing during startup.
+ */
+export declare function toOrigin(value: string | undefined | null): string | null;
+/** Origins, deduped and with the unusable entries dropped. */
+export declare function toOrigins(values: readonly (string | undefined | null)[]): string[];
+export interface ApplyPolicyOptions {
+    policy: HostPolicy;
+    /**
+     * Hosts that are never mocked, whatever the policy says. Structural rather
+     * than user config: the app's own origin serves the dev server's HMR socket,
+     * the recording store itself, and every static asset.
+     */
+    alwaysPassthrough: readonly (string | undefined | null)[];
+}
+export declare function applyPolicy(server: PollyServer, { policy, alwaysPassthrough }: ApplyPolicyOptions): void;

package/dist/policy.js

@@ -0,0 +1,58 @@
+/**
+ * Reduce a base URL to the origin Polly matches on.
+ *
+ * The config values are axios `baseURL`s, so they arrive with trailing slashes
+ * (`https://gallery-statistics-dev.../`) and sometimes a path
+ * (`${SANHEDRIN}/louvre`). Polly compares `parsedUrl.origin`, so both must be
+ * reduced or the host never matches.
+ *
+ * Returns null for anything unusable — an env var that was never set resolves
+ * to `undefined` here, and silently skipping it beats throwing during startup.
+ */
+export function toOrigin(value) {
+    if (!value) {
+        return null;
+    }
+    try {
+        return new URL(value).origin;
+    }
+    catch {
+        return null;
+    }
+}
+/** Origins, deduped and with the unusable entries dropped. */
+export function toOrigins(values) {
+    const origins = values
+        .map(toOrigin)
+        .filter((origin) => origin !== null);
+    return Array.from(new Set(origins));
+}
+export function applyPolicy(server, { policy, alwaysPassthrough }) {
+    const never = toOrigins(alwaysPassthrough);
+    if (policy.kind === 'only') {
+        // Global default: everything passes through. Must be registered BEFORE
+        // the host-scoped overrides below, per last-writer-wins.
+        server.any().passthrough();
+        for (const origin of toOrigins(policy.hosts)) {
+            // A host that is both allowlisted and always-passthrough stays
+            // passed through: we simply never opt it back in.
+            if (never.includes(origin)) {
+                continue;
+            }
+            server.host(origin, () => {
+                server.any('/*path').passthrough(false);
+            });
+        }
+        return;
+    }
+    // `all` and `except` share the same default — Polly intercepts anything it
+    // has no route for — so only the exclusions need registering.
+    const excluded = policy.kind === 'except'
+        ? toOrigins([...policy.hosts, ...alwaysPassthrough])
+        : never;
+    for (const origin of excluded) {
+        server.host(origin, () => {
+            server.any('/*path').passthrough();
+        });
+    }
+}

package/dist/store.d.ts

@@ -0,0 +1,33 @@
+/**
+ * The Polly recording store, as a connect-style middleware.
+ *
+ * `@pollyjs/persister-rest` saves recordings by talking HTTP to a server that
+ * writes them to disk. That server ships as `@pollyjs/node-server`, but only as
+ * an express app or a standalone process on its own port — both of which would
+ * mean a second server and a CORS story for what is three routes.
+ *
+ * `API` is the part that actually touches the filesystem, independent of
+ * express, so this returns a bare `(req, res, next)` handler instead: mount it
+ * on a Vite dev server, an express app, or a plain `http.createServer`, on the
+ * same origin as the app. One command, no extra port.
+ *
+ * The contract is fixed by the persister (`@pollyjs/persister-rest/src/index.js`):
+ *
+ *   GET    {namespace}/{recordingId}  -> 200 + HAR json, or 204 when absent
+ *   POST   {namespace}/{recordingId}  -> 201, body is the HAR
+ *   DELETE {namespace}/{recordingId}  -> 200
+ *
+ * 204-rather-than-404 is deliberate on Polly's part: a missing recording is a
+ * normal outcome, and a 404 would show up as a scary red line in the console.
+ */
+import type { IncomingMessage, ServerResponse } from 'node:http';
+/** Matches the persister default, and what `startPolly` is configured with. */
+export declare const STORE_NAMESPACE = "/api/polly";
+export interface RecordingStoreOptions {
+    recordingsDir?: string;
+    /** Maximum HAR size accepted on POST, in bytes. */
+    bodyLimit?: number;
+}
+/** The connect signature, declared here so this file needs no framework types. */
+export type StoreMiddleware = (req: IncomingMessage, res: ServerResponse, next: (err?: unknown) => void) => void;
+export declare function recordingStore({ recordingsDir, bodyLimit }?: RecordingStoreOptions): StoreMiddleware;

package/dist/store.js

@@ -0,0 +1,73 @@
+import { API } from '@pollyjs/node-server';
+/** Matches the persister default, and what `startPolly` is configured with. */
+export const STORE_NAMESPACE = '/api/polly';
+/** 50mb, same as node-server's own default. A HAR with image bodies gets big. */
+const BODY_LIMIT = 50 * 1024 * 1024;
+function readBody(req, limit) {
+    return new Promise((resolve, reject) => {
+        const chunks = [];
+        let size = 0;
+        req.on('data', (chunk) => {
+            size += chunk.length;
+            if (size > limit) {
+                reject(new Error(`recording exceeds ${limit} bytes`));
+                req.destroy();
+                return;
+            }
+            chunks.push(chunk);
+        });
+        req.on('end', () => resolve(Buffer.concat(chunks).toString('utf8')));
+        req.on('error', reject);
+    });
+}
+function send(res, status, body) {
+    res.statusCode = status;
+    // node-server's express version wraps these routes in `nocache` for the same
+    // reason: a cached 204 would make a recording that exists on disk look missing.
+    res.setHeader('Cache-Control', 'no-store');
+    if (body === undefined) {
+        res.end();
+        return;
+    }
+    res.setHeader('Content-Type', 'application/json; charset=utf-8');
+    res.end(typeof body === 'string' ? body : JSON.stringify(body));
+}
+export function recordingStore({ recordingsDir = 'recordings', bodyLimit = BODY_LIMIT } = {}) {
+    const api = new API({ recordingsDir });
+    return async (req, res, next) => {
+        // Connect strips the mount path, so `req.url` is what follows the namespace.
+        const name = decodeURIComponent((req.url || '/').split('?')[0].replace(/^\//, ''));
+        // The name is joined straight into a filesystem path, and it arrives from
+        // the browser — a name containing separators could write outside
+        // `recordingsDir` entirely.
+        if (name === '' || name.includes('/') || name.includes('\\') || name.includes('..')) {
+            send(res, 400, { error: 'invalid recording id' });
+            return;
+        }
+        try {
+            if (req.method === 'GET') {
+                // `getRecording`, singular. node-server's own `types.d.ts` calls it
+                // `getRecordings`, but `src/api.js` defines `getRecording` and that
+                // is what runs. Editors flag this; renaming it to match breaks it.
+                const { status, body } = api.getRecording(name);
+                send(res, status, status === 200 ? body : undefined);
+                return;
+            }
+            if (req.method === 'POST') {
+                const raw = await readBody(req, bodyLimit);
+                const { status } = api.saveRecording(name, JSON.parse(raw));
+                send(res, status);
+                return;
+            }
+            if (req.method === 'DELETE') {
+                const { status } = api.deleteRecording(name);
+                send(res, status);
+                return;
+            }
+            next();
+        }
+        catch (error) {
+            send(res, 500, { error: error.message });
+        }
+    };
+}

package/dist/vite.d.ts

@@ -0,0 +1,31 @@
+/**
+ * One Vite plugin: the recording store plus the polly-studio editor.
+ *
+ * Two plugins would be honest about the two concerns, but they always go
+ * together and each needed the same `recordingsDir` — so the host app's
+ * vite.config gains one import and one line.
+ *
+ * WHY THE STUDIO'S `basePath` IS NOT SET. Connect strips the mount path before
+ * the handler runs — `GET /__polly/api/recordings` arrives as
+ * `/api/recordings` — so the handler must not strip it a second time. The
+ * browser side does not need to be told either: the page derives its API base
+ * from `location.pathname`. Set `basePath` here and every API call 404s.
+ *
+ * Dev only, deliberately. This hooks `configureServer`, which a production build
+ * never calls, and `pollyUi()` disables itself when `NODE_ENV === 'production'`
+ * anyway — recordings hold real recorded request and response bodies.
+ */
+import type { Plugin } from 'vite';
+export interface PollyKitOptions {
+    /** Where HARs are read from and written to. Gitignore it. */
+    recordingsDir?: string;
+    /** Mount path for the editor UI. */
+    studioPath?: string;
+    /** Where the store is mounted. Change it and `startPolly`'s `apiNamespace` together. */
+    apiNamespace?: string;
+    /** Set false to serve the store without the editor. */
+    studio?: boolean;
+}
+export default function pollyKit(options?: PollyKitOptions): Plugin;
+export { recordingStore, STORE_NAMESPACE } from './store.js';
+export type { RecordingStoreOptions, StoreMiddleware } from './store.js';

package/dist/vite.js

@@ -0,0 +1,85 @@
+import { pollyUi } from '@avivbenhamo/polly-studio';
+import { recordingStore, STORE_NAMESPACE } from './store.js';
+const STUDIO_PATH = '/__polly';
+export default function pollyKit(options = {}) {
+    const { recordingsDir = 'recordings', studioPath = STUDIO_PATH, apiNamespace = STORE_NAMESPACE, studio = true, } = options;
+    return {
+        name: 'polly-kit',
+        /**
+         * Contribute the settings Polly needs in a browser, so the host app's
+         * vite.config stays one import and one line.
+         *
+         * Vite merges what a plugin returns here into the user config, and all of
+         * these are additive — an app that already declares them ends up with the
+         * same result.
+         */
+        config() {
+            return {
+                // `@pollyjs/persister-rest` reads a bare, unbound `global` at module
+                // top level, which does not exist in a browser:
+                //
+                //   const REQUEST_ASYNC = !('navigator' in global) || ...
+                //
+                // `global-shim.ts` assigns it at runtime, and being the first import
+                // in `browser.ts` orders that correctly — but ONLY while those are
+                // app source. Once this is a dependency, Vite pre-bundles it and
+                // esbuild concatenates the modules in its own dependency order, so
+                // the assignment can land after the read. Verified: it does.
+                //
+                // So rewrite the identifier as well, in both places — which of the
+                // two applies has moved between Vite versions, and pre-bundled
+                // dependencies need the esbuild one specifically.
+                define: { global: 'globalThis' },
+                resolve: {
+                    alias: [
+                        {
+                            // `@pollyjs/utils` imports `buffer` to decide whether a
+                            // response body is utf8-representable. Vite externalizes
+                            // Node builtins in the browser, so without this the import
+                            // resolves to a stub and every response errors with
+                            // "Cannot read properties of undefined (reading 'from')".
+                            //
+                            // The trailing slash is what makes this resolve to the npm
+                            // `buffer` package rather than back to the Node builtin. The
+                            // anchored regex keeps it from also rewriting `buffer/...`.
+                            find: /^buffer$/,
+                            replacement: 'buffer/',
+                        },
+                    ],
+                },
+                optimizeDeps: {
+                    // `buffer`: pre-bundled alongside the Polly packages that import
+                    // it, so the dep optimizer does not treat it as an unresolved
+                    // external on a cold start.
+                    //
+                    // This package itself: without it, Vite discovers the dependency
+                    // when the entry module first requests it, optimizes, and triggers
+                    // a full reload — and on that first pass the esbuild `define` below
+                    // has not been applied, so persister-rest crashes on `global` and
+                    // Polly does not attach. Measured: the first load after a cold
+                    // `.vite` cache missed every request, the reload after it recorded
+                    // fine. Naming it here makes the optimizer run before the server
+                    // accepts requests, so the first load is the optimized one.
+                    include: ['buffer', '@avivbenhamo/polly-kit'],
+                    // The `define` above does not reach pre-bundled dependencies, and
+                    // persister-rest is one. This is the half that actually fixes it.
+                    esbuildOptions: { define: { global: 'globalThis' } },
+                },
+            };
+        },
+        configureServer(server) {
+            server.middlewares.use(apiNamespace, recordingStore({ recordingsDir }));
+            if (!studio) {
+                return;
+            }
+            server.middlewares.use(studioPath, pollyUi({ recordingsDir }));
+            server.httpServer?.once('listening', () => {
+                // Vite prints its own URLs just above; this rides along so the
+                // editor is discoverable without reading this file.
+                const port = server.config.server.port;
+                server.config.logger.info(`  \x1b[32m➜\x1b[0m  polly-studio: \x1b[36mhttp://localhost:${port}${studioPath}\x1b[0m`);
+            });
+        },
+    };
+}
+export { recordingStore, STORE_NAMESPACE } from './store.js';

package/package.json

@@ -0,0 +1,68 @@
+{
+  "name": "@avivbenhamo/polly-kit",
+  "version": "0.1.0",
+  "description": "Drop-in record/replay of an app's HTTP traffic with Polly.JS, plus the polly-studio editor. Bring your own host policy.",
+  "license": "MIT",
+  "type": "module",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "main": "./dist/browser.js",
+  "types": "./dist/browser.d.ts",
+  "//typesVersions": "For consumers still on moduleResolution 'node', which ignores `exports`. Drop once everything is on 'bundler'.",
+  "typesVersions": {
+    "*": {
+      "vite": ["./dist/vite.d.ts"],
+      "store": ["./dist/store.d.ts"],
+      "global-shim": ["./dist/global-shim.d.ts"]
+    }
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/browser.d.ts",
+      "default": "./dist/browser.js"
+    },
+    "./vite": {
+      "types": "./dist/vite.d.ts",
+      "default": "./dist/vite.js"
+    },
+    "./store": {
+      "types": "./dist/store.d.ts",
+      "default": "./dist/store.js"
+    },
+    "./global-shim": {
+      "types": "./dist/global-shim.d.ts",
+      "default": "./dist/global-shim.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "//scripts": "dist/ is gitignored, so `prepack` builds it — npm runs prepack before both `npm pack` and `npm publish`. Deliberately not `prepare`: that would also fire in a consumer's tree, where there is no src/ or tsconfig to compile.",
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "prepack": "tsc -p tsconfig.json"
+  },
+  "dependencies": {
+    "@avivbenhamo/polly-studio": "^0.1.0",
+    "@pollyjs/adapter-xhr": "^6.0.6",
+    "@pollyjs/core": "^6.0.6",
+    "@pollyjs/node-server": "^6.0.6",
+    "@pollyjs/persister-rest": "^6.0.6",
+    "buffer": "^6.0.3"
+  },
+  "peerDependencies": {
+    "vite": ">=4"
+  },
+  "peerDependenciesMeta": {
+    "vite": {
+      "optional": true
+    }
+  },
+  "//devDependencies": "vite is here only so `./vite` typechecks standalone; it stays an optional peer at runtime.",
+  "devDependencies": {
+    "typescript": "^5.3.3",
+    "vite": "^5.0.0"
+  }
+}