Skip to content
Tutorials Center
My learning

Topics

Lesson 2 of 37 ยท Getting Started

Creating an Astro Project

Install Astro with create astro, understand the src, public and dist folders, start the dev server and learn what each starter file does.

Starting an Astro project takes one command and about a minute. In this lesson you will create a project, look at every folder the starter gives you, run it locally and understand which files you will edit most often.

You need Node.js (an active LTS version is best) and a package manager: npm, pnpm or yarn. A code editor with Astro support, such as the official VS Code extension, gives you syntax highlighting and type checking in .astro files.

Creating the project

Run the official scaffolding tool. It asks a few questions and writes the files.

Terminal
npm create astro@latest

The wizard asks where to put the project, which template to use (a minimal "Empty" template is perfect for learning, "Blog" gives you a working example), whether to install dependencies, whether to use TypeScript and whether to start a Git repository. You can pass answers on the command line to skip the questions:

Terminal
npm create astro@latest my-site -- --template minimal --install --git

After it finishes, move into the folder and start the development server:

Terminal
cd my-site
npm run dev

The terminal prints a local address, by default http://localhost:4321. Open it and you have a running site. Edit a file and the browser updates immediately.

The project layout

Folders you will use

src/pages Every file becomes a route
src/components Reusable pieces
src/layouts Page shells
public Copied as is
1 / 2

A fresh minimal project looks like this:

TEXT
my-site/
โ”œโ”€โ”€ public/
โ”‚   โ””โ”€โ”€ favicon.svg
โ”œโ”€โ”€ src/
โ”‚   โ””โ”€โ”€ pages/
โ”‚       โ””โ”€โ”€ index.astro
โ”œโ”€โ”€ astro.config.mjs
โ”œโ”€โ”€ package.json
โ””โ”€โ”€ tsconfig.json

Here is what each part does:

  • src/pages/ is the only required folder. Each .astro, .md or .mdx file here becomes a page. This is called file-based routing and has its own lesson: File-based routing.
  • src/components/ and src/layouts/ are conventions, not rules. Astro does not treat them specially, but nearly every project uses them.
  • src/content/ (or any folder you choose) holds content for collections. See Content collections.
  • public/ holds files that are copied untouched to the output, such as favicon.svg, robots.txt and fonts you do not want processed. A file at public/robots.txt is served at /robots.txt.
  • dist/ appears after astro build. It is the finished site. Never edit it by hand.
  • .astro/ contains generated type information. It is safe to delete and is regenerated.

The starter page

The minimal template gives you src/pages/index.astro:

ASTRO
---
// Server code goes here.
---
<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>Astro</title>
  </head>
  <body>
    <h1>Astro</h1>
  </body>
</html>

Change the heading, save, and the browser reloads. Add a second file src/pages/about.astro with its own content and you instantly have a page at /about, with no router to configure.

The package.json scripts

The template defines a few scripts you will use daily:

JSON
{
  "scripts": {
    "dev": "astro dev",
    "build": "astro build",
    "preview": "astro preview",
    "astro": "astro"
  }
}
  • npm run dev starts the dev server with hot reloading.
  • npm run build writes the production site into dist/.
  • npm run preview serves dist/ locally so you can test the real output.
  • npm run astro -- add react runs any Astro CLI command, such as adding an integration. We cover the CLI in The CLI and configuration.

Stand-in: scaffolding a project

The wizard is just a function that writes a file tree from a template. This stand-in builds the minimal template in memory and prints it as a tree, so you can see how a "template" is plain data.

Node.js Stand-in: a project scaffolder

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Stand-in: the dev server and hot reload

The dev server watches files and tells the browser what changed. Here a small simulation keeps a page registry and re-renders only the page whose source changed.

Node.js Stand-in: what a dev server does

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Good habits from day one

  • Commit package.json and the lock file, but not node_modules/ or dist/.
  • Keep .astro/ out of version control as well; it is generated.
  • Set the site option in astro.config.mjs early. Sitemaps, canonical URLs and RSS feeds need your real domain.
  • Use npm run build regularly, not only dev. Some errors (for example, invalid dynamic routes) only show up in a build.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which folder is required for Astro to create pages from files?

    Files in src/pages become routes. The other folders are optional conventions or outputs.
  2. 2. What is the purpose of the public folder?

    public/ holds static files such as favicon.svg and robots.txt that are served as they are.
  3. 3. Which command serves the built dist folder locally so you can test production output?

    astro preview serves the already-built dist folder. astro dev serves source files with hot reload.
  4. 4. Should you edit files inside dist by hand?

    dist is build output. Changes are lost on the next build, so edit the sources in src instead.

Summary

  • npm create astro@latest scaffolds a project; npm run dev starts it on port 4321.
  • src/pages is required; src/components, src/layouts and src/content are conventions.
  • public/ is copied as is, dist/ is the build output, .astro/ holds generated types.
  • Use dev for development, build for production output and preview to test it.
  • Set site in the config early and build often.

Next: Anatomy of an Astro Component