Getting Started with Astro

By Syncfusion®, Inc. · Last updated November 14, 2026

What Astro is and why it was created, its features, the HTML-first approach, what you can build, Astro vs Next.js and React, the ecosystem, system requirements, creating and running a project, its files, and the Astro CLI.

Astro Introduction

• Astro is a tool for building websites.
• It is best for sites with a lot of content, such as blogs, docs and shop pages.
• It turns your code into plain HTML pages that load very fast.
• It adds JavaScript only to the parts of a page that need it.
• In this lesson, you will see what Astro is and create your first Astro site.

Simple lesson: Astro builds fast websites from plain HTML, and adds JavaScript only where you ask for it.

A Real-World Example

• Asha is a computer science student in Chennai.
• She wants a personal site called Asha's Dev Journal.
• It will have a home page, an about page and many blog posts.
• Visitors only read the pages. Nothing needs to move or change.
• She wants it to open fast, even on a slow phone network.
• Astro is a good fit, because it sends ready-made HTML and almost no JavaScript.

Press ▶ Run to build Asha's first page. Then click HTML sent to browser under the preview.

What happened:

• The part between the two --- lines is the component script. It runs when the site is built.
• {siteName} puts the value of siteName into the page.
• The HTML sent to browser view shows only HTML. There is no <script> tag at all.

What You Will Learn

In this lesson, you will learn:

1. What Astro is and why it was created.
2. The main features of Astro.
3. What "HTML first" and "zero JavaScript by default" mean.
4. What you can build with Astro, and when to pick another tool.
5. The Astro ecosystem: themes, Starlight and the docs.
6. What you need to install on your computer.
7. How to create, run, build and preview an Astro project.
8. What the main files and folders of a project do.

What Is Astro?

• Astro = a web framework for building fast, content-driven websites.
• Web framework = ready-made code and rules that help you build websites faster.
• Content-driven = the site is mostly things to read or look at: text, images and lists.
• Astro is free and open source.
• You write pages in .astro files. They look like HTML with a few extras.

HTML First

• A browser needs HTML to show a page.
• Many modern tools send JavaScript first. The browser then runs it to make the HTML.
• Astro does it the other way round. It makes the HTML before anyone visits.
• The visitor's browser gets a finished page. It can show it at once.

Watch the animation. Astro builds HTML once. Every visitor gets the same ready page.

Simple lesson: Astro does the work before the visitor arrives, so the visitor's browser has less to do.

Why Astro Was Created

• Many sites, like blogs and docs, are mostly text and pictures.
• Tools made for apps often send these sites a lot of JavaScript anyway.
• The phone must download and run that JavaScript before the page works.
• On a cheap phone or a slow network, this makes the page feel slow.
• Astro was made for these content sites. Version 1.0 came out in 2022.
• Its idea is simple: send HTML, and send JavaScript only where it is needed.

Features of Astro

• Content-driven. Made for sites full of text, images and posts. It has built-in tools for Markdown and blog posts.
• Server-first. Pages are made into HTML before they reach the visitor. The visitor's browser does not build them. This is why they load fast.
• Zero JavaScript by default. A page ships no JavaScript unless you add some. Less to download means a faster page.
• UI-agnostic. You can use React, Vue, Svelte or other UI tools inside Astro. You are not locked to one.
• Fast by default. You get a fast site without extra work. The features above do the work for you.

Simple lesson: Astro was made for content sites, so its default choices make content sites fast.

The Astro Approach

JavaScript Only Where Needed

• Most of a page never changes after it loads: headings, text, pictures, links.
• Only a few parts react to the visitor: a menu button, a like button, a search box.
• Astro sends plain HTML for the parts that never change.
• It adds JavaScript only for the parts that react.
• Astro calls these small interactive parts islands. You will learn them in Astro Islands.

Watch the animation. The page is a sea of plain HTML. Only the like button needs JavaScript.

See It in Code

• The lab below has a page with one button.
• The heading and the list are plain HTML.
• Only the <script> tag adds JavaScript, for the button.

Press ▶ Run and click the button. Then open HTML sent to browser and find the one <script> tag.

What to compare:

• The list: it arrives as three finished <li> tags. The browser runs nothing to make it.
• The button: it needs the small <script> to count clicks.
• The size: the JavaScript is a few lines, not a whole framework.

Simple lesson: in Astro, JavaScript is something you add on purpose, only to the parts that react.

What You Can Build with Astro

Astro is a very good fit for:

• Blogs and personal sites.
• Documentation sites.
• Marketing and landing pages.
• Portfolios.
• Online shop pages, such as product lists and product pages.
• News and magazine sites.

