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

# Astro

> Use Fimo content, labels, and native components in Astro pages.

Astro pages read Fimo content on the server and render it through native `.astro` components. Fimo adds Studio preview and editing without installing React or taking control of Astro routing.

Start a new Astro project with the opt-in first-party shell:

```bash theme={null}
fimo init my-astro-site --framework astro
```

React Router remains the default when `--framework` is omitted.

## Configure the runtime

```json theme={null}
{
  "runtime": { "framework": "astro" }
}
```

Astro owns its static or server output, routes, and 404 behavior. It needs no hosting rewrite.

Install `fimo-astro` at the same version as `fimo`, then add the Fimo integration beside the adapters and integrations the project already uses:

```bash theme={null}
npm install fimo fimo-astro
```

```js theme={null}
import { defineConfig } from 'astro/config';
import { fimo } from 'fimo-astro/config';

import fimoConfig from './.fimo/config.json' with { type: 'json' };

export default defineConfig({
  integrations: [fimo()],
  i18n: {
    defaultLocale: fimoConfig.i18n.defaultLocale,
    locales: fimoConfig.i18n.locales,
    routing: { prefixDefaultLocale: false },
  },
});
```

`fimo-astro` owns Fimo hosting for `output: 'server'` projects; content and components stay in `fimo`. Fimo loads its preview script only inside a Fimo preview, reports the current location to Studio, and uses full-page Astro navigation when Studio changes pages. You do not need to add a provider, preview URL, or script tag.

A static Astro site hosted elsewhere can import `fimo` from `fimo/astro/config` instead, which wires the preview connector and branch environment without a hosting adapter.

## Generate content clients

Create `src/schemas/<Uid>.json`, then run:

```bash theme={null}
fimo schemas push <Uid>
```

Astro projects receive one server-only `<Uid>.ts` module plus its public types. Fimo does not generate React hooks, `.client.ts` modules, or a client content registry.

## Read and render content

```astro theme={null}
---
import { fimo, getLabels } from 'fimo/astro';
import { Image, RichText, Text } from 'fimo/astro/components';

import * as Article from '../schemas/Article';

const locale = Astro.currentLocale;
const article = await Article.getBySlug(Astro.params.slug ?? '', { locale });
const labels = await getLabels({ locale });
---

<Text as="h1" value={fimo`${labels.t('article.title')}: ${article?.title}`} />
<Image value={article?.cover} />
<RichText value={article?.body} />
```

The native component surface includes `Text`, `RichText`, `Image`, `StaticImage`, `Video`, `Date`, `Boolean`, and `Json`. Pass tracked values directly so Fimo preserves their `data-fimo-source` metadata.

## Routes and locales

The starter configures Astro's native i18n router from `.fimo/config.json`: the default locale stays unprefixed and other locales use their Astro prefix. Use `Astro.currentLocale` for generated content reads, `getLabels()`, and document language. Existing sites can keep another Astro locale strategy; Fimo does not impose a router or provider.

Keep `.fimo/config.json#routes` aligned with the pages you want Studio to list. This is Studio metadata, not an Astro route manifest; Astro files, middleware, redirects, and 404s remain authoritative.

Client-island content hooks are not part of the Astro surface yet. Preserve existing islands and do not add React just to read Fimo content.

<Card title="Content & CMS" icon="database" href="/docs/cli/content">
  Declare schemas and use generated collection or Single clients.
</Card>