This guide covers the development workflow for your Astro landing page, from initial setup to testing production builds.
Prerequisites Before you begin, ensure you have:
Node.js 18.17.1 or highernpm (comes with Node.js) or another package managerA code editor (VS Code recommended)
The project includes VS Code configuration in .vscode/ for an optimal development experience.
Initial Setup
Install dependencies
Navigate to your project directory and install the required packages: This installs Astro and any other dependencies defined in package.json.
Verify installation
Check that Astro is installed correctly: npm run astro -- --version
You should see version 5.17.1 or higher. Development Server Starting the Server Launch the development server with hot module replacement:
You’ll see output similar to:
🚀 astro v5.17.1 started in 123ms ┃ Local http://localhost:4321/ ┃ Network use --host to expose
The server runs at http://localhost:4321 by default. Open this URL in your browser to see your landing page.
Hot Module Replacement Astro automatically reloads your changes:
Component changes - Updates instantly without full page reloadStyle changes - Injected without refreshContent changes - Page reloads to show new content
src/pages/index.astro
Terminal
--- // Edit this frontmatter --- < html lang = "en" > < head > < meta charset = "utf-8" /> < link rel = "icon" type = "image/svg+xml" href = "/favicon.svg" /> < meta name = "viewport" content = "width=device-width" /> < title > Astro </ title > </ head > < body > <!-- Changes here appear instantly --> < h1 > Astro Landing Page </ h1 > </ body > </ html >
Development Options Customize the dev server behavior:
# Expose to network (access from other devices) npm run dev -- --host # Use a different port npm run dev -- --port 3000 # Open browser automatically npm run dev -- --open
Building for Production Create Production Build Generate optimized static files:
The build process:
Compiles all pages
Astro processes all .astro files in src/pages/ and generates HTML.
Optimizes assets
Minifies JavaScript and CSS
Optimizes images
Generates build artifacts
Outputs to dist/
All production files are written to the dist/ directory: dist/ ├── favicon.ico ├── favicon.svg └── index.html
The dist/ directory contains everything you need to deploy. Upload these files to any static hosting service.
Build Output After a successful build, you’ll see a summary:
building client (vite) ✓ built in 456ms Complete! Build output: dist/
Preview Production Build Test your production build locally before deploying:
This starts a local server serving files from dist/:
🚀 astro preview started ┃ Local http://localhost:4321/
Always run npm run build before npm run preview. The preview command only serves existing files from dist/.
Why Preview?
Test optimizations Verify minification and bundling work correctly
Check routing Ensure all links and routes function properly
Validate assets Confirm images and static files load correctly
Performance testing Measure actual load times and performance
Common Development Tasks Adding a New Page Create a new route by adding a file to src/pages/:
# The file will be accessible at /about touch src/pages/about.astro
--- const pageTitle = "About Us" ; --- < html lang = "en" > < head > < meta charset = "utf-8" /> < meta name = "viewport" content = "width=device-width" /> < title > { pageTitle } </ title > </ head > < body > < h1 > { pageTitle } </ h1 > < p > Learn more about our landing page. </ p > </ body > </ html >
Adding Static Assets Place files in public/ to serve them directly:
# Add an image cp my-logo.png public/logo.png
Reference in your pages:
< img src = "/logo.png" alt = "Logo" />
Using TypeScript Astro supports TypeScript out of the box:
--- interface Props { title : string ; description ?: string ; } const { title , description = "Default description" } : Props = Astro . props ; --- < html lang = "en" > < head > < title > { title } </ title > </ head > < body > < h1 > { title } </ h1 > < p > { description } </ p > </ body > </ html >
Using the Astro CLI Run Astro CLI commands directly:
# Get help npm run astro -- --help # Check for errors npm run astro -- check # Add an integration npm run astro add tailwind # Show Astro info npm run astro info
The -- separator passes arguments to the Astro CLI instead of npm.
Troubleshooting
If port 4321 is occupied: npm run dev -- --port 3000
Hard refresh your browser (Cmd+Shift+R or Ctrl+Shift+R)
Restart the dev server
Clear .astro/ cache: rm -rf .astro
Check for:
Syntax errors in .astro files
Missing imports
TypeScript type errors
Run type checking:
Reinstall dependencies: rm -rf node_modules package-lock.json npm install
Next Steps Now that you’re comfortable with development:
