Skip to content

Astro: introduction, setup and project structure

Astro is a web framework for content-driven websites: documentation, blogs, marketing sites, portfolios and stores where most of each page is content rather than application state. It renders pages to HTML on the server or at build time and sends no JavaScript by default; interactive parts are added as isolated β€œislands”. This site is itself built with Astro and its Starlight documentation theme.

This page is the starting point of the Astro section. It explains the model, then gets a project running and walks through the files it contains. The other two pages build on it: pages, layouts and content and integrations, build and deploy.

Everything here targets Astro 7 (astro 7.4.12 and create-astro 5.3.2 on npm at the time of writing). The samples belong to an invented OrdersPortal docs site with release notes and a status page; they were run with Astro 7.4.12 on Node.js 22.23.4 using the dev server.

Topic What it covers
What Astro is Server-first rendering, islands and when Astro is the right tool
Install and create a project Node.js requirement, npm create astro, dev server
Project structure src/pages, src/components, src/layouts, public/, config files
What changed in Astro 7 Upgrade notes that affect existing projects

Astro is server-first: every component renders to HTML on the server, either once at build time (static, the default) or per request with an adapter (on-demand rendering). The .astro component format looks like HTML with a frontmatter script fenced by ---; that script runs only on the server, so it can read files, call APIs with secrets and query a CMS without any of that code reaching the browser.

Interactivity comes from islands. You can use React, Preact, Svelte, Vue, Solid or Alpine components inside Astro pages, and each one stays static HTML unless you add a client:* directive such as client:visible. Only those components ship JavaScript, each island hydrates independently, and the rest of the page stays plain HTML. Server islands (server:defer) apply the same idea on the server: a slow or personalized component renders after the main page, so the cached page is not held back by it.

That makes Astro a strong fit when content is the product and pages must load fast on slow devices. It is a weaker fit for highly interactive single-page applications, such as a dashboard where nearly every element is stateful: there you would put the whole app in one large island, and a client-side framework such as Angular, React or Vue on its own may be simpler.

Pitfalls:

  • Expecting .astro components to be interactive. Code in the frontmatter never runs in the browser. Use a <script> tag or a framework component with a client:* directive for behavior.
  • Hydrating everything. Adding client:load to every framework component recreates the bundle size Astro is designed to avoid. Hydrate the smallest component that needs it, as late as possible.
  • Choosing Astro for an app shell. If most of the screen is interactive state, you get little benefit from islands and still pay for two component models.

Astro 7 requires Node.js 22.23.4 or later; odd-numbered Node.js releases such as 23 are not supported (the engines field of astro 7.4.12 is >=22.23.4). Check with node -v before you start; on older Node.js 22 releases the install fails with an engine error.

The create astro wizard scaffolds a project from a template, installs dependencies and can initialize Git. The dev server runs on port 4321 by default with hot module reloading. The terminal session below follows the official install guide; it is not reproduced here.

Terminal window
node -v # v22.23.4 or later (Node.js 24 or 26 LTS also work)
npm create astro@latest orders-portal-docs
cd orders-portal-docs
npm run dev # astro dev, http://localhost:4321
# Other package managers
pnpm create astro@latest orders-portal-docs
yarn create astro orders-portal-docs
# Add an official integration later, with config changes made for you
npx astro add mdx sitemap

To check the samples on these pages without the wizard, the project was created by hand: a package.json with "type": "module" and the scripts dev, build and preview mapped to astro dev, astro build and astro preview, then npm install astro@7. npx astro --version printed astro v7.4.12.

Add astro check to your workflow once TypeScript matters: tsc ignores .astro files, while astro check type-checks both .astro and .ts files. A common pattern is "build": "astro check && astro build".

Pitfalls:

  • An old Node.js 22. Astro 7.0 needed Node.js 22.12, 7.4.1 needed 22.22 and 7.4.2 raised the minimum to 22.23.4, so CI images pinned to an earlier 22.x fail after a patch upgrade. Pin the Node.js version in CI and in .nvmrc deliberately.
  • Relying on tsc for .astro files. It silently skips them; use astro check.
  • Editing astro.config.mjs by hand for integrations. It works, but astro add also installs matching versions and updates TypeScript settings where needed.

Astro uses a few reserved folders and leaves the rest to you. src/pages/ is required: every .astro, .md, .mdx or .html file there becomes a route, and .js or .ts files become endpoints. src/components/ and src/layouts/ are conventions for reusable components and page shells. src/content.config.ts defines content collections, and the content itself can live anywhere (often src/content/ or src/data/). Files in public/ are copied untouched to the root of the build output, which suits robots.txt, favicons and files that must keep their exact name; images you want optimized belong in src/ so Astro can process them.

