Configuration

The @query-api/next package is configured by calling the craftInit function. This function initializes the Query API client with your Craft CMS backend details and maps your React components to Craft CMS entries and blocks.

Typically, you will do this in a dedicated file, such as libs/query-api.ts, to keep your configuration organized and easily accessible.

Example Configuration

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

craftInit({
  baseUrl: 'https://your-craft-backend.ddev.site',
  authToken: 'Bearer yourBearerToken',
  contentMapping: {
    pages: {}
    components: {},
  },
})

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

contentMapping

The contentMapping option lets you connect your Craft CMS sections and entry types to React components.

In pages, use sectionHandle:entryTypeHandle (e.g., news:home) to map to a React page. If the entry type handle is the same as the section handle, or if it's the default entry type for that section, you can simply use the section handle as the key (e.g., home).

In components, map entry types to React components. This is useful for things like matrix blocks.

• Type: object
• Default: { pages: {}, components: {} }
• Example:

contentMapping: {
  pages: {
    home: Home, // Maps section home entry with entry type home to the Home component.
    'news:home': News, // Maps section news entry with entry type home to the News component.
  },
  components: {
    headline: Headline, // Entry type headline will be rendered with the Headline component.
    imageText: CraftNotImplemented,
  },
}

Error Pages

You can also map error pages by providing special keys in the contentMapping.pages object. This allows you to render custom Next.js components for specific error scenarios.

• page404: For 404 Not Found errors.
• page500: For 500 Internal Server Error responses from Craft.
• error: A general fallback for other errors.

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'

Default Configuration

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

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