Configuration

You can configure the @query-api/react package 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 Entries.

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. This is the URL where your Craft CMS is hosted.

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

authToken

The authentication token for accessing the Craft CMS API. This is your generated Bearer token.

• Type: string
• Example: Bearer asdfasdfasdfasdfasdfasdf

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 is the same as the section handle or is default, just use the section handle (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 to React components in the contentMapping.pages object. There are two special keys for this:

• page404 for 404 Not Found pages
• page500 for 500 Internal Server Error pages
• error for general error pages

debug

Enable debug mode to log additional information to the console. This is useful for development and debugging purposes.

• Type: boolean
• Default: false
• Example: true

enableEntryTypeMapping

Enable or disable entry type mapping. If set to false, the contentMapping will not use the sectionHandle:entryTypeHandle mapping, and will only use the section handle for pages.

• Type: boolean
• Default: true
• Example: false

siteDetectionMode

The siteDetectionMode option controls how the site is identified in a multi-site Craft CMS setup:

• path: Detects the site from the URL path (e.g., /en/news).
• origin: Detects the site from the domain or origin (e.g., example.com).

This is useful if you want to load data from different sites based on the URL. While the feature is not yet implemented, you can already set siteDetectionMode to path or origin to prepare for future support.

• Type: path | origin
• Default: path
• Example: origin

siteMap

The siteMap option allows you to define an array of Craft Sites. This is useful for multi-site setups, as a global definition. In future versions, this will be used to detect the site based on the URL.

• Type: CraftSite[]

type CraftSite = {
  handle: string
  origin: string
  path: string
  id?: number
  label?: string
  lang?: string
  primary?: boolean
}

• Default: []
• Example:

siteMap: [
  {
    handle: 'en',
    path: '/',
    origin: 'http://localhost:3000',
    id: 1,
  },
  {
    handle: 'de',
    path: '/de',
    origin: 'http://localhost:3000/de',
    id: 2,
  },
]

Default Configuration

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

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