Skip to main content

​
Installation

Get started with Astro by installing it in your project. This guide covers both automatic setup with create-astro and manual installation.

​
Prerequisites

Before installing Astro, ensure you have the following installed on your system:

Node.js

Version 22.12.0 or higher (or version 20.19.1)

Package manager

npm (v9.6.5+), pnpm (v7.1.0+), or Yarn
You can check your Node.js version by running node -v in your terminal. If you need to install or update Node.js, visit nodejs.org.
Astro also supports:
  • Text editor: We recommend VS Code with the Astro extension
  • Terminal: Astro is accessed through its command-line interface (CLI)
The fastest way to set up a new Astro project is with create-astro. This automated CLI tool will scaffold a new project with everything you need to get started.
1

Run the create-astro command

Open your terminal and run the following command using your preferred package manager:
npm create astro@latest
The create-astro wizard will guide you through the setup process.
2

Choose your project options

The CLI will ask you several questions:
  • Where would you like to create your new project? - Enter a directory name (e.g., my-astro-site)
  • How would you like to setup your new project? - Choose a template or start from scratch
  • Install dependencies? - Recommended: Yes
  • Initialize a git repository? - Recommended: Yes
  • Add integrations? - Optional: Select any you want to add now
You can skip all prompts and use defaults by adding the --yes flag:
npm create astro@latest -- --yes
3

Navigate to your project

Once the installation is complete, navigate to your new project directory:
cd my-astro-site
4

Start the dev server

Start the local development server:
npm run dev
Astro will start a local development server at http://localhost:4321.

​
Using a template

You can start with a specific template by using the --template flag: 
npm create astro@latest my-astro-site -- --template minimal
Browse all official templates at astro.new or view the examples directory on GitHub.

​
Using a GitHub repository

You can also use any public GitHub repository as a template: 
npm create astro@latest my-astro-site -- --template username/repo

​
Manual installation

If you prefer to set up Astro manually in an existing project, follow these steps:
1

Install Astro

Install the astro package using your package manager:
npm install astro
2

Create your first page

Create a src/pages directory and add an index.astro file:
src/pages/index.astro
---
// Component frontmatter (JavaScript)
const pageTitle = "My Astro Site";
---

<html lang="en">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width" />
    <title>{pageTitle}</title>
  </head>
  <body>
    <h1>Welcome to Astro!</h1>
  </body>
</html>
3

Create the public directory

Create a public/ directory at the root of your project for static assets like images and fonts.
4

Create astro.config.mjs

Create an Astro configuration file at the root of your project:
astro.config.mjs
// @ts-check
import { defineConfig } from 'astro/config';

// https://astro.build/config
export default defineConfig({});
5

Create tsconfig.json

Create a TypeScript configuration file (even if you’re not using TypeScript):
tsconfig.json
{
  "extends": "astro/tsconfigs/base"
}
6

Update package.json scripts

Add the following scripts to your package.json:
package.json
{
  "scripts": {
    "dev": "astro dev",
    "build": "astro build",
    "preview": "astro preview",
    "astro": "astro"
  }
}

​
CLI flags

Customize your installation with these flags:
​
--template
string
Specify a template to use (e.g., minimal, blog, portfolio)
​
--install
boolean
Automatically install dependencies
​
--no-install
boolean
Skip dependency installation
​
--git
boolean
Initialize a git repository
​
--no-git
boolean
Skip git initialization
​
--add
string
Add integrations (e.g., --add react,tailwind)
​
--yes
boolean
Skip all prompts by accepting defaults
​
--no
boolean
Skip all prompts by declining defaults
​
--dry-run
boolean
Walk through steps without executing

​
Example with flags

npm create astro@latest my-astro-site -- \
  --template minimal \
  --install \
  --git \
  --add tailwind

​
Editor setup

For the best development experience, we recommend:

​
VS Code

Install the official Astro VS Code extension for:
  • Syntax highlighting for .astro files
  • TypeScript type information
  • VS Code IntelliSense for code completion and hints

​
Other editors

​
Next steps

Now that you have Astro installed, you’re ready to start building!

Quick start tutorial

Follow our step-by-step tutorial to build your first Astro site

Core concepts

Learn about the Astro core concepts

Build docs developers (and LLMs) love

Get started for freeTalk to us