Quickstart

Learn how to make your first HTTP request with ofetch in minutes

This guide will help you make your first HTTP request with ofetch.

1. Install ofetch

   Install ofetch using your preferred package manager:

   npm install ofetch
   
2. Import ofetch

   Import ofetch in your JavaScript or TypeScript file:

   import { ofetch } from 'ofetch';
   

   You can also use the $fetch alias: import { $fetch } from 'ofetch'

3. Make your first request

   Make a simple GET request. ofetch automatically parses JSON responses:

   const data = await ofetch('https://api.github.com/repos/unjs/ofetch');
   console.log(data);
   

   The response is automatically parsed as JSON and returned directly - no need to call .json() manually.

4. Send data with POST

   Send data to an API endpoint. ofetch automatically stringifies objects and sets the correct headers:

   const result = await ofetch('https://api.github.com/markdown', {
     method: 'POST',
     body: {
       text: 'UnJS is **awesome**!\n\nCheck out their [website](https://unjs.io).'
     }
   });
   

   ofetch automatically:

   • Converts the body object to JSON
   • Sets Content-Type: application/json
   • Sets Accept: application/json
5. Add query parameters

   Add query parameters using the query option:

   const tags = await ofetch('https://api.github.com/repos/unjs/ofetch/tags', {
     query: {
       per_page: 2
     }
   });
   

   The URL will automatically become https://api.github.com/repos/unjs/ofetch/tags?per_page=2.

6. Handle errors

   ofetch automatically throws errors for failed requests with helpful error messages:

   try {
     await ofetch('https://api.github.com/invalid-endpoint', {
       method: 'POST'
     });
   } catch (error) {
     // Error includes status, message, and parsed response body
     console.error(error.message);
     console.log(error.data); // Parsed error response
   }
   

   The error includes:

   • error.data - Parsed response body
   • error.status - HTTP status code
   • error.statusText - HTTP status message
   • A clean stack trace with internals hidden

Common patterns

Using a base URL

When working with an API, you can set a base URL to avoid repeating it:

const api = ofetch.create({ baseURL: 'https://api.example.com' });

// These requests use the base URL automatically
await api('/users');        // GET https://api.example.com/users
await api('/posts/123');    // GET https://api.example.com/posts/123

Adding headers

Add custom headers to your requests:

await ofetch('https://api.github.com/user', {
  headers: {
    'Authorization': 'token YOUR_TOKEN',
    'Accept': 'application/vnd.github.v3+json'
  }
});

Accessing raw response

If you need access to response headers or other metadata, use ofetch.raw:

const response = await ofetch.raw('/api/data');

console.log(response._data);      // Parsed response body
console.log(response.status);     // Status code
console.log(response.headers);    // Response headers

Next steps

You now know the basics of ofetch. Explore more features:

• Configure automatic retries for failed requests
• Use interceptors to modify requests and responses
• Set timeouts to prevent hanging requests
• Handle different response types (blob, stream, text)
• Work with TypeScript for full type safety