Create an Astro project

Let’s create the project we’ll use for the whole course. Astro ships a wizard that sets everything up.

Run it in the folder where you keep your projects:

npm create astro@latest

The wizard asks a few questions. Where to create the project, which template to start from, whether to install dependencies, whether to create a Git repository.

Call the project astro-notes. Pick the smallest starter offered, we don’t want a blog template full of files we didn’t write. Say yes to installing dependencies.

When it finishes, enter the folder and start the development server:

cd astro-notes
npm run dev

Astro prints a local URL, usually http://localhost:4321/. Open it in the browser. You should see the starter page.

Make your first change

Now open src/pages/index.astro in your editor. Replace its content with this:

---
const title = 'Astro notes'
---

<h1>{title}</h1>

Save the file. The browser updates by itself and shows the heading. No reload needed.

Notice what just happened. The development server rendered the page when you requested it. The title variable was read during that render and turned into HTML.

Later in the course we’ll run a production build. There, the same component runs once, during the build, and Astro writes the result to a static file. Same component, different moment. Keep this in mind, because a lot of Astro clicks into place once you know when your code runs.

When something breaks

Sooner or later a page fails. When it does, go to the terminal and read the first error. Not the last one, the first.

The three mistakes I see most often are different problems with different fixes:

• an unclosed tag in the template, which Astro reports with a file and line number
• an import that points to a file that doesn’t exist
• running npm run dev from the wrong directory, so there is no package.json

My advice is to keep the terminal and the browser open side by side while you work. For every example in this course, check both. The terminal tells you if the render failed. The browser tells you what the visitor gets.