How to Create an Astro Project: Step-by-Step Guide

To create an Astro project, run npm create astro@latest in your terminal and follow the prompts to set up your project folder and template. Then, navigate into your project directory and start the development server with npm run dev.

Syntax

The basic command to create a new Astro project is npm create astro@latest. This command downloads the latest Astro starter and guides you through naming your project and choosing a template. After setup, use cd your-project-name to enter your project folder and npm install to install dependencies. Finally, run npm run dev to start the local development server.

bash

npm create astro@latest
cd your-project-name
npm install
npm run dev

Example

This example shows creating a new Astro project named my-astro-site using the starter template, installing dependencies, and running the development server.

bash

npm create astro@latest
# When prompted, enter 'my-astro-site' as project name and select 'starter' template
cd my-astro-site
npm install
npm run dev

Output

  VITE v4.3.9  ready in 300 ms

  ➜  Local:   http://localhost:3000/
  ➜  Network: use --host to expose

Common Pitfalls

• Not having Node.js installed: Astro requires Node.js version 16.8 or higher. Install it before running commands.
• Skipping npm install: Without installing dependencies, the project won't run.
• Wrong directory: Make sure to cd into your project folder before running npm run dev.
• Firewall or port issues: If the server doesn't start, check that port 3000 is free.

bash

Wrong way:
npm create astro@latest
npm run dev

Right way:
npm create astro@latest
cd your-project-name
npm install
npm run dev

Quick Reference

Here is a quick summary of commands to create and run an Astro project:

Command	Purpose
npm create astro@latest	Create a new Astro project with prompts
cd your-project-name	Change directory to your new project
npm install	Install project dependencies
npm run dev	Start the local development server

Key Takeaways

Use npm create astro@latest to start a new Astro project easily.

Always run npm install before starting the development server.

Navigate into your project folder before running commands.

Make sure Node.js 16.8+ is installed to use Astro.

Use npm run dev to see your site live locally.