---
name: build-astro-site
description: Builds a content site with Astro and TypeScript - pages and layouts, Markdown or MDX content collections with a typed schema, interactive islands only where needed, Tailwind styling, images and SEO basics, then a static or server build. Use when the user wants a blog, docs, marketing or portfolio site with Astro, or asks about islands or content collections.
license: CC0-1.0
metadata:
  category: frontend
  tags: "astro,typescript,website"
  author: johnny-bravo
  version: "1.0"
  updated: "2026-11-02"
  status: published
  aliases: "astro, content site, blog with astro, islands"
  source_url: "https://github.com/PatrickJS/awesome-cursorrules/blob/b044f956f021b6e8877f16781bcfc466a6a120e9/rules/astro-typescript-cursorrules-prompt-file.mdc"
  source_license: CC0-1.0
  copyright: "Public domain (CC0 1.0) - rules contributed to PatrickJS/awesome-cursorrules"
  original_author: "awesome-cursorrules contributors (astro-typescript rules)"
  modified: "Adapted by TheSkillVault: turned a JSON rules file into a build order with original examples; dropped commit-message and editor rules; added content collections, SEO, safety notes, gotchas, portability and done-when."
  imported_on: "2026-11-02"
---

# Build an Astro site

Astro ships plain HTML by default and adds JavaScript only to the parts that need it. That makes content sites fast with little effort.

## When to use
- You are building a blog, docs, portfolio or marketing site.
- Page speed and SEO matter more than app-like interactivity.
- You want to write content in Markdown or MDX.

## When not to use
- You are building a logged-in app with lots of interactive screens. A full app framework such as Next.js or SvelteKit fits better.

## Steps
1. Create the site: `npm create astro@latest`, choose TypeScript (strict), then `npm run dev`.
2. Add pages as `.astro` files in `src/pages`; `src/pages/about.astro` becomes `/about`.
3. Make a shared layout in `src/layouts` with the `<head>`, title and meta description as props.
4. Put posts in a content collection (`src/content/blog`) and define a typed schema with `defineCollection` and Zod in the content config.
5. List and render posts with `getCollection` and dynamic routes such as `src/pages/blog/[slug].astro`.
6. Add interactive parts as islands: a React, Svelte or Vue component with `client:visible` or `client:load`. Leave everything else static.
7. Add Tailwind with `npx astro add tailwind`, and use Astro's `<Image />` for optimised images.
8. Add the sitemap integration and an RSS feed, and set the `site` URL in the Astro config.
9. Build with `npm run build`. Static output deploys anywhere; add an adapter only if you need server rendering.

```astro
---
import { getCollection } from "astro:content";
import Layout from "../layouts/Layout.astro";
const posts = (await getCollection("blog")).sort((a, b) => +b.data.date - +a.data.date);
---
<Layout title="Blog" description="Notes and guides">
  {posts.map((p) => <a href={`/blog/${p.id}/`}>{p.data.title}</a>)}
</Layout>
```

## Gotchas
- Code in the `---` frontmatter runs at build or on the server; it never reaches the browser. Still, keep secrets in non-public env vars, as `PUBLIC_` values are exposed.
- Forgetting a `client:` directive makes a component render as static HTML with no interactivity.
- `client:load` everywhere throws away Astro's speed advantage. Prefer `client:visible` or `client:idle`.
- Set the `site` config, or canonical URLs and the sitemap will be wrong.

## Portability
Static builds deploy to Vercel, Netlify, Cloudflare Pages or GitHub Pages. If you use React, Svelte or Vue components, Astro supports all of them as islands.

## Example prompt
"Build an Astro blog with TypeScript, a typed content collection for posts, Tailwind, a sitemap and an RSS feed."

## Done when
- Pages build as static HTML and only island components ship JavaScript.
- Posts come from a typed content collection.
- The sitemap and RSS feed list every post, and `npm run build` passes.

---
Based on the Astro TypeScript rules file in PatrickJS/awesome-cursorrules (CC0 1.0, public domain). See LICENSE.txt.