> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/withastro/astro/llms.txt
> Use this file to discover all available pages before exploring further.

# Quick start

> Get your first Astro project up and running in minutes

# 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

<Steps>
  <Step title="Run create-astro">
    Open your terminal and run the installation command:

    <CodeGroup>
      ```bash npm theme={null}
      npm create astro@latest
      ```

      ```bash pnpm theme={null}
      pnpm create astro@latest
      ```

      ```bash yarn theme={null}
      yarn create astro
      ```
    </CodeGroup>
  </Step>

  <Step title="Follow the setup wizard">
    The `create-astro` wizard will guide you through setup. For this tutorial, choose:

    ```bash theme={null}
    # Directory name
    my-first-astro-site

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

    # Install dependencies?
    Yes

    # Initialize git?
    Yes
    ```
  </Step>

  <Step title="Navigate to your project">
    ```bash theme={null}
    cd my-first-astro-site
    ```
  </Step>
</Steps>

## Understand the project structure

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

```text theme={null}
/
├── public/
│   └── favicon.svg
├── src/
│   └── pages/
│       └── index.astro
├── astro.config.mjs
├── package.json
└── tsconfig.json
```

<AccordionGroup>
  <Accordion title="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`
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="src/layouts/">
    Another common directory for layout components that wrap your page content. This is also just a convention.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="astro.config.mjs">
    Your Astro configuration file. This is where you configure integrations, build options, server options, and more.
  </Accordion>

  <Accordion title="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
  </Accordion>

  <Accordion title="tsconfig.json">
    TypeScript configuration. Even if you're not using TypeScript, this file helps editors provide better IntelliSense.
  </Accordion>
</AccordionGroup>

## Start the dev server

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

<Steps>
  <Step title="Start the server">
    Run the dev command:

    <CodeGroup>
      ```bash npm theme={null}
      npm run dev
      ```

      ```bash pnpm theme={null}
      pnpm dev
      ```

      ```bash yarn theme={null}
      yarn dev
      ```
    </CodeGroup>

    You should see a confirmation message in your terminal:

    ```bash theme={null}
    🚀 astro v6.0.0 started in 45ms

    ┃ Local    http://localhost:4321/
    ┃ Network  use --host to expose
    ```
  </Step>

  <Step title="Open your browser">
    Navigate to `http://localhost:4321` in your browser to see your site.
  </Step>
</Steps>

<Info>
  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.
</Info>

## Make your first changes

Let's customize your homepage:

<Steps>
  <Step title="Open the index page">
    Open `src/pages/index.astro` in your text editor. You'll see something like this:

    ```astro src/pages/index.astro theme={null}
    ---
    // 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>
    ```
  </Step>

  <Step title="Add some content">
    Update your page with custom content:

    ```astro src/pages/index.astro theme={null}
    ---
    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!
  </Step>

  <Step title="Add styles">
    Astro makes it easy to style your components with scoped CSS:

    ```astro src/pages/index.astro theme={null}
    ---
    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>
    ```

    <Tip>
      Styles defined in a `<style>` tag are scoped to that component by default. They won't affect other pages or components!
    </Tip>
  </Step>
</Steps>

## Create a layout component

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

<Steps>
  <Step title="Create a layouts directory">
    ```bash theme={null}
    mkdir src/layouts
    ```
  </Step>

  <Step title="Create a layout component">
    Create `src/layouts/Layout.astro`:

    ```astro src/layouts/Layout.astro theme={null}
    ---
    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.
  </Step>

  <Step title="Use the layout">
    Update `src/pages/index.astro` to use your new layout:

    ```astro src/pages/index.astro theme={null}
    ---
    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>
    ```
  </Step>
</Steps>

## Add another page

Let's add an about page to demonstrate routing:

```astro src/pages/about.astro theme={null}
---
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:

<Steps>
  <Step title="Create a components directory">
    ```bash theme={null}
    mkdir src/components
    ```
  </Step>

  <Step title="Create a navigation component">
    ```astro src/components/Navigation.astro theme={null}
    ---
    // 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>
    ```
  </Step>

  <Step title="Add it to your layout">
    ```astro src/layouts/Layout.astro {2,15} theme={null}
    ---
    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>
    ```
  </Step>
</Steps>

## Build for production

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

<Steps>
  <Step title="Build your site">
    <CodeGroup>
      ```bash npm theme={null}
      npm run build
      ```

      ```bash pnpm theme={null}
      pnpm build
      ```

      ```bash yarn theme={null}
      yarn build
      ```
    </CodeGroup>

    Astro will create an optimized production build in the `dist/` folder.
  </Step>

  <Step title="Preview the build locally">
    Test your production build before deploying:

    <CodeGroup>
      ```bash npm theme={null}
      npm run preview
      ```

      ```bash pnpm theme={null}
      pnpm preview
      ```

      ```bash yarn theme={null}
      yarn preview
      ```
    </CodeGroup>

    This will start a local server to preview your built site at `http://localhost:4321`.
  </Step>
</Steps>

<Info>
  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.
</Info>

## Deploy your site

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

<CardGroup cols={2}>
  <Card title="Netlify" icon="netlify">
    Deploy with zero configuration using Netlify Drop or the Netlify CLI
  </Card>

  <Card title="Vercel" icon="vercel">
    Import your Git repository for automatic deployments on every push
  </Card>

  <Card title="Cloudflare Pages" icon="cloudflare">
    Connect your repository for instant deployments
  </Card>

  <Card title="GitHub Pages" icon="github">
    Deploy directly from your GitHub repository with Actions
  </Card>
</CardGroup>

### Example: Deploy to Netlify

<Steps>
  <Step title="Create a Netlify account">
    Sign up at [netlify.com](https://netlify.com)
  </Step>

  <Step title="Connect your repository">
    Import your project from GitHub, GitLab, or Bitbucket
  </Step>

  <Step title="Configure build settings">
    Netlify should auto-detect these settings:

    * **Build command**: `npm run build`
    * **Publish directory**: `dist`
  </Step>

  <Step title="Deploy">
    Click "Deploy site" and Netlify will build and deploy your site automatically!
  </Step>
</Steps>

## Next steps

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

<CardGroup cols={2}>
  <Card title="Add integrations" icon="puzzle-piece" href="/integrations/overview">
    Enhance your site with React, Tailwind CSS, and more
  </Card>

  <Card title="Content collections" icon="book" href="/concepts/content-collections">
    Learn to manage content with type safety
  </Card>

  <Card title="Islands architecture" icon="island-tropical" href="/concepts/islands">
    Master Astro's approach to partial hydration
  </Card>

  <Card title="API reference" icon="code" href="/api/configuration">
    Dive deep into Astro's configuration and APIs
  </Card>
</CardGroup>