Skip to main content

Bundlers and frameworks for the Keploy capture SDK​

View as Markdown
FreeTeamsScaleEnterpriseSelf-HostedDedicated

@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​

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.

SetupVersion testedBody workerWhat you do
Vite8.3.8YesNothing
Next.js, with Turbopack (its default)16.4.3, React 19.3.1YesNothing
Next.js, with --webpack16.4.3, React 19.3.1YesNothing
webpack 55.112.2YesNothing
webpack 5 with babel-loader, for Chrome 60 and Safari 115.112.2YesRun babel-loader over node_modules, and set webpack's target to the same browsers
webpack 4 with babel-loader, as Create React App 4 runs it4.47.0NoNothing; bodies are redacted on the main thread
Parcel 22.16.4Yesnpm install buffer
esbuild0.28.2NoCopy the worker beside your bundle
esbuild, with the worker copied0.28.2Yes—
No bundler, an import map for rrweb—YesServe the package's dist/ as it is, and map rrweb

The three UI capture sample shops 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 shows their setup.

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 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.

With any other bundler, check that your build emits the worker. Redaction off the main thread says what a cut body looks like.

Vite​

Vite emits everything on its own. In the React sample 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​

Next.js emits the worker with Turbopack, its default, and with --webpack: in the Next.js sample 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.

  • 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 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 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 needs the buffer package:

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:

@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 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:

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

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. Without the import map, rrweb cannot load, and the capture ends before anything is sent with KUI_E_DOM_RECORDER_UNAVAILABLE.

The plain HTML sample shop does exactly this: see the Plain HTML tab of Install the SDK.

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​

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:

FileGzippedLoaded
dist/body-redact.mjsabout 9.7 kBAt init(), beside rrweb, for a capture that records bodies (the default, "balanced")
dist/body-worker.jsabout 9.3 kBIn the page's next idle period after such a capture starts
dist/strict-attributes.mjsabout 1.3 kBUnder privacyMode: "strict" only, which loads neither body file
dist/request-term.mjsabout 1.2 kBThe 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 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.