Quickstart

This guide gets you from zero to a working ACI site in about 5 minutes. You’ll clone a starter repo, run a local server, edit content, and publish changes.

ACI is currently available to design partners. This quickstart works entirely locally — no cloud account needed. Request access → for production features.

Prerequisites

Node.js 18+ and npm
macOS (Apple Silicon or Intel) — Linux/Windows support coming soon
A terminal and text editor

Step 1: Install the CLI

curl -fsSL https://raw.githubusercontent.com/gradial/aci-learn/main/install.sh | sh

This installs the aci CLI to ~/.local/bin/. Make sure it’s in your PATH:

aci version
# 0.1.0

Step 2: Clone the Starter Repo

git clone https://github.com/gradial/aci-learn.git
cd aci-learn
npm install

The aci-learn repo contains:

A complete Astro site with components and design system
Sample content (homepage and product page)
The ACI runtime and configuration

Step 3: Start the Dev Server

cd packages/astro
npm run dev

Open http://localhost:4321 in your browser. You should see a demo site.

The dev server watches your files. Any changes to content or code will hot-reload in the browser.

Step 4: Edit Some Content

Content lives in JSON files. Open the homepage content:

# In another terminal
code packages/astro/.content/pages/home/_index.json

Find the hero section and change the headline:

{
  "id": "hero",
  "component": "home_hero",
  "props": {
    "headline": "Your New Headline Here",
    ...
  }
}

Save the file. Refresh your browser — the headline updates instantly.

Step 5: Understand the Structure

Here’s what you’re working with:

packages/astro/
├── .aci.yaml           # Site configuration
├── .content/                 # Content (JSON files)
│   ├── config/
│   │   └── site.json         # Site-wide settings (nav, footer)
│   └── pages/
│       ├── home/
│       │   └── _index.json   # Homepage content
│       └── product/
│           └── aeroflow-pro/
│               └── _index.json
├── src/
│   ├── cms/                  # ACI integration
│   │   ├── components.ts     # Component registry (schemas)
│   │   ├── layouts.ts        # Layout registry
│   │   └── renderer.ts       # Render function
│   ├── components/           # Astro components
│   └── design-system/        # Tokens and styles

Content Structure

A page’s content is structured JSON:

{
  "$type": "page",
  "id": "home",
  "layout": "marketing",
  "metadata": {
    "title": "Page Title",
    "description": "SEO description"
  },
  "regions": {
    "main": [
      {
        "id": "hero",
        "component": "home_hero",
        "props": {
          "headline": "Welcome",
          "image": { "src": "...", "alt": "..." }
        }
      }
    ]
  }
}

$type: Always “page” for page content
layout: Which layout template to use
metadata: SEO and page-level data
regions: Named areas containing components
component: References a registered component by name
props: Data passed to the component

Component Registry

Components are defined with Zod schemas in src/cms/components.ts:

defineComponent({
  name: 'home_hero',
  schema: z.object({
    headline: z.string().min(1),
    description: z.string().optional(),
    image: z.object({
      src: z.string(),
      alt: z.string().optional(),
    }),
  }),
  renderModes: { canStatic: true, canSSR: true, canClientIsland: false },
})

The schema defines what props are valid. If content doesn’t match the schema, validation fails.

Step 6: Add a New Section

Let’s add a new section to the homepage.

Open packages/astro/.content/pages/home/_index.json
Add a new component to the regions.main array:

{
  "id": "my-cta",
  "component": "cta_band",
  "props": {
    "headline": "Ready to get started?",
    "description": "Join thousands of happy customers.",
    "ctaLabel": "Sign up free",
    "ctaHref": "/signup"
  }
}

Save and refresh — your new CTA section appears on the page.

Step 7: Check Your Setup

Run the doctor command to verify everything is configured correctly:

aci doctor

ok: config discovered (.aci.yaml)
ok: version is 1
ok: siteId present
ok: framework valid (astro)
ok: component registry exists
ok: layout registry exists
ok: renderer entry exists
ok: node available
ok: npm available

What’s Next

Read the Tutorial

Follow the complete workflow: validate → preview → publish → rollback.

Understand the Concepts

Learn how content, components, layouts, and releases work together.

Add Components

Create your own components with schemas and render modes.

Explore the CLI

Master the commands for building, validating, and publishing.

Common Tasks

Add a New Page

Create the directory and content file:

mkdir -p packages/astro/.content/pages/about

Create _index.json:

