# Astro

How Smoodly plugs into an Astro project: one integration in astro.config, views by file name, reads as live collections, pages cached whole and expired by tag, and what happens on a request. The installer writes all of it; this page is for reading it.

## The integration

One line in `astro.config.ts` mounts Smoodly:

File: `astro.config.ts`

```ts
import { defineConfig, memoryCache } from "astro/config";
import node from "@astrojs/node";
import smoodly from "smoodly/astro";
// …
  cache: { provider: memoryCache() },
// …
  site: process.env.SITE_URL,
  integrations: [smoodly({ config: "src/smoodly/config.ts" })],
```

`smoodly()` adds three routes and one middleware, so the project has no route file for any of them:

- **The admin**, at `/admin`. To move it, pass `adminPath: "/studio"` here and set `admin: { path: "/studio" }` in the config; the admin says so when the two disagree.
- **The preview address**, `/_smoodly/preview/<path>`, where the admin's canvas shows drafts.
- **The pages**, at every address a page file of your own does not take.

`config` names the Smoodly config file. `site` is the site's own address: canonical and hreflang links are absolute on it. Astro reads `astro.config.ts` before `.env`, so `process.env.SITE_URL` there sees only a value set in the shell or on the host; when it is empty, `smoodly()` sets `site` from `SITE_URL` in `.env`, and the build warns when nothing names one. The integration reads `.env` at `astro dev` and `astro build`, the `SMOODLY_` keys and `SITE_URL`; `npm start` reads it when it is there, and a deployed server takes the variables from its host.

## Views by file name

A view is an `.astro` file named after its schema's `name`. There is no list of views to keep:

| Folder | What it renders, and its props |
| --- | --- |
| `src/page-types/<name>.astro` | A page type. It receives `page` (where the page sits: title, path, ancestors, children, locales), `zones` and `head`. |
| `src/sections/<name>.astro` | A section. Its fields arrive flat, with `settings` and `styles`. |
| `src/elements/<name>.astro` | An element inside richtext. Its fields and `settings`. |
| `src/entry-pages/<collection>.astro` | The entry page of a collection with a `path`. It receives `entry` and `head`. |

A schema with no view, and a view with no schema, are named once in the server log at the first request. A section is the same file in every framework apart from its view; [Sections](https://smoodly.io/docs/content-modeling/sections.md) shows one.

## Reads

Smoodly's content reaches your views as Astro live collections. `src/live.config.ts` names one loader per collection, global item, the pages and the page tree:

File: `src/live.config.ts`

```ts
import { defineLiveCollection } from "astro:content";
import { entriesLoader, globalLoader, pageLoader, pageTreeLoader } from "smoodly/astro/content";
// …
export const collections = {
  pages: defineLiveCollection({ loader: pageLoader() }),
  pageTree: defineLiveCollection({ loader: pageTreeLoader() }),
  articles: defineLiveCollection({ loader: entriesLoader(articles) }),
  // …
  header: defineLiveCollection({ loader: globalLoader(header) }),
  // …
};
```

A view reads with `getLiveCollection` and `getLiveEntry` from `astro:content`:

File: `src/page-types/articlesIndex.astro`

```astro
---
import { getLiveCollection } from "astro:content";
// …
const { entries = [] } = await getLiveCollection("articles", { locale: page.locale });
// …
---
```

A collection takes `locale`, `where`, `order` and `limit`; `getLiveEntry("footer", { locale })` reads a global item, and `getLiveEntry("pages", { path, locale })` one page. In a preview the same reads return drafts. A global flagged `layout: true` is answered from the page's own read, so a layout's `getLiveEntry` calls cost no call ([Defining a global](https://smoodly.io/docs/globals/defining.md#layout-globals)).

## The cache

Every read tags the response with what it read. Once the page is rendered, the response is stored whole, and a publish expires exactly the tags it touched. The first request after a publish reads from the service again; the rest are served from the cache. A 404, a draft and anything under the preview address are never stored.

`memoryCache()` keeps pages in the server process's memory: one process, one cache. On Vercel, `cacheVercel()` stores them on the CDN instead; [Deploying](https://smoodly.io/docs/getting-started/deploying.md) shows the swap.

That is live mode, the default: pages render on demand and a publish is live at once. The other mode is static: with `output: "static"` in `astro.config`, every published page is built as a file, visitors need no function and no service, and editors press **Deploy** in the admin when their publishes should go live. Sections, schemas, the admin and the preview address are the same in both; [Deploying › Static](https://smoodly.io/docs/getting-started/deploying.md#static) has the switch and the Deploy tile.

## Preview

The admin's canvas loads a page at the preview address. A signed cookie, set for the admin's session, opens it; without the cookie the address is closed. Reads there return drafts, and the editor's bridge is added to the response. A live address never shows a draft and carries no Smoodly script. There is no pill: drafts are seen in the admin only.

## Images

`Image` from `smoodly/astro/components` renders an `f.image()` value as plain HTML, an `<img>` or a `<picture>`:

File: `src/sections/hero.astro`

```astro
{image && <Image image={image} class="hero__image" sizes="(min-width: 900px) 40vw, 100vw" priority {...m.field("image")} />}
```

The box keeps the crop's aspect and the `srcset` lists the cut's widths on Smoodly's media host, in AVIF or WebP, so Astro's image service, `/_image` and `image.remotePatterns` are not involved and no image setting is needed. `Head` opens a connection to the media host when the page shows an image. In static output the build writes every image its pages show into the output instead, so a static page loads its images from your own host. [Images and crops](https://smoodly.io/docs/media/images-and-crops.md) has named crops and the `media` prop.

## Languages

`i18n` in `astro.config.ts` and `locales` in the config name the same set; the site refuses to start when they disagree, and the installer writes both. Smoodly follows Astro's rule for the default locale: no prefix unless `routing.prefixDefaultLocale` says so. `Head` writes one hreflang link per language the page is published in. [Locales and routing](https://smoodly.io/docs/languages/locales.md) has the rest.

## A page of your own

A file under `src/pages/`, such as `src/pages/pricing.astro`, wins its address. A page an editor creates at `/pricing` saves and publishes, but visitors see your file, and the page editor says so. `src/pages/404.astro` is the site's "not found" page.

To write content from a script, see [Content from code](https://smoodly.io/docs/getting-started/content-from-code.md).