At the root, astro.config.mjs holds the configuration (site URL, integrations, adapter, Markdown settings), package.json the scripts and dependencies, and tsconfig.json extends one of Astro’s presets (astro/tsconfigs/base, strict or strictest).

This is the structure of the sample project used across the Astro pages:

orders-portal-docs/
β”œβ”€β”€ astro.config.mjs # site: 'https://docs.example.test'
β”œβ”€β”€ package.json
β”œβ”€β”€ tsconfig.json # extends astro/tsconfigs/strict
β”œβ”€β”€ public/
β”‚ └── robots.txt # served as /robots.txt
└── src/
β”œβ”€β”€ content.config.ts # the "releases" collection
β”œβ”€β”€ content/
β”‚ └── releases/ # v2-0.md, v2-1.md
β”œβ”€β”€ data/
β”‚ └── status.json
β”œβ”€β”€ components/
β”‚ └── ReleaseCard.astro
β”œβ”€β”€ layouts/
β”‚ β”œβ”€β”€ BaseLayout.astro
β”‚ └── MarkdownLayout.astro
└── pages/
β”œβ”€β”€ index.astro # /
β”œβ”€β”€ status.astro # /status
β”œβ”€β”€ support.md # /support
└── releases/
└── [id].astro # /releases/v2-0/, /releases/v2-1/

Running npm run dev served /, /releases/v2-0/, /status and /support from this tree; the page code is on pages, layouts and content.

Pitfalls:

  • Putting importable assets in public/. Files there are not bundled, hashed or optimized. Keep CSS, scripts and images you import in src/.
  • Helper files in src/pages/. Every page file there becomes a route. Keep utilities and partial components elsewhere, or prefix a file name with _ to exclude it from routing.
  • Reserved names. Astro 7 treats src/fetch.ts (or .js) as the advanced routing entry point, as src/middleware.ts is for middleware. Rename an unrelated file with that name, or set fetchFile.

Astro 7.0 is mostly an internal upgrade, and many projects need no code changes, but a few defaults changed that can alter output. Upgrade with npx @astrojs/upgrade, which updates Astro and official integrations together, then build and compare.

  • Vite 8 is the dev server and bundler. Projects with custom Vite plugins or configuration should check the Vite 8 migration guide.
  • A Rust compiler replaces the Go-based .astro compiler. It is faster and stricter: unclosed non-void tags are now errors, and invalid nesting such as a <div> inside a <p> is passed through as written instead of being silently corrected.
  • SΓ€tteri is the default Markdown and MDX processor. It applies GitHub-flavored Markdown and SmartyPants as before. remark and rehype plugins need @astrojs/markdown-remark and the unified() processor, or a port to SΓ€tteri plugins.
  • compressHTML now defaults to 'jsx'. Whitespace between inline elements is stripped with JSX rules, so <span>hello</span> followed by <em>world</em> on the next line renders as helloworld. Add {" "} where you need a space, or set compressHTML: true to keep the old behavior.
  • Stable features: route caching (cache, routeRules), advanced routing, queued rendering and the new logger moved out of experimental. @astrojs/db was removed.

Astro 6 had already removed the legacy content collections API (collections now need a loader), removed Astro.glob(), and required Node.js 22. Code written for Astro 4 or earlier usually needs those changes too.

Pitfalls:

  • Upgrading two majors at once without reading both guides. Apply the v6 changes (collections, Astro.glob()) before the v7 ones, and build after each.
  • Missing spaces after upgrading. The whitespace default change is easy to miss in review; check navigation links and inline formatting visually.
  • Assuming remark plugins still run. Without @astrojs/markdown-remark and unified(), they are not applied in Astro 7.

What does β€œzero JavaScript by default” mean in Astro? Astro components render to HTML on the server and their frontmatter code never ships to the browser. JavaScript is sent only for <script> tags you write and for framework components you hydrate with a client:* directive.

What is an island, and how is it different from hydrating a whole page? An island is one interactive component on an otherwise static page, hydrated independently with its own JavaScript. A traditional SPA hydrates the entire page tree, so the cost grows with the page rather than with the interactive parts.

Where should an image you reference from a component live? In src/ (for example src/images/) and imported, so Astro can optimize it with <Image /> from astro:assets. public/ is for files that must be served unchanged at a fixed path.

Senior scenario: you inherit an Astro 4 documentation site and must move it to Astro 7. How do you plan it? Pin Node.js 22.23.4 or later in CI first. Upgrade one major at a time with @astrojs/upgrade, building after each: on v5 migrate collections to loaders in src/content.config.ts and replace Astro.glob() with import.meta.glob() or collections, which v6 requires. On v7 fix compiler errors from unclosed tags, decide between porting remark and rehype plugins to SΓ€tteri or opting into unified(), and review whitespace changes. Compare the built HTML of key pages before and after with a link checker and a visual diff, and ship each major separately.