> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gradial.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Framework Guides

> Choose and configure the supported Astro or Next.js integration for an ACI site.

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.

<Note>
  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.
</Note>

## 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.

<CodeGroup>
  ```bash Astro theme={null}
  npx @gradial/aci init my-site --template astro-starter --with-starter-content
  ```

  ```bash Next.js theme={null}
  npx @gradial/aci init my-site --template next-starter --with-starter-content
  ```
</CodeGroup>

Then install dependencies and start the framework:

```bash theme={null}
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:

```txt theme={null}
.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:

```ts theme={null}
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

```yaml theme={null}
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:

```js theme={null}
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

```ts theme={null}
// 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

```yaml theme={null}
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()`:

```js theme={null}
// 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.

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

### App Router page

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

```tsx theme={null}
// 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

```ts theme={null}
// 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:

```bash theme={null}
npx @gradial/aci init aci-reference --template astro-starter
```

Use `next-starter` for Next.js. Then:

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

<Warning>
  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.
</Warning>

## Development and build commands

Both starters provide the same core scripts:

```bash theme={null}
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 →](/aci/developers/cli-reference)*


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.