Quick start

This guide will walk you through creating your first Astro project, understanding its structure, and deploying it to the web.

Create a new project

Run create-astro

Open your terminal and run the installation command:

npm create astro@latest

pnpm create astro@latest

yarn create astro

Follow the setup wizard

The create-astro wizard will guide you through setup. For this tutorial, choose:

# Directory name
my-first-astro-site

# Template
Empty (or choose "Include sample files" to see examples)

# Install dependencies?
Yes

# Initialize git?
Yes

Navigate to your project

cd my-first-astro-site

Understand the project structure

Look inside your new Astro project and you’ll see the following folders and files:

/
├── public/
│   └── favicon.svg
├── src/
│   └── pages/
│       └── index.astro
├── astro.config.mjs
├── package.json
└── tsconfig.json

src/pages/

This is where your website pages live. Astro looks for .astro, .md, or .mdx files here and automatically creates routes based on the file structure.

src/pages/index.astro → yoursite.com/
src/pages/about.astro → yoursite.com/about
src/pages/blog/first-post.md → yoursite.com/blog/first-post

src/components/

This is where you’ll put reusable components. There’s nothing special about this directory, but it’s a common convention for organizing your Astro, React, Vue, Svelte, or other UI framework components.

src/layouts/

Another common directory for layout components that wrap your page content. This is also just a convention.

public/

Static assets like images, fonts, and files that don’t need to be processed. These are served as-is and can be referenced directly.

astro.config.mjs

Your Astro configuration file. This is where you configure integrations, build options, server options, and more.

package.json

Your project’s dependencies and scripts. Astro provides these scripts by default:

dev: Start the development server
build: Build for production
preview: Preview your production build locally

tsconfig.json

TypeScript configuration. Even if you’re not using TypeScript, this file helps editors provide better IntelliSense.

Start the dev server

Astro comes with a built-in development server that has everything you need for project development.

Start the server

Run the dev command:

npm run dev

pnpm dev

yarn dev

You should see a confirmation message in your terminal:

🚀 astro v6.0.0 started in 45ms

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

Open your browser

Navigate to http://localhost:4321 in your browser to see your site.

The dev server features hot module replacement (HMR), so changes you make to your files will automatically update in the browser without needing to refresh.

Make your first changes

Let’s customize your homepage:

Open the index page

Open src/pages/index.astro in your text editor. You’ll see something like this:

src/pages/index.astro

---
// Component frontmatter
---

<html lang="en">
  <head>
    <meta charset="utf-8" />
    <link rel="icon" type="image/svg+xml" href="/favicon.svg" />
    <meta name="viewport" content="width=device-width" />
    <meta name="generator" content={Astro.generator} />
    <title>Astro</title>
  </head>
  <body>
    <h1>Astro</h1>
  </body>
</html>

Add some content

Update your page with custom content:

src/pages/index.astro

---
const pageTitle = "My First Astro Site";
const skills = ['HTML', 'CSS', 'JavaScript', 'Astro'];
---

<html lang="en">
  <head>
    <meta charset="utf-8" />
    <link rel="icon" type="image/svg+xml" href="/favicon.svg" />
    <meta name="viewport" content="width=device-width" />
    <title>{pageTitle}</title>
  </head>
  <body>
    <h1>{pageTitle}</h1>
    <p>I'm learning to build with Astro!</p>
    <h2>Skills:</h2>
    <ul>
      {skills.map((skill) => <li>{skill}</li>)}
    </ul>
  </body>
</html>

Save the file and check your browser - you should see the changes instantly!

Add styles

Astro makes it easy to style your components with scoped CSS:

src/pages/index.astro

---
const pageTitle = "My First Astro Site";
const skills = ['HTML', 'CSS', 'JavaScript', 'Astro'];
---

<html lang="en">
  <head>
    <meta charset="utf-8" />
    <link rel="icon" type="image/svg+xml" href="/favicon.svg" />
    <meta name="viewport" content="width=device-width" />
    <title>{pageTitle}</title>
  </head>
  <body>
    <h1>{pageTitle}</h1>
    <p>I'm learning to build with Astro!</p>
    <h2>Skills:</h2>
    <ul>
      {skills.map((skill) => <li class="skill">{skill}</li>)}
    </ul>
  </body>
</html>

<style>
  body {
    font-family: sans-serif;
    margin: 2rem;
    line-height: 1.6;
  }
  h1 {
    color: #6366f1;
    font-size: 2.5rem;
  }
  .skill {
    color: #4b5563;
    font-weight: 500;
  }
</style>

Styles defined in a <style> tag are scoped to that component by default. They won’t affect other pages or components!

Create a layout component

To avoid repeating the same HTML structure on every page, let’s create a reusable layout:

Create a layouts directory

mkdir src/layouts

Create a layout component

Create src/layouts/Layout.astro:

src/layouts/Layout.astro

---
const { title } = Astro.props;
---

