How to Use Astro: The Beginner's Guide (First Project, Islands Architecture, and the Zero-JavaScript Default)

CodexFuse Team · 2026-10-31T03:57:27.257Z · 12 min read

Install Astro free, scaffold your first project, build pages from components and layouts, hydrate islands only where you need interactivity, and deploy — a beginner's guide to the content-first web framework.

What is Astro, and when should you use it?

Astro is a web framework for content-driven websites that renders your pages to HTML and ships zero JavaScript to the browser by default. This guide teaches you how to use Astro from a clean install: scaffold your first project, build pages from components and layouts, add interactive islands only where you need them, and deploy the finished site. It is aimed at HTML-capable beginners — you do not need React or Vue experience to follow along.

Astro fits best when your site is mostly content: blogs, documentation, marketing pages, portfolios, and content-heavy storefronts. The framework's bet is simple: most of a page is static text and images, so most of it can be plain HTML. Interactive pieces — a carousel, a search box, a newsletter form — are loaded as isolated "islands" of JavaScript inside that sea of static markup. The official Astro documentation calls this approach partial or selective hydration, and it is the reason Astro sites tend to score well on performance audits out of the box.

If you are building a deeply interactive app — a dashboard, a game, a real-time collaboration tool — a single-page-app framework is the more honest choice. Astro is not trying to be that. For a content site, though, it removes the tax you usually pay: no framework runtime downloads just to render text. The what is VPS hosting guide is the companion read if your end goal is self-hosting the finished site.

How do you install Astro and start your first project?

You install Astro with the official setup wizard, npm create astro@latest, which creates the project and walks you through its choices. Before you run it, check that your Node.js version meets the current floor: the Astro docs require Node.js v22.23.4 or higher, and explicitly note that odd-numbered versions like v23 are not supported. Beginners hit a cryptic scaffold failure at exactly this step, so run node -v first.

1. Run the wizard. In your terminal, type npm create astro@latest and answer its prompts. It asks where to create the project (it can create the folder for you), which starter template to use, whether to install dependencies now, and whether to initialize a Git repository. While learning, pick the empty starter.
2. Enter the project. cd into the new project directory. If you skipped the install-dependencies step, run npm install now.
3. Start the dev server. Run npm run dev (this calls astro dev). The terminal prints the local URL — the dev port defaults to 4321, so open http://localhost:4321 in your browser. The server uses Hot Module Replacement, so saved changes appear in the browser without a manual refresh.
4. Confirm it is alive. You should see the starter page. Open the project in VS Code — the Astro docs recommend it, with their official Astro extension — and you are ready to build.

The wizard has equivalents for other package managers: pnpm create astro@latest and yarn create astro. If you live in the pnpm world, the pnpm beginner guide covers that toolchain's install and update flow.

How does an Astro project fit together?

An Astro project uses file-based routing: every file you put in src/pages becomes a route on your site. A fresh project has a small, predictable shape, and knowing it saves you from hunting through folders later.

The magic file is the one in src/pages. Create src/pages/about.astro with some markup, save, and /about exists — no router to configure. Nested folders make nested routes: src/pages/blog/first-post.astro becomes /blog/first-post. The wizard also offers a one-flag shortcut for starters: npm create astro@latest -- --template <github-username>/<github-repo> scaffolds from any GitHub theme's main branch, which is the fast lane for blogs and docs sites. When your first project outgrows your machine, the GitHub beginner guide shows how to push it to a repository for deploying.

What do Astro components and layouts look like?

An Astro component is a .astro file with two parts: an optional component script between two --- fences, and the template below it. The script runs once at build time (or on the server) — it never reaches the browser — and the template is the HTML it renders.

Here is the smallest honest example:

---
const greeting = "Hello, Astro!";
---
<html>
  <body>
    <h1>{greeting}</h1>
  </body>
</html>

The braces {greeting} inject the script's value into the markup. CSS written in a <style> block inside the component is scoped to that component by default, so a h1 { color: orange } rule here cannot leak into other pages. That scoping is one less thing for beginners to debug.

How do layouts keep your pages consistent?