Astro is a weaker fit for:

• Apps where almost every part reacts all the time. Examples: a photo editor or a chat app.
• Apps that work like a game, with the screen changing every second.

For those, a tool built for apps, such as React or Next.js, is often easier.

Simple lesson: the more your site is "read and look", the better Astro fits.

Astro Compared to Other Tools

Astro vs React

• React = a JavaScript library for building interactive user interfaces.
• React builds the page in the browser by default, with JavaScript.
• Astro builds the page into HTML before the visit.
• They are not rivals. You can use React components inside an Astro page.

Astro vs Next.js

• Next.js = a framework built on React for building full web apps.
• Next.js is made for apps first. Every page is a React app.
• Astro is made for content first. A page is HTML unless you add an island.
• Both can make pages ahead of time and on a server.

When to Choose Astro

Simple lesson: pick Astro when your site is mostly content. Pick an app framework when your site is mostly interaction.

The Astro Ecosystem

• Ecosystem = the tools, add-ons and help that grow around a framework.
• Themes and starter templates = ready-made Astro sites you can copy and change. The Astro website lists many of them.
• Starlight = an official Astro tool for building documentation sites. It gives you search, a sidebar and dark mode.
• Integrations = add-ons you plug into Astro, such as React, Tailwind CSS or a sitemap. You will add one in Project Structure and Configuration.
• Astro docs = the official guide at docs.astro.build. It has a free step-by-step tutorial that builds a blog.

Simple lesson: you rarely start from zero. Use a starter, a theme or Starlight, then change it.

Astro Versions and Release Cycle

• This course uses Astro 7, the current major version. It came out in 2026.
• A major version (5, 6, 7) can change or remove old features.
• A minor version (7.1, 7.2) adds features without breaking your code.
• A patch version (7.4.11) fixes bugs.
• Astro usually ships one new major version each year, and new minor versions every few weeks.

When you read an old blog post, check the version. Some old code no longer works in Astro 7. For example:

• Astro.glob() was removed. You will learn its replacement in Markdown and MDX.
• output: "hybrid" was removed. You will learn why in How Astro Renders Pages.

Simple lesson: check the Astro version before you copy code from the internet.

Before You Start: System Requirements

You need three things on your computer.

Node.js

• Node.js = a program that runs JavaScript outside the browser. Astro's tools run on it.
• Astro 7.4 needs Node.js 22.23.4 or newer.
• Use an even-numbered LTS release, such as 22 or 24. LTS means "long-term support".
• The Astro docs say odd-numbered releases, such as 23 or 25, are not supported.
• Download it from nodejs.org. The installer also installs npm, the tool that downloads packages.

Check it in a terminal:

node -v

• It prints a version such as v24.11.0.
• If it prints an error, or a version below 22.23.4, install the newest LTS version.

A Code Editor

• VS Code is free and the most common choice.
• Install the official Astro extension. It colours .astro files and suggests code as you type.

A Terminal

• Terminal = a window where you type commands.
• On Windows, use PowerShell or the terminal inside VS Code.
• On a Mac or Linux, use the Terminal app.

Simple lesson: Node.js, an editor and a terminal are all you need. All three are free.

Creating an Astro Project

The Setup Wizard

• Run npm create astro@latest in a terminal.
• It starts a setup wizard: a few questions with good default answers.

• It asks four things:

  • where to create the project,
  • which starter template to use,
  • whether to install the packages,
  • whether to start a Git repository.
• Press Enter to accept each default.

Click Next to see each command and what it prints.

Choosing a Starter Template

The wizard offers these starters:

• A basic, helpful starter project (recommended): one page with a little styling.
• Use blog template: a ready blog with posts.
• Use docs (Starlight) template: a ready documentation site.
• Use minimal (empty) template: one empty page. Good for learning.

TypeScript and JavaScript

• TypeScript = JavaScript with types. Types tell your editor what kind of value a name holds.
• The Astro 7 wizard does not ask about TypeScript any more.
• Every new project gets a tsconfig.json with Astro's strict settings.
• If you write TypeScript: you are ready. Write types in your .astro and .ts files.
• If you write JavaScript: you are ready too. Write plain JavaScript and .js files. tsconfig.json still gives your editor hints.
• Pick your flavour with the TypeScript / JavaScript switch in the top bar. Every lab on this site follows it.

Useful Flags

• Flag = an extra word after a command that changes what it does. It starts with --.

npm create astro@latest -- --template minimal
npm create astro@latest -- --template blog --add react

