Syncing the schema

Schema sync keeps the CMS in step with areca.config.ts. A push sends your config to the CMS. A pull writes the CMS's current collections back into a config file. You run a push whenever you change the content model, and you run a pull when the model was changed in the CMS and you want it in code.

Schema sync does not change content. Entries stay as they are, and the push does not build pages or migrate values.

Push the schemaCopy Anchor Link

pnpm exec areca manifest push
pnpm exec areca manifest push ./config/areca.config.ts

With no path, the command reads ./areca.config.ts. It loads the file, checks the identifiers, and sends the collections to the CMS. On success it prints Synced manifest from followed by the path. The config file must have a default export, which defineSiteContent gives you.

The older areca sync-manifest command still works as an alias for areca manifest push. It is deprecated, so use manifest push in new scripts. Your package scripts may still call sync-manifest, which areca init sets up.

Which tokens a push needsCopy Anchor Link

Get the schema-write token from the Developer tab, under the Schema-write token section. The site token is the read token that builds use. The two tokens are not interchangeable. A push with only the site token fails.

What a push changesCopy Anchor Link

A push replaces the schema on the CMS side for the collections in your file:

• Listed collections are updated. The label, route and fields are replaced with the values in your config. If you omit label, the CMS shows the collection key. Changes made to these collections in the CMS are overwritten by the push.
• Omitted collections are disabled. A collection that is not in your file is turned off. Its entries stay in the CMS, but they are left out of new snapshots, so they stop going live. Pushing an empty collections object disables every collection.
• A disabled collection can come back. Add its key to the config and push again. It is enabled again, with its entries.
• Entry values are not migrated. Values stay as they are. A new field starts empty, and values under a removed field are no longer published.

The same rules apply to the globals object of site content sections. Listed sections are updated, and a section left out of the file is disabled: editors cannot see it, it is left out of new releases, and its values are kept. Adding it back enables it again. Pushing a config with no globals key disables every section. See site content.

What happens to existing contentCopy Anchor Link

Changing a field can make existing entries invalid. Areca checks the published entries again each time you go live:

• Draft entries are saved with partial validation, so editors can save a draft that is missing a new required field.
• Entries that are ready or live are checked against the current schema when a snapshot is built. If a published entry no longer passes, for example because you made a field required and it is empty, Go live stops and reports the problem.

Before you remove a collection or make a field required, check which entries use it. Fill in or update those entries first, then push. Test the change on a non-production site when you can. For a reference field, also check that the entries it points to are still included in the snapshot.

The schema in a publicationCopy Anchor Link

Each time content goes live, Areca embeds the schema of the collections in that publication. The pull uses this embedded schema to check the entries and to generate areca.gen.ts, so the types always match the content they describe. See typed content.

This has a consequence for schema changes. A push changes the schema the CMS holds, but your types change only when a publication made after the push is pulled. After you push a change, go live, then pull.

Publications made before schemas were embedded have no schema. The pull then uses the schema the CMS holds now, and it prints a warning that asks you to go live again. Until you do, the types match the current schema, and a publication made from an older schema can fail the pull.

Collection keys resolve, href, preview and globals are reserved, because the content object in your code uses these names. A push that lists one of them fails with Collection key "<key>" is reserved, and nothing is sent. Rename the collection in areca.config.ts. Field keys may use these names.

Pull the schemaCopy Anchor Link

pnpm exec areca manifest pull --config ./areca.config.ts
pnpm exec areca manifest pull --config ./areca.config.ts --yes

The pull fetches the site's enabled collections from the CMS and writes a complete areca.config.ts. It uses the existing siteKey, or ARECA_SITE_KEY if the file does not exist.

The command shows the difference first:

• + for a collection, field or language the CMS has and your file does not
• ~ for a collection that differs on both sides
• - for a collection, section, field or language your file has and the CMS does not

It asks you to confirm only when something would be removed. Additions and changes are written without a question. If the file already matches the CMS, nothing is written. Without a terminal, a removal stops the command until you pass --yes.

A file the pull did not write (hand-written, or from areca init with collections) still asks before a populated file is replaced, even when nothing changed. Use --yes to accept everything. The pull only reads from the CMS, so it needs only the site token.

Use schema sync in CICopy Anchor Link

Keep the schema push out of routine website builds. A push is a change to the content model, so it should be a deliberate step. A common setup is a manual workflow that runs in a protected environment:

name: Publish content schema
on:
  workflow_dispatch:

jobs:
  manifest:
    runs-on: ubuntu-latest
    environment: areca-authoring
    steps:
      - uses: actions/checkout@v4
      - uses: pnpm/action-setup@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 24
      - run: pnpm install --frozen-lockfile
      - run: pnpm exec areca manifest push
        env:
          ARECA_CMS_URL: ${{ vars.ARECA_CMS_URL }}
          ARECA_SITE_TOKEN: ${{ secrets.ARECA_SITE_TOKEN }}
          ARECA_SCHEMA_TOKEN: ${{ secrets.ARECA_SCHEMA_TOKEN }}

Store the schema token as a secret in the protected environment only. Node 24 lets the CLI load areca.config.ts directly. On older Node versions, see the CLI reference.

ErrorsCopy Anchor Link

See errors and limits for the full list.

RelatedCopy Anchor Link

• Defining your content: the config file format.
• Pulling content at build time: download the published content.
• CLI reference: every command and flag.