Astro is evolving with Jamstack and broadening its application with the introduction of server-side rendering (SSR). SSR support in Astro is big because:
- Astro has been a framework focused around content sites; adding SSR expands the types of contents sites you can build, such as larger CMS-backed sites and E-commerce.
- Astro provides a simplified template syntax that allows you to write mostly HTML, with sprinkles of JS where you need.
- API routes allow you to now handle non-HTML requests, such as POST requests to save a user’s profile, or a GET to dynamically retrieve a list of recipes as JSON.
See the announcement post to learn more on what Astro SSR offers.
Netlify continues to be one of the best places to deploy your Astro site to production, and we’ve been lucky to work with Netlify on a launch-day Netlify adapter for Astro. In this post, we’re going to walk through the steps of deploying an Astro SSR site to Netlify.
Deploying an Astro App with Netlify Functions
Depending on what you are building, you very well might not need SSR. Static-site generation works great for a number of use-cases including blogs and other content sites that change infrequently.
Static sites are easier to deploy, do not need an adapter, and can be built locally and previewed more precisely. If this sounds like the site you are building, check out the Astro deploy docs to learn how to deploy a static site to Netlify.
If you want to learn SSR anyways, let’s walk through setting up an Astro app to be deployed to Netlify Functions.
Setting up your project
This guide assumes you already have an Astro app built, but if you need to create one, see the Astro installation docs on getting set up. It’s as simple as:
npm init astro@latest
Configuration
By default Astro apps build your website to static HTML. To take advantage of SSR you need to use an adapter. With Netlify an adapter already exists and can be installed like so:
npm install @astrojs/netlify --save
After installed, update your astro.config.mjs to use it on the adapter configuration option:
import { defineConfig } from 'astro/config';
+ import netlify from '@astrojs/netlify/functions';
export default defineConfig({
+ adapter: netlify()
});
The adapter will build everything (including your static assets) to the netlify/ folder, so no additional configuration is needed to your netlify.toml file (if you have one).
Deployment
The first step to deploying your Astro site is signing up for Netlify. Once you are signed up create a site to deploy the Astro app to.
You can configure the site to deploy when pushing to a GitHub repository, but for this guide we’ll use the Netlify CLI to deploy.
Install the CLI if you don’t already have it:
npm i -g netlify-cli@latest
Then build your Astro site as you normally would:
What you might notice is different about this build is that instead of .html files in your build folder, there is a single file, netlify/functions/entry.mjs. This is your entire site built and ready to render on requests.
Also present is netlify/_redirects. This is a configuration file produced by the adapter which specifies each route in your app (defined via file-based-routing) to be rendered by the SSR function.
You can go ahead and deploy to a preview URL by running netlify deploy:
You might notice that the output of this command picks up on the function to be used by SSR. It will give you a URL to go to to see your site run. When you’re ready to deploy to production just add the --prod flag.
Next Steps
Netlify Functions and Astro are an amazing pair that, as you have seen, enables building dynamic applications that get you to production quickly.
With Astro’s support for SSR you can now:
- Handle redirects, 404s, and other dynamic response codes directly in your templates.
- Handle non-GET HTTP methods directly in your Astro frontmatter; allowing save operations.
- Handle API calls from the client, allowing you to build the same dynamic UI you might build with the SPA approach.
SSR support in Astro is still experimental as we refine the APIs while we approach a 1.0 release. If you need help reach out in our Discord channel.
