Module 0: Getting Started with Astro

0.1 Welcome to Astro: The Why and What

Let’s start with a crucial question: Why Astro?

In today’s web, users expect lightning-fast experiences. But often, the sites we build, especially with traditional Single Page Application (SPA) frameworks like React or Vue, ship tons of JavaScript to the browser. This JavaScript then has to “hydrate” – essentially, take over the page – which can slow things down, especially on less powerful devices or slow connections. This isn’t just annoying; it can hurt your search engine rankings too!

Astro comes to the rescue by prioritizing performance first. Its core philosophy is to ship zero JavaScript by default. Think about that for a second. Most of your website will be pure, fast HTML and CSS, delivered directly to the browser.

How does it achieve this magic? Through something called Island Architecture. Imagine your website as a vast, calm ocean of static HTML. On this ocean, you have small, isolated “islands” of interactivity. These islands are where your favorite UI frameworks (like React, Vue, or Svelte) come into play, but only where truly needed. Astro carefully orchestrates when and how these islands “wake up” and become interactive, ensuring you send the absolute minimum JavaScript to the user.

This approach also means Astro is incredibly UI-framework agnostic. Love React? Great. Prefer Vue? No problem. You can even mix them on the same page! This flexibility is a huge win for developers.

Beyond performance and flexibility, Astro offers an amazing Developer Experience (DX). It’s designed to be intuitive, with fast refresh times during development and a clean, easy-to-understand component syntax. It embraces a server-first mentality, rendering most of your site to HTML on the server (or at build time), further reducing the client’s workload.

So, what exactly is Astro? It’s a modern web framework perfectly suited for building content-focused websites, blogs, e-commerce sites, and more, where performance and SEO are paramount. It’s not trying to be a full-blown SPA framework, but it gives you all the power you need to create dynamic and interactive experiences, all while keeping things incredibly lightweight.

0.2 Setting Up Your Development Environment

Before we can start building, we need to get your workspace ready.

Node.js: Astro runs on Node.js. If you don’t have it installed, or if you have an older version, head over to the official Node.js website and install the latest LTS (Long Term Support) version. This will also install npm (Node Package Manager). If you prefer pnpm or Yarn, feel free to use those instead.

📜 To read: What is Node.js?
Code Editor: We highly recommend VS Code for this course due to its excellent web development features and extensions.
- Essential Extensions:
  - Astro Official: This is an absolute must-have. It provides syntax highlighting, intelligent code completion (IntelliSense), and other features specifically for Astro files.
  - Prettier: For consistent code formatting. It’ll keep your code looking clean and organized automatically.
  - ESLint (Recommended): While optional for this module, ESLint helps enforce code quality and catches potential errors early.
Command Line Interface (CLI): You’ll be using your terminal or command prompt to create projects, run development servers, and execute build commands. If you’re new to the command line, don’t worry; we’ll guide you through the essential commands.

0.3 Creating Your First Astro Project

Time to get your hands dirty! This is where we create the foundation for our “Developer Portfolio & Blog.”

Open your terminal or command prompt and run the following magic command:

npm create astro@latest

This command will prompt you with a few questions. Let’s go through them:

Where would you like to create your new project? You can type . to create it in your current directory, or provide a new folder name (e.g., my-astro-portfolio). Let’s use my-astro-portfolio for clarity.
How would you like to use Astro? Select Just the basics for now. This gives us a clean slate to build upon.
Install dependencies? Type Yes.
Initialize a new git repository? Type Yes. Version control is a good habit to start early!

Once it’s finished, navigate into your new project directory:

cd my-astro-portfolio

Now, let’s fire up the development server and see your brand new Astro site:

npm run dev

You should see a message indicating that your site is running, usually at http://localhost:4321. Open your browser to that address, and you’ll be greeted by the default Astro welcome page!

0.4 Project Structure Deep Dive

Let’s explore the files and folders Astro just created for you. Understanding this structure is key to knowing where to put your code.

src/: This is the heart of your Astro project. All your source code lives here.
- src/pages/: This directory handles your site’s routing. Each .astro file (or other supported file types like .md or UI framework files) inside src/pages/ becomes a unique route on your website.
  - index.astro: This is your homepage.
  - blog/: You could create subdirectories for routes, like blog/about.astro for your-site.com/blog/about.
- src/layouts/: This is where you put reusable wrappers for your pages. Think of a layout as a template that defines common structures like your header, footer, or main content area, which multiple pages can share.
  - BaseLayout.astro: This will be our foundational layout for most pages.
- src/components/: This directory is for small, reusable UI elements. These are the building blocks you’ll use across your pages and layouts, such as buttons, navigation items, or cards.
- src/content/ (future): We’ll use this crucial directory in later modules. This is where we’ll store our structured content, like blog posts and portfolio projects, making them easy to manage and query.
public/: This folder is for static assets that don’t need any special processing by Astro. Things like images, fonts, robots.txt, or your favicon.ico go here. They’ll be served directly at the root of your website.
astro.config.mjs: This is your Astro configuration file. You’ll use this to add integrations (for UI frameworks, image optimization, etc.), configure build options, and customize Astro’s behavior.
package.json: This is a standard Node.js project file. It lists your project’s dependencies and defines scripts like npm run dev and npm run build.

