Skip to content
// EFFECT DAYS 2026

FetchHttpClient unstable

Fetch-based implementation of the Effect HTTP client service.

This module provides an HttpClient layer that executes requests through a Web Fetch API implementation. It is the transport to use in browsers, edge runtimes, and Node.js environments where globalThis.fetch is available, or anywhere a compatible fetch function can be supplied.

Requests with an Upgrade header fail with TransportError before anything is sent because fetch cannot hand over the connection.

4 exports Since v4.0.0 Source

Layers

layer

unstable
Since v4.0.0

Layer that provides an HttpClient implementation backed by the configured Fetch function.

When to use

Use when an Effect program should execute HttpClient requests through the platform fetch implementation, especially in browser, edge, or Node.js runtimes with globalThis.fetch.

Details

The layer uses the current Fetch reference and optional RequestInit service for each request. Request-specific method, headers, body, and abort signal are supplied by the client and override matching RequestInit fields.

Gotchas

Fetch behavior comes from the runtime's implementation, so CORS, cookies, redirects, abort handling, and streaming support can vary by platform. fetch follows redirects itself by default, so HttpClient.followRedirects has no effect unless RequestInit sets redirect: "manual". Trace propagation is on by default, and a browser preflight fails unless the target allows b3 and traceparent. Stream request bodies are sent as Web streams with duplex: "half" when the runtime supports it; see StreamBodyFallback for the unsupported case. Any content-length header is removed before calling fetch. Chrome passes the support check but rejects streaming uploads over HTTP/1.1, which surfaces as a TransportError, and browsers only deliver the response after the entire request body has been sent.

See

Signature

declare const layer: Layer.Layer<HttpClient.HttpClient>

Services

Fetch

unstable
Since v4.0.0

Context reference for the fetch implementation used by the fetch-based HTTP client.

Details

Defaults to globalThis.fetch.

Signature

declare const Fetch: Reference<{
  (input: URL | RequestInfo, init?: RequestInit): Promise<Response>;
  (input: string | URL | Request, init?: RequestInit): Promise<Response>;
}>

RequestInit

unstable
Since v4.0.0

Service that contains default fetch options for the fetch-based HTTP client.

When to use

Use to provide default credentials, cache, redirect, integrity, or other fetch options for outgoing HTTP requests.

Details

Request-specific method, headers, body, and abort signal are supplied by the client when a request is executed.

See

Signature

declare class RequestInit extends Shape<"effect/http/FetchHttpClient/RequestInit", RequestInit, this> {
  constructor(_: never);
}

StreamBodyFallback

unstable
Since v4.0.0

Context reference controlling stream bodies when the runtime does not support streaming requests.

Details

Defaults to "error", which fails with an EncodeError without sending the request. Set to "buffer" to collect the entire stream in memory and send it as a single body instead. Runtimes with streaming support always send the stream.

Gotchas

Buffering keeps the entire upload in memory and can exhaust memory for large or unbounded uploads. Support is detected once, on the first stream body sent, using the global Request implementation even when a custom Fetch is provided.

Signature

declare const StreamBodyFallback: Reference<"error" | "buffer">