Build pages with CMS data

Every Cactal website gets a generated @website SDK based on its current CMS schema. Page code uses that SDK to define routes, declare server-side CMS queries, and render typed results.

Page definition

A page directly default-exports definePage({ ... }):

pages/post

import { definePage } from '@website'

export default definePage({
	route: '/blog/:slug',
	queries: ({ cms, param }) => ({
		post: cms.posts.get({
			slug: param.path('slug'),
			depth: 1
		})
	}),
	metadata: {
		title: '{{ post.fields.title }}'
	},
	render: ({ data }) => (
		<article>
			<h1>{data.post.fields.title}</h1>
		</article>
	)
})

Property	Required	Purpose
`route`	Yes	Inline static or parameterized URL pattern
`queries`	No	Object or function returning named CMS query plans
`metadata`	No	Static or templated page metadata
`render`	Yes	Function returning the page’s React content

The default export, definePage call, top-level object, and route literal must be direct and inline. Top-level object spreads, computed properties, indirect exports, variables used as routes, and route template literals fail static extraction. See Configure routes and redirects for the complete route grammar and matching behavior. See Configure SEO metadata for metadata fields and templates.

Generated CMS query builder

The cms object has one property per collection slug in the website’s CMS schema. Each collection supports get and list:

queries: ({ cms }) => ({
	featuredPost: cms.posts.get({ slug: 'welcome' }),
	recentPosts: cms.posts.list({ limit: 10 })
})

Collection slugs, field keys, option choices, required fields, reference targets, and result types are inferred from the schema. A nonexistent collection, field, or option value is a type error and also fails the framework quality gate. A page can declare at most 20 queries. Query names must be safe JavaScript identifiers with at most 64 characters, and cannot be __proto__, constructor, or prototype.

Get one item

Use exactly one of slug or id:

queries: ({ cms, param }) => ({
	post: cms.posts.get({
		slug: param.path('slug'),
		depth: 1
	})
})

Input	Type	Behavior
`slug`	string or request parameter	Finds one published item by collection-local slug
`id`	string or request parameter	Finds one published item by stable item id
`depth`	`0`, `1`, or `2`	Hydrates references by that many levels; defaults to `0`

If the parameter is absent or no published item matches, Cactal serves the site’s custom not_found page with HTTP 404, exactly as it does for an unmatched route. Sites without a not_found file get the standard platform 404. Use a list query when an empty result is valid page content.

List items

list returns published items in manual CMS order by default:

pages/blog

import { definePage } from '@website'

export default definePage({
	route: '/blog',
	queries: ({ cms, param }) => ({
		posts: cms.posts.list({
			page: param.query('page'),
			limit: 12,
			search: param.query('q'),
			filter: {
				featured: { eq: true }
			},
			sort: {
				kind: 'field',
				field: 'published_date',
				direction: 'desc'
			}
		})
	}),
	render: ({ data }) => (
		<main>
			{data.posts.items.map(post => (
				<article key={post.id}>
					<h2>{post.fields.title}</h2>
				</article>
			))}
		</main>
	)
})

List inputs

Input	Shape	Behavior
`cursor`	string or request parameter	Continues cursor pagination
`page`	integer or numeric string, or request parameter	Selects a 1-based offset page
`limit`	integer `1` to `100`, or request parameter	Items per page; defaults to `20`
`depth`	`0`, `1`, or `2`, or request parameter	Reference hydration depth
`filter`	field-to-operator map	Filters using schema-aware field values
`filterLogic`	`and` or `or`	Combines field clauses; defaults to `and`
`search`	string, request parameter, or `{ query, fields? }`	Searches text-like fields
`sort`	`{ kind: 'field', field, direction }`	Sorts one supported field ascending or descending

Do not use cursor and page together. The list result includes both nextCursor and nextPage; use the value matching your pagination style.

Filters

filter: {
	category: { eq: param.query('category') },
	views: { gte: 100 },
	published_date: { lt: '2026-08-01T00:00:00.000Z' },
	title: { contains: param.query('q') }
}

Field kind	Supported operators
Text, markdown, link, email, color, single option	`eq`, `neq`, `in`, `nin`, `contains`, `startsWith`, `endsWith`, `exists`
Number and date	`eq`, `neq`, `in`, `nin`, `gt`, `gte`, `lt`, `lte`, `exists`
Boolean	`eq`, `neq`, `in`, `nin`, `exists`
Reference	`eq`, `neq`, `in`, `nin`, `exists`, plus `slug` equality
Image, gallery, and file	`eq`, `neq`, `in`, `nin`, `exists`
Multiple option	`exists`

A filter can address at most 20 fields and contain at most 50 field/operator clauses. Unlike the REST item-list endpoint, the page query builder filters schema fields only, not item metadata such as createdAt, publishedAt, or publishAt. Use slug to filter a reference from a dynamic route without first looking up the referenced item id:

export default definePage({
	route: '/events/:city',
	queries: ({ cms, param }) => ({
		events: cms.events.list({
			filter: { city: { slug: param.path('city') } },
			limit: 100
		})
	}),
	render: ({ data }) => data.events.items.map(event => event.fields.name)
})