0.5 Basic Routing and `.astro` Components

Let’s make some simple changes to see these concepts in action.

📜 To read: What is Routing in Astro?

Your First Astro Component:

Create a new file in src/components/ called Greeting.astro.
Add the following code to Greeting.astro:
```
---
// This is the "code fence" for JavaScript/TypeScript
// We'll define props here
interface Props {
    name: string;
}

const { name } = Astro.props;
---
<p>Hello, {name}!</p>
```
- The -- dashes define a “code fence” where you can write JavaScript/TypeScript that runs at build time or on the server.
- Astro.props is how you access data passed into this component.
📜 To read: What are Interfaces and Props?

Now, let’s use this component on your homepage. Open src/pages/index.astro and replace its content with:

---
import Greeting from '../components/Greeting.astro';
---

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>My First Astro Page</title>
</head>
<body>
    <h1>Welcome to Astro!</h1>
    <Greeting name="Learner" />
    <p>This is your exciting journey into performant web development.</p>
</body>
</html>

Save the file, and you should immediately see “Hello, Learner!” on your homepage! Notice how we import the component and then use it like a regular HTML tag.

Basic Routing:

Let’s create a simple “About” page.

Create a new file in src/pages/ called about.astro.

Add some simple content to about.astro:

---
---
<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>About Me</title>
</head>
<body>
    <h1>About Me</h1>
    <p>Hi there! This is my awesome Astro about page.</p>
    <a href="/">Go back home</a>
</body>
</html>

Now, you can navigate to this page by going to http://localhost:4321/about in your browser.

Let’s add a link to the About page from your homepage. Update src/pages/index.astro:

---
import Greeting from '../components/Greeting.astro';
---

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>My First Astro Page</title>
</head>
<body>
    <h1>Welcome to Astro!</h1>
    <Greeting name="Learner" />
    <p>This is your exciting journey into performant web development.</p>
    <p><a href="/about">Learn more about me!</a></p>
</body>
</html>

Now you have basic navigation between your pages!

Project Step: Laying the Foundation for the Portfolio

Now, let’s apply these concepts directly to our “Developer Portfolio & Blog.” This is where we start building the real project.

Ensure Your Project is Clean: If you added any extra test code in src/pages/index.astro from the previous section, remove it so your index.astro is minimal.

Create Your BaseLayout.astro:

In the src/layouts/ directory, create a new file named BaseLayout.astro.

This layout will serve as the base HTML structure for most of our site’s pages. Add the following code:

---
// This is a prop to dynamically set the page title
interface Props {
    title: string;
}

const { title } = Astro.props;
---
<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>{title} | My Developer Portfolio</title>
    <!-- We'll add global styles or links to CSS here later -->
</head>
<body>
    <slot /> {/* This is where the content from the page using this layout will be injected */}
</body>
</html>

The <slot /> element is crucial! It acts as a placeholder where the content of any page using this layout will be injected.

Integrate BaseLayout into index.astro:
- Open src/pages/index.astro.
- Remove all its previous content and replace it with this:
```
---
import BaseLayout from '../layouts/BaseLayout.astro';
---

<BaseLayout title="Home">
    <main>
        <h1>Welcome to My Developer Portfolio!</h1>
        <p>This is the start of building something truly performant and impressive.</p>
    </main>
</BaseLayout>
```
- Now, if you view your index.astro page, you won’t see much difference visually, but it’s now wrapped by our BaseLayout, meaning it inherits all the basic HTML structure, and we can manage common elements in one place.

Create Basic Header and Footer Components:

In src/components/, create Header.astro:

---
// No JavaScript needed for this simple header right now
---
<header>
    <nav>
        <a href="/">Home</a>
        <!-- We'll add more links here as we build out the site -->
    </nav>
</header>

In src/components/, create Footer.astro:

---
// No JavaScript needed for this simple footer right now
---
<footer>
    <p>&copy; {new Date().getFullYear()} My Developer Portfolio. All rights reserved.</p>
</footer>

Integrate Header and Footer into BaseLayout.astro:

Open src/layouts/BaseLayout.astro and import/use your new components:

---
import Header from '../components/Header.astro';
import Footer from '../components/Footer.astro';

interface Props {
    title: string;
}

const { title } = Astro.props;
---
<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>{title} | My Developer Portfolio</title>
</head>
<body>
    <Header /> {/* Our header component */}
    <slot /> {/* The page content goes here */}
    <Footer /> {/* Our footer component */}
</body>
</html>

Now, every page that uses BaseLayout (like our index.astro) will automatically include the header and footer. Go check your homepage in the browser to see them!