FrameworksAstro

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.

View as Markdown

The integration

One line in astro.config.ts mounts Smoodly:

astro.config.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:

FolderWhat it renders, and its props
src/page-types/<name>.astroA page type. It receives `page` (where the page sits: title, path, ancestors, children, locales), `zones` and `head`.
src/sections/<name>.astroA section. Its fields arrive flat, with `settings` and `styles`.
src/elements/<name>.astroAn element inside richtext. Its fields and `settings`.
src/entry-pages/<collection>.astroThe 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 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:

src/live.config.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:

src/page-types/articlesIndex.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).

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 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 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>:

src/sections/hero.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 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 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.

Edit this page on GitHubLast updated 16 Oct 2026