Skip to content
This is an unmaintained snapshot of the Astro v4 docs. View the latest docs.

@astrojs/ netlify

v5.5.4 GitHub npm Changelog

This adapter allows Astro to deploy your hybrid or server rendered site to Netlify.

If you’re using Astro as a static site builder, you don’t need an adapter.

Learn how to deploy your Astro site in our Netlify deployment guide.

Why Astro Netlify

Section titled Why Astro Netlify

Netlify is a deployment platform that allows you to host your site by connecting directly to your GitHub repository. This adapter enhances the Astro build process to prepare your project for deployment through Netlify.

Installation

Section titled Installation

Astro includes an astro add command to automate the setup of official integrations. If you prefer, you can install integrations manually instead.

Add the Netlify adapter to enable SSR in your Astro project with the astro add command. This will install @astrojs/netlify and make the appropriate changes to your astro.config.mjs file in one step.

Terminal window
npx astro add netlify

Manual Install

Section titled Manual Install

First, install the Netlify adapter to your project’s dependencies using your preferred package manager:

Terminal window
npm install @astrojs/netlify

Then, add the adapter and your desired on-demand rendering mode to your astro.config.* file:

astro.config.mjs
 import { defineConfig } from 'astro/config';
 import netlify from '@astrojs/netlify';


 export default defineConfig({
    // ...
    output: 'server',
    adapter: netlify(),
 });

Usage

Section titled Usage

Read the full deployment guide here.

Follow the instructions to build your site locally. After building, you will have a .netlify/ folder containing both Netlify Functions in the .netlify/functions-internal/ folder and Netlify Edge Functions in the.netlify/edge-functions/ folder.

To deploy your site, install the Netlify CLI and run:

Terminal window
netlify deploy

The Netlify Blog post on Astro and the Netlify Docs provide more information on how to use this integration to deploy to Netlify.

Accessing edge context from your site

Section titled Accessing edge context from your site

Netlify Edge Functions provide a context object that includes metadata about the request such as a user’s IP, geolocation data, and cookies.

This can be accessed through the Astro.locals.netlify.context object:

---
const {
  geo: { city },
} = Astro.locals.netlify.context;
---


<h1>Hello there, friendly visitor from {city}!</h1>

If you’re using TypeScript, you can get proper typings by updating src/env.d.ts to use NetlifyLocals:

src/env.d.ts
/// <reference path="../.astro/types.d.ts" />


type NetlifyLocals = import('@astrojs/netlify').NetlifyLocals


declare namespace App {
  interface Locals extends NetlifyLocals {
    // ...
  }
}

This is not available on prerendered pages.

Running Astro middleware on Netlify Edge Functions

Section titled Running Astro middleware on Netlify Edge Functions

Any Astro middleware is applied to pre-rendered pages at build-time, and to on-demand-rendered pages at runtime.

To implement redirects, access control or custom response headers for pre-rendered pages, run your middleware on Netlify Edge Functions by enabling the edgeMiddleware option:

astro.config.mjs
import { defineConfig } from 'astro/config';
import netlify from '@astrojs/netlify';


export default defineConfig({
  // ...
  output: 'server',
  adapter: netlify({
    edgeMiddleware: true,
  }),
});

When edgeMiddleware is enabled, an edge function will execute your middleware code for all requests including static assets, prerendered pages, and on-demand rendered pages.

For on-demand rendered pages, the context.locals object is serialized using JSON and sent in a header for the serverless function, which performs the rendering. As a security measure, the serverless function will refuse to serve requests with a 403 Forbidden response unless they come from the generated edge function.

Netlify Image CDN support

Section titled Netlify Image CDN support

This adapter by default uses the Netlify Image CDN to transform images on-the-fly without impacting build times. It’s implemented using an Astro Image Service under the hood.

To opt out of Netlify’s Image CDN remote image optimization, use the imageCDN option:

astro.config.mjs
import { defineConfig } from 'astro/config';
import netlify from '@astrojs/netlify';


export default defineConfig({
  // ...
  output: 'server',
  adapter: netlify({
    imageCDN: false,
  }),
});

If you are using images hosted on another domain, you must authorize the domain or URL patterns using the image.domains or image.remotePatterns configuration options:

astro.config.mjs
import { defineConfig } from 'astro/config';
import netlify from '@astrojs/netlify';


export default defineConfig({
    // ...
    output: 'server',
    adapter: netlify(),
    image: {
      domains: ['example.com'],
    },
});

For more information, see the guide to authorizing remote images. This is not required for images hosted on the same domain as your site.

Static sites with the Netlify Adapter

Section titled Static sites with the Netlify Adapter

For static sites (output: 'static') hosted on Netlify, you usually don’t need an adapter. However, some deployment features are only available through an adapter.

Static sites will need to install this adapter to use and configure Netlify’s image service.

If you use redirects configuration in your Astro config, the Netlify adapter can be used to translate this to the proper _redirects format.

astro.config.mjs
import { defineConfig } from 'astro/config';
import netlify from '@astrojs/netlify';


export default defineConfig({
  // ...
  adapter: netlify(),
  redirects: {
    '/blog/old-post': '/blog/new-post',
  },
});

Once you run astro build there will be a dist/_redirects file. Netlify will use that to properly route pages in production.

Caching Pages

Section titled Caching Pages

On-demand rendered pages without any dynamic content can be cached to improve performance and lower resource usage. Enabling the cacheOnDemandPages option in the adapter will cache all server-rendered pages for up to one year:

astro.config.mjs
export default defineConfig({
  // ...
  output: 'server',
  adapter: netlify({
    cacheOnDemandPages: true,
  }),
});

This can be changed on a per-page basis by adding caching headers to your response:

pages/index.astro
---
import Layout from '../components/Layout.astro';


Astro.response.headers.set('CDN-Cache-Control', 'public, max-age=45, must-revalidate');
---


<Layout title="Astro on Netlify">
  {new Date()}
</Layout>

With fine-grained cache control, Netlify supports standard caching headers like CDN-Cache-Control or Vary. Refer to the docs to learn about implementing e.g. time to live (TTL) or stale while revalidate (SWR) caching: https://docs.netlify.com/platform/caching

Examples

Section titled Examples

More integrations

UI Frameworks

SSR Adapters

Other integrations

Contribute

What’s on your mind?

Create GitHub Issue

Quickest way to alert our team of a problem.

Community