Plugins

Plugins are functions that can be used to modify the request, response, error and other parts of the request lifecycle and can be used to define Fetch Schema.

Init

The init function is called before the request is made and any of the internal functions are called. It takes the url and options as arguments and is expected to return the modified url and options.

fetch.ts

import { createFetch, BetterFetchPlugin } from "@better-fetch/fetch";
 
const myPlugin = {
    id: "my-plugin",
    name: "My Plugin",
    init: async (url, options) => {
       if(url.startsWith("http://")) {
           const _url = new URL(url)
           const DEV_URL = "http://localhost:3000"
           return {
               url: `${DEV_URL}/${_url.pathname}`,
               options,
           }
       }
        return {
            url,
            options,
        }
    },
} satisfies BetterFetchPlugin;
 
const $fetch = createFetch({
    baseURL: "https://jsonplaceholder.typicode.com",
    plugins: [myPlugin],
});

Hooks

Hooks are functions that are called at different stages of the request lifecycle. See Hooks for more information.

fetch.ts

import { createFetch, BetterFetchPlugin } from "@better-fetch/fetch";
 
const myPlugin = {
    id: "my-plugin",
    name: "My Plugin",
    hooks: {
        onRequest(context) {
        // do something with the context
        return context;
        },
        onResponse(context) {
            // do something with the context
            return context;
        },
        onError(context) {
            // do something with the context
        },
        onSuccess(context) {
            // do something with the context
        },
    }
} satisfies BetterFetchPlugin;
 
const $fetch = createFetch({
    baseURL: "https://jsonplaceholder.typicode.com",
    plugins: [myPlugin],
});

If more than one plugin is registered, the hooks will be called in the order they are registered.

Schema

You can define a schema for a plugin. This allows you to easily document the api usage using a schema.

fetch.ts

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({
                    /**
                     * You can write descriptions for the properties. Hover over the property to see 
                     * the description.
                     */
                    userId: z.string(),
                    /**
                     * The id property is required
                     */
                    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,
    },
});
 
 baseURL is inferred to "https://jsonplaceholder.typicode.com"

You can also pass a prefix to the createSchema function to prefix all the routes.

Get options

The getOptions function allows you to define additional options that can be passed to the fetch function. This is useful when you want to pass options to the plugins that are not part of the BetterFetchPlugin interface.

fetch.ts

import { createFetch, createSchema, BetterFetchPlugin } from "@better-fetch/fetch";
import { z } from "zod";
 
const plugin = {
    id: "my-plugin",
    name: "My Plugin",
    getOptions() {
        return z.object({
            onUploadProgress: z.function().args(z.object({
                loaded: z.number(),
                total: z.number(),
            })),
        });
    },
} satisfies BetterFetchPlugin;
 
const $fetch = createFetch({
    baseURL: "https://jsonplaceholder.typicode.com",
    plugins: [plugin],
});
 
const { data, error } = await $fetch("https://jsonplaceholder.typicode.com/path", {
    onUploadProgress({
        loaded,
        total,
    }) {
        console.log(`Uploaded ${loaded} of ${total} bytes`);
    },
});

Properties

Prop	Type	Default
`id`	`string`	-
`name`	`string`	-
`description`	`string`	-
`version`	`string`	-
`hooks`	`FetchHooks<any>`	-
`init`	`(url: string, options?: { cache?: RequestCache \| undefined; credentials?: RequestCredentials \| undefined; headers?: (HeadersInit & (HeadersInit \| CommonHeaders)) \| undefined; ... 32 more ...; disableValidation?: boolean \| undefined; } \| undefined) => Promise<...> \| { ...; }`	-
`schema`	`Schema`	-
`getOptions`	`() => ZodType<any, ZodTypeDef, any>`	-

Plugins

Init

Hooks

Schema

Get options

Properties

On this page