Getting Started

Package: @localess/astro

@localess/astro is the official Astro integration for the Localess headless CMS. It's a full Astro Integration (registered in astro.config.mjs) that provides dynamic component rendering by content schema, rich text rendering, asset resolution, and Visual Editor synchronization — for both static (output: 'static') and server-rendered (output: 'server') Astro projects.

Security: The integration builds the LocalessClient server-side only, via Astro's page-ssr script stage — your token never reaches the browser bundle, regardless of Astro's output mode.

Requirements

• Node.js >= 24.0.0
• Astro 6 or 7

Installation

# npm
npm install @localess/astro@latest

# yarn
yarn add @localess/astro@latest

# pnpm
pnpm add @localess/astro@latest

Configuration

Register the localess() integration in astro.config.mjs:

// astro.config.mjs
import { defineConfig } from 'astro/config';
import { localess } from '@localess/astro';

export default defineConfig({
  integrations: [
    localess({
      origin: process.env.LOCALESS_ORIGIN,
      spaceId: process.env.LOCALESS_SPACE_ID,
      token: process.env.LOCALESS_TOKEN,
      enableSync: true,
    }),
  ],
});

The integration also accepts the client's timeoutMs, retry and fetchInit options, as described for @localess/client. fetch and cache are not accepted, because the options are serialized into a generated module.

enableSync and livePreview are mutually exclusive tiers — see Visual Editor sync.

Component registry

Components auto-register from <componentsDir>/**/*.astro (default componentsDir: 'src'). Merge in an explicit map via the components option:

// astro.config.mjs
localess({
  // ...
  componentsDir: 'src/shared/components/localess',
  components: { 'hero-section': HeroSection },
});

Registry keys — filenames and components map keys alike — are matched against data._schema exactly by default: HeroSection.astro registers as HeroSection and matches _schema: 'HeroSection', which is how the playgrounds work (Page.astro for the Page schema). When your files and schemas are named differently, set componentNaming:

The strategy applies to both sides — registry keys and _schema — so with anything but exact, matching is case- and separator-insensitive. Only these built-in names are accepted, not a custom function: the options are serialized into a generated module, which a function can't survive.

Writing components

A registered component receives data, links, references, and assets as props. Type Props as LocalessSchemaProps<T> (the same helper every Localess SDK exports) instead of writing your own interface — it types data against your generated content type and gives you correctly-typed optional links/references/assets for free, so passing them through to nested components stays type-safe. Spread localessEditable(data) on the component's root element and localessEditableField('fieldName') on individual editable fields, so the Visual Editor can highlight and select them:

---
// src/shared/components/localess/Page.astro
import { localessEditable, localessEditableField } from '@localess/astro';
import type { LocalessSchemaProps } from '@localess/astro';
import type { Page } from '../../models/localess';

export type Props = LocalessSchemaProps<Page>;

const { data } = Astro.props;
---

<main {...localessEditable(data)} class="flex flex-col gap-4">
  <h1 {...localessEditableField('title')} class="text-center">
    {data.title}
  </h1>
  <p {...localessEditableField('description')} class="text-center whitespace-pre-line">
    {data.description}
  </p>
</main>

LocalessComponent passes localessEditable(data)'s attributes down as props alongside data/links/references/assets, but an Astro component only renders props it explicitly places on an element — so each component must call localessEditable(data) itself on its own root tag, as shown above, rather than relying on it being applied automatically.

Fallback component

// astro.config.mjs
localess({
  // ...
  enableFallbackComponent: true,
  customFallbackComponent: 'localess/CustomFallback', // optional; omit to use the built-in FallbackComponent.astro
});

Without enableFallbackComponent, LocalessComponent throws when a _schema key has no registry match — useful during development to catch a missing component immediately, but you'll usually want the fallback enabled once you deploy.

Playground: playgrounds/astro (server output with livePreview) and playgrounds/astro-static (output: 'static') are the reference implementations for this guide.

AI Coding Agents

This package ships a SKILL.md file that provides AI coding agents (GitHub Copilot, Claude Code, Cursor, and others) with accurate, up-to-date APIs, patterns, and best practices.

Reference it from your project's AGENTS.md:

## Localess

@node_modules/@localess/astro/SKILL.md

License

MIT