Skip to main content
This reference documents all available commands for working with your Astro landing page project. All commands should be run from the root of your project directory.

​
Prerequisites

Before running any commands, ensure you have installed project dependencies: 
npm install
This installs Astro and all required packages defined in package.json.

​
Development commands

​
Start development server

npm run dev
Starts the Astro development server with hot module replacement (HMR). Your site will be available at http://localhost:4321. Features:
  • Hot reloading when you edit files
  • Fast refresh for .astro components
  • Instant feedback on syntax errors
  • Automatic TypeScript type checking
The development server watches for file changes in src/ and automatically updates your browser. No manual refresh needed.
Options: You can pass additional flags to the dev server: 
# Run on a different port
npm run dev -- --port 3000

# Listen on all network interfaces
npm run dev -- --host

# Open browser automatically
npm run dev -- --open
The -- syntax passes arguments through npm to the underlying Astro command.

​
Build commands

​
Production build

npm run build
Builds your site for production deployment. This command:
  1. Compiles all .astro files to optimized HTML
  2. Bundles and minifies JavaScript
  3. Optimizes CSS and removes unused styles
  4. Processes and optimizes images
  5. Generates the final static site in ./dist/
Output: The build process creates a dist directory containing:
  • Static HTML files for each page
  • Optimized JavaScript bundles
  • Minified CSS files
  • Copied assets from public/
npm run build
Always test your production build locally using npm run preview before deploying to ensure everything works correctly.

​
Preview production build

npm run preview
Starts a local server to preview your production build. This serves the static files from ./dist/ exactly as they would appear on a production server. Use cases:
  • Test production build before deployment
  • Verify optimizations are working correctly
  • Check that all links and assets resolve properly
  • Validate responsive design at production speed
You must run npm run build before using the preview command. The preview server only serves pre-built files.
Preview with custom port: 
npm run preview -- --port 8080

​
Astro CLI commands

​
Run Astro CLI directly

npm run astro
Executes the Astro CLI with any command you specify. This is a passthrough to the Astro command-line interface. Common Astro CLI commands: 
npm run astro -- --help
Displays all available Astro CLI commands and options.
npm run astro add react
npm run astro add tailwind
npm run astro add sitemap
Installs and configures Astro integrations. The CLI automatically updates astro.config.mjs and installs required dependencies.
npm run astro check
Runs diagnostics on your project:
  • TypeScript type checking
  • Accessibility checks in .astro files
  • Validation of configuration files
npm run astro info
Displays information about your current Astro environment:
  • Astro version
  • Node.js version
  • Operating system
  • Installed integrations
npm run astro sync
Generates TypeScript type definitions for content collections and other Astro features. Useful after modifying configuration.
npm run astro add page about
npm run astro add component Header
Generates new pages or components with boilerplate code.

​
Command cheat sheet

Quick reference for all available commands:
CommandAction
npm installInstall project dependencies
npm run devStart development server at localhost:4321
npm run buildBuild production site to ./dist/
npm run previewPreview production build locally
npm run astroRun Astro CLI commands
npm run astro -- --helpDisplay Astro CLI help
npm run astro add [integration]Add and configure an integration
npm run astro checkCheck project for issues
npm run astro infoDisplay environment information
npm run astro syncGenerate type definitions

​
Development workflow

Here’s a typical development workflow using these commands: 
# Clone the repository
git clone <repository-url>
cd <project-directory>

# Install dependencies
npm install

# Start development server
npm run dev

​
CI/CD integration

These commands integrate seamlessly into continuous integration pipelines: 
name: Deploy
on:
  push:
    branches: [main]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
        with:
          node-version: 18
      - run: npm install
      - run: npm run build
      - run: npm run astro check
Most hosting platforms (Vercel, Netlify, Cloudflare Pages) automatically detect Astro projects and use the correct build command.

​
Troubleshooting commands

​
Clear cache and rebuild

If you encounter build issues, try clearing cached files: 
# Remove build artifacts
rm -rf dist/

# Remove Astro cache
rm -rf .astro/

# Remove dependencies
rm -rf node_modules/

# Reinstall and rebuild
npm install
npm run build

​
Debug build issues

Run the build with verbose logging: 
npm run build -- --verbose

​
Check for outdated packages

Ensure you’re using compatible versions: 
# Check for updates
npm outdated

# Update Astro
npm install astro@latest
Major version updates may include breaking changes. Always review the Astro changelog before upgrading.

​
Performance tips

The dev command provides the fastest feedback loop. Only use build and preview when you need to test production-specific behavior.
Astro automatically parallelizes builds across CPU cores. Ensure your build environment has adequate resources for optimal performance.
After running npm run build, check the size of your dist/ directory. Astro displays bundle sizes in the build output.
Add npm run astro check to your Git pre-commit hooks to catch errors before they reach CI/CD.

​
Next steps

Build docs developers (and LLMs) love

Get started for freeTalk to us