Better Fetch Documentation

Better Fetch allows you to define headers at three distinct levels. Headers are merged in a specific order where later levels override earlier ones:

1. Configuration Level: Set in createFetch({ headers: ... }). These are applied to every request made by the instance.
2. Schema Level: Defined within createSchema to provide runtime validation and type safety for specific routes.
3. Request Level: Set on individual calls to the fetch function (e.g., betterFetch(url, { headers: ... })).

Aggregation Order (Later overrides earlier): Configuration headers $\rightarrow$ Schema headers $\rightarrow$ Request headers.

import { createFetch, createSchema } from "@better-fetch/fetch";
import { z } from "zod";

const $fetch = createFetch({
    baseURL: "http://localhost:3000",
    headers: {
        "x-api-key": "config-key", // 1. Configuration level
    },
    schema: createSchema({
        "/api/data": {
            headers: z.object({
                "x-tenant-id": z.string(), // 2. Schema level
            }),
        },
    }),
});

// 3. Request level: Final headers will include x-api-key, x-tenant-id, and x-request-id
const { data } = await $fetch("/api/data", {
    headers: {
        "x-tenant-id": "tenant-123",
        "x-request-id": "req-456",
    },
});

Fetch Schema allows you to pre-define your API's structure, including URL paths, request inputs, and response outputs. This provides a way to document your API and ensures that both request and response data are validated.

When using a schema, the output is validated against your provided schema; if validation fails, an error is thrown. You can validate headers, request bodies, query parameters, and more using createSchema.

import { createSchema, createFetch } from "@better-fetch/fetch";
import { z } from "zod";

export const zodSchema = createSchema({
    "/path": {
        input: z.object({
            userId: z.string(),
            id: z.number(),
            title: z.string(),
            completed: z.boolean(),
        }),
        output: z.object({
            userId: z.string(),
            id: z.number(),
            title: z.string(),
            completed: z.boolean(),
        }),
    }
})

const $fetch = createFetch({
    baseURL: "https://jsonplaceholder.typicode.com",
    schema: zodSchema
});

const { data, error } = await $fetch("/path", {
    body: {
        userId: "1",
        id: 1,
        title: "title",
        completed: true,
    },
});

You can use Zod or any StandardSchema library to define header schemas. This provides runtime validation and TypeScript type inference for your headers.

Important: Always define header keys in lowercase within your schemas (e.g., "x-user-id") to ensure reliable case-insensitive matching. While keys must be lowercase in the schema, you can pass headers using any casing (e.g., "X-User-Id") in your actual requests.

import { createFetch, createSchema } from "@better-fetch/fetch";
import { z } from "zod";

const $fetch = createFetch({
    baseURL: "http://localhost:3000",
    schema: createSchema({
        "/api/users": {
            headers: z.object({
                "x-user-id": z.string().uuid(),
                "x-api-version": z.string().regex(/^\d+\.\d+\.\d+$/),
            }),
        },
    }),
});

// Validates headers at runtime
const { data, error } = await $fetch("/api/users", {
    headers: {
        "x-user-id": "123e4567-e89b-12d3-a456-426614174000",
        "x-api-version": "1.0.0",
    },
});

You can define a schema for a plugin to document and validate API usage. Better Fetch uses the Standard Schema specification, meaning you can use any Standard Schema-compliant validator (like zod), not just Zod.

Use createSchema to map paths to input and output validation schemas. You can also pass a prefix to createSchema to prefix all routes defined within that schema.

import { createFetch, createSchema, BetterFetchPlugin } from "@better-fetch/fetch";
import { z } from "zod";

const plugin = {
    id: "my-plugin",
    name: "My Plugin",
    schema: createSchema({
            "/path": {
                input: z.object({
                    userId: z.string(),
                    id: z.number(),
                }),
                output: z.object({
                    title: z.string(),
                    completed: z.boolean(),
                }),
            }
        },{
            baseURL: "https://jsonplaceholder.typicode.com",
        })
} satisfies BetterFetchPlugin;

const $fetch = createFetch({    
    baseURL: "localhost:3000"
})

const { data, error } = await $fetch("https://jsonplaceholder.typicode.com/path", {
    body: {
        userId: "1",
        id: 1,
        title: "title",
        completed: true,
    },
});