Configuration

The @query-api/nuxt package can be configured in the nuxt.config.ts file.

Example Configuration

This example shows a minimal setup for a Nuxt application using the Query API:

// https://nuxt.com/docs/api/configuration/nuxt-config
export default defineNuxtConfig({
  modules: ['@query-api/nuxt'],

  craftcms: {
    baseUrl: 'https://your-craft-backend.ddev.site',
    authToken: 'Bearer yourBearerToken',
  },
})

Configuration Options

baseUrl

The base URL of your Craft CMS backend where the Query API is running.

• Type: string
• Required: true
• Example: https://your-craft-backend.ddev.site

authToken

The authentication token for accessing the Craft CMS API. You can generate this Bearer token in the Query API plugin settings in your Craft control panel.

• Type: string
• Required: true
• Example: Bearer yourSecretToken...

siteMap

The siteMap option allows you to define an array of your Craft Sites. This is essential for multi-site setups, as it enables the library to correctly resolve sites based on the request URL.

• Type: CraftSite[]
• Default: []
• Example:

// Define the structure for a Craft site object.
type CraftSite = {
  handle: string
  origin: string
  path: string
  id?: number
  label?: string
  lang?: string
  primary?: boolean
}

// Example siteMap configuration.
siteMap: [
  {
    handle: 'en',
    path: '/',
    origin: 'http://localhost:3000',
    id: 1,
    primary: true,
  },
  {
    handle: 'de',
    path: '/de',
    origin: 'http://localhost:3000', // Origin can be the same for path-based multi-site
    id: 2,
  },
]

debug

Enable debug mode to log additional information to the console. This is useful during development for troubleshooting data fetching and component mapping.

• Type: boolean
• Default: false

enableEntryTypeMapping

By default, the library can map pages using a sectionHandle:entryTypeHandle format (e.g., news:article). If you prefer to only map by section handle, you can set this to false.

• Type: boolean
• Default: true

siteDetectionMode

This option controls how the current site is identified in a multi-site Craft CMS setup.

• path: (Default) Detects the site from the URL path (e.g., /de/news).
• origin: Detects the site from the domain or origin (e.g., german-site.com).
• Type: 'path' | 'origin'
• Default: 'path'

caching

Enables client side caching for all composables that fetch data on the cient side. Unfortunately this can't use the SSR payload that is generated by Nitro with SWR or ISR. This may change soon with this (PR)https://github.com/nuxt/nuxt/pull/33467.

• Type: boolean | { ttl: number }
• Default: false
• Example:

caching: {
  ttl: 3600 // cache for 1h
}
caching: true // cache for this session
caching: false // disable caching

Default Configuration

This is the default configuration for the @query-api/next package.

export const defaultCraftOptions = {
  baseUrl: '',
  authToken: '',
  debug: false,
  enableEntryTypeMapping: true,
  siteDetectionMode: siteDetectionModes.PATH,
  siteMap: [],
  caching: false,
}