Aether Sites SDK

The Aether Sites SDK (@aether-official/sites-sdk) enables you to build websites that connect to Aether’s visual headless CMS. Content editors can edit your site’s content inline using Aether’s visual editor, while you maintain complete control over your site’s design and technology stack.

Features

🎯 Type Generation - Auto-generate TypeScript types from your CMS schema
📝 Type-Safe API - Full autocomplete and type checking for all content fields
🔧 CLI Tool - Interactive setup wizard and schema synchronization
🎨 Helper API - Reduce boilerplate by ~60% with intuitive helper functions
🖼️ Visual Inline Editing - Content editors click and edit directly on your site
📦 Headless CMS - Content stored in Aether, fetched via API
🚀 Auto-Middleware - Zero-config visual editor support for Astro
⚡ Framework Agnostic - Works with Astro, Next.js, React, Vue, or plain JavaScript
Build-time & Runtime - Fetch content at build time or on-demand
Real-time Updates - Changes reflect immediately in the visual editor

Quick Start (5 Minutes)

1. Install Packages

# Install SDK and CLI
npm install @aether-official/sites-sdk
npm install -D @aether-official/cli

2. Run Interactive Setup

npx aether-sdk init

This will:

✅ Prompt for your Site ID, Org ID, and API Token
✅ Test your connection
✅ Create .env file with credentials
✅ Fetch your CMS schema
✅ Generate TypeScript types in src/aether-types.d.ts

3. Add Astro Integration

import { defineConfig } from 'astro/config';
import aetherSites from '@aether-official/sites-sdk/astro';

export default defineConfig({
  integrations: [
    aetherSites({
      siteId: process.env.AETHER_SITE_ID,
      organizationId: process.env.AETHER_ORG_ID,
      editorOrigin: process.env.PUBLIC_AETHER_EDITOR_ORIGIN || 'http://localhost:3000',
    })
  ]
});

4. Use in Your Pages

---
import { fetch, aether, getConfig } from '@aether-official/sites-sdk/astro';
import { SECTIONS } from '../aether-types'; // Auto-generated!
import type { HeroData } from '../aether-types';

const config = getConfig(import.meta.env);

// Fetch section content with full type safety
const section = await fetch.section(SECTIONS.HERO, config);
const content = section.data as HeroData; // TypeScript knows all fields!

// Create helper for visual editing
const helper = aether.section(SECTIONS.HERO);
---

<section {...helper.section()}>
  <h1 {...helper.field('title')}>
    {content.title}
  </h1>
  <p {...helper.field('subtitle')}>
    {content.subtitle}
  </p>
</section>

That’s it! You now have:

✅ Full TypeScript autocomplete for all your CMS fields
✅ Visual inline editing with ?aether-editor=true
✅ Auto-generated types that stay in sync with your CMS

What’s New in v1.2:

🎯 Auto-generated TypeScript types from CMS schema
🔧 CLI tool for interactive setup and type generation
📝 Full type safety with autocomplete for all fields
🎨 Helper API reduces boilerplate by ~60%
🚀 Auto-middleware injection (zero manual setup)

How It Works

graph LR
    A[Your Website] -->|Fetches Content| B[Aether API]
    B -->|Returns JSON| A
    A -->|Loads in| C[Visual Editor]
    C -->|PostMessage| D[Aether SDK]
    D -->|Highlights Fields| A
    C -->|Edits Content| B
    B -->|Updates| A

Build/Runtime: Your site fetches content from Aether’s API
Render: You display content with special data-aether-* attributes
Edit Mode: When loaded in Aether’s visual editor, the SDK activates
Visual Editing: Content editors click fields to edit them inline
Save: Changes save to Aether’s database and update immediately

Core Concepts

Sections

Sections are the primary content units. Each section has:

Unique ID
JSON data structure
Optional template reference

Example section data:

{
  "hero": {
    "title": "Welcome to Our Site",
    "subtitle": "We build amazing products",
    "cta": {
      "text": "Get Started",
      "url": "/signup"
    }
  }
}

Content Fields

Fields are individual editable values within sections. Use the helper API to add editing attributes:

---
const helper = aether.section(SECTIONS.HERO);
---

<h1 {...helper.field('title')}>{content.title}</h1>
<p {...helper.field('subtitle')}>{content.subtitle}</p>

Helper API benefits:

✅ Automatically adds all required data-aether-* attributes
✅ Type-safe field names with autocomplete
✅ ~60% less boilerplate than manual attributes
✅ Consistent attribute naming across your site

Repeater Fields

Repeaters are arrays of content (team members, features, testimonials). Use the helper API for clean syntax:

---
const helper = aether.section(SECTIONS.TEAM);
const section = await fetch.section(SECTIONS.TEAM, config);
const content = section.data as TeamData;
---

<div {...helper.repeater('members', content.members)}>
  {content.members.map((member, i) => (
    <div {...helper.repeaterItem(i)}>
      <h3 {...helper.field(`members.${i}.name`)}>
        {member.name}
      </h3>
      <p {...helper.field(`members.${i}.role`)}>
        {member.role}
      </p>
    </div>
  ))}
</div>

Helper API benefits:

✅ Automatic attribute generation
✅ Type-safe field paths
✅ Cleaner, more readable code

Next Steps

- [Installation Guide](/developers/sites-sdk/installation) - Install and configure the SDK - [CLI Tool](/developers/sites-sdk/cli) - Auto-generate TypeScript types - [Content Fetching](/developers/sites-sdk/content-fetching) - Fetch content from Aether's API - [Astro Integration](/developers/sites-sdk/astro-integration) - Complete Astro guide - [Visual Editor](/developers/sites-sdk/visual-editor) - Enable inline editing - [API Reference](/developers/sites-sdk/api-reference) - Complete API documentation

Example Projects

Astro Starter - Full Astro site example
Next.js Example - Next.js with App Router
React SPA - Client-side React application

Aether Sites SDK

Features

Quick Start (5 Minutes)

1. Install Packages

2. Run Interactive Setup

3. Add Astro Integration

4. Use in Your Pages

How It Works

Core Concepts

Sections

Content Fields

Repeater Fields

Next Steps

Example Projects

Support