Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
module configuration
✓ // nuxt.config.ts
export default defineNuxtConfig({
modules: ['nuxt-api-party'],
apiParty: { /* ... */ }
});
✗ import { ApiParty } from 'nuxt-api-party';
Nuxt API Party is a module, configured in `nuxt.config.ts`. Its composables are auto-imported and should not be explicitly imported in component/page code.
useApiData composable
✓ const { data, pending, error } = await useJsonPlaceholderData('posts/1');
✗ import { useJsonPlaceholderData } from 'nuxt-api-party'; // not needed, auto-imported
const { data } = await useApiData('jsonPlaceholder', 'posts/1'); // incorrect usage pattern
Composables like `useJsonPlaceholderData` are auto-generated and auto-imported based on your `endpoints` configuration in `nuxt.config.ts`. No explicit import statement is required in your components or pages.
$api fetcher
✓ const post = await $jsonPlaceholder('posts/1');
✗ import { $jsonPlaceholder } from 'nuxt-api-party'; // not needed, auto-imported
const post = await $api('jsonPlaceholder', 'posts/1'); // incorrect usage pattern
The `$api` fetcher (e.g., `$jsonPlaceholder`) is also auto-generated and auto-imported. It provides a shorthand for fetching data directly, similar to Nuxt's `$fetch` utility.
OpenAPI types
✓ type Post = paths['/posts/{id}']['get']['responses']['200']['content']['application/json'];
✗ import { Post } from 'nuxt-api-party/types'; // generally incorrect path or approach
OpenAPI types are typically generated into a local file (e.g., `api-party.d.ts`) by `openapi-typescript`. You would reference these types directly in your application code, usually through global declaration or direct path import if specified, not directly from the `nuxt-api-party` package itself.
This quickstart demonstrates configuring two API endpoints (`jsonPlaceholder` and `myCustomApi`) in `nuxt.config.ts` and then using their respective auto-generated composables (`useJsonPlaceholderData`) and `$api` fetchers (`$myCustomApi`) within a Vue component to fetch and display data.
// nuxt.config.ts
import { defineNuxtConfig } from 'nuxt';
export default defineNuxtConfig({
modules: ['nuxt-api-party'],
apiParty: {
endpoints: {
jsonPlaceholder: {
url: process.env.JSON_PLACEHOLDER_API_BASE_URL ?? 'https://jsonplaceholder.typicode.com',
headers: {
// In a real app, use environment variables for tokens
Authorization: `Bearer ${process.env.JSON_PLACEHOLDER_API_TOKEN ?? 'your-mock-token'}`
}
},
myCustomApi: {
url: process.env.MY_CUSTOM_API_BASE_URL ?? 'http://localhost:3001/api',
headers: {
'X-Api-Key': process.env.MY_CUSTOM_API_KEY ?? 'another-mock-key'
}
}
}
}
});
// app.vue (or any Vue component/page)
<script setup lang="ts">
interface Post {
userId: number;
id: number;
title: string;
body: string;
}
// Use the auto-generated composable for jsonPlaceholder endpoint
const { data: postData, pending, error, refresh } = await useJsonPlaceholderData<Post>('posts/1');
// Use the $api shorthand for another endpoint
const customApiResponse = await $myCustomApi('/data');
</script>
<template>
<div>
<h1>Nuxt API Party Example</h1>
<div v-if="pending">Loading post...</div>
<div v-else-if="error">Error loading post: {{ error.message }}</div>
<div v-else-if="postData">
<h2>Post Title: {{ postData.title }}</h2>
<pre>{{ JSON.stringify(postData, null, 2) }}</pre>
<button @click="refresh">Refresh Post</button>
</div>
<hr>
<h2>Custom API Response (from $myCustomApi)</h2>
<pre>{{ JSON.stringify(customApiResponse, null, 2) }}</pre>
</div>
</template>
Errors
Common errors & fixes
Error: Cannot find module 'openapi-typescript' from '...
The `openapi-typescript` package is a peer dependency and must be explicitly installed if you are leveraging OpenAPI features, but it's missing.
fixInstall `openapi-typescript` in your project's dev dependencies: `pnpm add -D openapi-typescript` or `npm install -D openapi-typescript`.
TypeError: Cannot read properties of undefined (reading 'title') in <template>
Data from the API might be `null` or `undefined` initially or after an error, and the template tries to access properties on it without null-checking.
fixAlways add null/undefined checks in your templates, e.g., `<h1 v-if="data">{{ data.title }}</h1>` or use optional chaining `{{ data?.title }}`. Type 'EndpointName' is not assignable to type 'string'. (TypeScript)
When using auto-generated types for `$api` or `useApiData` based on OpenAPI, the endpoint name (e.g., 'jsonPlaceholder') is inferred. If you're manually trying to pass a string literal that doesn't match a configured endpoint, TypeScript will complain.
fixEnsure the string literal used for the endpoint name exactly matches one of the keys defined in your `apiParty.endpoints` configuration in `nuxt.config.ts`.
Audit
Dependencies
openapi-typescriptoptionalRequired for OpenAPI type generation. Peer dependency, must be installed separately if using OpenAPI features.