Installing Astro

Astro ships with a guided scaffolding tool called create astro that bootstraps a fully configured project in seconds. Getting a clean, modern toolchain in place up front saves you from version mismatches and editor headaches later. This page walks through installing the prerequisites, generating a project, choosing a template and package manager, and verifying that everything works before you write your first line of .astro.

Prerequisites

Astro is a Node.js application, so you need a recent LTS or Current release of Node installed. Astro 5 requires Node.js 18.20.8, 20.3.0, or 22.0.0 and above — older 16.x and 19.x lines are not supported. You also need a terminal and, ideally, a code editor such as VS Code.

Check your Node version before doing anything else:

node --version

Output:

v22.11.0

If the command fails or prints an unsupported version, install Node from nodejs.org or use a version manager like nvm, fnm, or volta to manage multiple runtimes per project.

Tip: Use a version manager rather than a global system install. It lets you pin a Node version per project with a .nvmrc or .node-version file, which keeps your team and CI in sync.

Creating a project with create astro

The fastest way to start is the official CLI wizard. It scaffolds the project, installs dependencies, and can optionally initialize a Git repository. Run it with your package manager of choice:

# npm
npm create astro@latest

# pnpm
pnpm create astro@latest

# yarn
yarn create astro

# bun
bun create astro@latest

The wizard prompts you interactively: where to create the project, which template to use, whether to install dependencies, whether to use TypeScript, and whether to initialize Git. Answer the prompts and the CLI does the rest.

You can also skip the questions by passing flags. This is handy for scripting or CI:

npm create astro@latest my-astro-site -- --template minimal --install --git --typescript strict

Output:

 astro   Launch sequence initiated.

   dir   Creating a new project in ./my-astro-site...
  tmpl   Using minimal as project template.
  deps   Installing dependencies with npm...
    ts   Using strict TypeScript configuration.
   git   Initialized a new git repository.

  next   Liftoff confirmed. Explore your project!

         Enter your project directory using cd ./my-astro-site
         Run npm run dev to start the dev server. CTRL+C to stop.

Choosing a template

The --template flag accepts the name of any official starter or a path to a community example on GitHub. The built-in options cover the most common starting points:

Template	Best for
minimal	A bare project with a single page — ideal for learning the core
basics	A small starter with layout, components, and styling wired up
blog	Content-collection-driven blog with Markdown and RSS
portfolio	A multi-page personal/portfolio site
framework-*	Starters preconfigured with React, Vue, Svelte, etc.

To use a community example from the withastro/astro examples directory or any GitHub repo:

npm create astro@latest my-site -- --template withastro/astro/examples/blog

Choosing a package manager

Astro is agnostic about your package manager. Pick one and stay consistent so the lockfile stays clean. All four below are first-class:

Manager	Create command	Notes
npm	npm create astro@latest	Bundled with Node, zero extra setup
pnpm	pnpm create astro@latest	Fast, disk-efficient, strict by default
yarn	yarn create astro	Mature, widely used in existing teams
bun	bun create astro@latest	Fastest installs; verify integration compat

Warning: Don’t mix package managers in one project. Committing both a package-lock.json and a pnpm-lock.yaml leads to inconsistent dependency trees across machines and CI. Delete the stray lockfile and node_modules, then reinstall with your chosen tool.

Verifying the toolchain

Move into the project directory and start the development server. Astro’s Vite-powered dev server boots almost instantly and supports hot module replacement.

cd my-astro-site
npm run dev

Output:

 astro  v5.9.0 ready in 142 ms

┃ Local    http://localhost:4321/
┃ Network  use --host to expose

watching for file changes...

Open http://localhost:4321 in your browser and you should see the starter page. Because Astro renders to zero JavaScript by default, the page ships as pure HTML and CSS — interactivity is opt-in via islands and client:* directives only where you need it.

Here is the minimal page the minimal template produces, demonstrating the --- component-script fence:

---
const greeting = "Welcome to Astro";
---

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

Editor setup

For the best experience in VS Code, install the official Astro extension. It provides syntax highlighting, IntelliSense, and inline TypeScript diagnostics for .astro files. To get type checking from the command line — useful in CI — run the bundled checker:

npm run astro check

Output:

Result (1 file):
- 0 errors
- 0 warnings
- 0 hints

Adding integrations later

You rarely scaffold everything at once. Use astro add to wire up UI frameworks, adapters, and tooling with automatic config edits:

npx astro add react tailwind

This installs the packages and updates astro.config.mjs for you, so a React island like <Counter client:load /> works immediately.

Best Practices

• Pin a supported Node version with .nvmrc or volta so local and CI environments match.
• Choose one package manager per project and commit only its lockfile.
• Start from the minimal or basics template while learning; reach for blog/portfolio once you understand the structure.
• Enable --typescript strict from the start — it costs nothing and catches errors early.
• Install the official Astro VS Code extension and run astro check in CI to guard against type regressions.
• Add frameworks and adapters with astro add rather than editing config by hand, to avoid version drift.

Related Topics

• Introduction to Astro
• Why Astro
• Your first project
• The dev server
• Zero JS by default