# Install Astro

> How to install Astro and start a new project.

The [`create astro` CLI command](#install-from-the-cli-wizard) is the fastest way to start a new Astro project from scratch. It will walk you through every step of setting up your new Astro project and allow you to choose from a few different official starter templates.

You can also run the CLI command with the `template` flag to begin your project using any existing theme or starter template. Explore our [themes and starters showcase](https://astro.build/themes/) where you can browse themes for blogs, portfolios, documentation sites, landing pages, and more!

To install Astro manually instead, see our [step-by-step manual installation guide](#manual-setup).

Online previews

Prefer to try Astro in your browser? Visit [astro.new](https://astro.new/) to browse our starter templates and spin up a new Astro project without ever leaving your browser.

## Prerequisites

[Section titled “Prerequisites”](#prerequisites)

* **Node.js** - `v18.20.8` or `v20.3.0`, `v22.0.0` or higher. (`v19` and `v21` are not supported.)
* **Text editor** - We recommend [VS Code](https://code.visualstudio.com/) with our [Official Astro extension](https://marketplace.visualstudio.com/items?itemName=astro-build.astro-vscode).
* **Terminal** - Astro is accessed through its command-line interface (CLI).

## Browser compatibility

[Section titled “Browser compatibility”](#browser-compatibility)

Astro is built with Vite which targets browsers with modern JavaScript support by default. For a complete reference, you can see the [list of currently supported browser versions in Vite](https://vite.dev/guide/build.html#browser-compatibility).

## Install from the CLI wizard

[Section titled “Install from the CLI wizard”](#install-from-the-cli-wizard)

You can run `create astro` anywhere on your machine, so there’s no need to create a new empty directory for your project before you begin. If you don’t have an empty directory yet for your new project, the wizard will help create one for you automatically.

1. Run the following command in your terminal to start the install wizard:

   * npm

     ```shell
     # create a new project with npm
     npm create astro@latest
     ```

   * pnpm

     ```shell
     # create a new project with pnpm
     pnpm create astro@latest
     ```

   * Yarn

     ```shell
     # create a new project with yarn
     yarn create astro
     ```

   If all goes well, you will see a success message followed by some recommended next steps.

2. Now that your project has been created, you can `cd` into your new project directory to begin using Astro.

3. If you skipped the “Install dependencies?” step during the CLI wizard, then be sure to install your dependencies before continuing.

   * npm

     ```shell
     npm install
     ```

   * pnpm

     ```shell
     pnpm install
     ```

   * Yarn

     ```shell
     yarn install
     ```

4. You can now [start the Astro dev server](/en/develop-and-build/#start-the-astro-dev-server) and see a live preview of your project while you build!

## CLI installation flags

[Section titled “CLI installation flags”](#cli-installation-flags)

You can run the `create astro` command with additional flags to customize the setup process (e.g. answering “yes” to all questions, skipping the Houston animation) or your new project (e.g. install git or not, add integrations).

See [all the available `create astro` command flags](https://github.com/withastro/astro/blob/main/packages/create-astro/README.md).

### Add integrations

[Section titled “Add integrations”](#add-integrations)

You can start a new Astro project and install any [official integrations](/en/guides/integrations-guide/) or community integrations that support the `astro add` command at the same time by passing the `--add` argument to the `create astro` command.

Run the following command in your terminal, substituting any integration that supports the `astro add` command:

* npm

  ```shell
  # create a new project with React and Partytown
  npm create astro@latest -- --add react --add partytown
  ```

* pnpm

  ```shell
  # create a new project with React and Partytown
  pnpm create astro@latest --add react --add partytown
  ```

* Yarn

  ```shell
  # create a new project with React and Partytown
  yarn create astro --add react --add partytown
  ```

### Use a theme or starter template

[Section titled “Use a theme or starter template”](#use-a-theme-or-starter-template)

You can start a new Astro project based on an [official example](https://github.com/withastro/astro/tree/main/examples) or the `main` branch of any GitHub repository by passing a `--template` argument to the `create astro` command.

Run the following command in your terminal, substituting the official Astro starter template name, or the GitHub username and repository of the theme you want to use:

* npm

  ```shell
  # create a new project with an official example
  npm create astro@latest -- --template <example-name>


  # create a new project based on a GitHub repository’s main branch
  npm create astro@latest -- --template <github-username>/<github-repo>
  ```

* pnpm

  ```shell
  # create a new project with an official example
  pnpm create astro@latest --template <example-name>


  # create a new project based on a GitHub repository’s main branch
  pnpm create astro@latest --template <github-username>/<github-repo>
  ```

* Yarn

  ```shell
  # create a new project with an official example
  yarn create astro --template <example-name>


  # create a new project based on a GitHub repository’s main branch
  yarn create astro --template <github-username>/<github-repo>
  ```

By default, this command will use the template repository’s `main` branch. To use a different branch name, pass it as part of the `--template` argument: `<github-username>/<github-repo>#<branch>`.

## Manual Setup

[Section titled “Manual Setup”](#manual-setup)

This guide will walk you through the steps to manually install and configure a new Astro project.

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

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

   ```bash
   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.

   * npm

     ```shell
     npm init --yes
     ```

   * pnpm

     ```shell
     pnpm init
     ```

   * Yarn

     ```shell
     yarn init --yes
     ```

2. Install Astro

   First, install the Astro project dependencies inside your project.

   Important

   Astro must be installed locally, not globally. Make sure you are *not* running `npm install -g astro` `pnpm add -g astro` or `yarn add global astro`.

   * npm

     ```shell
     npm install astro
     ```

   * pnpm

     ```shell
     pnpm add astro
     ```

   * Yarn

     ```shell
     yarn add astro
     ```

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

   package.json

   ```diff
   {
     "scripts": {
       -"test": "echo \"Error: no test specified\" && exit 1",
       +"dev": "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

   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

   ```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

   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

   ```diff
   # 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`

   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

   ```js
   import { defineConfig } from "astro/config";


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

   If you want to include [UI framework components](/en/guides/framework-components/) such as React, Svelte, etc. or use other tools such as MDX or Partytown in your project, here is where you will [manually import and configure integrations](/en/guides/integrations-guide/).

   Read Astro’s [API configuration reference](/en/reference/configuration-reference/) for more information.

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/](https://github.com/withastro/astro/blob/main/packages/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

   ```json
   {
     "extends": "astro/tsconfigs/base"
   }
   ```

   Read Astro’s [TypeScript setup guide](/en/guides/typescript/#setup) for more information.

7. Next Steps

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

   * node\_modules/

     * …

   * public/

     * robots.txt

   * src/

     * pages/

       * index.astro

   * astro.config.mjs

   * package-lock.json or `yarn.lock`, `pnpm-lock.yaml`, etc.

   * package.json

   * tsconfig.json

8. You can now [start the Astro dev server](/en/develop-and-build/#start-the-astro-dev-server) and see a live preview of your project while you build!