Getting started

Installation

Package on npm: @hamdymohamedak/openfetch. Source repo: openfetch-js/OpenFetch on GitHub.

npm install @hamdymohamedak/openfetch

The package is ESM-only ("type": "module"). Import from "@hamdymohamedak/openfetch".

Subpath imports (tree-shaking)

import openFetch from "@hamdymohamedak/openfetch";
import { retry, timeout, debug } from "@hamdymohamedak/openfetch/plugins";
import { createFluentClient } from "@hamdymohamedak/openfetch/sugar";

The exports field in package.json lists these entrypoints so bundlers can include only what you use. See Plugins & fluent API.

Requirements

Runtime	Notes
Node.js	18+ (global fetch and AbortController)
Bun / Deno	Standard fetch
Browsers	Modern browsers with fetch
Cloudflare Workers	fetch available in worker global

No mandatory polyfills on supported environments.

Default instance

The default export is a client created with createClient() and no initial defaults:

import openFetch from "@hamdymohamedak/openfetch";

const res = await openFetch.get("https://api.example.com/v1/users");
// res is OpenFetchResponse: { data, status, statusText, headers, config }

Named client with createClient / create

createClient and create are aliases. Pass initial defaults; you can still mutate client.defaults later.

import { createClient } from "@hamdymohamedak/openfetch";

const api = createClient({
  baseURL: "https://api.example.com",
  headers: { Authorization: "Bearer <token>" },
  timeout: 10_000,
  unwrapResponse: true,
});

const users = await api.get("/v1/users");
// With unwrapResponse: true, users is the parsed body only (T), not OpenFetchResponse

HTTP helpers (overview)

Each method returns Promise<OpenFetchResponse<T>> unless unwrapResponse is true, then Promise<T>.

Method	Notes
request(urlOrConfig, config?)	url string/URL or full config object
get, head, options	URL + optional config
post, put, patch	URL, optional data, optional config — plain objects get JSON body + content-type when no CT set
delete	URL + optional config

URL required: If the merged config has no url, the client throws: openfetch: `url` is required.

For method-by-method examples (query params, JSON, FormData, unwrapResponse), see HTTP methods.

Registering middleware

import { createClient, createRetryMiddleware } from "@hamdymohamedak/openfetch";

const client = createClient({
  middlewares: [createRetryMiddleware()],
});
// or later:
client.use(createRetryMiddleware({ maxAttempts: 5 }));

See Interceptors & middleware and Retry & cache.

Plugins (shorter DX)

Same behavior as createRetryMiddleware, with an attempts alias:

import { createClient } from "@hamdymohamedak/openfetch";
import { retry, timeout, hooks, debug, strictFetch } from "@hamdymohamedak/openfetch/plugins";

const client = createClient({ baseURL: "https://api.example.com" })
  .use(retry({ attempts: 3, baseDelayMs: 400 }))
  .use(timeout(12_000))
  .use(debug({ includeRequestHeaders: true, maskStrategy: "partial" }));

Register retry before timeout. Full plugin reference: Plugins & fluent API.

Next

• HTTP methods — detailed syntax for every verb
• Plugins & fluent API — retry, timeout, debug, fluent chains
• React & Vue — framework integration patterns
• Configuration for every request option and response details.