Skip to content

The Astro CLI

If you have run next dev you already know the pattern. Astro ships a single astro binary that handles every stage of the development lifecycle — development server, production build, local preview, integration scaffolding, and type checking. It maps almost exactly to the Next.js CLI commands you already use daily.

Core commands

# Start the dev server (hot module reloading, port 4321 by default)
npx astro dev

# Production build → dist/
npx astro build

# Serve the dist/ folder locally (mirrors the production build exactly)
npx astro preview

# Add an official integration and update astro.config.mjs automatically
npx astro add react
npx astro add tailwind
npx astro add sitemap

# Type-check all .astro and .ts files
npx astro check

package.json scripts

Both frameworks follow the same convention of aliasing the CLI commands to short script names.

// package.json — Next.js project
{
  "scripts": {
    "dev":         "next dev",
    "build":       "next build",
    "start":       "next start",
    "lint":        "next lint",
    "type-check":  "tsc --noEmit"
  }
}

// package.json — Astro project
{
  "scripts": {
    "dev":     "astro dev",
    "build":   "astro build",
    "preview": "astro preview",
    "check":   "astro check"
  }
}

Two things stand out:

astro preview is the local preview server — it is not a production server. Use an adapter (Node, Vercel, Cloudflare) for real production SSR.
astro check replaces the two-step tsc --noEmit + linter that Next.js projects typically maintain separately.

The `astro add` command

npx astro add scaffolds official integrations in one step: it installs the npm package, updates astro.config.mjs, and prints what changed.

# Add the React integration (enables .tsx islands)
npx astro add react

# Add Tailwind CSS
npx astro add tailwind

# Add the Vercel SSR adapter
npx astro add vercel

# Add multiple at once
npx astro add react tailwind sitemap

There is no Next.js equivalent for this — in Next you npm install a package, then manually update next.config.js. The astro add command automates the config step.

CLI flags

# Custom port
astro dev --port 3000

# Bind to all interfaces (useful in Docker / WSL)
astro dev --host

# Verbose output during build
astro build --verbose

# Watch mode for astro check (re-runs on file save)
astro check --watch