Config

Eden Treaty accepts two parameters:

• urlOrInstance – URL endpoint or Elysia instance
• options (optional) – Customize fetch behavior

urlOrInstance

Accepts either a URL endpoint as a string or a literal Elysia instance.

URL Endpoint (string)

If a URL endpoint is passed, Eden Treaty will use fetch (or config.fetcher) to create a network request to an Elysia instance.

import { treaty } from '@elysiajs/eden';
import type { App } from './server';

const api = treaty<App>('localhost:3000');

You may or may not specify a protocol for the URL endpoint.
Elysia will append the endpoint automatically as follows:

1. If a protocol is specified, use the URL directly
2. If the URL is localhost and ENV is not production, use http
3. Otherwise use https

This also applies to WebSocket URLs to determine whether to use ws:// or wss://.

Elysia Instance

If an Elysia instance is passed, Eden Treaty will create a Request class and pass it directly to Elysia.handle without making a network request.

import { Elysia } from 'elysia';
import { treaty } from '@elysiajs/eden';

const app = new Elysia()
  .get('/hi', 'Hi Elysia')
  .listen(3000);

const api = treaty(app);

When an instance is passed, the generic type is inferred automatically. This pattern is recommended for unit tests or creating a type‑safe reverse proxy server or micro‑services.

options

The second optional parameter customizes fetch behavior, accepting the following properties:

• fetch – default parameters for fetch (RequestInit)
• headers – default headers
• fetcher – custom fetch function (e.g. Axios, unfetch)
• onRequest – intercept and modify fetch request before firing
• onResponse – intercept and modify fetch’s response

fetch

Default parameters are appended to the second parameters of fetch, extending the Fetch.RequestInit type.

export type App = typeof app;

import { treaty } from '@elysiajs/eden';

treaty<App>('localhost:3000', {
  fetch: {
    credentials: 'include'
  }
});

All parameters passed to fetch are forwarded to the fetcher:

fetch('http://localhost:3000', {
  credentials: 'include'
});

headers

You can provide additional default headers to fetch. This is a shorthand for options.fetch.headers.

treaty<App>('localhost:3000', {
  headers: {
    'X-Custom': 'Griseo'
  }
});

All parameters passed to fetch will be forwarded to the fetcher:

fetch('localhost:3000', {
  headers: {
    'X-Custom': 'Griseo'
  }
});

headers may accept either an Object or a Function.

Headers Object

If an object is passed, it is forwarded directly to fetch.

treaty<App>('localhost:3000', {
  headers: {
    'X-Custom': 'Griseo'
  }
});

Function

You can specify a function to return custom headers based on conditions:

treaty<App>('localhost:3000', {
  headers(path, options) {
    if (path.startsWith('user')) {
      return {
        authorization: 'Bearer 12345'
      };
    }
  }
});

The function receives:

• path (string) – the request path (hostname excluded, e.g. /user/griseo)
• options (RequestInit) – parameters passed through the second fetch argument

Array

Multiple header functions can be supplied as an array; all functions run even if one returns a value.

treaty<App>('localhost:3000', {
  headers: [
    (path, options) => {
      if (path.startsWith('user')) {
        return { authorization: 'Bearer 12345' };
      }
    }
  ]
});

Headers Priority

When headers are duplicated, Eden Treaty prioritizes in this order:

1. Inline method – headers passed directly in the request
2. config.headers – (array: later functions override earlier ones)
3. fetch.headers

Example:

const api = treaty<App>('localhost:3000', {
  headers: {
    authorization: 'Bearer Aponia'
  }
});

api.profile.get({
  headers: {
    authorization: 'Bearer Griseo'
  }
});

Resulting fetch call:

fetch('http://localhost:3000', {
  headers: {
    authorization: 'Bearer Griseo'
  }
});

If the inline method does not specify headers, the result would be "Bearer Aponia".

fetcher

Provide a custom fetcher function instead of using the environment’s default fetch.

treaty<App>('localhost:3000', {
  fetcher(url, options) {
    return fetch(url, options);
  }
});

Use this to replace fetch with another client, e.g. Axios or unfetch.

onRequest

Intercept and modify fetch request before it is sent.

treaty<App>('localhost:3000', {
  onRequest(path, options) {
    if (path.startsWith('user')) {
      return {
        headers: {
          authorization: 'Bearer 12345'
        }
      };
    }
  }
});

If a value is returned, Eden Treaty performs a shallow merge between the returned value and value.headers.

onRequest accepts two parameters:

• path (string) – the request path (hostname excluded)
• options (RequestInit) – fetch options

onResponse

(Details omitted in the provided content – see the full markdown documentation.)