---
title: "Astro"
canonical: "https://frontman.sh/docs/integrations/astro/"
---

# Astro

## Overview

`@frontman-ai/astro` is an Astro integration that embeds the Frontman AI agent directly into your Astro dev server. It combines Astro integration lifecycle hooks with a Vite plugin chain, giving the AI access to your source files, dev server logs, and resolved route manifest.

**Frontman is a development-only tool.** The integration is a no-op in production builds — nothing is injected into your deployment bundle.

## Requirements

- Node.js 22.19 or later
- Astro 5.x, 6.x, or 7.x

## Installation

Use Astro's built-in integration installer:

```sh
npx astro add @frontman-ai/astro
```

This adds the integration to your `astro.config.mjs` automatically. Alternatively, install the package manually:

```sh
npm install --save-dev @frontman-ai/astro
```

Then register it in your config:


```ts
import { defineConfig } from 'astro/config';
import frontman from '@frontman-ai/astro';

export default defineConfig({
  integrations: [
    frontman({
      projectRoot: import.meta.dirname,
    }),
  ],
});
```


:::note[Sign-in and AI provider required]
The default setup connects to Frontman's hosted server at `api.frontman.sh`. When you first open `/frontman`, your browser redirects there so you can sign in to Frontman with a GitHub or Google account, then attempts to return to your project. Standard `localhost` and `127.0.0.1` URLs return automatically; if you use another local hostname and remain on the hosted page, reopen `/frontman` after signing in. Before your first prompt, connect a supported AI provider with OAuth or add an API key. Frontman does not include a built-in model credential; see [API Keys & Providers](/docs/api-keys/).

If you configure `host` or `FRONTMAN_HOST`, sign-in happens on that Frontman server instead. Self-hosted production servers still require GitHub or Google OAuth through WorkOS; see [Self-Hosting](/docs/reference/self-hosting/).
:::

## Configuration

All options are optional. Defaults are inferred from environment variables and the Astro config.

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `projectRoot` | `string` | `process.env.PROJECT_ROOT` \| `process.env.PWD` \| `"."` | Absolute path to your project root. Scopes all file operations performed by the AI. |
| `sourceRoot` | `string` | Same as `projectRoot` | Root for resolving source file paths. Set this to the monorepo root when `projectRoot` is a workspace package so the AI can reach files outside the Astro package. |
| `basePath` | `string` | `"frontman"` | URL prefix for all Frontman routes. Leading and trailing slashes are stripped automatically. |
| `host` | `string` | `process.env.FRONTMAN_HOST` \| `"api.frontman.sh"` | Frontman server host used for WebSocket client connections. Accepts bare hostnames, full URLs, or local dev server addresses (e.g. `frontman.local:4000`). |
| `serverName` | `string` | `"frontman-astro"` | Identifier included in every tool response. Useful when multiple Frontman instances run concurrently. |
| `serverVersion` | `string` | Package version | Version string included in tool responses. |
| `clientUrl` | `string` | Auto-derived from `host` | Override the URL of the Frontman client JS bundle. Must include a `host` query parameter. |
| `clientCssUrl` | `string` | Production CDN URL; `undefined` in dev | Override the URL of the Frontman client CSS stylesheet. |
| `entrypointUrl` | `string` | — | Custom entrypoint URL for the AI API. |
| `isLightTheme` | `boolean` | `false` | Render the Frontman UI with a light color scheme instead of the default dark theme. |

### Monorepo configuration

For monorepos where the Astro app is a workspace package but source files span the whole repository, set `sourceRoot` to the repo root:

```js
import path from 'node:path';

const appRoot = path.resolve(import.meta.dirname);
const monorepoRoot = path.resolve(appRoot, '../..');

frontman({
  projectRoot: appRoot,
  sourceRoot: monorepoRoot,
})
```

File edits are resolved relative to `sourceRoot`, letting the AI reach files outside the Astro package boundary.

## Accessing Frontman

Start your dev server (`astro dev`) and open `http://localhost:4321/frontman`. The port matches whatever Astro binds to. If you've set a custom `basePath`, replace `frontman` in the URL accordingly.

## How It Works

### Astro lifecycle hooks

The integration registers handlers at four Astro lifecycle points:

**`astro:config:setup`** — Registers the Vite plugin chain (described below), injects the element annotation capture script into every page, and registers a Dev Toolbar app that provides element-to-source-file mapping.

**`astro:config:done`** — Captures sanitized resolved Astro config so Frontman can inspect build output, adapter, integrations, routing, image, Markdown, security, session, and server settings.

**`astro:server:setup`** — Initializes the log capture buffer, registers the Frontman request handler on the Vite Connect server, and canonicalizes Frontman routes according to the final trailing-slash policy.

**`astro:routes:resolved`** — Captures the complete resolved route manifest from Astro's routing system. This catches content collection routes, config-level redirects, API endpoints, and routes injected by other integrations.

