Framework Guides - Gradial Docs

Gradial ACI (Agentic Content Infrastructure) supports Astro and Next.js. Both integrations use the same content files, component contracts, layout contracts, and registry shape, so your content model stays consistent when the rendering framework changes.

Choose a framework

	Astro	Next.js
Best starting point	New ACI sites	Sites with a Next.js requirement
Primary strength	Focused, content-oriented frontend	React and App Router ecosystem
Runtime components	Astro components	React components
ACI integration	`@gradial/aci/astro`	`@gradial/aci/next` and `@gradial/aci/next/config`
Local URL in the starter	`http://localhost:4321`	`http://localhost:3000`

Astro is the standard choice for a new customer site. Choose Next.js when the project depends on its ecosystem or needs its framework-specific server-rendering path.

Astro and Next.js are the supported framework integrations. If you are migrating a site on another framework, work with your Gradial team to plan the frontend transition.

Start with a generated project

The initializer creates the required routes, adapters, tests, and build configuration. This is the fastest and safest setup for either framework.

npx @gradial/aci init my-site --template astro-starter --with-starter-content

npx @gradial/aci init my-site --template next-starter --with-starter-content

Then install dependencies and start the framework:

cd my-site
npm install
npm run dev

Remove --with-starter-content when you want the integration, empty registries, design system, and project guidance without the sample pages and components.

Shared project contract

Both starters use this structure:

.aci.yaml
.content/
src/cms/contracts/components/
src/cms/contracts/layouts/
src/cms/registry.ts
src/components/
tests/

Contract files import framework-neutral APIs from the package root:

import {
  defineComponentContract,
  defineLayoutContract,
  slot,
} from '@gradial/aci';

Framework integration code uses explicit subpaths:

Import	Use
`@gradial/aci/astro`	Astro integration, content loading, and page helpers
`@gradial/aci/next`	Next.js App Router page helpers
`@gradial/aci/next/config`	Next.js configuration wrapper
`@gradial/aci/react`	Shared React bindings

Keeping framework imports out of contract files lets ACI extract and validate the same content model independently of the runtime component implementation.

Astro

The Astro starter configures ACI as an Astro integration and renders CMS-managed routes through a catch-all page.

Astro site configuration

version: "1"
siteId: "my-astro-site"
domain: "meridian.local"
framework: astro

source:
  root: "./"
  outDir: "dist"
  publicDir: "public"

componentRegistry: ./src/cms/contracts/components/index.ts
layoutRegistry: ./src/cms/contracts/layouts/index.ts

routes:
  cmsManaged: "/[...slug]"

rendererProtocol: stdio-json

rendererProtocol is starter-managed integration configuration. Keep the generated value unless your Gradial team directs otherwise.

Astro integration

astro.config.mjs includes withAci() alongside the rest of your Astro configuration:

import { defineConfig } from 'astro/config';
import { withAci } from '@gradial/aci/astro';

export default defineConfig({
  integrations: [withAci()],
  trailingSlash: 'always',
});

The generated configuration also preserves the output and adapter settings ACI needs when it builds a deployable code artifact. Extend that file in place instead of replacing it with the abbreviated example above.

Catch-all page

The generated src/pages/[...slug].astro uses ACI’s Astro helpers to:

enumerate known routes for a static build;
load and normalize the page for the current route;
resolve layout slots and default fragments;
map content blocks through src/cms/registry.ts; and
handle an unknown route through the project’s authored 404 page.

Keep src/pages/404.astro in place when you customize routing. It is part of the starter’s not-found behavior.

Register an Astro component

// src/cms/registry.ts
import { createRegistry } from '@gradial/aci';
import { homeHeroContract } from './contracts/components/homeHero.contract';
import HomeHero from '../components/sections/HomeHero.astro';

export const registry = createRegistry([
  [homeHeroContract, HomeHero],
]);

The Astro component can use framework features, CSS, and client islands as usual. Its contract remains a framework-neutral schema.

Next.js

