Skip to main content

​
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

1

Run create-astro

Open your terminal and run the installation command:
npm create astro@latest
2

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
3

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
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
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.
Another common directory for layout components that wrap your page content. This is also just a convention.
Static assets like images, fonts, and files that don’t need to be processed. These are served as-is and can be referenced directly.
Your Astro configuration file. This is where you configure integrations, build options, server options, and more.
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
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.
1

Start the server

Run the dev command:
npm run 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
2

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:
1

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

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!
3

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:
1

Create a layouts directory

mkdir src/layouts
2

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.
3

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!

​
Add navigation

Create a navigation component to link between pages:
1

Create a components directory

mkdir src/components
2

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

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:
1

Build your site

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

Preview the build locally

Test your production build before deploying:
npm run 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

1

Create a Netlify account

Sign up at netlify.com
2

Connect your repository

Import your project from GitHub, GitLab, or Bitbucket
3

Configure build settings

Netlify should auto-detect these settings:
  • Build command: npm run build
  • Publish directory: dist
4

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

Build docs developers (and LLMs) love

Get started for freeTalk to us