Registry / devops / cloudflare-tools-fetch

cloudflare-tools-fetch

library0.2.3jsnpmunverified

A lightweight HTTP client built on the native fetch API, specifically designed for Cloudflare Workers and browser environments. Version 0.2.3 (as of mid-2025) provides zero-dependency HTTP utilities including timeout control, automatic retry with configurable strategies, request/response interceptors, streaming support, and TypeScript definitions. Differentiates from generic fetch wrappers like node-fetch or ky by being optimized for Cloudflare Workers' edge runtime, supporting Request object passthrough, and offering fluent builder patterns for common worker patterns like KV storage integration and environment handling. Active development with monthly releases.

devops

npm install cloudflare-tools-fetch

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · CLOUDFLARE-TOOLS-F

cloudflare-tools-fetch

devopsjavascriptv0.2.3

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

FetchClient

✓ import { FetchClient } from 'cloudflare-tools-fetch'

✗ const { FetchClient } = require('cloudflare-tools-fetch');

ESM-only. CommonJS require will fail because the package uses 'type':'module' and only exports ESM.

fetchWithTimeout

✓ import { fetchWithTimeout } from 'cloudflare-tools-fetch'

✗ import fetchWithTimeout from 'cloudflare-tools-fetch';

Named export, not default. Common pattern mistake when expecting a default export.

fetchWithRetry

✓ import { fetchWithRetry } from 'cloudflare-tools-fetch'

✗ import fetchWithRetry from 'cloudflare-tools-fetch';

Named export. Default export not available.

Create a FetchClient with timeout, perform GET and POST requests, and parse JSON responses.

import { FetchClient } from 'cloudflare-tools-fetch'; const client = new FetchClient(); // GET request with timeout const response = await client.get('https://jsonplaceholder.typicode.com/posts/1', { timeout: 5000 }); const data = await response.json(); console.log('Data:', data); // POST request const postResponse = await client.post('https://jsonplaceholder.typicode.com/posts', { title: 'foo', body: 'bar', userId: 1 }, { headers: { 'Content-Type': 'application/json' } }); const postData = await postResponse.json(); console.log('Created:', postData);

Debug

Known issues

breakingIn version 0.2.0, the constructor signature changed: new FetchClient() no longer accepts options directly. Use setConfig() instead.

fix

// Old (removed): new FetchClient({timeout: 5000})
// New:
const client = new FetchClient();
client.setConfig({timeout: 5000});

affects: >=0.2.0

breakingThe 'fetchStream' method returns an object with 'data' (ReadableStream) and 'response' (Response) since v0.2.0. Previously it returned the raw Response.

fix

// Old: const stream = await client.fetchStream(url);
// New: const { data, response } = await client.fetchStream(url);

affects: >=0.2.0

deprecatedMethod 'fetchText' is deprecated since v0.2.0 and will be removed in v0.3.0. Use client.get(url).then(r => r.text()) instead.

fix

const text = await client.get('url').then(r => r.text());

affects: >=0.2.0 <0.3.0

gotchaThe package does not support Node.js http module. It relies on Web API 'fetch' which exists in Cloudflare Workers, browsers, and Node 18+ (with --experimental-fetch flag on older versions). Might throw in Node 16 without flag.

fix

Use on Cloudflare Workers or Node 18+ with global fetch. For Node.js <18, add polyfill: npm i -D node-fetch and import 'node-fetch'.

affects: all

gotchaInterceptors mutate the config object. Be careful when reusing config objects across requests, as interceptors may modify them (e.g., adding auth headers). Consider cloning.

fix

client.useRequestInterceptor(config => ({ ...config, headers: { Authorization: 'Bearer token' } }));

affects: all

Errors

Common errors & fixes

TypeError: FetchClient is not a constructor

CommonJS require pattern used instead of ESM import.

fix

Change to: import { FetchClient } from 'cloudflare-tools-fetch'

Error: fetch is not defined

Running in Node.js environment older than 18 (or without experimental fetch).

fix

Use Node 18+ or install global fetch polyfill: npm install node-fetch. Then add 'import fetch from "node-fetch";' before using the client.

TypeError: response.json is not a function

Trying to call .json() on an error Response-like object or calling it before properly reading the stream.

fix

Ensure you are calling .json() on a valid Response object, not on the raw body or on a rejected promise. Use response.ok to check status before parsing.

Upgrade

Version history

0.2.3latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

4 hits · last 30 days

node

Resources

githubhttps://github.com/jwyGithub/cloudflare-tools ↗

packagecloudflare-tools-fetch ↗

homepagehttps://github.com/jwyGithub/cloudflare-tools ↗