Astro Build Log

dev starts the dev server on port 4321. build writes the production site to dist/, and preview serves that build locally. astro add installs an integration and edits astro.config.mjs for you; it is the safest way to add React, MDX, a sitemap or a deployment adapter. astro check type-checks your .astro files.

FrontmatterPlain TypeScript that runs once per render on the server. Top-level await works, secrets stay safe, and nothing here reaches the browser. interface Props types the props and Astro.props reads them. You will also use Astro.cookies, Astro.request, Astro.url, Astro.params and Astro.redirect() a lot.

Template{} holds expressions. Conditionals use && or ternaries, lists use .map(), as in JSX. The differences: write class instead of className, attributes are plain HTML, class:list builds class strings from arrays and objects, and there are no hooks or state because the template runs once.

Slots<slot /> is Astro's version of children. A named slot is filled by a child carrying slot="footer". Content inside the slot tag is the fallback.

<style>Scoped to this component automatically. Use <style is:global> or :global(.x) to escape the scope.

<script>Client JavaScript. Astro bundles it, compiles TypeScript and imports, loads it as a module, and includes it once even if the component appears ten times. Add is:inline to ship it exactly as written instead.

The server renders a custom element with a data-api attribute. The bundled script defines the element once, and the browser upgrades every copy on the page, including copies that arrive later through view transitions. For one-off values you can also use define:vars={{ value }} on a script, which makes it inline.

getStaticPaths runs once at build and returns one object per page. params fills the bracketed segment; props goes straight to the page so you never refetch. render(post) turns a Markdown entry into a <Content /> component plus its heading list, which you can use for a table of contents.

Pagination is built in: return paginate(posts, { pageSize: 10 }) from getStaticPaths in a [page].astro file, then read Astro.props.page for data, url.prev, url.next and currentPage.

With an adapter installed (section 08), prerender = false renders the page per request. There is no getStaticPaths; you read Astro.params directly and can return a redirect or a Response from the frontmatter.

Each exported HTTP method returns a standard Response. The context gives you params, request, url, cookies, locals and redirect. Leave out prerender = false and the endpoint runs once at build and writes a file, which is how rss.xml and JSON feeds are generated. Permanent redirects belong in config: redirects: { '/old': '/new' }.

Importing global.css in the layout applies it to every page that uses the layout. Astro.site comes from the site config option and is needed for canonical URLs, sitemaps and RSS. <ClientRouter /> is optional and turns on view transitions. The named head slot lets a page add its own meta tags:

Props must serializeStrings, numbers, booleans, arrays, plain objects, Date, Map, Set, URL and RegExp cross the boundary. Functions do not, so an .astro parent cannot pass an onClick. Keep event handling inside the island.

ChildrenChildren passed to an island are rendered on the server and arrive as static HTML (children in React). Static content can sit inside an interactive shell.

No shared contextEach island is its own React root, so context providers do not span islands. Share state with a small store such as Nano Stores, custom DOM events, or the URL.

The store exports one atom any island can import. useStore subscribes the badge, so when another island calls cartCount.set(3) the badge updates, even though the two islands are separate React roots. A vanilla <script> can import the same atom and call .subscribe().

globReads a folder of files; each file path becomes the entry id.

fileReads one JSON or YAML file holding an array or a keyed object.

inline loaderAny async function returning objects with an id. It runs at build, so remote data becomes static content.

schemaValidates at build and generates types. image() validates and optimizes local images; reference() links to entries in another collection. In Astro 6, import z from astro/zod.

getCollection returns every entry, with an optional filter; here drafts show in dev and disappear in production. getEntry resolves a reference to the full entry. The body is rendered with render(entry), shown in section 04.

Live collectionsStable in Astro 6. They fetch at request time instead of build time, for content that must change without a rebuild. Define them with defineLiveCollection (I believe in src/live.config.ts) and read them with getLiveCollection and getLiveEntry, which return { entry, error }. They need on-demand routes. Prefer build-time collections unless freshness matters.

server:defer lets a static, cacheable page hand one personalised piece to the server. The page loads at once with the fallback, then UserMenu is rendered separately (it can read cookies and query a database) and swapped in. Needs an adapter.

Every key on server becomes an action. accept: 'form' parses FormData and validates it before the handler runs; context holds cookies, locals and the request. The page posts the form straight to the action with no client JavaScript and reads the result on re-render. From a React island you call await actions.subscribe(formData) and get { data, error }.

auth reads the session cookie, stores the user on locals (read it as Astro.locals.user in any page), and redirects anonymous visitors away from /admin. timing wraps next() to add a header after the page renders. sequence runs them in order. Type locals by declaring App.Locals in src/env.d.ts. In Astro 6, middleware also runs during the build for prerendered pages, where there is no real request, so guard cookie and header reads.

Any .env value is available on the server as import.meta.env.NAME; only names starting with PUBLIC_ reach client code. The schema above adds validation and types: import secrets from astro:env/server and public values from astro:env/client.

The frontmatter takes a typed list and the template maps it to native <details> elements. The script is bundled once per page, even with several accordions, and closes the other panels when one opens.

The rest parameter sends every /app/* URL to this one page, and client:only skips server rendering so browser-only code inside the app keeps working. Set React Router's basename to /app. This needs an adapter because the paths are unknown at build. On a pure static host, use a single app.astro page and a host rewrite of /app/* to it instead.

The loading state, the two pieces of state and the effect all disappear: the list is fetched on the server and arrives as finished HTML. Link becomes a plain anchor. LikeButton is untouched React code that now hydrates only when scrolled into view, so the rest of the list ships no JavaScript. API_URL has no PUBLIC_ prefix because it is only read on the server.

className becomes class (here class:list), children becomes <slot />, and the types move into interface Props. Only convert components with no state or handlers; anything with useState stays React.

Importing from src/assets/ gives Astro the image's real size, so it can resize, convert to WebP and set width and height to stop layout shift. <Picture> outputs several formats. Remote images need explicit dimensions, and their domains must be listed in image.domains in config to be optimized. I am fairly sure priority is the current prop for eager-loading a hero image; check it if your version complains. Files in public/ are never optimized.

The Fonts API downloads and self-hosts the font at build, generates fallbacks and exposes it as a CSS variable. Both imports are confirmed by the Astro 6 post; the exact option names inside each entry are from memory, so compare with the Fonts guide.

<ClientRouter /> (formerly <ViewTransitions />) intercepts link clicks and animates between pages. transition:name pairs elements across pages for morph animations; transition:persist keeps an element alive, such as a playing audio player. Use astro:page-load for setup code. Without the router, modern browsers can still do cross-document transitions with the CSS @view-transition { navigation: auto; } rule.