Reference slug traversal is limited to one level. It is applied by the CMS before limit, cursor, or page, so pagination describes the filtered set.

Search and sort

Search accepts a string or request parameter:

search: param.query('q')

Restrict search to selected text, markdown, link, email, or color fields with an object:

search: {
	query: param.query('q'),
	fields: ['title', 'summary']
}

Sort supports one schema field. Text, markdown, references, assets, galleries, files, and multiple-choice option fields are not sortable through page queries. Sort fields and directions must be static; they cannot be request-parameter placeholders.

Bind request parameters

The queries function receives a placeholder builder named param:

queries: ({ cms, param }) => ({
	post: cms.posts.get({ slug: param.path('slug') }),
	results: cms.posts.list({
		page: param.query('page'),
		filter: {
			category: { in: param.query('category') },
			featured: { eq: param.query('featured') }
		}
	})
})

param.path(name) is type-checked against :name segments in the page route.
param.query(name) reads one query-string key.
Values are coerced for their destination. Numeric pagination and number filters require numbers; boolean filters accept true or false.
Repeated query-string values are accepted only where an in or nin filter expects multiple values.

Missing parameter behavior depends on its use:

Location	Missing value behavior
`get` id or slug	The query reports not found and SSR fails
List `cursor` or `page`	Omitted, so the list begins at its default position
List filter or search	Returns an empty list without calling the CMS
Other list inputs such as `limit` or `depth`	SSR fails with a required-parameter diagnostic

Path and query parameters are source-specific. A missing path parameter never falls back to a query parameter with the same name.

Render results

The render function receives:

Property	Type	Meaning
`data`	object	One property per declared query, inferred from its plan
`path`	string	Requested path
`params`	string map	Matched route parameters
`query`	string or string-array map	Parsed query parameters
`param.path(name)`	string	Type-checked route-parameter reader
`param.query(name)`	string, string array, or `undefined`	Query-parameter reader
`metadata`	object	Fully resolved metadata rendered for this request

Item result

get returns:

{
	id: string
	slug: string
	fields: Record<string, unknown>
	meta: {
		publishedAt: string | null
		publishAt: string | null
		createdAt: string
		updatedAt: string
	}
}

The actual fields type is generated from the collection. Optional values include null; gallery and multi-value fields use arrays. Image and file fields include their ready CDN URL and asset metadata. At depth: 0, references are item ids. At greater depths, references become nested items with the same { id, slug, fields, meta } shape. The page query maximum is 2, even though direct CMS API reads support depth 3.

List result

list returns:

{
	items: CMSItem[]
	nextCursor: string | null
	nextPage: number | null
}

Published content and schema changes

Published sites and draft previews both query published CMS items. Draft, scheduled, unpublished, and deleted items do not appear in page results. A scheduled item begins appearing after Cactal promotes it and records publishedAt. The published website guards its schema. A collection or field change that would break published page queries is rejected. Update page source, publish the compatible code, then change the schema. Collection-slug and field-key renames use dedicated CMS operations that migrate references safely.

Sitemap discovery

A dynamic route can be enumerated in the generated sitemap when it has exactly one route parameter and exactly one get query whose slug or id is bound to that parameter:

route: '/blog/:slug',
queries: ({ cms, param }) => ({
	post: cms.posts.get({ slug: param.path('slug') })
})

See Configure SEO metadata for the complete crawler behavior.

Troubleshooting

Problem	Cause	Fix
`cms.posts` does not exist	The collection slug differs from the generated schema	Read `GET /v1/cms/schema` and use the current slug
A field is missing from `data`	The field key changed or the build uses an older schema	Re-check the schema and rebuild the draft
A reference is an id instead of an item	The query uses `depth: 0`	Set `depth: 1` or `2`
SSR reports not found	A `get` query received no value or found no published item	Publish the item, correct the parameter, or use a list query
A repeated query parameter fails	Its destination expects one value	Use it in `in` or `nin`, or send a single value
A list is unexpectedly empty	A filter or search request parameter is absent	Supply the parameter or remove that conditional input
A dynamic page is absent from the sitemap	Its route/query shape is not inferable	Use one path parameter and one matching `get` query by slug or id

Next steps

Manage CMS content to create collections, fields, and published items
Configure routes and redirects for route matching and canonical paths
Configure SEO metadata to resolve query data into titles and social tags
Style a website with global CSS and Tailwind CSS

Get started

Core concepts

Guides

Build with agents

Platform

Build pages with CMS data

Page definition

Generated CMS query builder

Get one item

List items

List inputs

Filters

Search and sort

Bind request parameters

Render results

Item result

List result

Published content and schema changes

Sitemap discovery

Troubleshooting

Next steps

​Page definition

​Generated CMS query builder

​Get one item

​List items

​List inputs

​Filters

​Search and sort

​Bind request parameters

​Render results

​Item result

​List result

​Published content and schema changes

​Sitemap discovery

​Troubleshooting

​Next steps

Page definition

Generated CMS query builder

Get one item

List items

List inputs

Filters

Search and sort

Bind request parameters

Render results

Item result

List result

Published content and schema changes

Sitemap discovery

Troubleshooting

Next steps