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 build compiles your cms.ts schema, indexes all content files, and writes the output to the @alinea/generated module inside node_modules. This generated module is what your application imports at build time to get fully-typed content queries and the pre-indexed content cache. Run alinea build as the first step of your CI/CD pipeline, before next build or any other framework build command.

​
Usage

Generate types and content cache
npx alinea build [options] [-- <command>]
Like alinea dev, the -- <command> separator lets you chain a downstream build command that runs after generation completes.

​
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.
​
-w, --watch
boolean
Watch schema and content source files for changes and regenerate automatically. This flag only takes effect when combined with --fix; without --fix, the build process runs through the internal server pipeline which controls watching independently.
​
--fix
boolean
Scan all content files and overwrite any missing or incorrect properties with their default values. For example, if a content entry is missing a required path field, --fix will compute and write the correct default. Use this after schema migrations that introduce new required fields.

​
The --fix Flag in Detail

When you add a new required field to an existing content type, existing content files will be missing that field. Running alinea build --fix iterates over every content file, detects missing or invalid properties, and writes the corrected defaults back to disk before generating the output module.
Fix content files then exit
npx alinea build --fix
When --fix is provided, the CLI runs the generator directly (bypassing the local server) and exits with code 0 after the fix pass completes. This makes it safe to run as a one-off migration step without leaving any background processes running.

​
CI Usage

In a typical CI pipeline, run alinea build before your framework’s build command. The -- separator is the cleanest way to chain them:
Build for production (CI)
npx alinea build && next build
Or use the forwarding syntax to let Alinea manage the process lifecycle:
Forward to next build
npx alinea build -- next build
In both forms, NODE_ENV is set to production automatically — you do not need to set it manually.

​
package.json example

If you ran alinea init, your build script was already patched:
package.json
{
  "scripts": {
    "dev": "alinea dev -- next dev",
    "build": "alinea build -- next build"
  }
}

​
What Gets Generated

alinea build writes its output to node_modules/@alinea/generated/. The key output files are:
  • source.js — a serialized snapshot of all indexed content, used by the query engine at runtime.
  • settings.json — dashboard configuration derived from your cms.ts (e.g. the admin path).
  • Dashboard bundle — if dashboardFile is set in your config, the admin HTML file is bundled into your public directory.
Skipping alinea build before next build (or any framework build) will result in stale or missing content. The @alinea/generated module will reflect the last time you ran the command — if it has never been run, the build will fail entirely. Always run alinea build as the first step in your CI pipeline.
alinea build can also be invoked as alinea generate — both names run the exact same command. The generate alias exists for backwards compatibility with earlier Alinea versions. Either form works in scripts and CI configurations.

Build docs developers (and LLMs) love

Get started for freeTalk to us