{
  "$type": "page",
  "id": "about",
  "layout": "marketing",
  "metadata": {
    "title": "About Us",
    "description": "Learn about our company"
  },
  "regions": {
    "main": [
      {
        "id": "hero",
        "component": "home_hero",
        "props": {
          "headline": "About Us",
          "description": "We build great products.",
          "image": {
            "src": "https://images.unsplash.com/photo-1522071820081-009f0129c71c?w=800",
            "alt": "Team photo"
          },
          "ctaLabel": "Contact us",
          "ctaHref": "/contact"
        }
      }
    ]
  }
}

The page is now available at /about

Modify a Component

Edit the Astro component in src/components/sections/
The dev server hot-reloads your changes
If you change the props interface, update the schema in src/cms/components.ts

Validate Content

aci validate

This checks all content files against the component schemas.

Troubleshooting

”command not found: aci”

Add ~/.local/bin to your PATH:

export PATH="$HOME/.local/bin:$PATH"

Add this to your ~/.zshrc or ~/.bashrc to make it permanent.

Dev server not starting

Make sure you’re in the right directory:

cd packages/astro
npm run dev

Content changes not showing

Make sure you saved the file
Check for JSON syntax errors
Run aci validate to see if there are schema violations

”Component not found”

The component name in your content JSON must match a registered component. Check src/cms/components.ts for the list of available components.

Architecture Overview

┌─────────────────────────────────────────────────────────────┐
│                        Your Code                             │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐       │
│  │  Components  │  │   Layouts    │  │   Renderer   │       │
│  │  (Astro)     │  │   (Astro)    │  │   (TS)       │       │
│  └──────────────┘  └──────────────┘  └──────────────┘       │
│         │                 │                 │                │
│         └─────────────────┼─────────────────┘                │
│                           │                                  │
│                   .aci.yaml                            │
│                     (contract)                               │
└───────────────────────────┼─────────────────────────────────┘
                            │
                            ▼
┌─────────────────────────────────────────────────────────────┐
│                     ACI CLI                          │
│  ┌────────┐  ┌──────────┐  ┌─────────┐  ┌─────────────┐    │
│  │validate│  │  preview │  │ publish │  │   rollback  │    │
│  └────────┘  └──────────┘  └─────────┘  └─────────────┘    │
└─────────────────────────────────────────────────────────────┘
                            │
                            ▼
┌─────────────────────────────────────────────────────────────┐
│                       Content                                │
│  ┌──────────────────────────────────────────────────┐       │
│  │  .content/pages/home/_index.json                 │       │
│  │  .content/pages/product/widget/_index.json       │       │
│  │  .content/config/site.json                       │       │
│  └──────────────────────────────────────────────────┘       │
└─────────────────────────────────────────────────────────────┘

Content is separate from code. The CLI validates content against component schemas, renders pages through your renderer, and manages releases.

Next: Frontend Contract →

Getting Started

Architecture

Developers

Platform

Quickstart

Quickstart

Prerequisites

Step 1: Install the CLI

Step 2: Clone the Starter Repo

Step 3: Start the Dev Server

Step 4: Edit Some Content

Step 5: Understand the Structure

Content Structure

Component Registry

Step 6: Add a New Section

Step 7: Check Your Setup

What’s Next

Read the Tutorial

Understand the Concepts

Add Components

Explore the CLI

Common Tasks

Add a New Page

Modify a Component

Validate Content

Troubleshooting

”command not found: aci”

Dev server not starting

Content changes not showing

”Component not found”

Architecture Overview

Getting Started

Architecture

Developers

Platform

Documentation Index

​Quickstart

​Prerequisites

​Step 1: Install the CLI

​Step 2: Clone the Starter Repo

​Step 3: Start the Dev Server

​Step 4: Edit Some Content

​Step 5: Understand the Structure

​Content Structure

​Component Registry

​Step 6: Add a New Section

​Step 7: Check Your Setup

​What’s Next

Read the Tutorial

Understand the Concepts

Add Components

Explore the CLI

​Common Tasks

​Add a New Page

​Modify a Component

​Validate Content

​Troubleshooting

​”command not found: aci”

​Dev server not starting

​Content changes not showing

​”Component not found”

​Architecture Overview

Quickstart

Prerequisites

Step 1: Install the CLI

Step 2: Clone the Starter Repo

Step 3: Start the Dev Server

Step 4: Edit Some Content

Step 5: Understand the Structure

Content Structure

Component Registry

Step 6: Add a New Section

Step 7: Check Your Setup

What’s Next

Common Tasks

Add a New Page

Modify a Component

Validate Content

Troubleshooting

”command not found: aci”

Dev server not starting

Content changes not showing

”Component not found”

Architecture Overview