Paully D - A Step-by-Step Basic Guide for Setting Up Astro

Astro has quickly become the go-to framework for building fast, content-driven websites, which is why we ranked it as the premier choice in our breakdown of the top 8 static site frameworks. By sending zero JavaScript to the client by default, Astro ensures your site loads instantly. This makes it a much more efficient choice for content-heavy sites compared to heavyweight SPA architectures like Next.js or overly complex setups like Headless WordPress.

In this guide, we will walk you through the absolute basics of getting an Astro project up and running from scratch.

Prerequisites

Before we begin, ensure you have the following installed on your machine:

Node.js (v18.14.1 or higher)
A code editor (like VS Code)
A terminal

Step 1: Run the Create Astro CLI

The easiest way to start a new Astro project is to use their official CLI. Open your terminal and run the following command:

npm create astro@latest

You can also use pnpm or yarn if you prefer:

pnpm create astro@latest
# or
yarn create astro

Step 2: Answer the Setup Prompts

The CLI will walk you through a few quick questions to configure your new project.

Where would you like to create your new project? Enter a folder name, for example: ./my-astro-site.
How would you like to start your new project? Choose "Include sample files" to get a basic template with some helpful examples, or "Empty" if you want to start completely from scratch.
Install dependencies? Select "Yes" so the CLI automatically runs npm install for you.
Do you plan to write TypeScript? Select "Yes" if you prefer TypeScript (highly recommended for better tooling), or "No" if you want to stick to plain JavaScript.

Step 3: Navigate and Start the Dev Server

Once the installation is complete, navigate into your newly created project directory:

cd my-astro-site

Now, start the Astro development server:

npm run dev

The terminal will provide a local URL (usually http://localhost:4321). Open this URL in your browser, and you should see your new Astro site live!

Step 4: Explore the Project Structure

Let's look at the basic folder structure of your new Astro project:

src/: This is where all your source code lives.
- pages/: Every .astro or .md file in this directory automatically becomes a route on your website. For example, src/pages/index.astro is your homepage.
- components/: Place your reusable UI components here (like headers, footers, or buttons). You can write them in Astro, React, Vue, Svelte, or others.
public/: Store static assets like images, fonts, or favicon.ico here. These files are served exactly as they are without processing.
astro.config.mjs: This is where you configure Astro, add integrations (like Tailwind CSS or React), and define site-wide settings.

Step 5: Make Your First Edit

Open src/pages/index.astro in your code editor. You will see two sections: the frontmatter script (fenced by ---) and the HTML-like template below it.

Change some text inside the <h1> tag in the template section and save the file. Notice how your browser automatically reloads with the updated content. Astro's Hot Module Replacement (HMR) makes development incredibly fast.

Next Steps

Congratulations! You've successfully set up your first Astro project. From here, you can start building out your pages, exploring the "Islands Architecture" to add interactive components, and leveraging Astro's powerful content collections for your blog or documentation.

Welcome to the incredibly fast world of Astro!

A STEP-BY-STEP BASIC GUIDE FOR SETTING UP ASTRO