• --template picks a starter without asking.
• --add adds an integration, such as React, while creating the project.
• The first -- tells npm to pass the flags on to the wizard.

Using pnpm, Yarn or Bun

npm is not the only package manager. These commands do the same job:

pnpm create astro@latest
yarn create astro
bun create astro@latest

• Use the one your team already uses.
• This course uses npm.

Manual Installation

• You can also set up a project by hand: make a folder, run npm install astro, and add src/pages/index.astro.
• The wizard does all of this for you, so most people use it.

Simple lesson: run npm create astro@latest, accept the defaults, and you have a working site.

Project Structure

A new project has a few files and folders. Click each one to see its job.

The most important rule:

• Every .astro file in src/pages/ becomes a page of your site.
• src/pages/index.astro becomes / (the home page).
• src/pages/about.astro becomes /about.

You will meet every file in detail in Project Structure and Configuration.

Try It: Add a Second Page

• The lab has two pages: index.astro and about.astro.
• Press ▶ Run, then click the About link in the preview.
• The address bar changes to /about. You can also pick a page from the address bar.

Simple lesson: to add a page, add a file to src/pages.

Running the Project

The Dev Server

• Run npm run dev inside your project folder. It runs astro dev.
• Dev server = a small test website that runs on your own computer.
• Open http://localhost:4321 to see your site. 4321 is Astro's default port.
• Port = a numbered door on your computer that a program listens on.
• Press Ctrl+C in the terminal to stop it.

Hot Reloading

• Hot reloading = the browser updates by itself when you save a file.
• You do not need to press refresh.
• Edit a file, save it, and look at the browser. The change is already there.

Changing the Port

If another program already uses port 4321, start Astro on another port:

npm run dev -- --port 3000

Build and Preview

• npm run build runs astro build. It makes the finished site in the dist/ folder.
• npm run preview runs astro preview. It shows the dist/ folder, so you can check the real result.
• You upload the dist/ folder to a web host. You will do this in Deploying Your Site.

Where Your Code Runs

• The component script (between the --- lines) runs on your computer when the page is built.
• Its console.log prints in the terminal, not in the browser.
• A <script> tag runs later, in the visitor's browser.
• Its console.log prints in the browser's console.

Press ▶ Run. The Terminal view tags each line with where it ran. Then click the button.

What to compare:

• [terminal] lines: printed while Astro built the page.
• [browser] lines: printed by the <script> in the visitor's browser.
• On your own computer: the first line appears in the terminal that runs npm run dev. The others appear in the browser's developer tools.

Simple lesson: the component script runs at build time. The <script> tag runs in the browser.

The Astro CLI

• CLI = command-line interface: a tool you use by typing commands.
• astro is Astro's CLI. npm run dev is a short way to call astro dev.

Two commands help you when you are stuck:

npx astro --help
npx astro info

• astro --help lists every command and what it does.
• astro info prints your Astro, Node.js and system versions. Paste it when you ask for help online.

A Starter Page in the Lab

This is close to the src/pages/index.astro file of the minimal starter. Change the heading, then press ▶ Run.

• The two --- lines are there, even with nothing between them.
• Astro.generator adds the Astro version to the page. Look for content="Astro v7 in HTML sent to browser.

Simple lesson: astro --help and astro info are your first two helpers.

TL;DR

1. Astro = a web framework for fast, content-driven websites.
2. HTML first = Astro makes finished HTML before anyone visits.
3. Zero JavaScript by default = a page sends no JavaScript unless you add some.
4. Island = a small part of a page that has JavaScript.
5. Choose Astro = when your site is mostly content. Choose an app framework when it is mostly interaction.
6. Requirements = Node.js 22.23.4 or newer (even-numbered LTS), an editor, a terminal.

7. Project steps:

   • npm create astro@latest creates the project.
   • npm run dev starts the dev server at localhost:4321.
   • npm run build makes the dist/ folder.
   • npm run preview shows the built site.
8. src/pages = every .astro file here becomes a page.
9. Component script = the code between --- lines. It runs at build time.

Common mistakes

Check Yourself

Exercises

What to Remember

• Astro builds content sites into fast, finished HTML.
• It sends JavaScript only for the parts that react.
• Pick Astro for content. Pick an app framework for heavy interaction.
• npm create astro@latest, then npm run dev, npm run build and npm run preview.
• Every .astro file in src/pages becomes a page.
• The component script runs at build time. A <script> tag runs in the browser.

Next: Project Structure and Configuration, where you meet every file of a project and add your first integration.