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:

npx astro add @frontman-ai/astro

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

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

Then register it in your config:

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

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

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.

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.

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:

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 the final trailingSlash policy so Frontman routes follow always, never, and ignore consistently.

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

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