How to Install and Set Up a New Astro Project
A complete, in-depth guide to installing Astro, understanding the CLI wizard, and configuring your local development environment for maximum performance.
Welcome to the world of modern web development! If you are tired of shipping massive JavaScript bundles to your users just to render a static page, Astro is the framework you have been waiting for.
Astro’s unique “Islands Architecture” allows you to build lightning-fast websites by stripping away unnecessary JavaScript by default. Yet, it still grants you the flexibility to use your favorite UI frameworks—like Svelte, React, Vue, or Solid—precisely when and where you need interactivity.
Here is a comprehensive, step-by-step guide on how to properly install and set up a brand-new Astro project from scratch.
Prerequisites
Before diving into the installation process, you need to ensure your local development environment is properly configured. Skipping these prerequisites is the most common cause of installation errors.
- Node.js Environment: You must have Node.js installed on your machine. Astro requires version v18.17.1 or higher. To verify your current version, open your terminal and run
node -v. If you need to update, consider using NVM (Node Version Manager) to easily switch between Node versions without breaking global packages. - Code Editor: A robust text editor is highly recommended for modern web development. Visual Studio Code (VS Code) is the industry standard. I strongly advise installing the official Astro extension in VS Code. It provides syntax highlighting, intelligent auto-completion, and real-time error checking specifically for
.astrofiles. - Command Line Interface: You will need a terminal to execute the installation commands (Terminal on macOS/Linux, or Command Prompt/PowerShell/Windows Terminal on Windows).
Step-by-Step Installation
1. Open your terminal and prepare your workspace
Launch your command line interface. Before running any installation commands, it is a best practice to navigate to the exact folder on your computer where you manage your coding projects. You can do this using the cd (change directory) command.
For example:
cd Documents/projects/web-development