{"id":13454952,"url":"https://github.com/unjs/ofetch","last_synced_at":"2025-05-13T16:03:29.472Z","repository":{"id":37016382,"uuid":"319960543","full_name":"unjs/ofetch","owner":"unjs","description":"😱 A better fetch API. Works on node, browser and workers.","archived":false,"fork":false,"pushed_at":"2025-04-28T00:54:21.000Z","size":1446,"stargazers_count":4551,"open_issues_count":58,"forks_count":135,"subscribers_count":16,"default_branch":"main","last_synced_at":"2025-04-30T20:04:12.187Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/unjs.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2020-12-09T13:11:38.000Z","updated_at":"2025-04-30T11:56:03.000Z","dependencies_parsed_at":"2023-11-24T01:29:55.637Z","dependency_job_id":"38deefeb-2549-4fb2-911b-b1be13196c35","html_url":"https://github.com/unjs/ofetch","commit_stats":{"total_commits":367,"total_committers":58,"mean_commits":6.327586206896552,"dds":0.5013623978201636,"last_synced_commit":"bdfb50735d9ed3a46a9cf13395da7498c053f599"},"previous_names":["unjs/ohmyfetch"],"tags_count":54,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/unjs%2Fofetch","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/unjs%2Fofetch/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/unjs%2Fofetch/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/unjs%2Fofetch/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/unjs","download_url":"https://codeload.github.com/unjs/ofetch/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":251961985,"owners_count":21671963,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-07-31T08:00:59.708Z","updated_at":"2025-05-05T22:45:15.573Z","avatar_url":"https://github.com/unjs.png","language":"TypeScript","readme":"# ofetch\n\n[![npm version][npm-version-src]][npm-version-href]\n[![npm downloads][npm-downloads-src]][npm-downloads-href]\n[![bundle][bundle-src]][bundle-href]\n[![Codecov][codecov-src]][codecov-href]\n[![License][license-src]][license-href]\n[![JSDocs][jsdocs-src]][jsdocs-href]\n\nA better fetch API. Works on node, browser, and workers.\n\n\u003cdetails\u003e\n  \u003csummary\u003eSpoiler\u003c/summary\u003e\n  \u003cimg src=\"https://media.giphy.com/media/Dn1QRA9hqMcoMz9zVZ/giphy.gif\"\u003e\n\u003c/details\u003e\n\n## 🚀 Quick Start\n\nInstall:\n\n```bash\n# npm\nnpm i ofetch\n\n# yarn\nyarn add ofetch\n```\n\nImport:\n\n```js\n// ESM / Typescript\nimport { ofetch } from \"ofetch\";\n\n// CommonJS\nconst { ofetch } = require(\"ofetch\");\n```\n\n## ✔️ Works with Node.js\n\nWe use [conditional exports](https://nodejs.org/api/packages.html#packages_conditional_exports) to detect Node.js\nand automatically use [unjs/node-fetch-native](https://github.com/unjs/node-fetch-native). If `globalThis.fetch` is available, will be used instead. To leverage Node.js 17.5.0 experimental native fetch API use [`--experimental-fetch` flag](https://nodejs.org/dist/latest-v17.x/docs/api/cli.html#--experimental-fetch).\n\n## ✔️ Parsing Response\n\n`ofetch` will smartly parse JSON and native values using [destr](https://github.com/unjs/destr), falling back to the text if it fails to parse.\n\n```js\nconst { users } = await ofetch(\"/api/users\");\n```\n\nFor binary content types, `ofetch` will instead return a `Blob` object.\n\nYou can optionally provide a different parser than `destr`, or specify `blob`, `arrayBuffer`, or `text` to force parsing the body with the respective `FetchResponse` method.\n\n```js\n// Use JSON.parse\nawait ofetch(\"/movie?lang=en\", { parseResponse: JSON.parse });\n\n// Return text as is\nawait ofetch(\"/movie?lang=en\", { parseResponse: (txt) =\u003e txt });\n\n// Get the blob version of the response\nawait ofetch(\"/api/generate-image\", { responseType: \"blob\" });\n```\n\n## ✔️ JSON Body\n\nIf an object or a class with a `.toJSON()` method is passed to the `body` option, `ofetch` automatically stringifies it.\n\n`ofetch` utilizes `JSON.stringify()` to convert the passed object. Classes without a `.toJSON()` method have to be converted into a string value in advance before being passed to the `body` option.\n\nFor `PUT`, `PATCH`, and `POST` request methods, when a string or object body is set, `ofetch` adds the default `content-type: \"application/json\"` and `accept: \"application/json\"` headers (which you can always override).\n\nAdditionally, `ofetch` supports binary responses with `Buffer`, `ReadableStream`, `Stream`, and [compatible body types](https://developer.mozilla.org/en-US/docs/Web/API/fetch#body). `ofetch` will automatically set the `duplex: \"half\"` option for streaming support!\n\n**Example:**\n\n```js\nconst { users } = await ofetch(\"/api/users\", {\n  method: \"POST\",\n  body: { some: \"json\" },\n});\n```\n\n## ✔️ Handling Errors\n\n`ofetch` Automatically throws errors when `response.ok` is `false` with a friendly error message and compact stack (hiding internals).\n\nA parsed error body is available with `error.data`. You may also use `FetchError` type.\n\n```ts\nawait ofetch(\"https://google.com/404\");\n// FetchError: [GET] \"https://google/404\": 404 Not Found\n//     at async main (/project/playground.ts:4:3)\n```\n\nTo catch error response:\n\n```ts\nawait ofetch(\"/url\").catch((error) =\u003e error.data);\n```\n\nTo bypass status error catching you can set `ignoreResponseError` option:\n\n```ts\nawait ofetch(\"/url\", { ignoreResponseError: true });\n```\n\n## ✔️ Auto Retry\n\n`ofetch` Automatically retries the request if an error happens and if the response status code is included in `retryStatusCodes` list:\n\n**Retry status codes:**\n\n- `408` - Request Timeout\n- `409` - Conflict\n- `425` - Too Early ([Experimental](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Early-Data))\n- `429` - Too Many Requests\n- `500` - Internal Server Error\n- `502` - Bad Gateway\n- `503` - Service Unavailable\n- `504` - Gateway Timeout\n\nYou can specify the amount of retry and delay between them using `retry` and `retryDelay` options and also pass a custom array of codes using `retryStatusCodes` option.\n\nThe default for `retry` is `1` retry, except for `POST`, `PUT`, `PATCH`, and `DELETE` methods where `ofetch` does not retry by default to avoid introducing side effects. If you set a custom value for `retry` it will **always retry** for all requests.\n\nThe default for `retryDelay` is `0` ms.\n\n```ts\nawait ofetch(\"http://google.com/404\", {\n  retry: 3,\n  retryDelay: 500, // ms\n  retryStatusCodes: [ 404, 500 ], // response status codes to retry\n});\n```\n\n## ✔️ Timeout\n\nYou can specify `timeout` in milliseconds to automatically abort a request after a timeout (default is disabled).\n\n```ts\nawait ofetch(\"http://google.com/404\", {\n  timeout: 3000, // Timeout after 3 seconds\n});\n```\n\n## ✔️ Type Friendly\n\nThe response can be type assisted:\n\n```ts\nconst article = await ofetch\u003cArticle\u003e(`/api/article/${id}`);\n// Auto complete working with article.id\n```\n\n## ✔️ Adding `baseURL`\n\nBy using `baseURL` option, `ofetch` prepends it for trailing/leading slashes and query search params for baseURL using [ufo](https://github.com/unjs/ufo):\n\n```js\nawait ofetch(\"/config\", { baseURL });\n```\n\n## ✔️ Adding Query Search Params\n\nBy using `query` option (or `params` as alias), `ofetch` adds query search params to the URL by preserving the query in the request itself using [ufo](https://github.com/unjs/ufo):\n\n```js\nawait ofetch(\"/movie?lang=en\", { query: { id: 123 } });\n```\n\n## ✔️ Interceptors\n\nProviding async interceptors to hook into lifecycle events of `ofetch` call is possible.\n\nYou might want to use `ofetch.create` to set shared interceptors.\n\n### `onRequest({ request, options })`\n\n`onRequest` is called as soon as `ofetch` is called, allowing you to modify options or do simple logging.\n\n```js\nawait ofetch(\"/api\", {\n  async onRequest({ request, options }) {\n    // Log request\n    console.log(\"[fetch request]\", request, options);\n\n    // Add `?t=1640125211170` to query search params\n    options.query = options.query || {};\n    options.query.t = new Date();\n  },\n});\n```\n\n### `onRequestError({ request, options, error })`\n\n`onRequestError` will be called when the fetch request fails.\n\n```js\nawait ofetch(\"/api\", {\n  async onRequestError({ request, options, error }) {\n    // Log error\n    console.log(\"[fetch request error]\", request, error);\n  },\n});\n```\n\n### `onResponse({ request, options, response })`\n\n`onResponse` will be called after `fetch` call and parsing body.\n\n```js\nawait ofetch(\"/api\", {\n  async onResponse({ request, response, options }) {\n    // Log response\n    console.log(\"[fetch response]\", request, response.status, response.body);\n  },\n});\n```\n\n### `onResponseError({ request, options, response })`\n\n`onResponseError` is the same as `onResponse` but will be called when fetch happens but `response.ok` is not `true`.\n\n```js\nawait ofetch(\"/api\", {\n  async onResponseError({ request, response, options }) {\n    // Log error\n    console.log(\n      \"[fetch response error]\",\n      request,\n      response.status,\n      response.body\n    );\n  },\n});\n```\n\n### Passing array of interceptors\n\nIf necessary, it's also possible to pass an array of function that will be called sequentially.\n\n```js\nawait ofetch(\"/api\", {\n  onRequest: [\n    () =\u003e {\n      /* Do something */\n    },\n    () =\u003e {\n      /* Do something else */\n    },\n  ],\n});\n```\n\n## ✔️ Create fetch with default options\n\nThis utility is useful if you need to use common options across several fetch calls.\n\n**Note:** Defaults will be cloned at one level and inherited. Be careful about nested options like `headers`.\n\n```js\nconst apiFetch = ofetch.create({ baseURL: \"/api\" });\n\napiFetch(\"/test\"); // Same as ofetch('/test', { baseURL: '/api' })\n```\n\n## 💡 Adding headers\n\nBy using `headers` option, `ofetch` adds extra headers in addition to the request default headers:\n\n```js\nawait ofetch(\"/movies\", {\n  headers: {\n    Accept: \"application/json\",\n    \"Cache-Control\": \"no-cache\",\n  },\n});\n```\n\n## 🍣 Access to Raw Response\n\nIf you need to access raw response (for headers, etc), you can use `ofetch.raw`:\n\n```js\nconst response = await ofetch.raw(\"/sushi\");\n\n// response._data\n// response.headers\n// ...\n```\n\n## 🌿 Using Native Fetch\n\nAs a shortcut, you can use `ofetch.native` that provides native `fetch` API\n\n```js\nconst json = await ofetch.native(\"/sushi\").then((r) =\u003e r.json());\n```\n\n## 🕵️ Adding HTTP(S) Agent\n\nIn Node.js (\u003e= 18) environments, you can provide a custom dispatcher to intercept requests and support features such as Proxy and self-signed certificates. This feature is enabled by [undici](https://undici.nodejs.org/) built-in Node.js. [read more](https://undici.nodejs.org/#/docs/api/Dispatcher) about the Dispatcher API.\n\nSome available agents:\n\n- `ProxyAgent`: A Proxy Agent class that implements the Agent API. It allows the connection through a proxy in a simple way. ([docs](https://undici.nodejs.org/#/docs/api/ProxyAgent))\n- `MockAgent`: A mocked Agent class that implements the Agent API. It allows one to intercept HTTP requests made through undici and return mocked responses instead. ([docs](https://undici.nodejs.org/#/docs/api/MockAgent))\n- `Agent`: Agent allows dispatching requests against multiple different origins. ([docs](https://undici.nodejs.org/#/docs/api/Agent))\n\n**Example:** Set a proxy agent for one request:\n\n```ts\nimport { ProxyAgent } from \"undici\";\nimport { ofetch } from \"ofetch\";\n\nconst proxyAgent = new ProxyAgent(\"http://localhost:3128\");\nconst data = await ofetch(\"https://icanhazip.com\", { dispatcher: proxyAgent });\n```\n\n**Example:** Create a custom fetch instance that has proxy enabled:\n\n```ts\nimport { ProxyAgent, setGlobalDispatcher } from \"undici\";\nimport { ofetch } from \"ofetch\";\n\nconst proxyAgent = new ProxyAgent(\"http://localhost:3128\");\nconst fetchWithProxy = ofetch.create({ dispatcher: proxyAgent });\n\nconst data = await fetchWithProxy(\"https://icanhazip.com\");\n```\n\n**Example:** Set a proxy agent for all requests:\n\n```ts\nimport { ProxyAgent, setGlobalDispatcher } from \"undici\";\nimport { ofetch } from \"ofetch\";\n\nconst proxyAgent = new ProxyAgent(\"http://localhost:3128\");\nsetGlobalDispatcher(proxyAgent);\n\nconst data = await ofetch(\"https://icanhazip.com\");\n```\n\n**Example:** Allow self-signed certificates (USE AT YOUR OWN RISK!)\n\n```ts\nimport { ProxyAgent } from \"undici\";\nimport { ofetch } from \"ofetch\";\n\n// Note: This makes fetch unsecure against MITM attacks. USE AT YOUR OWN RISK!\nconst unsecureProxyAgent = new ProxyAgent({ requestTls: { rejectUnauthorized: false } });\nconst unsecureFetch = ofetch.create({ dispatcher: unsecureProxyAgent });\n\nconst data = await unsecureFetch(\"https://www.squid-cache.org/\");\n```\n\nOn older Node.js version (\u003c18), you might also use use `agent`:\n\n```ts\nimport { HttpsProxyAgent } from \"https-proxy-agent\";\n\nawait ofetch(\"/api\", {\n  agent: new HttpsProxyAgent(\"http://example.com\"),\n});\n```\n\n### `keepAlive` support (only works for Node \u003c 18)\n\nBy setting the `FETCH_KEEP_ALIVE` environment variable to `true`, an HTTP/HTTPS agent will be registered that keeps sockets around even when there are no outstanding requests, so they can be used for future requests without having to re-establish a TCP connection.\n\n**Note:** This option can potentially introduce memory leaks. Please check [node-fetch/node-fetch#1325](https://github.com/node-fetch/node-fetch/pull/1325).\n\n## 📦 Bundler Notes\n\n- All targets are exported with Module and CommonJS format and named exports\n- No export is transpiled for the sake of modern syntax\n  - You probably need to transpile `ofetch`, `destr`, and `ufo` packages with Babel for ES5 support\n- You need to polyfill `fetch` global for supporting legacy browsers like using [unfetch](https://github.com/developit/unfetch)\n\n## ❓ FAQ\n\n**Why export is called `ofetch` instead of `fetch`?**\n\nUsing the same name of `fetch` can be confusing since API is different but still, it is a fetch so using the closest possible alternative. You can, however, import `{ fetch }` from `ofetch` which is auto-polyfill for Node.js and using native otherwise.\n\n**Why not have default export?**\n\nDefault exports are always risky to be mixed with CommonJS exports.\n\nThis also guarantees we can introduce more utils without breaking the package and also encourage using `ofetch` name.\n\n**Why not transpiled?**\n\nBy transpiling libraries, we push the web backward with legacy code which is unneeded for most of the users.\n\nIf you need to support legacy users, you can optionally transpile the library in your build pipeline.\n\n## License\n\nMIT. Made with 💖\n\n\u003c!-- Badges --\u003e\n\n[npm-version-src]: https://img.shields.io/npm/v/ofetch?style=flat\u0026colorA=18181B\u0026colorB=F0DB4F\n[npm-version-href]: https://npmjs.com/package/ofetch\n[npm-downloads-src]: https://img.shields.io/npm/dm/ofetch?style=flat\u0026colorA=18181B\u0026colorB=F0DB4F\n[npm-downloads-href]: https://npmjs.com/package/ofetch\n[codecov-src]: https://img.shields.io/codecov/c/gh/unjs/ofetch/main?style=flat\u0026colorA=18181B\u0026colorB=F0DB4F\n[codecov-href]: https://codecov.io/gh/unjs/ofetch\n[bundle-src]: https://img.shields.io/bundlephobia/minzip/ofetch?style=flat\u0026colorA=18181B\u0026colorB=F0DB4F\n[bundle-href]: https://bundlephobia.com/result?p=ofetch\n[license-src]: https://img.shields.io/github/license/unjs/ofetch.svg?style=flat\u0026colorA=18181B\u0026colorB=F0DB4F\n[license-href]: https://github.com/unjs/ofetch/blob/main/LICENSE\n[jsdocs-src]: https://img.shields.io/badge/jsDocs.io-reference-18181B?style=flat\u0026colorA=18181B\u0026colorB=F0DB4F\n[jsdocs-href]: https://www.jsdocs.io/package/ofetch\n","funding_links":[],"categories":["js library/framework","TypeScript","Utilities","Projects Using Vue.js","others"],"sub_categories":["pure js","HTTP / URLs","Open Source"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Funjs%2Fofetch","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Funjs%2Fofetch","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Funjs%2Fofetch/lists"}