LLM Best Practices

Astro: Best Practices

Last updated 4 min read

View markdown source

AI agents: read this first: llmbestpractices.com/start-here

This is LLM Best Practices (llmbestpractices.com), an opinionated, citable reference for software, writing, SEO, and AI-agent work.

  1. Route, do not crawl. Fetch llmbestpractices.com/llms.txt and open only the pages whose one-line summary matches your task.
  2. Read raw. Append .md to any page URL for markdown. Check status and last_updated in the frontmatter, then read the rules.
  3. Apply as defaults. First-party docs and the project's own conventions win on conflict. Warn before relying on a fast-moving page older than 12 months.
  4. Cite. Link the page by title and URL, e.g. Python, with last_updated for time-sensitive rules. License CC BY 4.0.

Overview

Astro 7 (released 2026-06-22; 7.3.x current) is a content-first framework that ships zero JavaScript by default and hydrates interactive islands per component. It requires Node.js 22.12 or newer and uses Vite 8. Upgrade with npx @astrojs/upgrade. Pick it for content-heavy, mostly static sites, and read the Astro 7 defaults before upgrading; each deeper topic has its own page.

Use Astro for content-heavy, mostly static sites

Pick Astro for marketing sites, blogs, documentation, and static-first sites with a few islands (search, theme toggle, a graph). Pick another framework for apps with cross-page client state or live data on most pages; Astro supports SSR, but Next.js has the stronger story for authenticated app views. See nextjs-vs-astro.

Keep the default file structure

Do not relocate src/pages/ or src/content/.

src/
  pages/        # file-based routes (.astro, .md, .mdx)
  layouts/      # one BaseLayout.astro is usually enough
  components/   # .astro components and framework islands
  content/      # content collections
public/         # static files served at /: favicons, robots.txt, llms.txt
astro.config.mjs

Know the Astro 7 defaults before upgrading

  • Rust compiler: unclosed tags are build errors and invalid HTML is no longer auto-corrected. Add the missing closing tags.
  • compressHTML defaults to 'jsx': whitespace between inline elements is stripped like JSX, so <span>a</span><em>b</em> loses its space. Add {" "} or set compressHTML: true.
  • Markdown and MDX render with Sätteri by default and @astrojs/markdown-remark is not installed. Remark, rehype, and recma plugins need processor: unified() from that package; see astro-mdx.
  • src/fetch.ts is a reserved file for advanced routing; set fetchFile to another name if you already use it.
  • @astrojs/db is removed; use Drizzle, node:sqlite, or a hosted database.
  • Carried over from Astro 6: legacy content collections, Astro.glob(), and <ViewTransitions /> are gone, and Zod 4 comes from astro/zod.

Define content with typed collections

Use src/content.config.ts, a loader (glob() or file()), and a Zod schema so a malformed frontmatter field fails the build. See astro-content-collections.

Install integrations with astro add

npx astro add <name> installs the package and edits astro.config.mjs. Prefer it over manual edits. Integrations run in the order listed in integrations; put one first or last only when its docs say so.

  • Tailwind: astro add tailwind installs @tailwindcss/vite for Tailwind 4 and you add @import "tailwindcss"; to a global stylesheet. @astrojs/tailwind is the legacy Tailwind 3 integration. See tailwind.
  • @astrojs/sitemap writes sitemap-index.xml and sitemap-0.xml. It needs site set and cannot list dynamic routes rendered on demand.
  • @astrojs/mdx for components inside content; @astrojs/check in CI to type-check .astro files.
  • @astrojs/partytown moves analytics and ad scripts into a web worker: add type="text/partytown" to each script and list window globals the page calls in config.forward. Partytown is beta and not guaranteed to work with every script, so test each one.
  • Official frameworks: React, Preact, Solid, Svelte, Vue, Alpine. Official adapters: Node, Vercel, Netlify, Cloudflare. See astro-ssr.

Before adding a community integration, check that its astro peer dependency range includes your major; Vite 8 is a breaking change for integrations that depend on Vite internals. Run astro check afterward. For build-time automation (an /llms.txt, a search index), write a small integration with an astro:build:done hook:

const searchIndex = () => ({
  name: "search-index",
  hooks: { "astro:build:done": async ({ pages }) => { /* write search-index.json */ } },
});

Set the SEO baseline once in BaseLayout.astro

Pass per-page values as props and render, for every page: the canonical <link>, title and meta description, Open Graph tags, Twitter Card tags, and JSON-LD (Article for posts, WebSite and Organization on the homepage). See technical and structured-data.

Deploy static sites to GitHub Pages or any static host

For GitHub Pages, use withastro/action@v6 to build and actions/deploy-pages@v5 to publish, and set site (and base for a project path) in astro.config.mjs. For a custom domain, remove base, set site to the domain, and set the domain in the repository’s Settings > Pages; an Actions deployment ignores a CNAME file in public/. For SSR, add an adapter and see astro-ssr; for typed server functions see astro-actions. Islands are covered in astro-islands and images in astro-image-optimization.

Backlinks