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 dev starts a local HTTP server that hosts the Alinea content editing dashboard. While running, it watches your cms.ts configuration file for schema changes, recompiles on the fly, and pushes live-reload signals to the browser. It also exposes the CMS backend API so the dashboard can read and write content files directly to your local repository. This is the command you run during day-to-day development whenever you want to edit content or iterate on your schema.

​
Usage

Start the dashboard
npx alinea dev [options] [-- <command>]
The optional -- <command> separator lets you forward process spawning to another command — most commonly your framework’s dev server — so that a single terminal session runs both simultaneously.

​
Options

​
-c, --config
string
Path to the Alinea config file. Defaults to auto-detection: Alinea searches for cms.ts (or cms.js) starting from the project root. Use this flag when your config file lives in a non-standard location.
​
-d, --dir
string
Root directory of the project. Defaults to process.cwd(). All relative paths in the config are resolved from this directory. Useful in monorepos where the Alinea project is not at the repository root.
​
-p, --port
number
Port for the local CMS dashboard server. Defaults to 4500. If the preferred port is unavailable, Alinea will automatically try the next available port.
​
-b, --base
string
Base URL used for live preview links inside the dashboard. Set this to your local framework dev server URL (e.g. http://localhost:3000) if your framework runs on a different origin than the dashboard.
​
--production
boolean
Run the development dashboard against the production backend (sets NODE_ENV=production). Useful for debugging production-specific content behavior locally without deploying.
​
--dev
boolean
Watch Alinea’s own source files in addition to your project files. This flag is intended for Alinea contributors developing on the CMS itself and is not needed in normal projects.

​
Forwarding to a Framework Dev Server

The -- separator passes everything after it to a child process that is spawned once after the initial schema generation completes. The child process inherits the current environment plus the ALINEA_DEV_SERVER variable (set to the dashboard URL), and its exit code propagates to the parent process.
Run Alinea and Next.js together
npx alinea dev -- next dev
Run Alinea and Vite together
npx alinea dev -- vite
The ALINEA_DEV_SERVER environment variable is automatically injected into the forwarded process, making it available to your framework if you need to reference the dashboard origin.

​
Typical package.json Setup

If you ran alinea init, your package.json dev script was already patched. It should look something like this:
package.json
{
  "scripts": {
    "dev": "alinea dev -- next dev",
    "build": "alinea build -- next build"
  }
}
Run it with:
Start dev via npm
npm run dev

​
Dashboard URL

Once started, the dashboard is available at: 
http://localhost:4500
The URL is printed to the terminal on startup alongside the Alinea version and config file location. If port 4500 is already in use, the next free port is selected automatically and printed to the console.
Next.js uses port 3000 by default. The Alinea dashboard runs on port 4500 by default, so the two servers do not conflict when both are started together. If you explicitly pass --port 3000 to alinea dev, you will need to also change the port used by your framework dev server.

Build docs developers (and LLMs) love

Get started for freeTalk to us