Install Astro manually

This guide will walk you through the steps to manually install and configure a new Astro project if you prefer not to use the automatic CLI tool.

Prefer a quicker way to get started?

Section titled Prefer a quicker way to get started?
Try the create astro CLI wizard →

Prerequisites

Section titled Prerequisites
  • Node.js - v16.12.0 or higher.
  • Text editor - We recommend VS Code with our Official Astro extension.
  • Terminal - Astro is accessed through its command-line interface (CLI).

Installation

Section titled Installation

If you prefer not to use our automatic create astro CLI tool, you can set up your project yourself by following the guide below.

1. Create your directory

Section titled 1. Create your directory

Create an empty directory with the name of your project, and then navigate into it.

Terminal window
mkdir my-astro-project
cd my-astro-project

Once you are in your new directory, create your project package.json file. This is how you will manage your project dependencies, including Astro. If you aren’t familiar with this file format, run the following command to create one.

Terminal window
npm init --yes

2. Install Astro

Section titled 2. Install Astro

First, install the Astro project dependencies inside your project.

Terminal window
npm install astro

Then, replace any placeholder “scripts” section of your package.json with the following:

package.json
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1",
    "dev": "astro dev",
    "start": "astro dev",
    "build": "astro build",
    "preview": "astro preview"
  },

You’ll use these scripts later in the guide to start Astro and run its different commands.

3. Create your first page

Section titled 3. Create your first page

In your text editor, create a new file in your directory at src/pages/index.astro. This will be your first Astro page in the project.

For this guide, copy-and-paste the following code snippet (including --- dashes) into your new file:

src/pages/index.astro
---
// Welcome to Astro! Everything between these triple-dash code fences
// is your "component frontmatter". It never runs in the browser.
console.log('This runs in your terminal, not the browser!');
---
<!-- Below is your "component template." It's just HTML, but with
     some magic sprinkled in to help you build great templates. -->
<html>
  <body>
    <h1>Hello, World!</h1>
  </body>
</html>
<style>
  h1 {
    color: orange;
  }
</style>

4. Create your first static asset

Section titled 4. Create your first static asset

You will also want to create a public/ directory to store your static assets. Astro will always include these assets in your final build, so you can safely reference them from inside your component templates.

In your text editor, create a new file in your directory at public/robots.txt. robots.txt is a simple file that most sites will include to tell search bots like Google how to treat your site.

For this guide, copy-and-paste the following code snippet into your new file:

public/robots.txt
# Example: Allow all bots to scan and index your site.
# Full syntax: https://developers.google.com/search/docs/advanced/robots/create-robots-txt
User-agent: *
Allow: /

5. Create astro.config.mjs

Section titled 5. Create astro.config.mjs

Astro is configured using astro.config.mjs. This file is optional if you do not need to configure Astro, but you may wish to create it now.

Create astro.config.mjs at the root of your project, and copy the code below into it:

astro.config.mjs
import { defineConfig } from 'astro/config';


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

If you want to include UI framework components such as React, Svelte, etc. or use other tools such as Tailwind or Partytown in your project, here is where you will manually import and configure integrations.

📚 Read Astro’s API configuration reference for more information.

6. Add TypeScript support

Section titled 6. Add TypeScript support

TypeScript is configured using tsconfig.json. Even if you don’t write TypeScript code, this file is important so that tools like Astro and VS Code know how to understand your project. Some features (like npm package imports) aren’t fully supported in the editor without a tsconfig.json file.

If you do intend to write TypeScript code, using Astro’s strict or strictest template is recommended. You can view and compare the three template configurations at astro/tsconfigs/.

Create tsconfig.json at the root of your project, and copy the code below into it. (You can use base, strict or strictest for your TypeScript template):

tsconfig.json
{
  "extends": "astro/tsconfigs/base"
}

Finally, create src/env.d.ts to let TypeScript know about ambient types available in an Astro project:

src/env.d.ts
/// <reference types="astro/client" />

📚 Read Astro’s TypeScript setup guide for more information.

7. Next Steps

Section titled 7. Next Steps

If you have followed the steps above, your project directory should now look like this:

  • Directorynode_modules/
    • …
  • Directorypublic/
    • robots.txt
  • Directorysrc/
    • Directorypages/
      • index.astro
    • env.d.ts
  • astro.config.mjs
  • package-lock.json or yarn.lock, pnpm-lock.yaml, etc.
  • package.json
  • tsconfig.json

Congratulations, you’re now set up to use Astro!

If you followed this guide completely, you can jump directly to Step 2: Start Astro to continue and learn how to run Astro for the first time.