tursodatabase / tursodatabase/libsql-client-ts
@libsql/client v0.17.0 regression?: "XMLHttpRequest is not defined" on Cloudflare Pages
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.
- Setup:
mkdir repro-libsql && cd repro-libsql
npm init -y
npm install @libsql/client@0.17.0
- Create
repro.ts:
import { createClient } from "@libsql/client";
export const onRequest = async () => {
const client = createClient({ url: "https://example.com" });
await client.execute("SELECT 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
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- 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