Configuration Reference

The conlocaCMS() function accepts a configuration object that controls every aspect of the CMS: content storage location, visual editor components, routing patterns, authentication, media library, and multi-locale support.

This page documents every configuration option available when adding Conloca CMS to your Astro project via the conlocaCMS() integration function.

Quick Reference

// astro.config.mjs
import { conlocaCMS } from '@conloca/astro-cms/node';

conlocaCMS({
  // Required
  contentRoot: './content',
  puckConfigPath: './src/puck.config.tsx',

  // Optional — content & routing
  canvasDir: './canvas',
  route: '/__cms',
  schemasPath: './src/schemas/data.ts',
  layout: './src/layouts/Layout.astro',
  routing: true,
  templates: {
    /* ... */
  },
  componentPaths: ['src/components/puck'],
  assetsPath: 'src/assets/uploads',

  // Optional — UI
  siteBaseUrl: '',
  siteStyles: ['./src/styles/puck-preview.css'],
  enableDevtools: true,
  queryClientOptions: {
    /* ... */
  },
});

ConlocaCMSOptions

The ConlocaCMSOptions interface extends the CMS UI configuration and adds all server-side options.

Required Options

contentRoot

• Type: string
• Required: Yes

Path to the directory where Conloca stores content files. Can be relative to the project root or absolute. The directory is created automatically if it does not exist.

contentRoot: './content';

Content is stored as VXJSON files within this directory, organized by site, collection, and locale. See Architecture & Concepts for details on the content model.

puckConfigPath

• Type: string
• Required: Yes

Path to the Puck component configuration module. Must be a .tsx file that default-exports a Puck Config object.

puckConfigPath: './src/puck.config.tsx';

The Puck config defines which components are available in the visual editor. See the Getting Started guide for a minimal example.

Content Options

canvasDir

• Type: string
• Default: './canvas'

Path to the canvas directory used for temporary editor state.

canvasDir: './canvas';

schemasPath

• Type: string
• Default: undefined

Path to a module that exports schemas for the CMS. The module can export { dataSchemas, pageSchemas } — dataSchemas maps collection names to Zod schemas for structured data forms, and pageSchemas registers page-level schemas.

schemasPath: './src/schemas/data.ts';

When provided, data entry forms in the CMS are generated from these schemas, giving editors structured input fields instead of raw JSON.

Routing Options

route

• Type: string
• Default: '/__cms'

Base URL path for the CMS admin interface. The admin UI is served at this path, and the content API is mounted at {route}/api.

route: '/__cms';

layout

• Type: string
• Default: undefined

Default layout component for content pages. When provided without a routing configuration, this enables routing with a catch-all pattern that wraps all content pages in this layout.

layout: './src/layouts/Layout.astro';

For multi-route setups with different layouts per collection, use routing.routes.{name}.layout instead.

routing

• Type: boolean | RoutingConfig
• Default: undefined (routing disabled)

Content page routing configuration. When enabled, Conloca automatically injects Astro routes that serve content pages from your content directory.

Simple form — enable with all defaults (catch-all route for pages collection):

routing: true;

Full form — configure multiple routes with different collections and layouts:

routing: {
  enabled: true,
  routes: {
    pages: {
      pattern: '/[...slug]',
      collection: 'pages',
      layout: './src/layouts/Layout.astro',
      prerender: true,
    },
    blog: {
      pattern: '/blog/[slug]',
      collection: 'posts',
      layout: './src/layouts/BlogLayout.astro',
    },
  },
  fallback: '404',
  siteName: 'default',
  locale: 'en',
}

RoutingConfig

Field	Type	Default	Description
enabled	boolean	true	Whether routing is active
routes	Record<string, RouteConfig>	catch-all /[...slug]	Route definitions mapping URL patterns to collections
fallback	'404' | 'passthrough'	'404'	Behavior when route matches but no content exists. passthrough lets Astro try the next handler.
onConflict	'warn' | 'error' | 'silent'	'warn'	What to do when an injected route conflicts with a file-based route
siteName	string	'default'	Site name for content resolution in multi-site setups
locale	string	'en'	Default locale for content resolution

RouteConfig

Field	Type	Default	Description
pattern	string	—	Astro route pattern (e.g., /[...slug], /blog/[slug])
collection	string	'pages'	Content collection to query
layout	string	undefined	Path to layout component wrapping the rendered content
prerender	boolean	true	Whether to statically generate pages at build time (SSG)
meta	Record<string, unknown>	undefined	Additional metadata passed to the page handler
dataBindings	DataBindingConfig	undefined	Data collections to inject into Puck component resolvers

DataBindingConfig

When dataBindings is set on a route, Conloca fetches the specified collections and page lists at render time and injects them into Puck component resolveData() calls via metadata (typed as DataContext).

Field	Type	Description
collections	string[]	Data collection names to fetch. Available as metadata.collections[name] in resolveData.
pages.prefix	string	URL prefix filter — only pages whose pathname starts with this value are included.
pages.limit	number	Maximum number of pages to return.
pages.sort	'date-desc' | 'date-asc' | 'title'	Sort order for pages. Defaults to 'date-desc' (newest first).
locale	string	Locale override for data fetching. Defaults to the route’s locale setting.

