Areca Docs

SDK overview

The Areca site SDK connects a Node.js website to your CMS site, so you can push its schema, pull published content and render it.

The site SDK, @areca-cms/site-sdk, is the package your website uses to talk to Areca. It runs in the website project, not in the CMS. Use it when you build a Node.js website, such as a TanStack Start, Vite or Astro project, that shows content from an Areca site.

The SDK covers the developer side of the content workflow:

  • Schema push. It sends the content model you define in areca.config.ts to the CMS, so editors see the same collections and fields in the CMS.
  • Build-time pull. It downloads the latest published snapshot into local JSON files while your site builds, and checks it against the schema.
  • Typed content. It generates areca.gen.ts from the schema, so every collection, field, value, reference and route is typed in your code.
  • Reading content. A typed content object queries the local files from your server code: all, first, get, where, orderBy, references and links.
  • Rich text. It turns a rich text value into a Markdown document, Markdown source or static HTML.
  • SEO. It turns each entry's SEO data into page title, meta tags, links and JSON-LD.
  • Preview. It fetches a draft entry with a signed token, so editors can see unpublished changes on your site.

How it fits into going live

The SDK sits between the CMS and your website build. A typical cycle looks like this:

Define and push the schema. You describe your collections in areca.config.ts and run areca manifest push. You do this when the content model changes, not on every content edit.

Write and publish content. Editors write entries in the CMS and approve them. When they go live, Areca creates an immutable snapshot of the published content.

Pull during the build. Your build runs areca pull, which downloads the snapshot into local files. It also copies the images and files the content uses into your public folder. Your site reads those files, so visitor requests never call the CMS.

Deploy and check. The build is deployed, and the site reports the publication it was built from. See Go-live builds for the health check.

Read How Areca works for the full model, and going live for what editors see.

Package and entry points

Install the package once. It exposes one command-line tool, areca, and four import paths:

ImportWhat it provides
@areca-cms/site-sdkdefineSiteContent, manifestFromConfig, createArecaClient, getPreviewEntry, previewHeaders, the SEO and rich text helpers, and the TypeScript types
@areca-cms/site-sdk/pullpullContent, readContent and readContentManifest
@areca-cms/site-sdk/contentcreateContent, which builds the typed content object (Node only)
@areca-cms/site-sdk/seoseoHead, seoHeadHtml and seoJsonLd
@areca-cms/site-sdk/rich-textrichTextDocument, richTextMarkdown and richTextHtml

The root entry does not re-export pullContent, readContent or createContent. Import them from their subpaths. Most sites read content through the content object in areca.gen.ts, which needs none of them.

Requirements

  • Node.js 22.6 or newer. On Node.js 24 LTS, the CLI can load areca.config.ts directly, so Node 24 is recommended. On older versions, see the CLI reference for running the config through tsx.
  • ESM only. Use import syntax. The package has no CommonJS build.
  • No React dependency. The SDK works with any Node.js framework. To render rich text with React, install @tanstack/markdown yourself, at the version the SDK pins. See rich text.

Where to start

New to the SDK? The step-by-step guides build a website from an empty folder.

Installation and setup

Install the package, run areca init, and set the environment variables.

Defining your content

Write areca.config.ts with collections, fields and identifiers.

Syncing the schema

Push your content model to the CMS and pull it back.

Pulling content at build time

Download the published snapshot before your site builds.

Typed content

How areca.gen.ts types every collection, field and route.

Reading content

Query entries with the typed content object.

Example site

Run the demo site that ships with the repository.

Reference

Field types

Every field type, its options and the values it produces.

CLI reference

Every areca command and flag.

Client

createArecaClient and its methods.

HTTP API

The endpoints the SDK calls, and their responses.

Errors and limits

Common errors, and the size and rate limits.

Installation and setup

Install the site SDK, run areca init, and set the environment variables that connect your website to its Areca site.

On this page

How it fits into going livePackage and entry pointsRequirementsWhere to startReferenceRelated