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 Cloud is the managed backend that handles OAuth2 authentication, draft storage, and content publishing on your behalf. Instead of standing up your own database and wiring up a GitHub integration, you point your project at Alinea Cloud and let it manage the editing infrastructure. Your content still lives in your git repository — Cloud only manages the editing layer on top of it.

​
How Cloud works

When a createHandler call does not receive a backend or remote option, it automatically instantiates CloudRemote as the backend. CloudRemote implements the full RemoteConnection interface: it authenticates editors via OAuth2, stores drafts, reads and writes content trees, and commits published changes back to your repository through the Alinea Cloud API.
Even when using Alinea Cloud, your content files are stored in and served from your own git repository. Alinea Cloud never becomes the source of truth for published content — it only manages draft state and the editing session.

​
Minimal setup

With Alinea Cloud, your handler route contains no backend configuration at all:
app/api/cms/route.ts
import {cms} from '@/cms'
import {createHandler} from 'alinea/next'

const handler = createHandler({cms})

export const GET = handler
export const POST = handler
createHandler detects the absence of a backend option and falls back to CloudRemote automatically. You can also pass the NextCMS instance directly as shorthand:
app/api/cms/route.ts
import {cms} from '@/cms'
import {createHandler} from 'alinea/next'

const handler = createHandler(cms)

export const GET = handler
export const POST = handler

​
API key

Alinea Cloud identifies your project by the ALINEA_API_KEY environment variable. Set it in your deployment environment (Vercel dashboard, .env.local for local development, CI secrets, etc.):
.env.local
ALINEA_API_KEY=alineapk_your_key_here
Visit alineacms.com to create an account and obtain an API key for your project. The key is scoped to a single project and must be kept secret — treat it like a database password.

​
Authentication with CloudAuthView

Alinea provides a ready-made authentication view for Cloud projects. By default, createConfig (called internally by createCMS) sets auth to CloudAuthView automatically. You do not need to configure it manually unless you are overriding the default:
src/cms.ts
import {Config} from 'alinea'
import {CloudAuthView} from 'alinea/cloud/view/CloudAuth'
import {createCMS} from 'alinea/next'
import * as schema from './schema'

export const cms = createCMS({
  schema,
  handlerUrl: '/api/cms',
  baseUrl: {
    development: 'http://localhost:3000',
    production: 'https://example.com'
  },
  // CloudAuthView is set automatically by createConfig,
  // but you can reference it explicitly if needed:
  auth: CloudAuthView,
  workspaces: {
    main: Config.workspace('Main', {
      source: 'content',
      mediaDir: 'public',
      roots: {
        pages: Config.root('Pages', {contains: [schema.Page]}),
        media: Config.media()
      }
    })
  }
})
CloudAuthView renders the Cloud OAuth2 login screen inside the dashboard. When a user signs in, the handler exchanges tokens with cloudConfig.auth and stores the session in secure HTTP-only cookies prefixed with alinea..

​
Cloud API key validation

CloudRemote validates that ALINEA_API_KEY starts with alineapk before making draft API calls. If the key is missing or malformed, draft reads will return undefined silently. A missing key is reported in the authentication status response so the dashboard can display a setup prompt.

​
Connection to Cloud endpoints

CloudRemote communicates with the following Cloud services:
OperationEndpoint
OAuth2 / authcloudConfig.auth
JWKS verificationcloudConfig.jwks
Token exchangecloudConfig.token
Token revocation (logout)cloudConfig.revocation
Content tree synccloudConfig.tree
Blob fetchcloudConfig.blobs
Publish (write)cloudConfig.write
Draft storagecloudConfig.drafts
File uploadscloudConfig.upload
Revision historycloudConfig.history
You do not configure these URLs directly — they are managed by the cloudConfig module inside alinea/cloud.

​
Environment variables

VariableDescription
ALINEA_API_KEYYour Alinea Cloud project key. Must start with alineapk. Required in production.
In development, when NODE_ENV is "development", Alinea falls back to the string "dev" as the API key. Because "dev" does not start with "alineapk", draft reads that require a valid Cloud key are skipped silently. Set ALINEA_API_KEY in development if you want to connect to your real Cloud project while developing locally.

Build docs developers (and LLMs) love

Get started for freeTalk to us