Module Configuration

Configure Nuxt API Party to your needs in the apiParty key of your Nuxt configuration. The module options are fully typed.

nuxt.config.ts

export default defineNuxtConfig({
  modules: ['nuxt-api-party'],

  apiParty: {
    endpoints: {
      // ... Your endpoints go here
    }
  }
})

apiParty.endpoints

Main module configuration for your API endpoints. Each key is an endpoint ID used to generate composables. The value is an object with the following properties:

• url (required): Base URL of the API
• token (optional): Bearer token for authentication
• query (optional): Default query parameters to send with each request
• headers (optional): Default headers sent with each request
• cookies (optional): Whether to forward cookies in requests
• allowedUrls (optional): URLs allowed for dynamic backend switching
• schema (optional): OpenAPI Schema schema URL or file path for type generation
• openAPITS (optional): Endpoint-specific configuration options for openapi-typescript. Will override the global openAPITS options if provided.

Default value: {}

Placeholders

Composables are generated based on your API endpoint ID. For example, an endpoint jsonPlaceholder generates useJsonPlaceholderData and $jsonPlaceholder.

Type Declaration:

export interface EndpointConfiguration {
  url: string
  token?: string
  query?: QueryObject
  headers?: HeadersInit
  cookies?: boolean
  allowedUrls?: string[]
  schema?: string | OpenAPI3
  openAPITS?: OpenAPITSOptions
}

Example:

export default defineNuxtConfig({
  apiParty: {
    endpoints: {
      // Will generate `$jsonPlaceholder` and `useJsonPlaceholderData`
      jsonPlaceholder: {
        url: process.env.JSON_PLACEHOLDER_API_BASE_URL!,
        token: process.env.JSON_PLACEHOLDER_API_TOKEN!
      },
      // Will generate `$cms` and `useCmsData`
      cms: {
        url: process.env.CMS_API_BASE_URL!,
        headers: {
          Authorization: `Basic ${globalThis.btoa(`${process.env.CMS_API_USERNAME}:${process.env.CMS_API_PASSWORD}`)}`
        }
      },
      // Will generate `$petStore` and `usePetStore` as well as types for each path
      petStore: {
        url: process.env.PET_STORE_API_BASE_URL!,
        schema: `${process.env.PET_STORE_API_BASE_URL!}/openapi.json`
      }
    }
  }
})

apiParty.openAPITS

Global configuration options for openapi-typescript. Options set here apply to every endpoint schema but can be overridden per endpoint.

apiParty.experimental

These feature flags enable experimental features which change the default behavior of the module that may become the default in the future.

enableAutoKeyInjection

When enabled, Nuxt generates a unique key for each composable call based on its location in the code, similar to useFetch and useAsyncData.

To share data between multiple calls to the same resource, provide a key option to the composable call. The same restrictions apply as with useFetch and useAsyncData: each call must share the same pick, transform, and getCachedData options.

enablePrefixedProxy

When enabled, globally enables direct API proxying using h3's requestProxy utility.

By default, all API requests go through an internal POST endpoint that passes the request to the backend service. This can be confusing when inspecting the browser network tab if you don't expect it. Since it uses a POST request, it isn't compatible with cache control.

Enable this option if you prefer matching HTTP methods or want to use cache control.

disableClientPayloadCache

When enabled, disables client-side payload cache for all generated composables.

This has the same effect as setting cache: false in each composable call and enforces it globally. Additionally, in-memory caching logic is completely removed from composables, resulting in smaller bundle sizes.

enableSchemaFileWatcher

TIP

This option is enabled by default in development mode.

When enabled, watches local OpenAPI schema files using chokidar.

Changes to local schema files automatically regenerate types. When disabled, restart the Nuxt dev server to pick up changes to local schema files. Has no effect on remote schemas.

Type Declaration

export interface EndpointConfiguration {
  url: string
  token?: string
  query?: QueryObject
  headers?: HeadersInit
  cookies?: boolean
  allowedUrls?: string[]
  schema?: string | OpenAPI3
  openAPITS?: OpenAPITSOptions
}

export interface ModuleOptions {
  /**
   * API endpoints
   *
   * @remarks
   * Each key represents an endpoint ID, which is used to generate the composables. The value is an object with the following properties:
   * - `url` (required): Base URL of the API
   * - `token` (optional): Bearer token for authentication
   * - `query` (optional): Default query parameters to send with each request
   * - `headers` (optional): Default headers to send with each request
   * - `cookies` (optional): Whether to forward cookies in requests
   * - `allowedUrls` (optional): URLs allowed for [dynamic backend switching](https://nuxt-api-party.byjohann.dev/guides/dynamic-backend-url)
   * - `schema` (optional): [OpenAPI Schema](https://swagger.io/resources/open-api) schema URL or file path for [type generation](https://nuxt-api-party.byjohann.dev/guides/openapi-integration)
   * - `openAPITS` (optional): Endpoint-specific configuration options for [`openapi-typescript`](https://openapi-ts.dev/node/#options). Will override the global `openAPITS` options if provided.
   *
   * @example
   * export default defineNuxtConfig({
   *   apiParty: {
   *     endpoints: {
   *       jsonPlaceholder: {
   *         url: 'https://jsonplaceholder.typicode.com'
   *         headers: {
   *           Authorization: `Basic ${globalThis.btoa('username:password')}`
   *         }
   *       }
   *     }
   *   }
   * })
   *
   * @default {}
   */
  endpoints: Record<string, EndpointConfiguration>

  /**
   * Allow client-side requests besides server-side ones
   *
   * @remarks
   * By default, API requests are only initiated server-side. This option allows you to make requests on the client-side as well. Keep in mind that this will expose your API credentials to the client.
   * Note: If Nuxt SSR is disabled, all requests are made on the client-side by default.
   *
   * @example
   * useJsonPlaceholderData('/posts/1', { client: true })
   *
   * @default false
   */
  client: boolean | 'allow' | 'always'

  /**
   * Global options for [`openapi-typescript`](https://openapi-ts.dev/node/#options)
   */
  openAPITS: OpenAPITSOptions

  server: {
    /**
     * The API base route for the Nuxt server handler
     *
     * @default '__api_party'
     */
    basePath?: string
  }

  experimental: {
    /**
     * Enable key injection for `useMyApiData` composables like Nuxt's `useAsyncData` and `useFetch` composables.
     *
     * With an auto-generated default key, payload caching will be unique for each instance without an explicit key option.
     *
     * @default false
     */
    enableAutoKeyInjection?: boolean
    /**
     * Set to `true` to enable prefixed proxy endpoints.
     *
     * Prefixed endpoints more closely match the target endpoint's request by forwarding the path, method, headers,
     * query, and body directly to the backend. It uses h3's `proxyRequest` utility. The default behavior is to wrap
     * each endpoint in a POST request.
     *
     * @default false
     */
    enablePrefixedProxy?: boolean

    /**
     * Set to `true` to disable the built-in payload caching mechanism by default.
     *
     * Disabling this can be useful if you want to implement your own caching strategy or reuse the browser's HTTP
     * cache by setting the `cache` option on requests.
     *
     * @default false
     */
    disableClientPayloadCache?: boolean

    /**
     * Enable the file watcher for local OpenAPI schema files using chokidar.
     *
     * When enabled, changes to local schema files will automatically regenerate the types. When disabled, you will
     * need to restart the Nuxt dev server to pick up changes to local schema files. Has no effect if no local schema
     * files are used or for remote schemas.
     *
     * @default true
     */
    enableSchemaFileWatcher?: boolean
  }
}