routing: {
  routes: {
    blog: {
      pattern: '/blog/[...slug]',
      collection: 'posts',
      dataBindings: {
        collections: ['team', 'testimonials'],
        pages: {
          prefix: '/blog/',
          sort: 'date-desc',
          limit: 10,
        },
        locale: 'en',
      },
    },
  },
}

templates

• Type: Record<string, TemplateConfig>
• Default: undefined

Page creation templates that appear in the CMS “New Page” dialog. Templates let editors create pages with pre-defined component structures.

templates: {
  blog: {
    label: 'Blog Post',
    component: 'BlogPostTemplate',
    pathPrefix: '/blog/',
    description: 'A blog post with hero image and content area',
  },
  landing: {
    label: 'Landing Page',
    component: 'LandingPageTemplate',
  },
}

TemplateConfig

Field	Type	Required	Description
label	string	Yes	Display label in the template dropdown
component	string	Yes	Puck component name to pre-drop into the page. Must match a component in your puck.config.
pathPrefix	string	No	Auto-applied path prefix (e.g., /blog/ turns my-post into /blog/my-post)
description	string	No	Description shown in the dropdown

Media Library Options

assetsPath

• Type: string
• Default: undefined

Path to the assets directory for image uploads. When provided, the CMS enables the Media Library and asset upload API routes, allowing editors to upload and manage images.

assetsPath: 'src/assets/uploads';

componentPaths

• Type: string[]
• Default: undefined

Paths to scan for hydratable Puck components. Components using withHydration() in these directories are auto-discovered for client-side hydration in production builds.

componentPaths: ['src/components/puck'];

UI Options

These options control the CMS admin interface behavior.

siteBaseUrl

• Type: string
• Default: ''

Base URL for the site. Used when the site is served under a subpath (e.g., /docs) or a different domain.

siteBaseUrl: '/docs';

enableDevtools

• Type: boolean
• Default: true

Enable React Query devtools in the CMS admin UI. The Astro integration enables devtools by default; set to false to disable.

enableDevtools: true;

queryClientOptions

• Type: QueryClientConfig (from @tanstack/react-query)
• Default: { defaultOptions: { queries: { staleTime: 300000, retry: 1 } } }

Override React Query client configuration for the CMS admin UI. Useful for tuning cache behavior during development.

queryClientOptions: {
  defaultOptions: {
    queries: {
      staleTime: 0,
      refetchOnWindowFocus: true,
      retry: 0,
    },
  },
}

siteStyles

• Type: string | string[]
• Default: undefined

CSS files to load in the CMS editor for component preview styling. When your Puck components use site-specific CSS (custom properties, utility classes, etc.), add those stylesheets here so the editor preview matches production.

siteStyles: ['./src/styles/global.css'];

Accepts a single path or an array. Paths are resolved relative to the project root.

Authentication

ConlocaCMSOptions does not currently expose an auth option on this branch.

Today, CMS request protection is limited to Cloudflare Access validation driven by environment variables. When both variables below are set, the CMS handler validates the incoming Cloudflare Access JWT before serving /__cms or /__cms/api requests:

Variable	Type	Required	Description
CF_ACCESS_TEAM_NAME	string	Yes	Zero Trust team name, used to resolve https://<team>.cloudflareaccess.com
CF_ACCESS_AUD	string	Yes	Access application audience (aud)

When either variable is missing, validation is skipped so local development keeps working without Cloudflare Access.

Note

Dev Branch Preview — Provider factories such as oauth(), apiKey(), role mapping, and conlocaCMS({ auth: ... }) are implemented on the dev branch, but they are not available on this branch yet.

See the Cloudflare Access guide for the current production setup.

Dev Branch Preview: auth

If you are following the dev branch specifically, the preview config shape is:

auth: {
  provider: oauth({
    github: {
      clientId: process.env.GITHUB_CLIENT_ID,
      clientSecret: process.env.GITHUB_CLIENT_SECRET,
    },
    sessionSecret: process.env.SESSION_SECRET,
  }),
  roles: {
    admin: ['admin@company.com'],
    editor: ['*@company.com'],
  },
}

That preview API should be treated as branch-specific until it lands outside dev.

Complete Example

This example from the website-with-cms canonical example shows a full development configuration:

// astro.config.mjs
import { defineConfig } from 'astro/config';
import node from '@astrojs/node';
import { conlocaCMS } from '@conloca/astro-cms/node';
import react from '@astrojs/react';

export default defineConfig({
  output: 'server',
  adapter: node({ mode: 'standalone' }),
  integrations: [
    react(),
    conlocaCMS({
      contentRoot: './content',
      canvasDir: './canvas',
      puckConfigPath: './src/puck.config.tsx',
      schemasPath: './src/schemas/data.ts',
      assetsPath: './public/assets',
      routing: true,
    }),
  ],
});

Tip

For production deployments, configure Cloudflare Access or a reverse proxy for authentication, and set enableDevtools: false. See the deployment guides for environment-specific recommendations.