Day3 - Astro Series: Hello Astro World

@ Astro

A beautiful gradient background with a title: "Create a New Project"

Preface

Previously we mentioned how Astro builds pages, such as breaking a page into “components” and using Astro Islands to assemble pages. In this chapter we’ll actually create an Astro project!

Creating a project

Prerequisites

Astro provides a CLI tool to scaffold projects. Before creating a project, you’ll need the following environment:

Create an Astro project with the automatic setup tool

Terminal window
npm create astro@latest
Terminal window
# Install the following packages create-astro@4.0.1? Type y to continue
Need to install the following packages:
  create-astro@4.0.1
Ok to proceed? (y) y


# Where should we create your new project?
   dir   Where should we create your new project?
         ./project-name


# Use a project template? 1. Include sample files (recommended) 2. Use blog template 3. Empty
   tmpl   How would you like to start your new project?
         > Include sample files (recommended)
         — Use blog template
         — Empty


# Install dependencies? (recommended)
   deps   Install dependencies? (recommended)
         ● Yes  ○ No


# Do you plan to use TypeScript?
   ts   Do you plan to write TypeScript?
         ● Yes  ○ No


# How strict should TypeScript be configured? 1. Strict (recommended) 2. Strictest 3. Relaxed
   use   How strict should TypeScript be?
         > Strict (recommended)
         — Strictest
         — Relaxed


# Initialize a Git repo?
git   Initialize a new git repository? (optional)
         ● Yes  ○ No

With that, a complete Astro project is created. The overall project structure will look like this:

Terminal window
project
├── .git # Git-related files
├── .vscode # VS Code related files
├── node_modules # NPM dependencies
├── public # Files you don't want Astro to process
│   └── favicon.svg
├── src # Project source code
│   ├── pages
│   │   └── index.astro
│   └── env.d.ts
├── .gitignore
├── astro.config.mjs # Astro config file
├── package.json # NPM records
├── README.md # Project description file
└── tsconfig.json # TypeScript config file

public/ folder

Used to store files you don’t want Astro to process. Contents are copied verbatim into the rendered output folder.

src/ folder

Used to store project source files. You can organize your source files into folders. Folder names are flexible; a common src structure looks like this:

Terminal window
src/
├── components # Components
├── content # Files related to Content Collections
├── layouts # Layout components
├── pages # Page components
└── styles # Project styles

Except for src/pages/ and src/content/, folder names can be whatever you prefer. Only the pages folder is required because files in it are used to create pages. Later chapters will explain their individual purposes; for now it’s enough to understand the general project layout.

Starting Astro

There are three common commands: start the dev server, build the site, and preview the built site. The rendered site is output to a dist folder by default.

Terminal window
# Start the development server
npm run dev


# Build the site
npm run build


# Preview the built site
npm run preview

Summary

Creating an Astro project is very simple. The CLI quickly scaffolds a working project. If you’re familiar with Vite, the structure may feel familiar, since Astro uses Vite under the hood!

Further reading