Edge Handlers API overview

This feature is in early access BETA.

This guide provides information to get started with the Netlify Edge Handlers JavaScript API. Check out the Edge Handlers API reference documentation for details.

Cache

The Cache API gives you access to the Netlify edge caching layer to store documents generated by your Edge Handlers. The recommended maximum file size for documents stored via this API is 1 MB. Using larger documents in this cache may result in an Edge Handler timeout. If you need to store larger file sizes in the edge cache, please contact sales.

Here's an example using the Cache API to store the response from an external service:

const fetchAndSave = async () => {
  const headers = { "User-Agent": "Netlify" };
  const [resp, newDoc] = await Promise.all([
    fetch("https://api.github.com/emojis", {
      headers
    }),
    event.cache.setDocument("emojis"),
  ]);
  
  const data = await resp.text();
  await newDoc.write(data);
  
  return data;
};

export function onRequest(event) {
  event.replaceResponse(async () => {
    let data;
    
    try {
      let doc = await event.cache.getDocument("emojis");
      data = await doc.text();
    } catch (e) {
      data = await fetchAndSave();
    }
    
    return new Response(data);
  });
}

Fetch

The Fetch API enables sending requests to external endpoints to gather additional data. It works like a browser's Fetch API, and you can use it to retrieve any kind of data.

Here's an example using the Fetch API to retrieve data from a URL:

export function onRequest(event) {
  event.replaceResponse(() => fetch("https://api.github.com/emojis", {
    headers: { "User-Agent": "Netlify" }
  }));
}

You can also use the Fetch API to get the original request:

export function onRequest(event) {
  event.replaceResponse(() => fetch(ev.request));
}

Geolocation

The Geolocation API adds location information in the headers of every request that an Edge Handler receives. The geolocation data is available in the request event received in the Edge Handler invocation as well as in the request headers.

You can access the information from the request object by using the origin access method. This method exposes additional country, subdivision, and city access methods. Each of these methods provides access to the area name and to the ISO 3166 code for country and subdivision.

Here's an example that logs each one of these properties for an incoming request:

export function onRequest(event) {
  console.log(`Request served from ${event.request.zone}`);
  
  const origin = event.request.origin;
  if (origin.country) {
    const {
      name,
      code
    } = origin.country;
    console.log(`country: ${name} (${code || "missing code"})`);
  }
  
  if (origin.subdivision) {
    const {
      name,
      code
    } = origin.subdivision;
    console.log(`subdivision: ${name} (${code || "missing code"})`);
  }
  
  if (origin.city) {
    console.log(`city: ${origin.city.name}`);
  }
}

You can access location information from the request headers by using the following keys:

  • X-NF-Country-Name: Name of the country, in English, where the request is coming from. For example, Spain.
  • X-NF-Country-Code: ISO 3166 code of the country where the request is coming from. For example, ES.
  • X-NF-Subdivision-Name: Name of the area or region, in English, where the request is coming from. For example, California.
  • X-NF-Subdivision-Code: ISO 3166 code of the region where the request is coming from. For example, US-CA for California.
  • X-NF-City-Name: Name of the city, in English, where the request is coming from. For example, Seville.
  • X-NF-Availability-Zone: IATA location identifier for the metropolitan area where the Edge Handler is being executed. For example, NYC.

Here's an example using a header of the Geolocation API to customize a response:

export function onRequest(event) {
  const area = event.request.headers.get('X-NF-Subdivision-Code');
  if (area === 'US-CA') {
    event.replaceResponse(() => {
      const response = new Response('Sorry, not available in California', 
      { status: 404 }, 
      );
      return response;
    });
  }
}

User Context

When an incoming request includes an authentication token from Netlify Identity or an external provider, the Edge Handler will automatically verify the token signature and give you access to its claims and roles directly from the userContext object in the incoming event. This information helps you make informed decisions to grant access to your visitors directly from the handler.

Here's an example using the userContext object to redirect visitors to a login page based on the token's role information:

export function onRequest(event) {
  if (!event.userContext || !event.userContext.is("admin")) {
    event.replaceResponse(new Response("Access unauthorized", {
      status: 301,
      headers: { "Location": "/login" }
    });
  }
}

Server Push

The Server Push API enables sending resources over HTTP/2 to a client preemptively before an ongoing transaction completes. Push messages alert the browser or any other HTTP/2-capable client to start accepting resources without waiting for the response of the current request to arrive.

Here's an example using the Server Push API to push an image resource to the client over HTTP/2:

export function onRequest(event) {
  event.pushAssetToClient('/imgs/dog.jpg');
}