### Vite plugin chain

Three Vite plugins run inside the Astro Vite instance:

**`frontman-middleware`** — Installs a Connect middleware that intercepts all `/{basePath}/*` requests. Serves the Frontman UI, handles tool call requests (`POST /frontman/tools/call`), manages SSE streams for streaming responses (`GET /frontman/tools`), and resolves source locations. CORS is enabled for all `/frontman/*` routes.

**`frontman-source-annotations`** *(Astro 7)* — Adds dev-only `data-frontman-source-*` attributes before Astro's Rust compiler runs. Production output remains unchanged.

**`frontman-props-injection`** — During server rendering, injects bounded, secret-redacted component props as HTML comments. The Frontman client reads these comments to give the AI component props without requiring a client framework runtime.

Markdown source metadata is composed into the active processor: Sätteri `hastPlugins` on Astro 7, unified `rehypePlugins` when configured, and the legacy rehype config path on Astro 5/6.

### Log capture

A circular buffer of 1024 entries is maintained for the lifetime of the dev server. It captures:

- All `console.*` methods (`log`, `warn`, `error`, `info`, `debug`)
- Astro/Vite build and HMR output (compilation results, module graph updates, hot reload events)
- Uncaught exceptions with full stack traces

The AI queries this buffer with the `get_logs` tool. Queries support: `pattern` (regex), `level` (log level filter), `since` (ISO 8601 timestamp lower bound), and `tail` (N most recent entries).

### Element source detection

Frontman identifies the source file and line number for a clicked DOM element using two mechanisms:

**Astro 5/6 Dev Toolbar attributes** — Astro injects `data-astro-source-file` and `data-astro-source-loc` attributes onto elements during development. Frontman reads these for exact file and line information.

**Astro 7 Frontman attributes** — Frontman adds `data-frontman-source-file` and `data-frontman-source-loc` before compilation because Astro 7's Rust compiler no longer emits the legacy source attributes.

**CSS selector fallback** — When `devToolbar.enabled` is `false` in your Astro config, Frontman falls back to matching DOM elements by CSS selector against the parsed AST. This is less precise.

Keep `devToolbar.enabled: true` (the Astro default) for accurate source detection on Astro 5 and 6. Astro 7 source detection does not depend on this setting.

## Available Tools

### Astro-specific

| Tool | Description |
|------|-------------|
| `get_client_pages` | Returns all Astro pages with their file paths and URL route patterns from the resolved route manifest, including content collection and integration-injected routes. |
| `get_resolved_astro_config` | Returns sanitized resolved Astro config from `astro:config:done`. Use before changing routing, SSR/static behavior, adapters, i18n, images, Markdown/MDX, redirects, sessions, security, or deployment behavior. |
| `get_logs` | Queries the dev server log buffer. Parameters: `pattern` (regex string), `level` (`log`/`warn`/`error`/`info`/`debug`), `since` (ISO 8601 timestamp), `tail` (integer). |

### File system

| Tool | Description |
|------|-------------|
| `read_file` | Read a file with an optional line range. |
| `edit_file` | Apply targeted edits or replace file contents. Runs a post-edit log check to surface errors introduced by the change. |
| `write_file` | Write a new file. |
| `search_files` | Search file contents with a regex pattern. |
| `list_files` | List files in a directory. |
| `list_tree` | Recursive directory tree. |
| `file_exists` | Check whether a path exists. |

### Other

| Tool | Description |
|------|-------------|
| `lighthouse` | Run a Lighthouse performance audit against a URL using a local Chrome instance. |
| `load_agent_instructions` | Fetch agent instructions from the project (e.g. `AGENTS.md`). |

## Environment Variables

| Variable | Description |
|----------|-------------|
| `FRONTMAN_HOST` | Override the default server host. Takes precedence over the `host` config option. |
| `PROJECT_ROOT` | Override the default project root. Takes precedence over `projectRoot`. |

## Troubleshooting

If your issue is broader than Astro-specific integration behavior (for example WebSocket disconnects, agent timeouts, tool-call failures, or model/key errors), check the [Frontman troubleshooting guide](/docs/reference/troubleshooting/).


**`/frontman` returns 404**

The middleware is not registered. Verify the integration appears in `integrations` in `astro.config.mjs` and that you are running the dev server (`astro dev`), not `astro build` or `astro preview`.

**Clicked element shows the wrong source file**

On Astro 5 or 6, ensure `devToolbar.enabled` is not set to `false`. Astro 7 uses Frontman-owned annotations and does not require Dev Toolbar source attributes.

**`get_client_pages` returns no routes**

Verify pages appear in Astro's resolved route manifest and restart the dev server after route configuration changes.

**The log buffer is empty**

Logs are captured from the moment the dev server starts. Earlier logs are gone after a restart. Reproduce the action that generates the log you need, then query immediately.