{"id":16157,"library":"nuxt-api-party","title":"Nuxt API Party","description":"Nuxt API Party is a module for Nuxt that streamlines secure and type-safe interaction with multiple API endpoints. It achieves this by generating composables dynamically for each configured API, similar in feel to Nuxt's native `useFetch` and `$fetch`. The module effectively secures API credentials and circumvents common CORS issues by proxying requests through a Nuxt server route. It features robust OpenAPI specification integration for generating fully typed API clients, offering enhanced developer experience and compile-time safety. The current stable version is 3.4.2, with frequent patch and minor releases addressing bugs and introducing new features. Its key differentiators include automated composable generation, strong type-safety via OpenAPI, built-in credential protection, and smart caching.","status":"active","version":"3.4.2","language":"javascript","source_language":"en","source_url":"https://github.com/johannschopplich/nuxt-api-party","tags":["javascript","api","fetch","nuxt","open-api","openapi","query","typescript"],"install":[{"cmd":"npm install nuxt-api-party","lang":"bash","label":"npm"},{"cmd":"yarn add nuxt-api-party","lang":"bash","label":"yarn"},{"cmd":"pnpm add nuxt-api-party","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required for OpenAPI type generation. Peer dependency, must be installed separately if using OpenAPI features.","package":"openapi-typescript","optional":true}],"imports":[{"note":"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.","wrong":"import { ApiParty } from 'nuxt-api-party';","symbol":"module configuration","correct":"// nuxt.config.ts\nexport default defineNuxtConfig({\n  modules: ['nuxt-api-party'],\n  apiParty: { /* ... */ }\n});"},{"note":"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.","wrong":"import { useJsonPlaceholderData } from 'nuxt-api-party'; // not needed, auto-imported\nconst { data } = await useApiData('jsonPlaceholder', 'posts/1'); // incorrect usage pattern","symbol":"useApiData composable","correct":"const { data, pending, error } = await useJsonPlaceholderData('posts/1');"},{"note":"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.","wrong":"import { $jsonPlaceholder } from 'nuxt-api-party'; // not needed, auto-imported\nconst post = await $api('jsonPlaceholder', 'posts/1'); // incorrect usage pattern","symbol":"$api fetcher","correct":"const post = await $jsonPlaceholder('posts/1');"},{"note":"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.","wrong":"import { Post } from 'nuxt-api-party/types'; // generally incorrect path or approach","symbol":"OpenAPI types","correct":"type Post = paths['/posts/{id}']['get']['responses']['200']['content']['application/json'];"}],"quickstart":{"code":"// nuxt.config.ts\nimport { defineNuxtConfig } from 'nuxt';\n\nexport default defineNuxtConfig({\n  modules: ['nuxt-api-party'],\n  apiParty: {\n    endpoints: {\n      jsonPlaceholder: {\n        url: process.env.JSON_PLACEHOLDER_API_BASE_URL ?? 'https://jsonplaceholder.typicode.com',\n        headers: {\n          // In a real app, use environment variables for tokens\n          Authorization: `Bearer ${process.env.JSON_PLACEHOLDER_API_TOKEN ?? 'your-mock-token'}`\n        }\n      },\n      myCustomApi: {\n        url: process.env.MY_CUSTOM_API_BASE_URL ?? 'http://localhost:3001/api',\n        headers: {\n          'X-Api-Key': process.env.MY_CUSTOM_API_KEY ?? 'another-mock-key'\n        }\n      }\n    }\n  }\n});\n\n// app.vue (or any Vue component/page)\n<script setup lang=\"ts\">\ninterface Post {\n  userId: number;\n  id: number;\n  title: string;\n  body: string;\n}\n\n// Use the auto-generated composable for jsonPlaceholder endpoint\nconst { data: postData, pending, error, refresh } = await useJsonPlaceholderData<Post>('posts/1');\n\n// Use the $api shorthand for another endpoint\nconst customApiResponse = await $myCustomApi('/data');\n</script>\n\n<template>\n  <div>\n    <h1>Nuxt API Party Example</h1>\n    <div v-if=\"pending\">Loading post...</div>\n    <div v-else-if=\"error\">Error loading post: {{ error.message }}</div>\n    <div v-else-if=\"postData\">\n      <h2>Post Title: {{ postData.title }}</h2>\n      <pre>{{ JSON.stringify(postData, null, 2) }}</pre>\n      <button @click=\"refresh\">Refresh Post</button>\n    </div>\n    <hr>\n    <h2>Custom API Response (from $myCustomApi)</h2>\n    <pre>{{ JSON.stringify(customApiResponse, null, 2) }}</pre>\n  </div>\n</template>","lang":"typescript","description":"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."},"warnings":[{"fix":"Install `openapi-typescript` in your project: `pnpm add -D openapi-typescript@'^5 || ^6 || ^7'` or `npm install -D openapi-typescript@'^5 || ^6 || ^7'`.","message":"The peer dependency `openapi-typescript` is required for OpenAPI type generation features. Ensure it is installed in your project and matches the supported versions (currently ^5, ^6, or ^7).","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"Upgrade to `nuxt-api-party@3.4.2` or newer to resolve issues with `client: false` and non-SSR usage. Review your configuration to ensure `client` option aligns with your rendering strategy.","message":"When using the `client: false` option, ensure that it's compatible with your intended SSR/non-SSR usage. Prior to v3.4.2, there were issues with non-SSR usage when `client: false` was set, potentially leading to hydration mismatches or unexpected behavior.","severity":"gotcha","affected_versions":"<3.4.2"},{"fix":"Consult the official documentation for the latest guidance on OpenAPI integration and type usage. Ensure `openapi-typescript` is updated and regenerate types as needed. Check for specific fixes like 'Add missing OpenAPI type helper imports' (v3.1.2).","message":"OpenAPI type helpers were significantly overhauled in v3.1.0, and further refined in subsequent patches (e.g., v3.1.2 fixed missing imports). This might require adjustments to how you import or reference generated OpenAPI types.","severity":"breaking","affected_versions":">=3.1.0"},{"fix":"Update to `nuxt-api-party@3.4.1` or newer to benefit from improved schema resolution logic, especially if you are developing on Windows.","message":"Incorrect schema resolution paths, particularly on Windows environments, could lead to failed type generation or API client setup. This was addressed in v3.4.1.","severity":"gotcha","affected_versions":"<3.4.1"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"fix":"Install `openapi-typescript` in your project's dev dependencies: `pnpm add -D openapi-typescript` or `npm install -D openapi-typescript`.","cause":"The `openapi-typescript` package is a peer dependency and must be explicitly installed if you are leveraging OpenAPI features, but it's missing.","error":"Error: Cannot find module 'openapi-typescript' from '..."},{"fix":"Always add null/undefined checks in your templates, e.g., `<h1 v-if=\"data\">{{ data.title }}</h1>` or use optional chaining `{{ data?.title }}`.","cause":"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.","error":"TypeError: Cannot read properties of undefined (reading 'title') in <template>"},{"fix":"Ensure the string literal used for the endpoint name exactly matches one of the keys defined in your `apiParty.endpoints` configuration in `nuxt.config.ts`.","cause":"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.","error":"Type 'EndpointName' is not assignable to type 'string'. (TypeScript)"}],"ecosystem":"npm"}