suhaotian/xior has a typo in a types export path and ships a separate Node build
A liteweight fetch wrapper with plugins support and similar API to axios.
At a glance
- What is it?
- xior is a fetch based HTTP client with an axios shaped API, eleven documented plugins and a conditional exports map covering five runtimes. Two details decide whether an import resolves cleanly: the ESM types path for the throttle plugin contains a doubled dot, and the package keeps a Node specific entry point alongside the browser one.
- Who is it for?
- xior is a reasonable choice when you want the axios call shape without axios, and the plugin list, the separate Node build and the fetch passthrough are the reasons people pick it.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 68 days ago.
- What is it written in?
- Mainly TypeScript, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.
Star history
- suhaotian/xior457 ★ · +8
| Repository | 2026-08-04 | 2026-11-15 |
|---|---|---|
| suhaotian/xior | 449 | 457 |
8 Stars in the last 103 days, measured from the daily GitHub snapshot. Compare with other projects
Editorial analysis
The throttle plugin points its ESM types at a file with a doubled dot
Every plugin is exposed as its own subpath in the exports map, and each one declares two module formats with matching type files. The error-retry entry is shaped correctly:
"./plugins/error-retry": {
"import": {
"types": "./dist/plugins/error-retry.d.mts",
"default": "./dist/plugins/error-retry.mjs"
},
"require": {
"types": "./dist/plugins/error-retry.d.ts",
"default": "./dist/plugins/error-retry.js"
}
}The throttle entry has one character wrong:
"./plugins/throttle": {
"import": {
"types": "./dist/plugins/throttle..dmts",
"default": "./dist/plugins/throttle.mjs"
},
"require": {
"types": "./dist/plugins/throttle.d.ts",
"default": "./dist/plugins/throttle.js"
}
}That path reads as .d.mts with an extra dot, so a TypeScript project resolving types for that subpath under ESM is pointed at a filename the build does not produce. The CommonJS branch of the same subpath is correct, which means the failure is specific to how you import rather than to the package as a whole, and it will surface as a missing declaration rather than as a runtime error. The dedupe entry follows the same pattern immediately after.
The rest of the map is consistent. The root export offers both module systems with a types entry each, and a separate ./utils subpath for the helper functions the documentation lists separately from the client itself.
One package, five runtime conditions and two different entry files
The manifest declares three top level fields that disagree about which file you get:
"main": "./dist/index-node.js",
"module": "./dist/index.mjs",
"types": "./dist/index.d.ts",
"sideEffects": falsemain points at the Node build while module points at the shared one, so the file a bundler picks and the file a legacy resolver picks are different files. The exports map settles it properly for anything that honours it, with import and require branches each carrying a types entry and then a condition ladder:
- browser, react-native and worker all resolve to the shared build - node resolves to a separate index-node entry - default falls back to the same Node file
That means a package manager that reads exports gets the browser build in a browser context and the Node build in a server context, while a bundler that only reads main gets the Node one everywhere. The sideEffects flag being false is what allows tree shaking, and the size claim in the documentation, roughly 6KB and about 3KB gzipped, is measured for the default export as a tree shaken bundle rather than for either whole file.
The build tooling in the repository matches that split: a tsup config for producing the dual format output, a tsconfig, and a typedoc configuration alongside a checked in typedoc directory for the API reference.
The pitch is axios parity, and the FAQ asks whether it is complete
The claim is a familiar call surface on top of fetch. The feature list names axios.create, axios.interceptors and the method set .get, .post, .put, .patch, .delete, .head and .options, plus timeout support, request cancellation and nested query encoding. Size is stated as lightweight at roughly 6KB.
The instance is configured the axios way:
import xior from 'xior';
export const xiorInstance = xior.create({
baseURL: 'https://apiexampledomain.com/api',
headers: {
// put your common custom headers here
},
});Defaults are mutated in place rather than replaced, which is the axios habit people depend on for token handling:
function setAccessToken(token: string) {
xiorInstance.defaults.headers['Authorization'] = `Bearer ${token}`;
}Nested parameters are the visible difference from a plain fetch wrapper, since a nested object is passed straight through as params:
const { data: data2 } = await xiorInstance.get('/', { params: { a: 1, b: 2, c: { d: 1 } } });What the library does not claim is completeness. The first entry in its own FAQ is the question of whether xior is 100 percent compatible with axios, and the repository carries a dedicated migration document for moving from axios, plus a second guide for moving from fetch. A question phrased that way in your own documentation is the honest signal to test the specific axios behaviours you rely on rather than assuming the surface matches.
Eleven documented plugins, and auth refresh appears twice
The plugin system is the largest part of the library, and it is organised as one subpath export per plugin. The feature list names error retry, deduplication, throttling, cache, error cache, mock and custom plugins, and the document structure lists the individual pages: an error retry plugin, a request throttle plugin, a request dedupe plugin, an error cache plugin, a cache plugin, a page on persisting cache data, an upload and download progress plugin, a mock plugin, and a page on creating your own custom plugin, plus a cleanup plugins example.
Two entries are worth pausing on. There is an auth refresh token plugin from community and an auth refresh token plugin built in, listed as separate pages in the structure. Two sources for one feature means a reader has to work out which one they are reading before they can tell whether the built in version supersedes the community one, and no version note in the visible text settles it.
The cleanup page is the other tell. A plugin that registers interceptors or holds state has to be removable, so the plugin system evidently has lifecycle hooks rather than being a pure request wrapper, which matches the axios style of the rest of the API. What those hooks are called, what order plugins run in, and whether one plugin can short circuit the next are all in pages that come after the point where the retrieved copy was cut off.
Two more files at the repository root extend the story. Mock-plugin.md sits beside the README as a standalone document on the mock plugin, and the mock example is also a runnable project under a directory named for vitest.
Eight example applications live in the repository, not in the package
The tree is mostly examples. Alongside src/, tests/ and scripts/ there are directories named bun-example, cloudflare-example, expo-app, my-react-app, next-example, vite-example, vue-cli-app and vitest-mock-example. Eight separate applications in one repository, each covering a different host environment for the same client.
That spread is the argument for the conditional exports map rather than a footnote to it. React Native and Cloudflare Workers are both named as environments where the shared build is used, while a Node server gets its own entry, and each of those directories is a place where the resolution order can actually be exercised. It is also why the FAQ asks whether xior can be used in Bun, Expo, React Native, RemixJS, Next.js, Vue, Nuxt.js, Tauri or NervJS and Taro, listing the frameworks rather than asserting a blanket compatibility.
What does not ship is the repository itself. The manifest points main, module and types at dist paths, so the published package is the built output plus its declarations, and the example applications are there for development and for the documentation rather than for consumers.
The rest of the tooling is small and conventional: pnpm with a workspace file and a lockfile, an nvmrc pinning a Node version, husky for the git hooks, a changelog, and the migration and mock documents as plain markdown at the root.
The CDN examples pin a version and two different example hosts
Since v0.2.1 the package is available as a UMD build, and the browser examples load it from a CDN with the version written into the URL:
<script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/xior.umd.js"></script>
<!-- Usage -->
<script>
console.log(xior.VERSION);
xior.get('https://exmapledomain.com/api').then((res) => {
console.log(res.data);
});
</script>The same block appears for unpkg with the identical version and the identical request target. Two consequences follow. The script tag pins 0.8.5 while the package manager instructions, npm install xior, pnpm add xior, bun add xior and yarn add xior, install whatever satisfies your range, so a page using the CDN example and a service using the package are not guaranteed to be on the same code unless you pin both. And xior.VERSION is exposed on the global, which is the one thing that lets a page check at runtime what it actually loaded.
The example hostnames are inconsistent, which is a smaller problem but a real one for anyone copy pasting. The script examples request https://exmapledomain.com/api, while the instance examples set baseURL to https://apiexampledomain.com/api. Neither is a real service, and one of them is a misspelling of the other, so a half edited snippet can produce a request against a domain that resolves to something.
Version 0.8.5 appears in four places, and the tag gap before it was seven months
The version is consistent where it can be checked. The manifest says 0.8.5, the newest tag is v0.8.5, both CDN examples load [email protected], and the bundle size badge at the top of the document queries [email protected] with tree shaking enabled for the default export. The badge query itself is informative, since it measures the tree shaken default entry rather than the whole package.
The release history is not even. v0.8.3 was tagged on 2026-01-14, v0.8.4 on 2026-08-04 and v0.8.5 on 2026-09-09, so there is a seven month gap between the first two of those and a five week gap between the last two. The branch was last pushed on 2026-09-09, the same day as the tag. Package is MIT licensed, and the distribution channel is npm with the repository and homepage pointing back at the source.
Several of the document's own questions point at the gaps a fetch based client leaves open, and none of their answers came through with the retrieved copy. There is an entry on supporting older browsers, one on changing the default throw behaviour along with validStatus and validResponse, one on responses of type stream, document, arraybuffer or blob, and one on using a custom fetch implementation or supporting a proxy feature. Each of those is a place where the fetch abstraction stops matching the axios behaviour people migrate from, and each is worth reading before you switch a production client rather than after.
Editorial conclusion
xior is a reasonable choice when you want the axios call shape without axios, and the plugin list, the separate Node build and the fetch passthrough are the reasons people pick it. Two checks before you adopt it: type resolution for the throttle subpath under ESM, where the declared types file does not exist under that name, and whether the axios behaviours you rely on are the ones the migration guide actually covers, since the project's own FAQ questions whether compatibility is complete. If you need older browsers, read the FAQ answer on that before anything else, because a fetch based library has to answer the polyfill question for you.
Frequently asked questions
Is suhaotian/xior compatible with axios?
It offers a similar API, with axios.create, axios.interceptors, the same method set, timeout, cancellation and nested query encoding. The project's own first FAQ entry asks whether compatibility is 100 percent, and a dedicated migration document covers moving from axios.
How do I install xior?
With npm install xior, pnpm add xior, bun add xior or yarn add xior. Since v0.2.1 there is also a UMD build for browsers, loaded from a CDN with the version pinned in the script URL.
Which plugins does xior ship with?
Error retry, request throttle, request dedupe, error cache, cache, upload and download progress, and mock, each exposed as its own subpath export, plus custom plugins. Auth refresh appears as both a built in plugin and a community one.
Does xior support nested query parameters?
Yes. Nested query encoding is listed as a feature, and the examples pass a nested object directly as params, for example params: { a: 1, b: 2, c: { d: 1 } }.
Can xior be used outside a browser?
Yes. The exports map resolves the shared build for browser, react-native and worker conditions, and a separate Node entry for the node condition, with the top level main field pointing at the Node build.
Does xior work in older browsers?
The library is built on fetch, and the documentation has a dedicated FAQ entry on supporting older browsers. Because the client is built on the fetch API, that entry is the answer to check before relying on it for an older target.
Official sources
Add this badge to your README
If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.
[](https://hysenlabs.com/projects/suhaotian-xior)Star history chart for your README
[](https://hysenlabs.com/projects/suhaotian-xior)Was this useful?