Quick start

Install Relay, make a request, handle errors and share defaults across your app. This takes about five minutes.

Steps

1. #Install the package

   Relay is published to npm as @relayhttp/relay. Use whichever package manager your project already uses:

   npmpnpmyarnbun

   Copy

   npm install @relayhttp/relay

2. #Make your first request

   Import the default export and call one of the method helpers. Chain .json(), .text() or .blob() to read the body.

   posts.jsCopy

   import relay from '@relayhttp/relay';
   
   const posts = await relay.get('https://api.example.com/posts', {
     searchParams: { limit: 10, sort: 'newest' },
   }).json();
   
   console.log(posts.length); // 10

3. #Handle errors

   Unlike fetch, Relay rejects when the server answers with a 4xx or 5xx status, so you can't accidentally treat an error page as data.

   errors.jsCopy

   import relay, { RelayError } from '@relayhttp/relay';
   
   try {
     await relay.get('https://api.example.com/missing').json();
   } catch (error) {
     if (error instanceof RelayError) {
       console.log(error.status);   // 404
       console.log(error.code);     // 'HTTP_ERROR'
     }
   }

4. #Share defaults with an instance

   Most apps talk to one API. Create an instance with a base URL, headers and timeout once, then import it everywhere.

   api.jsCopy

   // api.js
   import relay from '@relayhttp/relay';
   
   export const api = relay.create({
     baseUrl: 'https://api.example.com/v2',
     headers: { 'x-client': 'web' },
     timeout: 8000,
   });
   
   // elsewhere
   const me = await api.get('me').json();

#Next steps

• Installation covers TypeScript, Deno, Bun and using Relay without a bundler.
• Examples has recipes for auth tokens, file uploads and polling.
• API reference lists every option.

Last updated September 18, 2026