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.
Topics on this page
Section titled βTopics on this pageβ| 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 |
What Astro is
Section titled βWhat Astro isβ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
.astrocomponents to be interactive. Code in the frontmatter never runs in the browser. Use a<script>tag or a framework component with aclient:*directive for behavior. - Hydrating everything. Adding
client:loadto 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.
Install and create a project
Section titled βInstall and create a projectβ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.
node -v # v22.23.4 or later (Node.js 24 or 26 LTS also work)npm create astro@latest orders-portal-docscd orders-portal-docsnpm run dev # astro dev, http://localhost:4321
# Other package managerspnpm create astro@latest orders-portal-docsyarn create astro orders-portal-docs
# Add an official integration later, with config changes made for younpx astro add mdx sitemapTo 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
.nvmrcdeliberately. - Relying on
tscfor.astrofiles. It silently skips them; useastro check. - Editing
astro.config.mjsby hand for integrations. It works, butastro addalso installs matching versions and updates TypeScript settings where needed.
Project structure
Section titled βProject structureβ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 insrc/. - 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, assrc/middleware.tsis for middleware. Rename an unrelated file with that name, or setfetchFile.
What changed in Astro 7
Section titled βWhat changed in Astro 7β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
.astrocompiler. 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-remarkand theunified()processor, or a port to SΓ€tteri plugins. compressHTMLnow 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 ashelloworld. Add{" "}where you need a space, or setcompressHTML: trueto keep the old behavior.- Stable features: route caching (
cache,routeRules), advanced routing, queued rendering and the new logger moved out ofexperimental.@astrojs/dbwas 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-remarkandunified(), they are not applied in Astro 7.
Interview questions
Section titled βInterview questionsβ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.
Related pages
Section titled βRelated pagesβ- Pages, layouts and content: routing, components, layouts, Markdown, collections and data fetching.
- Integrations, build and deploy: integrations, adapters, static and on-demand output, hosting.
- Static websites overview and static site generators compared