Skip to content
ACMS ACMS Docs

Astro

ACMS integrates naturally with Astro. Since Astro components render at build time by default, ACMS fields are resolved during the build and baked into the output HTML.

Installation

Section titled “Installation”
Terminal window
npm install @useacms/client @useacms/cli

Basic Usage

Section titled “Basic Usage”

Use acms directly in Astro component frontmatter and templates:

src/pages/index.astro
---
import { acms } from '@useacms/client';
---


<html>
  <body>
    <h1>{acms.hero.title}</h1>
    <p>{acms.hero.subtitle}</p>
    <a href={acms.hero.ctaLink}>{acms.hero.ctaText}</a>
  </body>
</html>

Fields are automatically registered when Astro renders the page during development.

In Astro Components

Section titled “In Astro Components”
src/components/Header.astro
---
import { acms } from '@useacms/client';
---


<header>
  <nav>
    <a href="/">{acms.site.name}</a>
  </nav>
</header>

In Layouts

Section titled “In Layouts”
src/layouts/Base.astro
---
import { acms } from '@useacms/client';


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


<html>
  <head>
    <title>{title} | {acms.site.name}</title>
  </head>
  <body>
    <header>
      <nav>{acms.site.name}</nav>
    </header>
    <main>
      <slot />
    </main>
    <footer>
      <p>{acms.footer.copyright}</p>
    </footer>
  </body>
</html>

With Framework Components

Section titled “With Framework Components”

Astro supports embedding React, Vue, Svelte, and other framework components. ACMS works in all of them:

src/pages/index.astro
---
import ReactHero from '../components/Hero.jsx';
import VueFeatures from '../components/Features.vue';
---


<ReactHero client:load />
<VueFeatures client:visible />
src/components/Hero.jsx
import { acms } from '@useacms/client';


export default function Hero() {
  return <h1>{acms.hero.title}</h1>;
}

Configuration

Section titled “Configuration”

Create acms.config.ts in your project root:

import { defineConfig } from '@useacms/client';
import { localFile, vercelEdgeConfig } from '@useacms/cli/adapters';


export default defineConfig({
  dev: localFile({ path: './acms.json' }),
  production: vercelEdgeConfig({
    token: process.env.VERCEL_TOKEN,
  }),
  strategy: 'build-time',
});

For Astro sites, build-time strategy is usually the best choice since Astro renders pages at build time by default.

Development Setup

Section titled “Development Setup”
Terminal window
# Terminal 1
acms dev


# Terminal 2
astro dev

Or use a concurrent script:

{
  "scripts": {
    "dev": "concurrently \"acms dev\" \"astro dev\""
  }
}

Working with Arrays

Section titled “Working with Arrays”
---
import { acms } from '@useacms/client';
---


<ul>
  {acms.features.map((feature) => (
    <li>{feature}</li>
  ))}
</ul>

Working with Images

Section titled “Working with Images”
---
import { acms } from '@useacms/client';
---


<img src={acms.hero.image} alt={acms.hero.imageAlt} />

SSR Mode

Section titled “SSR Mode”

If you’re using Astro in SSR mode (output: 'server'), you can use the runtime strategy for dynamic content:

export default defineConfig({
  strategy: 'runtime',
});

This fetches content on each request rather than at build time.

Next Steps

Section titled “Next Steps”