Resolve API URLs

Use baseUrl for standard URL resolution; use prefix when a leading slash in a request path must stay under the configured API path.

Choose how relative paths resolve

Set defaults on a ky instance with ky.extend(), then keep request paths relative:

ts
import ky from 'ky';

const run = async (): Promise<void> => {
	const baseUrlApi = ky.extend({
		baseUrl: 'https://jsonplaceholder.typicode.com/users/',
	});

	const prefixApi = ky.extend({
		prefix: 'https://jsonplaceholder.typicode.com/users',
	});

	const baseUrlResponse = await baseUrlApi.get('1');
	const prefixResponse = await prefixApi.get('/1');

console.log(baseUrlResponse.url);
console.log(prefixResponse.url);
};

void run();

Both requests target https://jsonplaceholder.typicode.com/users/1. baseUrl resolves '1' relative to the trailing-slash path. prefix joins its path with '/1', trimming the boundary slashes before URL resolution. Ky instances created with extend() inherit the parent instance's defaults.

Pick the option that matches your paths

Option	Type	Default	What it does
`baseUrl`	`URL \| string \| undefined`	No value set	Resolves a relative input as a URL reference. An input beginning with `/` replaces the base URL's path, so a base of `https://example.com/api/` and input `/users` resolves to `https://example.com/users`.
`prefix`	`URL \| string \| undefined`	No value set	Joins the prefix and string input before resolving the resulting URL. Leading slashes on the input are trimmed at the join boundary, so `/users` stays under an `/api/` prefix.

In most cases, choose baseUrl: it follows standard URL resolution. Include a trailing slash in a base URL that has a path, such as https://example.com/api/, so a page-relative input like 'users' extends that path. Choose prefix when your callers use origin-relative paths such as '/users' but you want those paths appended under the API prefix.

An absolute input bypasses baseUrl. prefix applies only when the input is a string; when the input is a Request, both baseUrl and prefix are ignored.

Choose how relative paths resolve

Pick the option that matches your paths

Related

Was this page helpful?