> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/withastro/astro/llms.txt
> Use this file to discover all available pages before exploring further.
# Server Islands
> Mix static and dynamic content with Astro's server islands for optimal performance
Server Islands allow you to embed dynamic, server-rendered components within static pages. This gives you the best of both worlds: fast static page loads with selective server-rendered content for personalization, real-time data, or authentication.
## What are Server Islands?
Server Islands are components that render on the server for each request, even when the rest of the page is statically generated. They load asynchronously after the initial page render, providing dynamic content without blocking the main page load.
Server Islands require an SSR adapter and work in `output: 'static'` or `output: 'hybrid'` modes.
## Creating a Server Island
Mark any component as a server island using the `server:defer` directive:
```astro src/pages/index.astro theme={null}
---
import UserProfile from '../components/UserProfile.astro';
import RealtimeStock from '../components/RealtimeStock.astro';
---
My Site
Welcome to My Site
This content is static and super fast!
```
## Server Island Component
Server islands are just regular Astro components that can access server-side features:
```astro src/components/UserProfile.astro theme={null}
---
const { cookies } = Astro;
const userId = cookies.get('userId')?.value;
let user = null;
if (userId) {
user = await db.users.find(userId);
}
---
{user ? (
Welcome back, {user.name}!
Last login: {new Date(user.lastLogin).toLocaleString()}
)}
```
## How It Works
The static HTML is served immediately with a placeholder for the server island.
```html theme={null}
Loading...
```
The browser requests the server island content via a background fetch:
```
GET /_server-islands/UserProfile?s=encrypted_slots&p=encrypted_props
```
The server responds with rendered HTML, which replaces the placeholder:
```html theme={null}
Welcome back, John!
```
* Initial page loads instantly (static HTML)
* Server islands load asynchronously
* No blocking on server-rendered content
* Main content visible immediately
Provide fallback content that shows while loading:
```astro theme={null}
Loading profile...
```
## Use Cases
Show user-specific content like profiles, recommendations, or preferences
Display live data like stock prices, availability, or analytics
Render auth-protected content based on session state
Serve different variants for experiments
## Passing Props
Pass props to server islands just like regular components:
```astro src/pages/product/[id].astro theme={null}
---
import StockStatus from '../../components/StockStatus.astro';
const { id } = Astro.params;
const product = await getProduct(id);
---
{stock.available ? (
✓ In Stock ({stock.quantity} available)
) : (
✗ Out of Stock
)}
```
Props are encrypted during transmission for security. Don't pass sensitive data that shouldn't be cached.
## Slots
Use slots to pass content to server islands:
```astro src/pages/dashboard.astro theme={null}
---
import AdminPanel from '../components/AdminPanel.astro';
---
Loading admin panel...
Admin Controls
Manage your site here
```
```astro src/components/AdminPanel.astro theme={null}
---
const user = Astro.locals.user;
if (!user?.isAdmin) {
return Astro.redirect('/forbidden');
}
---
```
## Configuration
Enable server islands in your Astro config:
```js astro.config.mjs theme={null}
import { defineConfig } from 'astro/config';
import node from '@astrojs/node';
export default defineConfig({
output: 'hybrid',
adapter: node(),
experimental: {
serverIslands: true
}
});
```
Server islands work best with `output: 'hybrid'` for mixing static and dynamic content.
## Combining with Client Islands
Mix server islands with client-side framework components:
```astro src/pages/app.astro theme={null}
---
import UserData from '../components/UserData.astro';
import InteractiveChart from '../components/Chart.tsx';
---
About Our Service
Static marketing content...
```
* Render on server for each request
* Access databases and sessions
* Load asynchronously
* No JavaScript hydration needed
* Render on client
* Interactive components
* Require JavaScript
* Hydrate in the browser
## Caching Strategies
Control caching for server islands:
```astro src/components/CachedWidget.astro theme={null}
---
// Set cache headers for this server island
Astro.response.headers.set('Cache-Control', 'public, max-age=60');
const data = await fetchExpensiveData();
---
{data.title}
Updated: {new Date().toLocaleTimeString()}
```
Use with `server:defer`:
```astro theme={null}
```
## Error Handling
Handle errors gracefully in server islands:
```astro src/components/WeatherWidget.astro theme={null}
---
interface Props {
city: string;
}
const { city } = Astro.props;
let weather;
let error;
try {
weather = await fetchWeather(city);
} catch (e) {
error = e.message;
}
---
{error ? (
Failed to load weather: {error}
) : (
{weather.city}
{weather.temperature}°F
{weather.condition}
)}
```
## Loading States
Provide meaningful loading states:
```astro src/pages/index.astro theme={null}
---
import RecentActivity from '../components/RecentActivity.astro';
---
```
## Advanced Example
A complete example combining multiple concepts:
```astro src/pages/dashboard.astro theme={null}
---
import UserStats from '../components/UserStats.astro';
import RealtimeNotifications from '../components/Notifications.astro';
import ActivityFeed from '../components/ActivityFeed.astro';
---
Dashboard
Dashboard
Loading stats...
Loading notifications...
Loading activity...
```
## Best Practices
Server islands should be focused components. Split large components into multiple islands.
Always show something while loading. Use skeleton screens or loading messages.
Gracefully handle failures and provide retry mechanisms.
Cache server island responses when appropriate to reduce server load.
Track server island response times and optimize slow queries.
## Related Resources
Understanding rendering modes
Building Astro components
Learn about islands architecture
Add server-side logic
