So you’re curious about Astro?
That’s awesome. I love when people are willing to dip their toes into something new, especially in the wild world of JavaScript frameworks. Honestly, sometimes all those choices can feel overwhelming. Over the past few years, I’ve watched Astro go from a “hmm, what’s this?” to being my go-to tool for building fast websites, especially for content driven websites like marketing sites, blogs and documentation sites that need to load in the blink of an eye.
Let’s dive right into A Beginner’s Guide to Astro Framework, not just a step-by-step tutorial, but my honest take on how to use Astro, the little head-scratcher moments I had, plus beginner tips that’ll save you from some classic rookie blunders.
Picture this: It was late 2022, I’d wrapped up yet another React project (Next.js fans will know what I mean by that tiring “client-side bundle” feeling) and needed to build a simple docs site for one of our clients. Their biggest demand: speed, blazing fast load times because their users often worked from spotty internet connections.
I tried static site generators before but always ran into bloat or configuration headaches. Our CEO slid into my DMs: “Hey Somrat, have you given Astro a look?”
After half an evening tinkering with it… man, was I hooked. The first thing that blew me away: how much faster and simpler it felt setting up compared to Next.js or Gatsby, and how little JavaScript shipped by default.
I’m gonna walk you through an actual Astro project setup, which is way less scary than it sounds.
Ready? Open your terminal and type:
npm create astro@latest
This launches a friendly CLI wizard, think of it like Choose Your Own Adventure books for web dev:
my-first-astro)blog or minimal are both great starts, if unsure, choose blog)All done. Hop into your shiny new directory:
cd my-first-astro
npm run dev
Now visit http://localhost:4321. That’s your starter Astro site running locally. Pretty quick compared to messing around with Next.js configs or waiting forever for Gatsby builds, right?
Don’t overthink your setup at first. I once lost two hours tweaking config files instead of diving in with Astro’s defaults. Just get started and tweak later!
If there’s one thing most beginners trip on (me included), it’s not knowing where files live or what goes where the first time they clone something new. Here’s what stood out when I opened my first Astro folder:
src/
pages/
index.astro # Home page 🚀
about.astro # About page example
components/
Header.astro # Navbar/Header example
public/ # Static assets (images etc.)
astro.config.mjs # Main config file
package.json # NPM stuff as usual
The beauty here? Pages become routes automatically by filename inside pages/. So if you drop in blog/hello-world.astro, boom, you’ve got /blog/hello-world.
I once wasted ages hand-wiring routes in React Router; seeing Astro do this out-of-the-box felt so refreshing.
Let me show you how dead-simple components are in an Astro Framework tutorial style walkthrough.
Open up src/pages/index.astro and peek inside, it’s basically HTML sprinkled with some extra power. Try editing it:
---
const welcome = "Welcome to My First Astro Site!"
---
<html>
<head>
<title>Astro Rocks</title>
</head>
<body>
<h1>{welcome}</h1>
<p>This page was built crazy-fast using static site generation with Astro.</p>
</body>
</html>
Notice those triple dashes at the top. That lets you write JavaScript directly inside .astro files, a killer feature when pulling in data or variables.
Pro Tip: You don’t need to wrap everything in
<div>soup like old-school React days. Write straight-up HTML until you need reusable logic with components.
Here's where things start to come together. Something no other modern framework does quite like Astro: you can mix React, Vue, Svelte components right alongside basic .astro ones.
I actually plugged in both Svelte and React widgets into one doc site last year while migrating content without any headaches.
Say you want a dynamic counter component from React:
npm install @astrojs/react react react-dom
Then add support in your config:
// astro.config.mjs
import react from '@astrojs/react';
export default {
integrations: [react()],
};
Create /src/components/MyCounter.jsx, then use it within your .astro page:
---
// src/pages/index.astro example snippet:
import MyCounter from '../components/MyCounter.jsx'
---
<MyCounter client:load />
The special part here is client:load, it tells Astro to only activate JS on just that component when needed (“islands architecture”).
This approach saved one of our clients hundreds of milliseconds per page load because we could keep most pages purely static for SEO win, and sprinkle interactivity only where truly needed.
Inside any .astro file's frontmatter block (--- ... ---) we can fetch data at build-time:
---
const posts = await fetch('https://jsonplaceholder.typicode.com/posts').then(res => res.json());
---
<ul>
{posts.slice(0,3).map(post => (
<li><a href={`/posts/${post.id}`}>{post.title}</a></li>
))}
</ul>
When you run npm run build, every route gets pre-rendered as plain HTML, the gold standard for speed and SEO friendliness.
I once rebuilt a multi-language non-profit website using just markdown + API calls +
.astrotemplates… then realized Google indexed their pages within days. That never used to happen so fast with JavaScript-heavy SPA frameworks.
Deploying an Astro site feels easier than burning toast (and trust me, I’ve ruined breakfast more often than deployments). Most hosting services love static output:
npm run build/dist folder straight up to Netlify/Vercel/GitHub PagesFor small businesses or personal projects just stick with static hosting. The peace-of-mind plus wicked-fast speeds still make me happy dance every launch day.
| Feature | Astro | Next.js |
|---|---|---|
| Default Output | Static HTML | Hybrid, Static/Server-Side |
| JS Shipped | Only what's absolutely needed | Usually bundles lots by default |
| Simplicity | Very beginner-friendly | More moving parts |
| Flexibility | Mix any UI framework | Mostly locked into React |
| Ideal Use | Blogs/docs/marketing sites; absurdly fast! | Apps w/ user auth/dashboards |
For pure content-driven sites where every ms matters, building fast websites with Astro has been game-changing for both performance numbers and developer sanity. But if you're deep into dynamic apps needing real-time server stuff or complex state management across pages, Next.js still rocks that world.
/src/pages/blog/my-post.md. Instant blog post magic!I wanted this Beginner’s Guide to Astro Framework to feel like we were sitting across Zoom screens together while sipping coffee and geeking out over cool tools.
If there was ever a time where picking up cutting-edge frontend didn’t mean spinning up Docker containers or memorizing weird GraphQL syntax, it’s now. Give this lightweight stack a try, play around fearlessly, remember speed doesn’t have to be intimidating.
Thanks for reading till the end.