# @xivapi/js

> A Node.JS wrapper for xivapi.com

Latest version **1.0.8** (published 2026-09-30) · MIT license · 0 weekly downloads

## Install

```sh
npm install @xivapi/js
pnpm add @xivapi/js
yarn add @xivapi/js
bun add @xivapi/js
```

## Health

**Score 75/100 (B)** — status: active.

Positive: has types; esm support; no vulnerabilities; has provenance; recently updated; high maintenance score; high quality score.

Warnings: low downloads.

## Facts

| | |
|---|---|
| Version | 1.0.8 |
| Published | 2026-09-30 |
| First published | 2021-01-26 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Node | >=20.0.0 |
| Dependencies | 1 |
| Unpacked size | 90 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Provenance | attested (GitHub Actions) |
| GitHub stars | 82 |
| Author | miichom <hello@cammy.xyz> (https://cammy.xyz/) |
| Maintainers | supamiu, ayyaruq, miichom |
| Keywords | xivapi, ffxiv |

## Links

- npm: https://www.npmjs.com/package/@xivapi/js
- Repository: https://github.com/xivapi/xivapi-js
- Issues: https://github.com/xivapi/xivapi-js/issues
- npm.io page: https://npm.io/package/@xivapi/js

## Dependencies (1)

- [std-env](https://npm.io/package/std-env.md) ^4.2.0

## Recent versions

- 1.0.8 (latest) — 2026-09-30
- 1.0.7 — 2026-08-19
- 1.0.6 — 2026-06-27
- 1.0.5 — 2026-06-20
- 1.0.4 — 2026-05-06
- 1.0.3 — 2026-03-05
- 1.0.2 — 2025-11-01
- 1.0.1 — 2025-10-30
- 0.4.5 — 2024-01-05
- 0.4.4 — 2023-12-05
- 0.4.3 — 2023-08-05
- 0.4.2 — 2023-05-23
- 0.4.1 — 2022-05-01
- 0.4.0 — 2022-01-14
- 0.3.3 — 2021-07-04
- … 1 more at https://npm.io/package/@xivapi/js/versions

## README

# xivapi-js

[![npm version](https://badge.fury.io/js/%40xivapi%2Fjs.svg)](https://badge.fury.io/js/%40xivapi%2Fjs)
[![license](https://img.shields.io/github/license/xivapi/xivapi-js.svg)](LICENSE)

A JavaScript library for working with [XIVAPI v2](https://v2.xivapi.com/), providing a source of Final Fantasy XIV game data. It lets you fetch, search, and use FFXIV data easily in a promise-based manner.

> [!WARNING]
> `@xivapi/js@0.4.5` (using XIVAPI v1) is now deprecated. Please use it at your own risk. We strongly recommend you update to the latest version. Migration guide and details: https://v2.xivapi.com/docs/migrate/.

If you need help or run into any issues, please [open an issue](https://github.com/xivapi/xivapi-js/issues) on GitHub or join the [XIVAPI Discord server](https://discord.gg/MFFVHWC) for support.

## Installation

```bash
npm install @xivapi/js # or pnpm/yarn/bun/deno
```

## Quick Start

### Node.js / Bundlers

```js
import xivapi from "@xivapi/js";

// Initialize with default settings
const xiv = new xivapi();

// Initialize with custom options
const xivCustom = new xivapi({
  version: "7.55",
  language: "ja",
});
```

### Browser (ESM)

No build step required &ndash; import directly via CDN:

```html
<script type="module">
  import xivapi from "https://cdn.jsdelivr.net/npm/@xivapi/js/+esm";

  const xiv = new xivapi();
</script>
```

## Examples

#### Fetch an Item

```js
const item = await xiv.items.get(1);
console.log(item.fields.Name); // "Gil"
````

#### Search Game Sheets

```js
const params = { query: 'Name~"gil"', sheets: "Item" };
const { results } = await xiv.search(params);
console.log(results[0]);

/*
Output:
{
  "score": 1,
  "sheet": "Item",
  "row_id": 1,
  "fields": {
    "Icon": {
      "id": 65002,
      "path": "ui/icon/065000/065002.tex",
      "path_hr1": "ui/icon/065000/065002_hr1.tex"
    },
    "Name": "Gil",
    "Singular": "gil"
  }
}
*/
```

#### Asset & Raw Sheet Queries

```js
// Fetch an asset path
const assets = await xiv.data.assets();
const asset = await assets.get({
  path: "ui/icon/051000/051474_hr1.tex",
  format: "png", // Supports "png", "jpg", or "webp"
});

// List rows from a game sheet
const sheets = await xiv.data.sheets();
const quests = await sheets.list("Quest");
console.log(quests);

// Query available game patch versions
const versions = await xiv.data.versions();
console.log(versions[0]); // e.g. "7.0"
```

## Contributing

Thanks for your interest in contributing! We welcome contributions of all kinds, including bug fixes, new features, documentation improvements, and translations.

For details on getting started, coding standards, and submitting PRs, please refer to our [Contributor Manual](CONTRIBUTING.md).

## License

This project is licensed under the MIT License. See [`LICENSE`](LICENSE) for details.

---
_Source: https://npm.io/package/@xivapi/js · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._