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.

alinea init bootstraps a new Alinea project in your current working directory. It writes a starter cms.ts configuration file, creates the initial content directory structure, and patches your package.json scripts so that dev and build automatically invoke the Alinea CLI alongside your existing tooling.

​
Usage

Initialize a project
npx alinea init
Run this command once from your project root. If an Alinea config file already exists, the command exits with a fatal error rather than overwriting your existing setup.

​
What Gets Created

When you run alinea init, the following actions take place: 1. Content directories Two directories are created if they don’t already exist:
  • content/pages/ — stores your page content as JSON files
  • content/media/ — stores media asset metadata
A seed file content/pages/welcome.json is written with a starter Page entry so the dashboard has something to display on first launch. 2. cms.ts configuration file The config file is written to the project root, or to src/cms.ts if a src/ directory is detected. When Alinea detects a Next.js project (via a next dependency in package.json), it imports from alinea/next instead of alinea/core. The generated file looks like this:
cms.ts
import {Config, Field} from 'alinea'
import {createCMS} from 'alinea/core'

// Create types for your CMS schema
const Page = Config.type('Page', {
  fields: {
    title: Field.text('Title'),
    path: Field.path('Path')
  }
})

export const cms = createCMS({
  // List out available types in your schema
  schema: {
    Page
  },

  // Define the content structure of your CMS
  workspaces: {
    main: Config.workspace('Example', {
      source: 'content',
      mediaDir: 'public',
      roots: {
        pages: Config.root('Example site', {
          contains: ['Page']
        }),
        media: Config.media()
      }
    })
  },

  baseUrl: {
    // Point to your local website
    development: 'http://localhost:3000',
    // The production URL of your website
    production: 'https://example.com'
  },

  // Enable live previews after adding <cms.previews widget /> to your layout
  // preview: true,

  // The handler route URL
  handlerUrl: '/api/cms',

  // The admin dashboard will be bundled in this static file
  dashboardFile: 'admin.html'
})
3. Next.js API route handler (Next.js projects only) If Next.js is detected, a route handler is written to src/app/(alinea)/api/cms/route.ts (or app/(alinea)/api/cms/route.ts without a src/ dir):
app/(alinea)/api/cms/route.ts
import {createHandler} from 'alinea/next'
import {cms} from '@/cms'

// This handler will respond to API requests from the dashboard
const handler = createHandler({cms})

export const GET = handler
export const POST = handler
4. package.json script patching Alinea prepends its CLI commands to your existing dev and build scripts:
  • "dev" becomes "alinea dev -- <previous command>"
  • "build" becomes "alinea build -- <previous command>"
This ensures the Alinea dashboard and content generation run automatically alongside your framework’s commands.

​
Package Manager Detection

alinea init detects your package manager by looking for lockfiles in the following order: bun.lockb, pnpm-lock.yaml, yarn.lock, package-lock.json. The detected runner (npx, pnpm, yarn, or bun) is used in the success message printed after initialization.

​
Next Steps

After running alinea init:
  1. Start the dashboard — run npx alinea dev (or your patched dev script) to open the local CMS at http://localhost:4500.
  2. Customize cms.ts — add your own content types, fields, and workspaces.
  3. Configure baseUrl — update the production URL in cms.ts to match your deployed site.
alinea init only needs to be run once per project. After the initial setup, modify cms.ts directly to evolve your schema. Running alinea init a second time in the same directory will exit with an error because Alinea detects the existing config file.

Build docs developers (and LLMs) love

Get started for freeTalk to us