# Astro API reference

> **Section:** [Reference](https://docs.atmyapp.com/reference.md)
> **Related:** [CLI Reference](https://docs.atmyapp.com/reference/cli.md) · [Core SDK](https://docs.atmyapp.com/reference/core.md) · [Field types and options](https://docs.atmyapp.com/reference/fields.md) · [Structure SDK](https://docs.atmyapp.com/reference/structure.md)
> **Also:** [HTML version](https://docs.atmyapp.com/reference/astro) · [Docs index](https://docs.atmyapp.com/llms.txt)

---
## Requirements and exports

Astro 5+ and Node 22.14+. The integration is tested with the workspace's Astro version; use an adapter compatible with your installed Astro version.

| Import                       | API                                                                                       |
| ---------------------------- | ----------------------------------------------------------------------------------------- |
| `@atmyapp/astro`             | Default `atmyapp(options?)` integration                                                   |
| `@atmyapp/astro/server`      | `getAtMyApp`, `getAtMyAppConfiguration`, `fetchWebsiteMetadataOnce`, `AstroClientOptions` |
| `@atmyapp/astro/client`      | Browser-only `getClient()`                                                                |
| `@atmyapp/astro/components`  | Default `AtMyAppHead` component                                                           |
| `@atmyapp/astro/form`        | Default `AtMyAppForm` component                                                           |
| `@atmyapp/astro/diagnostics` | Manual `createAstroDiagnosticsRoute`, `atMyAppDiagnostics` helpers                        |

## `atmyapp(options)`

Options: `apiKey?: string`, `baseUrl?: string`, `diagnostics?: boolean` (false by default). Environment configuration is usually enough. The integration configures output mode, shared environment defaults and optionally the diagnostics route. It does not install a server adapter or sitemap package.

## `getAtMyApp(context, options?)`

Pass Astro's render/API context, including `url` and `locals`. Returns the normal core SDK client. Options accept core client configuration, with optional `apiKey`/`baseUrl`, `env` overrides and `previewKey: string | null`. Passing a canonical schema preserves inferred types. Explicit overrides win; null disables preview. Errors throw by default instead of returning placeholder content.

The helper requires the integration's virtual configuration module. It is a server/build import, not a browser import. Browser consumers use `@atmyapp/astro/client` after a head component has initialized the page.

## `AtMyAppHead`

Accepts [metadata fields](/guides/astro-metadata/) plus:

- `clientOptions`: same options used for your content client.
- `defaults`: local fallback metadata.
- `metadataError`: `throw` (default) or `fallback`; preview failures always throw.
- `trackPageView`: false by default; ignored in preview context.

## `AtMyAppForm`

- `submission`: required submission type name.
- `returnTo`: optional result page URL.
- `clientOptions`: shared client options including schema.
- `allowPreviewSubmit`: false by default; true permits real submissions.
- `enhance`: false by default; inline browser feedback.
- Ordinary form attributes, such as `id`, `class` and `aria-label`.

The default slot contains developer-owned fields. The `captcha` slot contains an optional CAPTCHA widget. The component owns `action`, `method` and `enctype`.

## Diagnostics

Prefer `atmyapp({ diagnostics: true })`. Manual helpers remain available for custom client factories, but do not mount both approaches at the same path. Static reports describe the build; dynamic reports describe the current request. [Report fields and limitations](/guides/diagnostics/).