<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <link rel="icon" type="image/svg+xml" href="/favicon.svg" />
    <meta name="viewport" content="width=device-width" />
    <meta name="generator" content={Astro.generator} />
    <title>{title}</title>
  </head>
  <body>
    <slot />
  </body>
</html>

<style>
  body {
    font-family: sans-serif;
    margin: 0;
    padding: 2rem;
    line-height: 1.6;
  }
</style>

The <slot /> element is where child content will be injected.

Use the layout

Update src/pages/index.astro to use your new layout:

src/pages/index.astro

---
import Layout from '../layouts/Layout.astro';

const pageTitle = "My First Astro Site";
const skills = ['HTML', 'CSS', 'JavaScript', 'Astro'];
---

<Layout title={pageTitle}>
  <h1>{pageTitle}</h1>
  <p>I'm learning to build with Astro!</p>
  <h2>Skills:</h2>
  <ul>
    {skills.map((skill) => <li class="skill">{skill}</li>)}
  </ul>
</Layout>

<style>
  h1 {
    color: #6366f1;
    font-size: 2.5rem;
  }
  .skill {
    color: #4b5563;
    font-weight: 500;
  }
</style>

Add another page

Let’s add an about page to demonstrate routing:

src/pages/about.astro

---
import Layout from '../layouts/Layout.astro';
---

<Layout title="About Me">
  <h1>About Me</h1>
  <p>This is my about page. I'm learning Astro!</p>
  <p>
    I'm working through Astro's tutorial and having a great time.
  </p>
</Layout>

Now visit http://localhost:4321/about to see your new page! Create a navigation component to link between pages:

Create a components directory

mkdir src/components

Create a navigation component

src/components/Navigation.astro

---
// No component script needed
---

<nav>
  <a href="/">Home</a>
  <a href="/about">About</a>
</nav>

<style>
  nav {
    display: flex;
    gap: 1rem;
    padding: 1rem 0;
    border-bottom: 1px solid #e5e7eb;
    margin-bottom: 2rem;
  }
  a {
    color: #6366f1;
    text-decoration: none;
    font-weight: 500;
  }
  a:hover {
    text-decoration: underline;
  }
</style>

Add it to your layout

src/layouts/Layout.astro

---
import Navigation from '../components/Navigation.astro';
const { title } = Astro.props;
---

<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <link rel="icon" type="image/svg+xml" href="/favicon.svg" />
    <meta name="viewport" content="width=device-width" />
    <title>{title}</title>
  </head>
  <body>
    <Navigation />
    <slot />
  </body>
</html>

<style>
  body {
    font-family: sans-serif;
    margin: 0;
    padding: 2rem;
    line-height: 1.6;
  }
</style>

Build for production

When you’re ready to deploy your site, create a production build:

Build your site

npm run build

pnpm build

yarn build

Astro will create an optimized production build in the dist/ folder.

Preview the build locally

Test your production build before deploying:

npm run preview

pnpm preview

yarn preview

This will start a local server to preview your built site at http://localhost:4321.

By default, Astro builds a static site (Static Site Generation or SSG). All pages are pre-rendered to HTML at build time for maximum performance.

Deploy your site

Astro’s static output can be deployed to any static hosting provider:

Netlify

Deploy with zero configuration using Netlify Drop or the Netlify CLI

Vercel

Import your Git repository for automatic deployments on every push

Cloudflare Pages

Connect your repository for instant deployments

GitHub Pages

Deploy directly from your GitHub repository with Actions

Example: Deploy to Netlify

Create a Netlify account

Connect your repository

Import your project from GitHub, GitLab, or Bitbucket

Configure build settings

Netlify should auto-detect these settings:

Build command: npm run build
Publish directory: dist

Deploy

Click “Deploy site” and Netlify will build and deploy your site automatically!

Next steps

Congratulations! You’ve created your first Astro site. Here’s what to explore next:

Add integrations

Enhance your site with React, Tailwind CSS, and more

Content collections

Learn to manage content with type safety

Islands architecture

Master Astro’s approach to partial hydration

API reference

Dive deep into Astro’s configuration and APIs

Get Started

Core Concepts

Features

Integrations

Configuration

Guides

Quick start

Quick start

Create a new project

Understand the project structure

Start the dev server

Make your first changes

Create a layout component

Add another page

Add navigation

Build for production

Deploy your site

Netlify

Vercel

Cloudflare Pages

GitHub Pages

Example: Deploy to Netlify

Next steps

Add integrations

Content collections

Islands architecture

API reference

​Quick start

​Create a new project

​Understand the project structure

​Start the dev server

​Make your first changes

​Create a layout component

​Add another page

​Add navigation

​Build for production

​Deploy your site

Netlify

Vercel

Cloudflare Pages

GitHub Pages

​Example: Deploy to Netlify

​Next steps

Add integrations

Content collections

Islands architecture

API reference

Quick start

Create a new project

Understand the project structure

Start the dev server

Make your first changes

Create a layout component

Add another page

Add navigation

Build for production

Deploy your site

Example: Deploy to Netlify

Next steps