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:
- A standard
Request
object representing the incoming HTTP request - A Netlify-specific
Context
object
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:
- Netlify-specific
Context
object - Supported Web APIs
- Supported open-source Deno APIs
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 theoptions
value in theCookieStore.set
web standard.cookies.delete(name)
orcookies.delete(options)
: Adds an instruction to the outgoing response for the client to delete a cookie. Following theCookieStore.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 overconsole.log
becausecontext.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 usenext()
if you need access to the response body for tasks like transforming it. The function returns aPromise
containing theResponse
from the origin that can be modified before returning. If you want to bypass the current function, you should use an emptyreturn
.rewrite(url)
: A convenience method for rewriting the incoming request to another same-site URL with a 200 status code; accepts aURL
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:
-
Note that we recommend using the Netlify convenience method
context.log
overconsole.log
becausecontext.log
output indicates which edge function generated the log message. -
fetch
Request
Response
URL
File
Blob
-
randomUUID()
getRandomValues()
- SubtleCrypto
-
setTimeout
clearTimeout
setInterval
-
ReadableStream
WritableStream
TransformStream
# Deno APIs
Edge Functions support the following open-source Deno APIs:
Deno.env
: Interact with environment variablesget(key)
: Get the value of an environment variabletoObject()
: Get all environment variables as an object
Deno.connect
: Connect to TCP socketsDeno.connectTls
: Connect to TCP sockets using TLSDeno.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.
Did you find this doc useful?
Your feedback helps us improve our docs.