FetchOptions

Complete configuration options for ofetch requests

Overview

The FetchOptions interface extends the standard RequestInit and provides additional configuration for ofetch requests including base URL, query parameters, hooks, retry logic, and response parsing.

Type Signature

export interface FetchOptions<R extends ResponseType = ResponseType, T = any>
  extends Omit<RequestInit, "body">,
    FetchHooks<T, R> {
  baseURL?: string;
  body?: RequestInit["body"] | Record<string, any>;
  ignoreResponseError?: boolean;
  params?: Record<string, any>; // @deprecated use query instead
  query?: Record<string, any>;
  parseResponse?: (responseText: string) => any;
  responseType?: R;
  duplex?: "half" | undefined;
  dispatcher?: InstanceType<typeof import("undici").Dispatcher>;
  agent?: unknown;
  timeout?: number;
  retry?: number | false;
  retryDelay?: number | ((context: FetchContext<T, R>) => number);
  retryStatusCodes?: number[];
}

Options

baseURL

baseURL · string

Base URL to prepend to all requests. The request URL will be resolved against this base.

await ofetch('/users', {
  baseURL: 'https://api.example.com'
})
// Fetches: https://api.example.com/users

body

body · RequestInit['body'] | Record<string, any>

Request body. Accepts standard fetch body types or plain objects. Objects are automatically serialized to JSON and appropriate headers are set.

await ofetch('/users', {
  method: 'POST',
  body: { name: 'John', email: '[e-mail]' }
})

ignoreResponseError

ignoreResponseError · boolean · default: "false"

When true, prevents ofetch from throwing errors for 4xx and 5xx status codes. The response will be returned normally instead.

const response = await ofetch('/users/404', {
  ignoreResponseError: true
})

query

query · Record<string, any>

Query parameters to append to the URL. Values are automatically URL-encoded.

await ofetch('/users', {
  query: { page: 1, limit: 10 }
})
// Fetches: /users?page=1&limit=10

params

params · Record<string, any>

Deprecated: Use query instead. Query parameters to append to the URL.

parseResponse

parseResponse · (responseText: string) => any

Custom function to parse response text. Defaults to JSON.parse for JSON responses.

await ofetch('/data', {
  parseResponse: (text) => customParser(text)
})

responseType

responseType · ResponseType

Expected response type. One of: "json", "text", "blob", "arrayBuffer", or "stream". Defaults to "json". See ResponseType.

const blob = await ofetch('/image.png', {
  responseType: 'blob'
})

const text = await ofetch('/file.txt', {
  responseType: 'text'
})

duplex

duplex · 'half' | undefined

Experimental: Set to "half" to enable duplex streaming. Automatically set when using a ReadableStream as body.

await ofetch('/upload', {
  method: 'POST',
  body: readableStream,
  duplex: 'half'
})

dispatcher

dispatcher · InstanceType<typeof import('undici').Dispatcher>

Only supported in Node.js >= 18 using undici. Custom dispatcher for advanced request handling.

See undici documentation for details.

agent

agent · unknown

Only supported in older Node.js versions using node-fetch-native polyfill. Custom agent for HTTP(S) requests.

timeout

timeout · number

Request timeout in milliseconds. The request will be aborted if it takes longer than this value.

await ofetch('/slow-endpoint', {
  timeout: 5000 // 5 seconds
})

retry

retry · number | false

Number of times to retry failed requests. Set to false to disable retries. Defaults to 1 for GET requests and 0 for other methods.

await ofetch('/api/data', {
  retry: 3
})

retryDelay

retryDelay · number | ((context: FetchContext<T, R>) => number)

Delay between retries in milliseconds. Can be a number or a function that returns the delay based on the FetchContext.

// Fixed delay
await ofetch('/api/data', {
  retry: 3,
  retryDelay: 1000
})

// Dynamic delay (exponential backoff)
await ofetch('/api/data', {
  retry: 3,
  retryDelay: (context) => Math.pow(2, context.options.retry || 0) * 1000
})

retryStatusCodes

retryStatusCodes · number[]

HTTP status codes that should trigger a retry. Defaults to [408, 409, 425, 429, 500, 502, 503, 504].

await ofetch('/api/data', {
  retry: 3,
  retryStatusCodes: [429, 500, 502, 503]
})

Hooks

FetchOptions extends FetchHooks, providing lifecycle hooks:

onRequest · FetchHook | FetchHook[]

Called before the request is sent. See onRequest.

onRequestError · FetchHook | FetchHook[]

Called when the request fails. See onRequestError.

onResponse · FetchHook | FetchHook[]

Called after a successful response. See onResponse.

onResponseError · FetchHook | FetchHook[]

Called when the response has an error status (4xx, 5xx). See onResponseError.

Standard RequestInit Options

FetchOptions also includes all standard RequestInit options except body (which is redefined):

• method - HTTP method (GET, POST, PUT, DELETE, etc.)
• headers - Request headers
• signal - AbortSignal for request cancellation
• credentials - Credentials mode (omit, same-origin, include)
• mode - Request mode (cors, no-cors, same-origin)
• redirect - Redirect mode (follow, error, manual)
• referrer - Referrer URL
• referrerPolicy - Referrer policy
• integrity - Subresource integrity value
• keepalive - Keep connection alive
• cache - Cache mode

See MDN RequestInit documentation for details.

Type Parameters

R · ResponseType · default: "ResponseType"

The expected response type. See ResponseType.

T · any · default: "any"

The expected type of the response data

Related

• FetchHooks - Lifecycle hooks
• ResponseType - Response type options
• FetchContext - Context object passed to hooks