tursodatabase / tursodatabase/libsql-client-ts

@libsql/client v0.17.0 regression?: "XMLHttpRequest is not defined" on Cloudflare Pages

Open
#339 2 comments 3 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
TypeScript
Stars
576
Forks
69
PR merge metrics
No merged PRs in 30d

Description

Describe the bug

After upgrading to @libsql/client v0.17.0, applications on Cloudflare Pages (Pages Functions / Edge Runtime) fail at runtime when executing database queries.

The error is:

ReferenceError: XMLHttpRequest is not defined

This is a regression from v0.15.x, where the client worked correctly in the same environment.

  • Environment: Next.js 15 (using API Routes) deployed on Cloudflare Pages.
  • Build time: Success (No errors/warnings).
  • Runtime: Fails only when a database request is actually made.

Reproduction and Context

I was unable to create a minimal reproduction using Next.js 15 due to the complexity of the setup.

However, I found that the following esbuild command—which I believe mimics the Cloudflare Workers/Pages environment by using --platform=browser and --conditions=workerd—results in XMLHttpRequest being included in the bundle. Since the Edge Runtime lacks XMLHttpRequest, this seems to be the likely cause of the error I'm seeing, although I am not 100% certain this simulation also matches the Next.js/Wrangler build process.

  1. Setup:
mkdir repro-libsql && cd repro-libsql
npm init -y
npm install @libsql/client@0.17.0
  1. Create repro.ts:
import { createClient } from "@libsql/client";
export const onRequest = async () => {
  const client = createClient({ url: "https://example.com" });
  await client.execute("SELECT 1");
};
  1. Bundle and Verify:
npx esbuild repro.ts --bundle --platform=browser --conditions=workerd --format=esm --outfile=bundle.js
grep "new XMLHttpRequest" bundle.js
# Output: ... var xhr = new XMLHttpRequest(); ...

The output confirms that new XMLHttpRequest is present in the bundle generated with these settings. In v0.15.x, this same process resulted in a bundle that used the native fetch API without any references to XMLHttpRequest.

Root Cause Analysis

The regression appears to be caused by the switch from @libsql/isomorphic-fetch to cross-fetch in @libsql/hrana-client@0.9.0.

While @libsql/client itself has a workerd export condition, its dependency cross-fetch does not. When a bundler targets a non-Node environment (like Cloudflare Pages), it resolves cross-fetch to its browser distribution. This distribution includes the whatwg-fetch polyfill, which lazily instantiates XMLHttpRequest.

Since the Edge Runtime (workerd) provides a global fetch but strictly prohibits XMLHttpRequest, the application crashes with a ReferenceError as soon as a database query is executed.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with the repro.ts entry point and run the documented esbuild command using @libsql/client v0.17.0, then compare its output with v0.15.x. Trace how @libsql/hrana-client resolves cross-fetch under the browser and workerd conditions; done means the Edge bundle does not include XMLHttpRequest and a database query works in the described environment.

Written by the indexing model from the issue text.

Assessment

Tech stack
nextjs, sqlite, typescript
Domain
api, backend, databases
Issue type
Bug
Difficulty
4/5
Estimated time
3-5 days
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
45/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.