Which Node.js version should I use for Astro projects?

Use a current LTS version of Node.js for best compatibility and predictable package behavior.

What command starts Astro in local development mode?

Run npm run dev in your project directory, then open the local URL shown in the terminal.

How do I verify the project is ready for production?

Run npm run build and confirm the build completes successfully with generated output in the dist folder.

Getting Started with Astro (Node.js Setup)

Summary: A beginner-friendly guide to set up Astro with Node.js, add Tailwind CSS, run your first project, and build for production.

Introduction

Astro is a modern web framework focused on fast content sites.
This guide walks you through installing Node.js, creating an Astro project, running it locally, and building it for production.

Prerequisites

Before you start, make sure you have:

Node.js installed (LTS recommended)
npm available in your terminal
A code editor (VS Code or Cursor works well)

Check your installed versions:

node -v
npm -v

If these commands fail, install Node.js from the official site:

https://nodejs.org

Step 1: Create a new Astro project

Run:

npm create astro@latest

You will be prompted for:

Project folder name
Template choice
TypeScript preference
Dependency install confirmation

If dependencies were not installed during setup, run:

npm install

Step 2: Start the development server

Move into the project folder and run:

cd your-project-name
npm run dev

Astro will show a local URL, usually:

http://localhost:4321

Open that URL in your browser to view your site.

Step 3: Understand key project commands

Common commands you will use:

npm run dev

Starts local development server with hot reload.

npm run build

Builds production-ready files in dist/.

npm run preview

Serves the production build locally for testing.

Step 4: Add Tailwind CSS

Astro provides an official integration, which is the easiest setup path.

From your Astro project root, run:

npx astro add tailwind

This command will:

Install Tailwind dependencies
Add the Astro Tailwind integration
Create/update the needed config files

If the command prompts for install changes, confirm with Y.

Quick test

Edit src/pages/index.astro (or any page) and add:

<h1 class="text-3xl font-bold text-blue-600">Tailwind is working</h1>

Start dev server:

npm run dev

If the heading is blue and bold, Tailwind is active.

Step 5: Add your first page

Create a file:

src/pages/about.astro

Add:

---
---
<h1>About</h1>
<p>My first Astro page.</p>

Visit:

http://localhost:4321/about

Step 6: Build and test production output

Run:

npm run build
npm run preview

This confirms your production build works before deployment.

Troubleshooting

`node` command not found

Node.js is not installed or not on PATH. Reinstall Node.js LTS and reopen terminal.

Port already in use

Run Astro on another port:

npm run dev -- --port 4322

Package install errors

Try clearing and reinstalling:

rm -rf node_modules package-lock.json
npm install

On Windows PowerShell:

Remove-Item -Recurse -Force node_modules
Remove-Item package-lock.json
npm install

Next steps

After initial setup:

Learn Astro layouts and components
Add Markdown content collections
Add SEO metadata and sitemap
Deploy to a platform such as Netlify, Vercel, or Azure Static Web Apps