The Next.js starter connects ACI to the App Router. Use it when Next.js is already a project requirement or your application depends on its React ecosystem.

Next.js site configuration

version: "1"
siteId: "my-next-site"
domain: "meridian.local"
framework: next

source:
  root: "./"

componentRegistry: ./src/cms/contracts/components/index.ts
layoutRegistry: ./src/cms/contracts/layouts/index.ts

routes:
  cmsManaged: "/[...slug]"

rendererProtocol: stdio-json

rendererProtocol is starter-managed integration configuration. Keep the generated value unless your Gradial team directs otherwise.

Next.js configuration

Wrap the project configuration with withAci():

// next.config.mjs
import { withAci } from '@gradial/aci/next/config';

export default withAci();

If your site already exports a Next.js configuration, pass it to the wrapper and retain your existing settings according to the generated starter for your SDK version.

The Next.js integration currently uses webpack. Run next dev and next build without --turbopack; the generated package scripts are configured correctly.

App Router page

The generated catch-all route delegates content loading, metadata, and rendering to the ACI page helper:

// src/app/[[...slug]]/page.tsx
import { createPage } from '@gradial/aci/next';
import { registry } from '@/cms/registry';

const page = createPage(registry);

export const dynamic = 'force-dynamic';
export const generateMetadata = page.generateMetadata;
export default page.default;

Keep this route server-rendered. ACI selects the exact page experience before the framework renders it; your React components receive the selected, validated page graph.

Register a React component

// src/cms/registry.ts
import { createRegistry } from '@gradial/aci';
import { homeHeroContract } from './contracts/components/homeHero.contract';
import { HomeHero } from '@/components/sections/HomeHero';

export const registry = createRegistry([
  [homeHeroContract, HomeHero],
]);

Add ACI to an existing frontend

For an existing Astro or Next.js site, generate a clean reference project with the same framework first:

npx @gradial/aci init aci-reference --template astro-starter

Use next-starter for Next.js. Then:

Install @gradial/aci and Zod 4 in the existing project.
Add .aci.yaml and the src/cms/ contract and registry structure.
Add the framework integration and CMS-managed catch-all route from the reference project.
Map your existing components to new contracts in src/cms/registry.ts.
Add content under .content/.
Bring over the generated conformance tests and relevant build scripts.
Run the complete verification loop.

Do not copy integration files from an older project without comparing them to a starter generated by your installed SDK. The starter is the reference for that SDK’s routes, build hooks, and error-page behavior.

Development and build commands

Both starters provide the same core scripts:

npm run dev              # Compile, watch content, and start the framework
npm run content:compile  # Compile .content into .aci/compiled
npm run typecheck        # Check framework and TypeScript code
npm test                 # Run project conformance tests
npm run build            # Create a production build

Astro also includes npm run preview for its local production preview. The generated package scripts carry the required ACI environment and build hooks, so prefer them over recreating the underlying commands in CI.

Framework migration checklist

If you move between Astro and Next.js, the content and contract layer can remain unchanged. Review these framework-owned pieces:

runtime component implementations;
src/cms/registry.ts imports;
the catch-all route;
framework configuration and build scripts;
error-page components; and
framework-specific tests and deployment settings.

Run a full content compile after the new registry is in place. A successful TypeScript build alone does not prove that every authored block still has a valid runtime mapping.

Next: CLI reference →

​Choose a framework

​Start with a generated project

​Shared project contract

​Astro

​Astro site configuration

​Astro integration

​Catch-all page

​Register an Astro component

​Next.js

​Next.js site configuration

​Next.js configuration

​App Router page

​Register a React component

​Add ACI to an existing frontend

​Development and build commands

​Framework migration checklist

Choose a framework

Start with a generated project

Shared project contract

Astro

Astro site configuration

Astro integration

Catch-all page

Register an Astro component

Next.js

Next.js site configuration

Next.js configuration

App Router page

Register a React component

Add ACI to an existing frontend

Development and build commands

Framework migration checklist