A layout is just a component that wraps other pages. The standard pattern passes page-specific values — like the title — in as props and renders the page's own content through a <slot />:

---
// src/layouts/Layout.astro
const { title } = Astro.props;
---
<html>
  <head><title>{title}</title></head>
  <body>
    <header>…your site header…</header>
    <slot />
    <footer>…your site footer…</footer>
  </body>
</html>

Every page then imports the layout and hands it a title. One layout file, one header, one footer — change it once and every page updates. This is the piece beginners should build first, before any interactive widget.

What is the islands architecture?

The islands architecture renders almost everything on the page as static HTML, then "hydrates" only the parts that need JavaScript — each interactive component becomes an island floating in a sea of static markup. The term "component island" was coined by Etsy's frontend architect Katie Sylor-Miller in 2019 and expanded by Preact creator Jason Miller in 2020; Astro's docs credit Astro as the first mainstream JavaScript framework to build selective hydration in as the default, per its islands architecture guide.

The rule to internalize first: every UI component renders to HTML with no client-side JavaScript unless you explicitly opt in. A React component dropped into an Astro page renders as static HTML — the interactivity does not work — until you add a client:* directive. This is deliberate: it protects you from accidentally shipping JavaScript you never meant to send, and it is the most common beginner confusion in Astro.

You choose when each island loads with a directive:

Islands hydrate in isolation and load in parallel, so a heavy carousel lower on the page never blocks the header's interactivity. Because the choice is per component, you can be strategic: mark the newsletter form client:visible and it ships zero bytes until someone scrolls to it.

What are server islands?

Server islands are the mirror image: components whose server rendering is deferred, using the server:defer directive. The page's main content renders immediately with placeholder content, and the slow dynamic piece — a logged-in user's avatar, live pricing — fills in when ready. The main content does not wait for the slowest widget, and the outer page shell stays aggressively cacheable.

How do you add a React component as an island?

You add a framework integration with astro add, then mark the component with a client directive where you use it. Astro is UI-agnostic: the docs list React, Preact, Svelte, Vue, and SolidJS as supported, and you can mix several frameworks on the same page because each island runs in isolation.

1. Add React. Run npx astro add react in the project root. It updates astro.config.mjs and installs the renderer automatically.
2. Write the component. Create src/components/Counter.jsx as you would in any React project — a button with useState.
3. Mark it as an island. In your page:

   ---
   import Counter from '../components/Counter.jsx';
   ---
   <h1>Static page content</h1>
   <Counter client:visible />

   The heading ships as HTML; only the counter loads JavaScript, and only when scrolled into view.

The wizard can do this at scaffold time too: npm create astro@latest -- --add react --add partytown starts the project with React and the Partytown script-loading integration preconfigured.

How do content collections organize a blog?

Content collections turn a folder of Markdown files into a typed, queryable data source. They are how Astro wants you to build a blog: posts live in src/content/blog/, each with frontmatter (title, date, description), and a src/content.config.ts file declares the collection's shape with Zod validation.

// src/content.config.ts
import { defineCollection } from 'astro:content';
import { glob } from 'astro/loaders';
import { z } from 'astro/zod';

const blog = defineCollection({
  loader: glob({ base: './src/content/blog', pattern: '**/*.{md,mdx}' }),
  schema: z.object({
    title: z.string(),
    description: z.string(),
    pubDate: z.coerce.date(),
  }),
});

export const collections = { blog };

You query the collection with getCollection('blog') and render each entry — for example, building the blog index and generating one route per post from the same data. The schema gives you type safety and editor autocomplete, and the docs note collections scale to tens of thousands of entries because the data is cached between builds. Collections come in two flavors: build-time (the default above, prerendered) and live collections that fetch at request time for frequently changing data — build-time is the right default for a blog.

Astro vs Next.js: which one should a beginner pick?

Pick Astro if your site is content-first; pick Next.js if your app is interaction-first. They optimize for different shapes of the web, and choosing by that shape keeps you out of trouble.

