Skip to main content
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

Build docs developers (and LLMs) love

Get started for freeTalk to us