Installation

There are a few different ways to install Astro in a new project.

Prerequisites

  • Node.js - v12.20.0, v14.13.1, v16.0.0, or higher.
  • Text editor - We recommend VS Code with our Official Astro extension.
  • Terminal - Astro is mainly accessed via the terminal’s command-line.

For demonstration purposes, we will be using npm in the examples below, but you could also use yarn or pnpm if you prefer an npm alternative.

Create Astro

npm init astro is the easiest way to install Astro in a new project. Run this command in your terminal to start our create-astro install wizard to assist you with setting up a new project.

# With NPM
npm init astro

# Yarn
yarn create astro

create-astro wizard lets you choose from a set of starter templates or alternatively, you could import your own Astro project directly from Github.

# Note: Replace "my-astro-project" with the name of your project.
# npm 6.x
npm init astro my-astro-project --template starter

# npm 7+, extra double-dash is needed:
npm init astro my-astro-project -- --template starter

# yarn
yarn create astro my-astro-project --template starter

# Import Astro project from Github
npm init astro my-astro-project -- --template [GITHUB_USER]/[REPO_NAME]

# Import Astro from nested paths:
npm init astro my-astro-project -- --template [GITHUB_USER]/[REPO_NAME]/path/to/example

After create-astro scaffolds out your project, you would need to install the projects dependencies. To do this, enter:

npm install

You can now Start your Astro project. Once you have completed assembling your Astro project you can then Build your project. Astro would then package up your application and have the static files ready for you to Deploy to your favourite hosting provider

Manual Install

You can also setup Astro without the aide of the create-astro wizard, below are the few extra steps that are required to get Astro going.

Set up your project

# Make and enter a new directory
mkdir my-astro-project
cd my-astro-project

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

Create package.json

# This command will create a basic package.json for you
npm init --yes

Astro is designed to work with the entirety of the npm package ecosystem. This is managed by a project manifest at the root of your project known as package.json . If you’re not familiar with the package.json file, we highly recommend you to have a quick read over it on the npm documentation.

Install Astro

Following the instructions above, you should have a directory with a single package.json file inside of it. You can now setup Astro inside your project.

npm install astro

You can now replace the placeholder “scripts” section of your package.json file that npm init created for you with the following:

  "scripts": {
-    "test": "echo "Error: no test specified" && exit 1"
+    "start": "astro dev",
+    "build": "astro build"
  },
}

The start command launches the Astro Dev Server on http://localhost:3000. Once your project is ready, the build command outputs your project to the dist/ directory. Read more about deploying Astro in the Deploy guide.

Create your first page

Astro Open up your favourite text editor, and create a new file in your project:

  1. Create a new file at src/pages/index.astro
  2. Copy-and-paste the following snippet (including --- dashes) into it.
---
// JS/TS Code written in between the (---) code fence,
// is ran solely on the Server!
console.log('See me in the Terminal')
---

<html>
  <body>
    <h1>Hello, World!</h1>
  </body>
</html>

<style lang='css||scss'>
  body{
    h1{
      color:orange;
    }
  }
</style>

<script>
 // JS Code entered here is ran entirely on the Browser
 console.log('See me in the devTools')
</script>

Above is an example of the Astro’s Component’s Syntax, which comprises of both HTML & JSX.

You can create more pages in the src/pages directory, and Astro will use the filename to create new pages on your site. For example, by creating a new file at src/pages/about.astro (reusing the previous snippet), Astro will generate a new page at the URL : http://localhost/about

Start Astro

npm start

Astro will now start serving your application on http://localhost:3000. By opening this URL in your browser, you should see the Astro’s “Hello, World”

Build Astro

npm run build

This will instruct Astro to build your site and save it directly to disk. Your application is now ready in the dist/ directory.

Next Steps

Success! You’re now ready to start developing!

We highly encourage you to get more familiar with the way Astro works. You can do so by further exploring our Docs, we suggest that you consider the following:

📚 Learn more about Astro’s project structure in our Project Structure guide.

📚 Learn more about Astro’s component syntax in our Astro Components guide.

📚 Learn more about Astro’s file-based routing in our Routing guide.