How to create a new Astro project from scratch?

To create a new Astro project, make sure you have Node.js 22.23.4 or newer, then run npm create astro@latest in your terminal. The wizard asks where to create the project, which starter template to use, whether to install dependencies and whether to initialise a git repository. When it finishes, cd into the new folder and run npm run dev to start the development server at http://localhost:4321/. If you'd rather not use the wizard, you can set a project up by hand in a few minutes: install the astro package, add dev, build and preview scripts, and create your first page at src/pages/index.astro.

Both routes give you the same thing: a project that builds to static HTML by default and can grow into a server-rendered site later. In this article you'll learn the prerequisites, every prompt in the create astro wizard, the official templates, the CLI flags that skip prompts, how to set a project up manually, what the dev, build and preview commands do, and the first changes worth making. All commands were run against Astro 7.4.2 and create-astro 5.3.1.

Prerequisites

You need three things:

• Node.js v22.23.4 or higher: Astro doesn't support odd-numbered releases such as v23, so use an even-numbered LTS line.
• A terminal: Astro is driven by its command-line interface.
• A code editor: VS Code with the official Astro extension (astro-build.astro-vscode) gives you syntax highlighting, TypeScript checking and IntelliSense for .astro files.

Check your Node version first:

node -v

If it's older, install a current LTS release with your version manager of choice (nvm, fnm, Volta or the installer from nodejs.org). Astro also writes the requirement into the generated package.json as "engines": { "node": ">=22.23.4" }, so hosts that respect engines will use a suitable version.

Option 1: The create astro Wizard

You don't need to create an empty folder first. Run the command wherever you keep your projects:

npm create astro@latest

The equivalents for other package managers are pnpm create astro@latest and yarn create astro.

The Prompts

The wizard asks four questions:

1. Where should we create your new project? Enter a folder name such as ./my-site. It's created for you.
2. How would you like to start your new project? Choose a template (see the next section).
3. Install dependencies? Say yes unless you want to use a different package manager afterwards.
4. Initialize a new git repository? Recommended, so you can track changes and deploy from a Git host.

When it's done, you'll see a summary like this:

      ✔  Project initialized!
         ■ Template copied
         ■ Dependencies installed

  next   Liftoff confirmed. Explore your project!

         Enter your project directory using cd ./my-site
         Run npm run dev to start the dev server. q + ENTER to stop.
         Add frameworks like react or tailwind using astro add.

Choosing a Template

The wizard offers four starting points:

Template	What you get	Good for
A basic, helpful starter project (basics)	A layout, a welcome component and some assets	Learning, or a general site
Blog (blog)	Content collections, MDX, RSS, sitemap and post layouts	Blogs and publications
Docs (Starlight)	A full documentation site built on Starlight	Product or project documentation
Minimal (minimal)	A single empty page	Starting completely fresh

Beyond those, the Astro repository has more official examples, including portfolio, framework-react, framework-vue, framework-svelte, with-mdx, with-tailwindcss, with-markdoc, ssr and starlog. You can also start from any theme on GitHub, which is covered below.

Skipping the Prompts With Flags

Every prompt has a matching flag, which is handy for scripts, CI and repeatable set-ups. With npm, put the flags after -- so npm passes them through:

npm create astro@latest my-site -- --template basics --install --no-git --skip-houston --yes

The available flags are:

Flag	Effect
--template <name>	Use an official example or a GitHub repository
--install / --no-install	Install dependencies or not
--git / --no-git	Initialise a git repository or not
--add <integration>	Add an integration such as react or mdx (repeatable)
--yes (-y)	Accept all defaults
--no (-n)	Decline all defaults
--no-ai	Don't create the AGENTS.md file for AI coding agents
--dry-run	Walk through the steps without changing anything
--skip-houston	Skip the Houston mascot animation
--ref	Use a specific Astro branch
--fancy	Enable full Unicode support on Windows

Adding Integrations at Creation Time

You can add official integrations, or any community integration that supports astro add, while creating the project:

npm create astro@latest -- --add react --add partytown

This is the same as creating the project and then running npx astro add react and npx astro add partytown.

Starting From a Theme or Repository

--template also accepts a GitHub user/repo, which copies the repository's main branch. Add #branch to use another branch:

npm create astro@latest -- --template <github-username>/<github-repo>
npm create astro@latest -- --template <github-username>/<github-repo>#<branch>

The Astro themes showcase at astro.build/themes lists many free and paid starting points. If you'd rather try Astro without installing anything, astro.new opens the official templates in an online editor.

What the Wizard Creates

With the basics template, the generated project looks like this:

my-site/
├── .vscode/
│   ├── extensions.json
│   └── launch.json
├── public/
│   ├── favicon.ico
│   └── favicon.svg
├── src/
│   ├── assets/
│   │   ├── astro.svg
│   │   └── background.svg
│   ├── components/
│   │   └── Welcome.astro
│   ├── layouts/
│   │   └── Layout.astro
│   └── pages/
│       └── index.astro
├── .gitignore
├── AGENTS.md
├── astro.config.mjs
├── package.json
├── README.md
└── tsconfig.json

The package.json is deliberately small:

