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 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
• 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

The composables are generated based on your API endpoint ID. For example, if you were to call an endpoint jsonPlaceholder, the composables will be called 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

The global configuration options for openapi-typescript. Options set here will be applied to every endpoint schema, but can be overridden by individual endpoint options.

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 set to true, this experimental option will instruct nuxt to generate a unique key for each composable call based on its location in the code, similar to useFetch and useAsyncData.

As a consequence, in order to share data between multiple calls to the same resource, you will need to provide a key option to the composable call. The same restrictions apply as with useFetch and useAsyncData, meaning that each call must share the same pick, transform, and getCachedData options.

enablePrefixedProxy

When set to true, this experimental option will globally enable direct API proxying using h3's requestProxy utility.

By default, all API requests go through an internal POST endpoint which passes the request to the backend service. This can be confusing when looking at the browser network debug tool if you don't expect it. Also as it uses a POST request, it isn't compatible with cache control.

Enable this option if this behavior is undeired or you want to take advantage of cache control.

disableClientPayloadCache

When set to true, this experimental option will disable the client-side payload cache for all generated composables.

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

enableSchemaFileWatcher

TIP

This option is enabled by default in development mode.

When set to true, this experimental option will enable a 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. It 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
  }
}