Astro Native Integration

Kyro CMS is built ground-up to be the #1 Astro-Native Headless CMS. It seamlessly integrates into Astro projects via the dedicated @kyro-cms/astro package, using native Content Layer loaders, Astro Actions, Middleware, Dev Toolbar apps, and Zero-JS .astro rendering components.

---

Installation

Install @kyro-cms/core and @kyro-cms/astro in your Astro project:

pnpm add @kyro-cms/core @kyro-cms/astro

---

1. Core Astro Integration (kyro)

The core integration automatically configures Vite aliases (kyro:config), externalizes native database drivers, and injects API route handlers.

Setup (astro.config.mjs):

import { defineConfig } from 'astro/config';
import kyro from '@kyro-cms/astro';
import { kyroAdmin } from '@kyro-cms/admin/integration';

export default defineConfig({
  integrations: [
    kyro({
      configPath: './kyro.config.ts', // Path to your Kyro configuration
      apiPath: '/api',                // Base path for REST API endpoints
      enableGraphQL: true,            // Enable GraphQL at /api/graphql
      enableTRPC: false,              // Enable tRPC at /api/trpc
      enableWebSocket: false,         // Enable WebSockets for live subscriptions
    }),
    kyroAdmin({
      basePath: '/admin',             // Base path for Admin Dashboard
      apiPath: '/api',
    }),
  ],
});

---

2. Astro Content Layer Loader (kyroLoader)

Use kyroLoader() in src/content.config.ts to feed your Kyro CMS collections directly into Astro's getCollection() store with full type-safety and sub-second HMR store sync.

Setup (src/content.config.ts):

import { defineCollection } from 'astro:content';
import { kyroLoader } from '@kyro-cms/astro';

export const blog = defineCollection({
  loader: kyroLoader({
    collection: 'posts',
    drafts: import.meta.env.DEV, // Automatically include draft entries in dev mode
  }),
});

export const collections = { blog };

Querying in Astro Pages (src/pages/blog/index.astro):

---
import { getCollection } from 'astro:content';

const posts = await getCollection('blog');
---

<h1>Blog Posts</h1>
<ul>
  {posts.map((post) => (
    <li>
      <a href={`/blog/${post.id}`}>{post.data.title}</a>
    </li>
  ))}
</ul>

---

3. Astro Dev Toolbar Widget (kyroDevToolbarIntegration)

Kyro CMS provides a custom widget inside Astro's bottom Dev Toolbar. It lets you monitor live database connection status, inspect active collections, toggle draft mode preview, and jump straight to /admin with a single click.

Enabling the Dev Toolbar Widget (astro.config.mjs):

import { defineConfig } from 'astro/config';
import kyro, { kyroDevToolbarIntegration } from '@kyro-cms/astro';
import { kyroAdmin } from '@kyro-cms/admin/integration';

export default defineConfig({
  integrations: [
    kyro(),
    kyroAdmin(),
    kyroDevToolbarIntegration({ enabled: true }), // Optional dev toolbar widget
  ],
});

---

4. Astro Actions for CMS Forms (kyroAction)

Astro Actions (astro:actions) handle type-safe server-side form submissions and RPC calls. kyroAction automatically validates form data against your Kyro collection Zod schemas and saves documents straight into your database.

Creating an Action (src/actions/index.ts):

import { defineAction } from 'astro:actions';
import { kyroAction } from '@kyro-cms/astro';
import { z } from 'astro:schema';

export const server = {
  submitContact: defineAction(
    kyroAction({
      collection: 'submissions',
      action: 'create',
      schema: z.object({
        name: z.string().min(2),
        email: z.string().email(),
        message: z.string().min(10),
      }),
    })
  ),
};

Submitting from an Astro Component (src/components/ContactForm.astro):

---
import { actions } from 'astro:actions';
---

<form action={actions.submitContact}>
  <input name="name" type="text" placeholder="Your Name" required />
  <input name="email" type="email" placeholder="Your Email" required />
  <textarea name="message" placeholder="Your message..." required></textarea>
  <button type="submit">Submit Form</button>
</form>

---

5. Astro Auth Middleware (kyroAuthMiddleware)

Injects current authenticated Kyro user sessions into Astro.locals.kyroUser and protects routes automatically.

Setup (src/middleware.ts):

import { kyroAuthMiddleware } from '@kyro-cms/astro';

export const onRequest = kyroAuthMiddleware({
  protectedRoutes: ['/dashboard/**', '/profile/**'],
  loginPath: '/admin/login',
});

Accessing User Session in Astro Pages:

---
const user = Astro.locals.kyroUser;
---

{user ? (
  <p>Welcome back, <strong>{user.email}</strong>!</p>
) : (
  <a href="/admin/login">Log in</a>
)}

---

6. Pure Astro Zero-JS Component Renderers

Ship zero client-side JavaScript to your users by using native .astro components for content rendering.

<KyroRichText /> — Zero-JS Rich Text Renderer

Converts Kyro Rich Text AST into clean, semantic static HTML without loading React or client hydration runtimes.

---
import KyroRichText from '@kyro-cms/astro/components/KyroRichText.astro';

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

<KyroRichText content={post.content} class="prose dark:prose-invert" />

<KyroImage /> — Responsive Media Renderer

Wraps Kyro media items into responsive, accessible images with lazy loading and optimized attributes.

---
import KyroImage from '@kyro-cms/astro/components/KyroImage.astro';

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

<KyroImage src={heroImage} width={1200} height={630} loading="eager" alt="Hero banner" />

<KyroServerIsland /> — Astro Server Islands Helper

For hybrid / SSG sites, use Astro Server Islands (server:defer) to defer dynamic Kyro CMS content with automatic animated skeleton fallbacks:

---
import KyroServerIsland from '@kyro-cms/astro/components/KyroServerIsland.astro';
---

<KyroServerIsland collection="comments" id={Astro.params.id} server:defer>
  <div slot="fallback" class="animate-pulse bg-stone-100 p-4 rounded-lg">
    Loading real-time comments...
  </div>
</KyroServerIsland>

---

7. CLI & TypeGen Commands

Kyro provides command-line tools for database operations and TypeScript generation:

• npx kyro generate: Scans your kyro.config.ts and updates type definitions in src/env.d.ts or kyro-types.d.ts.
• npx kyro db migrate: Runs Drizzle / ORM database migrations based on configured collections.
• npx kyro dev: Starts the Astro dev server with full Kyro CMS API and Admin dashboard routes active.