Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/alineacms/alinea/llms.txt

Use this file to discover all available pages before exploring further.

A root is the top-level container inside a workspace’s content tree. Every entry in Alinea lives under exactly one root, and every root is identified by the key you give it in the roots map of a workspace. Roots control which entry types are allowed as direct children, the sort order displayed in the sidebar, internationalisation locales, and whether the root acts as the workspace’s media library.

​
Creating a standard root

Use Config.root(label, options) to create a content root. The label is shown in the dashboard sidebar and the options object accepts a RootMeta descriptor.
cms.ts
import {Config, Field} from 'alinea'
import {createCMS} from 'alinea/next'

const Page = Config.document('Page', {fields: {}})
const Folder = Config.document('Folder', {
  contains: ['Folder', Page],
  fields: {}
})

export const cms = createCMS({
  schema: Config.schema({types: {Page, Folder}}),
  workspaces: {
    main: Config.workspace('Main', {
      source: 'content/main',
      mediaDir: 'public',
      roots: {
        pages: Config.root('Pages', {
          contains: [Page, Folder]
        }),
        media: Config.media()
      }
    })
  }
})

​
Seeding children at creation time

Roots accept an optional children map. Any Page object listed there is seeded into the content tree automatically when Alinea initialises a fresh project. Use Config.page() to create seeded pages (see Types & Fields).
Seeded page inside a root
import {Config, Field} from 'alinea'

const Page = Config.document('Page', {fields: {}})

const pagesRoot = Config.root('Pages', {
  contains: [Page],
  children: {
    home: Config.page({
      type: Page,
      fields: {title: 'Home'}
    })
  }
})

​
Internationalisation (i18n) roots

Set the i18n option to enable locale-aware routing. Alinea will create a sub-tree per locale, and every entry inside the root carries a locale field automatically.
i18n root
const localisedPages = Config.root('Languages', {
  contains: [Page, Folder],
  i18n: {
    locales: ['en', 'fr', 'nl-BE', 'nl-NL']
  }
})
The RootI18n shape only requires one field: 
interface RootI18n {
  locales: ReadonlyArray<string>
}
The first locale in the array is treated as the default locale when rendering preview URLs.

​
Media root

Every workspace should contain exactly one media root. Use Config.media() — a convenience function that pre-configures isMediaRoot: true, the media explorer view, and the correct contains list.
Media root
roots: {
  pages: Config.root('Pages', {contains: [Page]}),
  media: Config.media()   // ← always include this
}
A workspace must have exactly one media root. Alinea will throw an error at runtime when attempting to resolve an upload destination if no media root is present. Config.media() is the recommended way to add one.

​
RootMeta properties

​
contains
Array<string | Type>
The entry types that can be created as direct children of this root. Each item is either a Type reference (the actual object) or a string key matching a name in the schema. If omitted, the root accepts no children and acts as a placeholder.
​
orderChildrenBy
OrderBy | Array<OrderBy>
Controls the default sort order of child entries in the dashboard sidebar. Accepts a single OrderBy expression or an array for multi-key sorting.
​
icon
ComponentType
A React component rendered as the root’s icon in the dashboard sidebar. Any component that renders an <svg> works. Alinea ships icon components under alinea/ui/icons.
​
i18n
RootI18n
Enables internationalised content. Provide a locales array of BCP 47 locale strings. When set, Alinea creates a locale-specific sub-tree for every locale and adds a locale field to each entry.
​
view
View
A path to a React component (e.g. './src/CustomRootView.tsx#CustomRootView') used to render the root’s landing page inside the dashboard. Defaults to the standard content-tree view.
​
isMediaRoot
boolean
default:"false"
Marks this root as the workspace’s media library. Set automatically when using Config.media(). Only one root per workspace should have this flag.
​
preview
Preview
A root-level preview configuration that overrides the workspace-level preview setting for all entries inside this root.
You can reference types in contains by their schema key string (e.g. 'Page') instead of the actual object. This is useful when a root in one workspace needs to reference a type name from a schema defined elsewhere, or when you want to avoid circular import issues.

Build docs developers (and LLMs) love

Get started for freeTalk to us