Netlify Docs

Contact

Edge Functions API

Experimental Feature

This experimental feature is available to try out before it’s fully released or ready for production. We recommend using it in non-critical sites and non-production environments only. Learn more in our Netlify Labs doc.

This page provides an overview of key concepts as well as a full reference.

# Overview

Use JavaScript or TypeScript to create an edge function file that exports a default function responsible for processing a request.

# Objects

When the function is invoked, it receives two arguments:

The expected return value is either a standard Response object representing the HTTP response to be delivered to the client or undefined if you choose to bypass the current function.

When using context.next() to transform a response, we modify the request to the downstream asset so that conditional requests don’t apply and you always get a full response back.

If you want full control over the client caching behavior and you’d like to use conditional requests, you should pass the sendConditionalRequest to the context.next() call.

export default async (req: Request, { next }: Context) => {
  const res = await next({sendConditionalRequest: true});

  // If the response is a 304, it’s cached in the client and we can return it
  if (res.status === 304) {
    return res;
  }
  
  // Transform the response however you need
  const text = await res.text();

  return new Response(text.toUpperCase(), res);
};

For TypeScript, you can import the types for the Context object from netlify:edge. The types for the Request and Response objects are in the global scope.

import type { Context } from "netlify:edge";
export default async (request: Request, context: Context): Promise<Response> => {
    // ...
}

# Runtime environment

Edge Functions run in a Deno runtime environment that supports many standard Web API and open-source Deno endpoints. Deno does not use Node modules, or support Node APIs, but instead can load modules directly from URLs.

# Reference

This reference covers the following:

You may encounter undocumented APIs as you work with Edge Functions. These are not supported in any way and you should not use them. Using undocumented APIs may lead to unexpected or broken functionality.

# Netlify-specific Context object

The Context object exposes the following properties:

  • cookies: A simplified interface for reading and storing cookies:
    • cookies.get(name): Reads a cookie with a given name from the incoming request.
    • cookies.set(options): Sets a cookie on the outgoing response, using the same format as the options value in the CookieStore.set web standard.
    • cookies.delete(name) or cookies.delete(options): Adds an instruction to the outgoing response for the client to delete a cookie. Following the CookieStore.delete web standard, accepts a string representing the name of the cookie, or an options object.
  • geo: An object containing geolocation data for the client with the following properties:
    • city: Name of the city.
    • country:
      • code: ISO 3166 code for the country.
      • name: Name of the country.
    • subdivision:
      • code: ISO 3166 code for the country subdivision.
      • name: Name of country subdivision.
  • ip: A string containing the client IP address.
  • json(value): A convenience method for returning a JSON-encoded response.
  • log(...values): A convenience method for outputting a log message associated with the current edge function. Recommended over console.log because context.log output indicates which edge function generated the log message.
  • next(): Invokes the next edge function in the chain if there is one. If there are no more edge functions, the next step is evaluating redirect rules before serving static content or returning responses from Netlify Functions. You should only use next() if you need access to the response body for tasks like transforming it. The function returns a Promise containing the Response from the origin that can be modified before returning. If you want to bypass the current function, you should use an empty return.
  • rewrite(url): A convenience method for rewriting the incoming request to another same-site URL with a 200 status code; accepts a URL object, a full URL as a string, or a relative URL as a string. You cannot rewrite to a different domain, attempts to do so will fail with an error.

# Web APIs

Edge Functions support the following Web APIs:

# Deno APIs

Edge Functions support the following open-source Deno APIs:

  • Deno.env: Interact with environment variables
    • get(key): Get the value of an environment variable
    • toObject(): Get all environment variables as an object
  • Deno.connect: Connect to TCP sockets
  • Deno.connectTls: Connect to TCP sockets using TLS
  • Deno.resolveDns: Make DNS queries

Experimental Feature

This experimental feature is available to try out before it’s fully released or ready for production. We recommend using it in non-critical sites and non-production environments only. Learn more in our Netlify Labs doc.

← Declarations →