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 is distributed as a single alinea npm package. It ships as pure ESM and is designed to integrate directly into an existing Next.js project — no separate server process, no external database to provision. This page covers everything you need to get the package installed and correctly wired into your toolchain.
Alinea requires a Node.js runtime. The cms instance (schema loading, content database, dashboard handler) does not run in the Edge runtime. You must deploy the API route handler (createHandler) to a Node.js environment. Content can be fetched and rendered on the edge once bundled, but the CMS itself must remain on Node.js.

​
Installation

Install alinea with your preferred package manager: 
npm install alinea

​
Peer dependencies

Alinea requires react and react-dom as peer dependencies. These are already included in every Next.js project, so no additional installation is needed. The minimum supported version of each is 18.0.0.
package.json (peer requirements)
{
  "peerDependencies": {
    "react": "*",
    "react-dom": "*"
  }
}

​
ESM requirement

Alinea is ESM-only. Your project’s package.json must include "type": "module" to ensure Node.js treats all .js files as ES modules. Without this, the CJS fallback shim will throw an error at startup.
package.json
{
  "type": "module"
}
Next.js fully supports ESM projects. If you are migrating an existing project, renaming config files from .js to .mjs (or adding "type": "module") is usually the only change required outside of Alinea itself.

​
Package exports

The alinea package exposes three main entry points:

​
alinea — core package

The primary entry point. Exports the Config, Field, Query, and Edit namespaces, plus all TypeScript types. 
import {Config, Field, Query, Edit} from 'alinea'
ExportPurpose
ConfigCreate workspaces, roots, document/page/snippet types, schemas, and roles
FieldAll field constructors: text, richText, select, image, date, number, list, object, and more
QueryGraph traversal helpers: children, parents, siblings, parent, next, previous, translations
EditMutation helpers for programmatic content updates

​
alinea/next — Next.js adapter

Next.js-specific exports. Use these in cms.ts and API route handlers. 
import {createCMS, createHandler, withAlinea} from 'alinea/next'
ExportPurpose
createCMS(config)Creates a NextCMS instance with find, first, get, count, draft-mode support, and preview integration
createHandler(cms)Returns a Request → Response function for use as a Next.js App Router route handler
withAlinea(nextConfig)Wraps your Next.js config to add dashboard routing, image domains, and server-external packages

​
alinea/css — dashboard styles

Optional global CSS for the Alinea dashboard. Import it once in your root layout if you are embedding the dashboard inside your Next.js app. 
import 'alinea/css'

​
Configuring Next.js

Wrap your Next.js config with withAlinea to enable the dashboard route rewriting and set up the @alinea/generated package as a server-external dependency:
next.config.ts
import {withAlinea} from 'alinea/next'
import type {NextConfig} from 'next'

const nextConfig: NextConfig = {
  // your existing Next.js options
}

export default withAlinea(nextConfig)
withAlinea performs the following automatically:
  • Reads @alinea/generated/settings.json (created by npx alinea build) to discover the configured adminPath (default: /admin).
  • Adds rewrite rules to proxy dashboard requests to the Alinea dev server during development.
  • Adds @alinea/generated to serverExternalPackages (Next.js 15+) or serverComponentsExternalPackages (Next.js 14) so the content database is not bundled twice.
  • Appends uploads.alinea.cloud to the images.remotePatterns list for projects using Alinea Cloud media.

​
TypeScript configuration

Alinea relies on modern TypeScript module resolution to resolve its exports map correctly. Set moduleResolution in your tsconfig.json to one of the following values:
tsconfig.json
{
  "compilerOptions": {
    "moduleResolution": "bundler"
  }
}
"bundler" is the recommended option for Next.js projects (it is the default generated by create-next-app). "node16" and "nodenext" also work. The legacy "node" resolver does not support the exports field and will fail to resolve alinea/next and other sub-path imports.
TypeScript is not strictly required to run Alinea, but without it you lose the end-to-end type inference that makes cms.find() and cms.get() return typed results. Using plain JavaScript is possible but not recommended.

​
Verifying the installation

After installing, run the init command to scaffold a starter config: 
npx alinea init
Then start the development server and dashboard together: 
npx alinea dev
If everything is configured correctly, Alinea will print the dashboard URL to the console and you can open it at http://localhost:3000/admin.

Build docs developers (and LLMs) love

Get started for freeTalk to us