Client Configuration & Defaults

Customize global networking defaults across all requests dispatched by an HttpClient instance.


Comprehensive Configuration Example

The following example shows all primary client options configured together:

client.ts
typescript
import { createClient } from 'react-native-fetch-client';

const api = createClient({
  // 1. Base URL
  baseURL: 'https://api.example.com/v1',

  // 2. Timeout in milliseconds (0 = no timeout)
  timeout: 8000,

  // 3. Default HTTP Headers
  headers: {
    'Accept': 'application/json',
    'X-Client-Platform': 'mobile',
  },

  // 4. Global Bearer token or async getter
  bearerToken: async () => {
    return await secureStorage.getItem('access_token');
  },

  // 5. Retry configuration with exponential backoff
  retry: {
    attempts: 3,
    backoff: 'exponential',
    delay: 500,
    maxDelay: 5000,
    jitter: true,
  },

  // 6. In-flight request deduplication
  dedup: {
    enabled: true,
  },

  // 7. Max concurrent requests (throttle)
  maxConcurrentRequests: 6,

  // 8. Circuit breaker
  circuitBreaker: {
    enabled: true,
    failureThreshold: 5,
    resetTimeoutMs: 30000,
  },

  // 9. Request diagnostics
  debug: false,
});

ClientConfig Reference

ClientConfig Properties
PropertyTypeDefaultDescription
baseURLstringundefinedBase URL prepended to all relative request endpoints. Must not have a trailing slash.
timeoutnumber0Default timeout in milliseconds. Defaults to 0 (no timeout).
headersRecord<string, string>{}Default headers attached to every outgoing HTTP request.
bearerTokenstring | (() => Promise<string | null>)undefinedStatic string or async function returning a Bearer token attached to requests.
retryPartial<RetryPolicy>undefinedRetry configuration including attempts, backoff type, delay, and retryOn status codes.
dedupDedupConfig{ enabled: false }Request deduplication options. Coalesces simultaneous identical GET flights.
cacheCacheConfig{ enabled: false }In-memory LRU and persistent storage caching configuration with SWR support.
authAuthConfigundefinedToken retrieval and optional single-flight refresh callbacks. getToken is required.
maxConcurrentRequestsnumberundefinedCaps concurrent active requests; excess requests wait in a FIFO queue.
circuitBreakerCircuitBreakerConfig{ enabled: false }Fails fast when error threshold is crossed to prevent cascading failures.
debugboolean | DebugLoggerfalseEnables request diagnostics or sends them to a custom logger.
Request-Level Overrides
Every client-level setting (such as timeout, headers, and retry) can be overridden on an individual request basis by passing a custom RequestConfig object as the final argument.