Skip to content

@astrojs/ netlify

v5.0.1 GitHub npm Changelog

This content is not available in your language yet.

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" />
/// <reference types="astro/client" />


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/functions';


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, context.locals are 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/functions';


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

Static sites & Redirects

Section titled Static sites &amp; Redirects

For static sites you usually don’t need an adapter. However, 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/static';


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

Frameworki UI

Adaptery SSR

Inne