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

The APIs the module generates composables for. Each key is an endpoint ID and names the pair it yields, so jsonPlaceholder gives you $jsonPlaceholder and useJsonPlaceholderData.

url is the base URL every request is resolved against, and the only required option. The rest are optional:

• token – Bearer token sent with each request.
• query – Query parameters added to each request.
• headers – Headers sent with each request.
• cookies – Whether the browser's cookies travel on to this API. See Cookie Forwarding.
• allowedUrls – Base URLs a request may switch to at runtime. See Dynamic Backend URL.
• schema – URL or file path of an OpenAPI schema to infer types from. See OpenAPI Integration.
• openAPITS – openapi-typescript options for this endpoint's schema, merged into the global openAPITS option by option.

token, query and headers stay on the server as long as client is off: the handler attaches them, and only in the default 'wrapped' proxy mode. See proxyMode.

Default Value: {}

Type Declarations

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 `usePetStoreData` 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.client

Whether composables may bypass the proxy and call your API straight from the browser. Doing so exposes the endpoint's credentials, so it is off by default.

• false – Every request goes through the server proxy.
• true or 'allow' – A composable call may opt in with client: true.
• 'always' – Every request is made client-side unless a call opts out.

Default Value: false, or 'always' when Nuxt runs with ssr: false, where there is no server to proxy through.

WARNING

Any value other than false writes every endpoint's token, query and headers into the public runtime config, because the browser has to send them itself. They are readable in the delivered HTML. 'allow' is no safer than 'always' here: the credentials ship whether or not a single call opts in. Reserve this for APIs whose credentials may be public.

See Client Requests for what a call looks like.

apiParty.openAPITS

Global configuration options for openapi-typescript. Options set here apply to every endpoint schema; an endpoint's own openAPITS replaces the options it names and leaves the rest in place.

apiParty.server

basePath

The path segment the module's server routes live under, below /api. Change it if __api_party collides with a route of your own.

Default Value: '__api_party'

proxyMode

How the server handler forwards a request to your API.

• 'wrapped' – Every call becomes a POST request that carries the original request in its body.
• 'passthrough' – The original request is mirrored: path, method, headers, query and body travel as they are, through h3's sendProxy utility.

Choose 'passthrough' when you want the browser's network tab to match the upstream request, or when you need HTTP cache control – a POST wrapper cannot be cached.

'passthrough' Adds No Credentials

The name is literal: the request travels as it stands, and nothing from the endpoint configuration is attached. The endpoint's token, headers and query are applied by the 'wrapped' handler only. Authenticate the upstream service in a request hook instead.

Default Value: 'wrapped'

apiParty.payloadCache

Whether a response may be cached in the Nuxt payload, keyed by the request. Turning it off also drops the caching logic from the client bundle.

An individual call opts out with payloadCache: false.

Default Value: true

Type Declarations

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. Keep in mind that a
   * client-side request exposes your API credentials to the client.
   *
   * - `false` keeps every request on the server.
   * - `'allow'` (or `true`) lets a call opt in with `client: true`, but still defaults to the server.
   * - `'always'` sends every call from the client unless it opts out with `client: false`.
   *
   * If Nuxt SSR is disabled, this defaults to `'always'`.
   *
   * @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

    /**
     * How the Nuxt server handler forwards a request to the API.
     *
     * @remarks
     * - `'wrapped'` sends every call as a POST request carrying the original request in its body, and adds the
     *   endpoint's `token`, `headers` and `query` along the way.
     * - `'passthrough'` mirrors the original request – path, method, headers, query and body travel as they are,
     *   and nothing from the endpoint configuration is added. Attach credentials in a request hook instead.
     *
     * @default 'wrapped'
     */
    proxyMode?: 'wrapped' | 'passthrough'
  }

  /**
   * Cache a response in the Nuxt payload, keyed by the request.
   *
   * @remarks
   * Turn this off to run your own caching strategy or to rely on the browser's HTTP cache through the `cache` option.
   *
   * @default true
   */
  payloadCache?: boolean

}