{
  "name": "my-site",
  "type": "module",
  "version": "0.0.1",
  "engines": {
    "node": ">=22.23.4"
  },
  "scripts": {
    "dev": "astro dev",
    "build": "astro build",
    "preview": "astro preview",
    "astro": "astro"
  },
  "dependencies": {
    "astro": "^7.4.2"
  }
}

AGENTS.md is new in recent versions of create-astro. It tells AI coding agents to run the dev server in background mode and points them to the relevant documentation pages. Pass --no-ai if you don't want it. Each file and folder is explained in the Astro project folder structure.

Option 2: Manual Setup

Setting up by hand is a good way to see how little Astro needs.

1. Create a folder and a package.json:

   mkdir my-astro-project
   cd my-astro-project
   npm init --yes
   

2. Install Astro locally (never globally):

   npm install astro
   

3. Add scripts to package.json, replacing the placeholder test script:

   {
     "scripts": {
       "dev": "astro dev",
       "build": "astro build",
       "preview": "astro preview"
     }
   }
   

4. Create your first page at src/pages/index.astro:

   ---
   // src/pages/index.astro
   const year = new Date().getFullYear();
   console.log('This runs in your terminal, not the browser!');
   ---
   <html lang="en">
     <head>
       <meta charset="utf-8" />
       <meta name="viewport" content="width=device-width" />
       <title>My Astro site</title>
     </head>
     <body>
       <h1>Hello, World!</h1>
       <p>&copy; {year}</p>
     </body>
   </html>
   
   <style>
     h1 {
       color: orange;
     }
   </style>
   

5. Create a config file at the project root:

   // astro.config.mjs
   import { defineConfig } from 'astro/config';
   
   export default defineConfig({});
   

6. Add a tsconfig.json, even if you write plain JavaScript, so editors understand your project. Use base, strict or strictest:

   {
     "extends": "astro/tsconfigs/strict",
     "include": [".astro/types.d.ts", "**/*"],
     "exclude": ["dist"]
   }
   

7. Add a .gitignore with at least .astro/, .env, dist/ and node_modules/.

8. Create a public/ folder for files that should be copied as they are, such as robots.txt and favicons.

Recent versions of npm write "type": "commonjs" into a new package.json. That's fine as long as your config file uses the .mjs extension, but setting "type": "module" (as the wizard does) means .js files are treated as ES modules everywhere, which is what Astro projects expect.

Running the Project

The Dev Server

npm run dev

 astro  v7.4.2 ready in 263 ms
┃ Local    http://localhost:4321/
┃ Network  use --host to expose
watching for file changes...

The dev server reloads as you edit files in src/. Add --host to open it on other devices on your network, or --port to change the port. While browsing, the Astro dev toolbar at the bottom of the page helps you inspect islands and spot accessibility issues.

Astro 7 also supports background mode, mainly for AI coding agents and scripts: astro dev --background starts a detached server, and astro dev status, astro dev logs and astro dev stop manage it. When Astro detects an AI agent on macOS or Linux, it uses background mode automatically.

Building and Previewing

npm run build

Astro writes the finished site to dist/. For the manual project above, the build log shows the component script running during the build, and dist/index.html contains:

<!DOCTYPE html><html lang="en" data-astro-cid-lcdefpme><head><meta charset="utf-8"><meta name="viewport" content="width=device-width"><title>My Astro site</title><style>h1[data-astro-cid-lcdefpme]{color:orange}
</style></head><body data-astro-cid-lcdefpme><h1 data-astro-cid-lcdefpme>Hello, World!</h1><p data-astro-cid-lcdefpme>&copy; 2026</p></body></html>

The console.log appeared in the terminal, not in the page, and the <style> was scoped using data-astro-cid-* attributes. Run npm run preview to serve dist/ locally and check the production build before deploying. If your tsconfig.json uses strict or strictest, the build also checks for type errors.

First Things to Do in a New Project

Once the project runs, a few small changes save time later:

• Set your site URL in astro.config.mjs (site: 'https://example.com'). Canonical URLs, sitemaps and RSS feeds rely on it.
• Add integrations you know you'll need: npx astro add react, npx astro add mdx or npx astro add sitemap. The command installs the package and updates your config.
• Create a layout in src/layouts/ so every page shares the same <head> and structure.
• Set up content collections in src/content.config.ts if you're writing articles. See Astro content collections.
• Deploy early. A static Astro site can be deployed to almost any host straight away, and deploying before you've written much makes problems easier to spot.

If you're new to .astro files themselves, continue with what .astro files are and how they work.

---

FAQ: Creating an Astro Project

---

Conclusion

Creating an Astro project takes one command: npm create astro@latest, four answers and npm run dev. Flags such as --template, --add, --install and --yes let you skip the prompts entirely, and --template user/repo starts from any theme on GitHub. If you prefer to see every piece, a manual set-up needs only the astro package, three scripts, a config file and one page.

From there, the workflow is the same whichever route you took: develop with the dev server, build to dist/, preview the result and deploy. Set your site URL, add a layout and the integrations you need, and you have a solid foundation for anything from a single landing page to a large content site.