Back to Home
Astro logoAstro INTERMEDIATE

Astro

Modern web framework with islands architecture for building fast, content-focused websites with zero JS by default

10 min read
astrostatic-siteislandsjavascripttypescriptssrview-transitions

Getting Started

Project setup and basic configuration

Create New Project

📄 Codebash
✅ CLI guides you through setup with TypeScript, dependencies, and git
💡 Dev server runs on http://localhost:4321 by default
🔍 Official templates: minimal, blog, portfolio, docs
⚡ Supports React, Vue, Svelte, Solid, Preact, Alpine.js
setupcliinstall

Project Structure

text
✅ src/pages/ creates routes automatically via file name
💡 public/ files served at root without processing
🔍 src/content/ requires content.config.ts for collections
⚡ All file types supported: .astro, .js, .ts, .jsx, .tsx, .vue, .svelte
structureorganizationfiles

Components & Syntax

Astro component structure, props, and slots

Component Structure

astro
✅ Components have two sections: script (---) and template (HTML)
💡 Script runs only on server at build time or on-demand
🔍 Use {expression} for JavaScript in template
⚡ Styles are scoped to component automatically
componentsyntaxstructure

Props & TypeScript

astro
✅ Access props via Astro.props object
💡 Use interface Props for TypeScript type checking
🔍 Destructure with default values for optional props
⚡ Functions cannot be passed to hydrated framework components
propstypescripttypes

Slots

astro
✅ <slot /> renders child content passed to component
💡 Named slots allow multiple content areas
🔍 Fallback content appears if slot is empty
⚡ Use Astro.slots API to check if slot has content
slotscompositionlayouts

Routing & Pages

File-based routing and dynamic routes

File-Based Routing

text
✅ Each file in src/pages/ becomes a route automatically
💡 index.astro maps to parent directory path
🔍 Prefix with _ to exclude from routing
⚡ .astro, .md, .mdx, .html, .js, .ts all supported
routingfile-basedpages

Dynamic Routes

astro
✅ getStaticPaths() generates all routes at build time
💡 Return array of { params, props } objects
🔍 Access params via Astro.params, props via Astro.props
⚡ Use [...rest] for catch-all routes of any depth
dynamic-routesgetStaticPathsparams

Content Collections

Type-safe content management with Markdown/MDX

Define Collection

typescript
✅ defineCollection() configures collection with loader and schema
💡 Use glob() loader for file-based content
🔍 Zod schema validates frontmatter at build time
⚡ Store content in any directory, specify with base option
contentcollectionsschemadefineCollection

Query Collections

astro
✅ getCollection() fetches entire collection as array
💡 Filter function receives {id, data} for each entry
🔍 getEntry() fetches single entry by collection and id
⚡ Access frontmatter via .data, entry id via .id
getCollectiongetEntryquery

Render Content

astro
✅ render() processes Markdown/MDX into renderable Content component
💡 Returns headings array for table of contents generation
🔍 Content component renders the processed HTML
⚡ Works with both Markdown and MDX files
rendercontentmarkdown

Framework Components

Using React, Vue, Svelte with client directives

Client Directives

astro
✅ Framework components render as static HTML by default
💡 client:* directives add interactivity (ship JavaScript)
🔍 client:load for above-fold critical components
⚡ client:visible for lazy loading below-the-fold content
clienthydrationislandsdirectives

Mix Frameworks

astro
✅ Mix React, Vue, Svelte, Solid in same .astro file
💡 Each framework only ships its own runtime when used
🔍 Cannot mix frameworks within same framework component file
⚡ Supported props: strings, numbers, objects, arrays, dates, maps, sets
frameworksreactvuesveltemulti-framework

Images & Assets

Optimized image handling with Image component

Image Component

astro
✅ Image component automatically optimizes at build time
💡 Local images (src/) auto-detect dimensions to prevent CLS
🔍 Remote images need authorization in astro.config.mjs
⚡ Picture component generates multiple formats and sizes
imagesImageassetsoptimization

View Transitions

Animated page transitions and SPA routing

Enable Transitions

astro
✅ ClientRouter enables SPA-like navigation with animations
💡 Built-in animations: fade (default), slide, none, initial
🔍 transition:name pairs elements between old/new pages
⚡ transition:persist keeps elements across navigation
transitionsClientRouteranimationsspa

Transition Control

astro
✅ navigate() triggers transitions programmatically
💡 data-astro-reload forces full page navigation
🔍 astro:page-load ideal for re-initializing scripts
⚡ Respects prefers-reduced-motion automatically
navigatelifecycleevents

API Routes & Endpoints

Server endpoints and API route handling

Create Endpoints

typescript
✅ Export GET, POST, PUT, DELETE functions from .ts/.js files
💡 File extension determines output: .json.ts → .json
🔍 Access params, request, redirect from context object
⚡ SSR mode: live routes. Static mode: pre-rendered files
apiendpointsroutesAPIRoute