Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions content/llms-root.txt
Original file line number Diff line number Diff line change
Expand Up @@ -58,6 +58,7 @@ Keploy (founded 2021) is a CNCF Landscape project and API testing platform with
## UI Testing (Beta)
- [UI Testing overview](https://keploy.io/docs/running-keploy/ui-capture/): Record real user sessions in a web app with the capture SDK (@keploy/capture-sdk) and read each visit as UI flows and journeys in the dashboard, over the REST API, or from an AI agent through MCP
- [Dashboard quickstart](https://keploy.io/docs/ui-capture/quickstart-dashboard/): Create an ingest key, add it to a sample React shop, and see your first flows
- [Install the SDK](https://keploy.io/docs/ui-capture/install-sdk/): Add @keploy/capture-sdk to a React and Vite app, a Next.js App Router app or plain HTML pages, and check that recordings arrive
- [From first visit to journeys](https://keploy.io/docs/ui-capture/walkthrough-dashboard/): Record five visits, read their flows and journeys, read the same data from a script, and clean up
- [AI agent quickstart](https://keploy.io/docs/ui-capture/quickstart-agent/): Connect Claude Code, Cursor, Codex or another MCP client to Keploy and have it set up UI capture in your frontend
- [An agent onboards a web app](https://keploy.io/docs/ui-capture/walkthrough-agent/): Every MCP tool call an agent makes to set up UI capture and read flows and journeys, with the answers
Expand Down
7 changes: 2 additions & 5 deletions docusaurus.config.js
Original file line number Diff line number Diff line change
Expand Up @@ -221,14 +221,11 @@ s.parentNode.insertBefore(b, s);})(window.lintrk);`,
"@docusaurus/plugin-client-redirects",
{
redirects: [
// The README of @keploy/capture-sdk 3.0.1, on npm.
// The README of @keploy/capture-sdk 3.0.1, on npm. Its other link,
// /ui-capture/install-sdk/, is a page of its own.
// scripts/verify-ui-capture-sdk-links.js keeps every link the SDK
// ships resolvable.
{from: "/ui-capture/overview/", to: "/running-keploy/ui-capture/"},
{
from: "/ui-capture/install-sdk/",
to: "/running-keploy/ui-capture/#install-the-sdk",
},
// Pages that moved into the Universal Mocker section.
{
from: "/running-keploy/mock-quickstart/",
Expand Down
3 changes: 2 additions & 1 deletion scripts/verify-ui-capture-sdk-links.js
Original file line number Diff line number Diff line change
Expand Up @@ -97,7 +97,8 @@ const README_LINKS = [
// The README of the releases after 3.0.1.
"https://keploy.io/docs/",
"https://keploy.io/docs/running-keploy/ui-capture/",
// The README of 3.0.1, on npm: pages that have since moved.
// The README of 3.0.1, on npm: the overview, since moved (a redirect),
// and the install page.
"https://keploy.io/docs/ui-capture/overview/",
"https://keploy.io/docs/ui-capture/install-sdk/",
];
Expand Down
3 changes: 1 addition & 2 deletions versioned_docs/version-4.0.0/running-keploy/ui-capture.md
Original file line number Diff line number Diff line change
Expand Up @@ -108,8 +108,7 @@ await KeployCapture.init({
Use the `endpoint` the setup card or the API gives you. It is `https://api.keploy.io/ui/v1/ingest` on Keploy Cloud, and your own API server's URL followed by `/ui/v1/ingest` when you self-host. A self-hosted API server builds it from its `API_SERVER_URL`; if that isn't set to the server's public URL, the API returns an empty `endpoint` and says so in `next`, rather than guessing.

- **Early, and once.** The SDK starts recording the page's requests once it has loaded rrweb, which your bundler normally puts in a chunk of its own. A request the page makes before then is not recorded, so start `init` before your app's own code runs. Call it once per page load, not per route: a second `init` returns the same capture.
- **Three sample setups.** The [UI capture sample shops](https://github.com/keploy/samples-typescript) show the call in a React and Vite app (`ui-capture-react-shop`: `src/keploy.ts`, imported first in `src/main.tsx`), a Next.js App Router app (`ui-capture-next-shop`: `instrumentation-client.ts`) and plain HTML pages with no bundler (`ui-capture-html-shop`).
- **Without a bundler**, serve the package's `dist/` directory as it is, import `dist/index.mjs` from it, and map `rrweb` with an import map before the SDK loads. If rrweb cannot be loaded, the capture ends before anything is sent and reports [`KUI_E_DOM_RECORDER_UNAVAILABLE`](../ui-capture/errors.md#kui-e-dom-recorder-unavailable).
- **Per framework.** [Install the SDK](../ui-capture/install-sdk.md) shows the call in a React and Vite app, a Next.js App Router app and plain HTML pages with no bundler, from the [UI capture sample shops](https://github.com/keploy/samples-typescript). [Bundlers and frameworks](../ui-capture/bundlers.md) says what webpack, Parcel, esbuild and a page with no bundler need, and [Content-Security-Policy and workers](../ui-capture/csp-and-workers.md) what a CSP must allow.

### SDK options {#sdk-options}

Expand Down
166 changes: 166 additions & 0 deletions versioned_docs/version-4.0.0/ui-capture/bundlers.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,166 @@
---
id: bundlers
title: Bundlers and frameworks for the Keploy capture SDK
sidebar_label: Bundlers and frameworks
description: Which bundlers and frameworks the Keploy capture SDK is built with in its tests, what each needs, and how it loads its body worker and chunks.
tags:
- UI testing
- UI capture
- capture SDK
keywords:
- capture SDK
- Vite
- Next.js
- webpack
- Create React App
- Parcel
- esbuild
- import map
- Web Worker
---

import ProductTier from '@site/src/components/ProductTier';

<ProductTier tiers="Free, Teams, Scale, Enterprise" offerings="Self-Hosted, Dedicated" />

`@keploy/capture-sdk` is an ES module that your bundler builds into your app. Besides its main bundle, it loads a few files of its own while it runs, and your build must emit and deploy them:

- **rrweb**, the library it records the page with, which `init()` imports;
- **its body redaction code** and **its body worker**, a Web Worker that redacts request and response bodies off your page's main thread, with a small module that starts it;
- **its GraphQL code**, the first time a request body could be a GraphQL request;
- **its attribute list**, under `privacyMode: "strict"` only.

Most bundlers emit all of them on their own. This page says which setups the SDK's tests build, and what the others need.

## Tested setups {#tested-setups}

The SDK's tests install the package, packed as it is for publishing, beside each of these bundlers, build an app that starts a capture, and check in Chromium that it records a GraphQL request with its term, records under `privacyMode: "strict"`, and redacts a large request body.

| Setup | Version tested | Body worker | What you do |
| ----------------------------------------------------------------------------------------------- | -------------------- | ----------- | ------------------------------------------------------------------------------------- |
| [Vite](#vite) | 8.3.8 | Yes | Nothing |
| [Next.js](#nextjs), with Turbopack (its default) | 16.4.3, React 19.3.1 | Yes | Nothing |
| [Next.js](#nextjs), with `--webpack` | 16.4.3, React 19.3.1 | Yes | Nothing |
| [webpack 5](#webpack-5) | 5.112.2 | Yes | Nothing |
| webpack 5 with babel-loader, for Chrome 60 and Safari 11 | 5.112.2 | Yes | Run babel-loader over `node_modules`, and set webpack's `target` to the same browsers |
| [webpack 4](#webpack-4-and-create-react-app-4) with babel-loader, as Create React App 4 runs it | 4.47.0 | No | Nothing; bodies are redacted on the main thread |
| [Parcel 2](#parcel-2) | 2.16.4 | Yes | `npm install buffer` |
| [esbuild](#esbuild) | 0.28.2 | No | Copy the worker beside your bundle |
| [esbuild](#esbuild), with the worker copied | 0.28.2 | Yes | — |
| [No bundler](#no-bundler), an import map for rrweb | — | Yes | Serve the package's `dist/` as it is, and map `rrweb` |

The three [UI capture sample shops](https://github.com/keploy/samples-typescript) are built and tested in their own CI: React with Vite 8.3.8, Next.js 16.4.3 with the App Router, and plain HTML pages with no bundler. [Install the SDK](./install-sdk.md#add-it-to-your-app) shows their setup.

## Where there is no body worker {#where-there-is-no-body-worker}

The SDK starts its worker as `new Worker(new URL("./body-worker.js", import.meta.url))`, which webpack 5, Next.js (webpack and Turbopack), Vite and Parcel 2 turn into a file of your build. Where the worker cannot run, the capture still records every request and response, and redacts the bodies on the page's main thread instead, each only up to its first 64 KiB: a body over that is recorded cut, under a first line `[Body cut: 65536 of N characters kept, unverified]`. The SDK says so once per page with the [`KUI_E_BODY_WORKER_UNAVAILABLE`](./errors.md#kui-e-body-worker-unavailable) warning. There is no worker:

- under **webpack 4**, which cannot parse `import.meta`;
- under **esbuild**, until you copy the worker beside your bundle;
- in a build that loads the SDK's **CommonJS** files (its `require` entry), whose worker start has no `import.meta`;
- when your build's **assets are served from another origin**, such as webpack's `publicPath` or Next.js's `assetPrefix` on a CDN: a browser runs a worker only from the page's own origin;
- when the page's **Content-Security-Policy** does not let your origin run it: see [Content-Security-Policy and workers](./csp-and-workers.md).

With any other bundler, check that your build emits the worker. [Redaction off the main thread](./network-and-bodies.md#redaction-off-the-main-thread) says what a cut body looks like.

## Vite {#vite}

Vite emits everything on its own. In the [React sample shop](https://github.com/keploy/samples-typescript/tree/main/ui-capture-react-shop)'s production build, `npm run build` writes rrweb, the SDK's body redaction code, its body worker, its GraphQL code and its attribute list as files of their own under `dist/assets/`, beside the app's own bundle. Deploy all of them.

Under `npm run dev`, React's development checks (`StrictMode`) make every request twice, and the recording shows both, so check what is recorded against a production build (`npm run build && npm run preview`).

## Next.js {#nextjs}

Next.js emits the worker with Turbopack, its default, and with `--webpack`: in the [Next.js sample shop](https://github.com/keploy/samples-typescript/tree/main/ui-capture-next-shop)'s build, with Turbopack, it is `.next/static/media/body-worker.<hash>.js`. The SDK's tests build both with an App Router page and a Pages Router page. The sample shop starts the capture from `instrumentation-client.ts`: see [Install the SDK](./install-sdk.md#add-it-to-your-app).

- With `assetPrefix` on a CDN, the worker is served from another origin and cannot run.
- The SDK records what runs in the browser. A fetch in a server component runs on the server and is not recorded.

## webpack 5 {#webpack-5}

webpack 5 reads the package's `exports` map, bundles the SDK's chunks and emits its worker. A build transpiled for older browsers builds too: the SDK's tests build webpack 5 with babel-loader for Chrome 60 and Safari 11, and check that every script it emits parses as ES2019, without `import()` or optional chaining. For that:

- **Run babel-loader over `node_modules` too.** The SDK's and rrweb's files use newer syntax, such as optional chaining, so a rule that excludes `node_modules` leaves it in your bundle.
- **Set webpack's own `target` to the same browsers** (`target: "browserslist:chrome 60, safari 11"` in the tests), or webpack's runtime code keeps syntax those browsers cannot parse.

The tests run that build in current Chromium, not in Chrome 60 or Safari 11.

With `publicPath` on another origin, the worker cannot run.

## webpack 4 and Create React App 4 {#webpack-4-and-create-react-app-4}

webpack 4 ignores a package's `exports` map and reads its `module` field, which names `dist/index.bundler.mjs`: the same SDK, built so that webpack 4 never reads `import.meta`. It resolves the SDK's GraphQL code and strict's attribute list through the `request-term/package.json` and `strict-attributes/package.json` the package ships. So the build works, with no worker: the main thread redacts bodies, each up to 64 KiB, and the console shows `KUI_E_BODY_WORKER_UNAVAILABLE` once per page load that records bodies. To redact large bodies whole, move to webpack 5 or another bundler that emits the worker.

The SDK's tests run webpack 4 as Create React App 4 runs it: with babel-loader over `node_modules`, since webpack 4's parser predates the syntax the SDK and rrweb ship, and with Node's legacy OpenSSL provider (`NODE_OPTIONS=--openssl-legacy-provider`), since webpack 4 hashes with MD4. They also build the same entry for the server, as webpack 4's `target: "node"`, Nuxt 2 and Angular Universal 9 to 11 build it.

## Parcel 2 {#parcel-2}

Parcel 2 needs the `buffer` package:

```bash
npm install buffer
```

rrweb's build reads Node's `Buffer`, and Parcel bundles no polyfill for a Node built-in unless its package is installed. That is rrweb's need, and SDK 3.0.1 has it too. When `buffer` is missing, Parcel 2.16 installs it by itself, as a dev dependency, unless the `CI` environment variable is set. With `CI` set, `parcel build` fails, naming rrweb's files and saying:

```text
@parcel/resolver-default: Node builtin polyfill "buffer/" is not installed, but auto install is disabled.
```

Install it yourself, so that every build has it.

Parcel reads the package's `module` field, as webpack 4 does, and the package's `alias` sends it to the worker's start, so Parcel emits the worker.

## esbuild {#esbuild}

esbuild does not emit the worker: copy it from the package into your output directory, beside your bundle, and it runs. The SDK's tests build esbuild with `--format=esm --splitting`, so that rrweb and the SDK's chunks stay files of their own:

```bash
npx esbuild src/main.js --bundle --format=esm --splitting --outdir=dist
cp node_modules/@keploy/capture-sdk/dist/body-worker.js dist/
```

## No bundler {#no-bundler}

There is no script-tag build. Without a bundler:

- **Serve the package's `dist/` directory as it is**, and import `dist/index.mjs` from it. The SDK loads its other files from beside `dist/index.mjs`: `body-redact.mjs`, `request-term.mjs`, `strict-attributes.mjs` under strict, and `body-worker-unbundled.mjs`, which starts `body-worker.js`.
- **Map `rrweb` with an import map** before the SDK loads, to rrweb's `dist/rrweb.js`. The SDK imports `rrweb` by name, which only a bundler or an import map resolves.
- An import map that also maps `@keploy/capture-sdk/body-redact`, `/body-worker-start`, `/request-term` or `/strict-attributes` is used first.

A page that serves `dist/index.mjs` alone has no code to redact a body with: it records each body as not captured, never in the clear, and refuses every strict capture with [`KUI_E_STRICT_ATTRIBUTES_UNAVAILABLE`](./errors.md#kui-e-strict-attributes-unavailable). Without the import map, rrweb cannot load, and the capture ends before anything is sent with [`KUI_E_DOM_RECORDER_UNAVAILABLE`](./errors.md#kui-e-dom-recorder-unavailable).

The [plain HTML sample shop](https://github.com/keploy/samples-typescript/tree/main/ui-capture-html-shop) does exactly this: see the **Plain HTML** tab of [Install the SDK](./install-sdk.md#add-it-to-your-app).

## Assets on a CDN {#assets-on-a-cdn}

A browser runs a worker only from the page's own origin. So when your build's assets are served from a CDN, through webpack's `publicPath` or Next.js's `assetPrefix`, the SDK's chunks load from there, but its worker cannot run, and bodies over 64 KiB are recorded cut.

Loading the SDK itself from a CDN with no bundler works the same way: the chunks load from the CDN, which must send CORS headers, as CDNs do, and the worker cannot. Import `dist/index.mjs` by its path, for example `https://cdn.jsdelivr.net/npm/@keploy/capture-sdk@3.1.0/dist/index.mjs`:

- unpkg's package root redirects to `dist/index.mjs`, so it works too.
- jsDelivr's package root answers with the file at the root's own URL, where no chunk is beside it, so name the path.
- Don't load the package root with unpkg's `?module`. It serves `dist/index.bundler.mjs`, the build for webpack 4, which loads no chunk from beside it: it records every body as not captured and refuses every strict capture.

To have the worker, serve `dist/` from your own origin.

## Size {#size}

The SDK's main bundle, `dist/index.mjs`, is about 40.9 kB gzipped, rrweb not included; the CommonJS `dist/index.js` is 41.1 kB. Its other files load only when a capture needs them:

| File | Gzipped | Loaded |
| ---------------------------- | ------------ | ---------------------------------------------------------------------------------------- |
| `dist/body-redact.mjs` | about 9.7 kB | At `init()`, beside rrweb, for a capture that records bodies (the default, `"balanced"`) |
| `dist/body-worker.js` | about 9.3 kB | In the page's next idle period after such a capture starts |
| `dist/strict-attributes.mjs` | about 1.3 kB | Under `privacyMode: "strict"` only, which loads neither body file |
| `dist/request-term.mjs` | about 1.2 kB | The first time a request body could be a GraphQL request |

The figures were measured on the SDK repository's build, as the package's README and the [3.1.0 release notes](./capture-sdk-3-1-0-release-notes.md#size) give them; the published files differ by a few bytes. The package also ships source maps beside each file, for your tools; they are never inlined.

## Related

- [Install the SDK](./install-sdk.md)
- [Content-Security-Policy and workers](./csp-and-workers.md)
- [Network calls and bodies](./network-and-bodies.md)
- [`KUI_E_BODY_WORKER_UNAVAILABLE`](./errors.md#kui-e-body-worker-unavailable)
- [UI capture sample shops](https://github.com/keploy/samples-typescript)
Loading
Loading