A beginner who knows HTML and is building a blog or portfolio will ship faster with Astro and a lighter page. A beginner whose goal is a job building React apps should learn Next.js — the ecosystem gravity is real. Neither choice is wrong; they just serve different sites.

How do you build and deploy an Astro site?

You build with npm run build, which renders every page and writes static files to dist/. Astro is static by default — the output is plain files any static host can serve — but not static-only: selected routes can render on demand with an adapter for your platform, so you add server rendering only to the routes that need cookies, authentication, or live data.

Before deploying, preview the production output locally with npm run preview — it serves dist/ so you catch build-only problems before they are public. Then ship the dist/ folder to a static host (Netlify, Vercel, Cloudflare Pages, GitHub Pages, or your own server). The deployment is boring on purpose: it is files, not a running process. If you want full control of the server underneath, pair the build with a self-hosted VPS (the VPS hosting guide linked earlier in this article walks through that decision); if your deploy pipeline needs review workflows, the GitLab beginner guide covers CI pipelines that can build and ship dist/ on every push.

Sources

All facts in this article were verified against the pages below on 2026-10-30. Claims about Astro 6.x popularity and the Cloudflare acquisition are reported by the named guide, not measured by CodexFuse.

• Astro official documentation — Install Astro: Node.js v22.23.4+ prerequisite (odd versions like v23 unsupported), npm create astro@latest wizard, --add and --template flags, pnpm/yarn equivalents. https://docs.astro.build/en/install-and-setup/
• Astro official documentation — Islands Architecture: term coined by Katie Sylor-Miller (Etsy, 2019), expanded by Jason Miller (Preact creator, Aug 2020); default strips client-side JavaScript; client:* directives (client:load, client:idle, client:visible); server:defer server islands; supported frameworks React, Preact, Svelte, Vue, SolidJS. https://docs.astro.build/en/concepts/islands/
• Astro official documentation — CLI Commands: dev server default port 4321 (--port flag), astro dev with HMR, astro build to dist/, astro preview, package.json script equivalents. https://docs.astro.build/en/reference/cli-reference/
• Astro official documentation — Content Collections: src/content.config.ts, defineCollection(), glob()/file() loaders, Zod schema, getCollection(), build-time vs live collections. https://docs.astro.build/en/guides/content-collections/
• Dmytro Shramko — "Astro Framework Guide: Build Faster Sites in 2026" (updated May 6, 2026): reports Astro 6.x, 57K+ GitHub stars, and Cloudflare's acquisition of Astro in January 2026. https://shramko.dev/blog/astro
• Flavio Copes — "Introduction to Astro" (updated Jul 18, 2026): static by default, not static-only; on-demand rendering via adapters; client:visible islands example. https://flaviocopes.com/astro-introduction/
• DevNudge — "How to setup and use Astro": bun create astro@latest path, dev URL at localhost:4321, src/pages file-based routing with dynamic [id].astro routes. https://devnudge.io/astro

Frequently Asked Questions

Do I need to know a JavaScript framework to use Astro?

No. Astro is HTML-first: you can build a complete site with .astro components, which are HTML plus a little build-time JavaScript. Framework components are only needed when you want specific interactive widgets, and even then you add them as isolated islands.

Why is my React component not interactive in Astro?

Because you did not add a client:* directive. Astro renders every UI component to static HTML with all client-side JavaScript stripped by default. Add client:load, client:idle, or client:visible to the component where you use it and the interactivity works.

What Node.js version does Astro need?

Node.js v22.23.4 or higher, per the official install docs. Odd-numbered versions like v23 are not supported. Check with node -v before running the setup wizard — an old Node is the most common cause of a failed scaffold.

Can I mix React and Vue in one Astro project?

Yes. Because each island hydrates in isolation, you can render React, Vue, Svelte, Preact, and SolidJS components on the same page. Add each framework's integration with astro add (for example npx astro add react) and mark components with client:* directives as usual.

Is Astro only for static sites?

No — static is the default, not the limit. Astro can render selected routes on demand using an adapter for your hosting platform, which covers pages that need cookies, authentication, or live data. Start static and add on-demand rendering only to the routes that need it.