AstroHow-ToBeginner · 3 min read

How to Enable SSR in Astro: Simple Guide

To enable SSR in Astro, create a server entry point by adding an astro.config.mjs file with the output: 'server' option and use server-side code in your components. This switches Astro from static site generation to server-side rendering, allowing dynamic content on each request.

📐

Syntax

To enable SSR in Astro, you need to configure the project to output server-rendered pages instead of static HTML. This is done by setting the output option to 'server' in the astro.config.mjs file.

Key parts:

export default: exports the config object.
output: 'server': tells Astro to build for server-side rendering.
adapter-node: adapter to run Astro on a Node.js server.

javascript

import { defineConfig } from 'astro/config';
import node from '@astrojs/node';

export default defineConfig({
  output: 'server',
  adapter: node(),
});

💻

Example

This example shows a simple Astro project configured for SSR that renders the current server time dynamically on each request.

astro

---
const now = new Date().toLocaleString();
---
<html lang="en">
  <head>
    <title>SSR Example</title>
  </head>
  <body>
    <h1>Server-Side Rendered Time</h1>
    <p>The current server time is: {now}</p>
  </body>
</html>

Output

<html lang="en"> <head> <title>SSR Example</title> </head> <body> <h1>Server-Side Rendered Time</h1> <p>The current server time is: 6/15/2024, 10:00:00 AM</p> </body> </html>

⚠️

Common Pitfalls

Common mistakes when enabling SSR in Astro include:

Not installing or configuring the correct adapter (e.g., @astrojs/node) for server output.
Forgetting to set output: 'server' in astro.config.mjs.
Using browser-only APIs or client-side code in server components, causing runtime errors.
Expecting static assets to update without rebuilding when using SSR; SSR only affects HTML rendering.

javascript

/* Wrong: Missing adapter and output setting */
export default {
  /* No output or adapter configured */
};

/* Right: Proper SSR config */
import { defineConfig } from 'astro/config';
import node from '@astrojs/node';

export default defineConfig({
  output: 'server',
  adapter: node(),
});

📊

Quick Reference

Set output: 'server' in astro.config.mjs to enable SSR.
Use an adapter like @astrojs/node to run Astro on a server.
Write server-side code in frontmatter to generate dynamic content.
Deploy your SSR build to a Node.js environment or compatible server.

✅

Key Takeaways

Enable SSR by setting output: 'server' in astro.config.mjs.

Use a server adapter like @astrojs/node to run SSR builds.

Write dynamic server-side code in Astro frontmatter for fresh content.

Avoid client-only APIs in server-rendered components to prevent errors.

Deploy SSR builds to Node.js or compatible server environments.