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

To run an Astro project, first install dependencies with npm install, then start the development server using npm run dev. This launches your project locally, usually at http://localhost:3000, where you can see your site live.

Syntax

Running an Astro project involves these main commands:

• npm install: Installs all project dependencies listed in package.json.
• npm run dev: Starts the Astro development server for live preview.
• npm run build: Builds the project for production deployment.
• npm run preview: Serves the built project locally to test production output.

bash

npm install
npm run dev

Example

This example shows how to run an Astro project after cloning or creating it:

1. Open your terminal in the project folder.
2. Run npm install to get dependencies.
3. Run npm run dev to start the local server.
4. Open http://localhost:3000 in your browser to see the site.

bash

npm install
npm run dev

Output

  > astro@ dev
  > astro dev

  [astro] Local: http://localhost:3000/
  [astro] Network: use --host to expose

Common Pitfalls

Common mistakes when running an Astro project include:

• Not running npm install first, causing missing dependencies errors.
• Running commands outside the project folder.
• Using npm start instead of npm run dev, which may not work unless configured.
• Firewall or port conflicts blocking localhost:3000.

bash

Wrong:
npm start

Right:
npm run dev

Quick Reference

Command	Purpose
npm install	Install project dependencies
npm run dev	Start development server
npm run build	Build project for production
npm run preview	Preview production build locally

Key Takeaways

Always run npm install before starting the Astro project.

Use npm run dev to launch the local development server.

Access your running site at http://localhost:3000 by default.

Avoid using npm start unless your project configures it.

Check for port conflicts if the server does not start.