How to use Netlify edge functions

Why Netlify Edge Functions are worth learning

Netlify is best known for static sites. You push your code, Netlify builds it, and the result is fast and reliable. For many sites, that is more than enough.

But sometimes you want a bit of logic to run before the page is served. Maybe you want to detect where the user is located. Maybe you want to personalize content, run an A/B test, or handle redirects in a smarter way.

This is where Netlify Edge Functions come in. They let you run code very close to the user, right at the CDN edge. That means faster responses and new possibilities that are not possible with purely static files.

What Netlify Edge Functions actually are

Netlify Edge Functions are similar to Netlify Serverless Functions, but they run in a different place.

Instead of running in a single region, Edge Functions run on Netlify's global edge network. This means:

• They execute closer to the user
• They are faster for location based logic
• They scale automatically across many regions

They are also billed differently, which makes them suitable for lightweight logic that runs often.

Enabling Netlify Edge Functions

To use Edge Functions, you need a netlify.toml file in your repository root. If you already have one, you can reuse it.

Here is the simplest configuration:

[[edge_functions]]
function = "hello"
path = "/hello"

This tells Netlify two things:

• The function file is called hello
• The function will run when someone visits /hello

The function file itself lives in this folder:

netlify/edge-functions/hello.ts

Your first Netlify Edge Function

Here is a very simple Edge Function written in TypeScript:

export default () => {
  return new Response("Hello from the Netlify Edge")
}

After deploying your site, you can open this URL in the browser:

https://your-site-name.netlify.app/hello

You should see the text rendered immediately. This response is generated dynamically at the edge.

Testing Edge Functions locally

Before deploying, it is a good idea to test Edge Functions locally.

Install or update the Netlify CLI:

npm install -g netlify-cli

Then run:

netlify dev

If your CLI version is recent enough, Edge Functions will work locally. Some features, like geolocation, only work on the real edge, but basic logic is testable.

Setting response headers

You can control headers, such as the content type, by passing options to the Response constructor.

Example:

export default () => {
  return new Response("<h1>Hello Edge</h1>", {
    headers: {
      "content-type": "text/html; charset=utf-8"
    }
  })
}

This makes the browser render the response as HTML instead of plain text.

Accessing request and context

An Edge Function receives two arguments: request and context.

export default (request: Request, context: any) => {
  // logic here
}

• request is the standard Fetch API request object
• context gives you access to Netlify specific features

This combination is very powerful and feels familiar if you have used modern web APIs before.

Writing logs from an Edge Function

You can write logs using context.log():

export default (_request: Request, context: any) => {
  context.log("Edge function executed")

  return new Response("Logged something")
}

You can view these logs in the Netlify dashboard under the Edge Functions section for your site.

Returning JSON from the edge

If you want to return JSON, Netlify provides a helper on the context object:

export default (_request: Request, context: any) => {
  return context.json({
    status: "ok",
    source: "netlify-edge"
  })
}

This automatically sets the correct headers and serializes the response.

Using multiple Edge Functions

You can define more than one Edge Function by adding more entries to netlify.toml:

[[edge_functions]]
function = "hello"
path = "/hello"

[[edge_functions]]
function = "second"
path = "/second"

Each function maps to its own file inside netlify/edge-functions.

Using async code and fetch

Edge Functions fully support async code and the Fetch API.

Example that fetches JSON from an external API:

export default async () => {
  const res = await fetch("https://dog.ceo/api/breeds/image/random")
  return res
}

You can also proxy images or other assets:

export default async () => {
  return await fetch("https://placekitten.com/300/300")
}

Accessing geolocation data

One of the biggest benefits of Netlify Edge Functions is access to geolocation data.

Example:

export default (_request: Request, context: any) => {
  const country = context.geo?.country?.name
  const city = context.geo?.city

  return new Response(
    `Hello from ${city ?? "somewhere"}, ${country ?? "unknown country"}`
  )
}

Important note: geolocation data only works on the real Netlify edge, not in local development.

Working with cookies

You can read and write cookies using the context.cookies API.

Setting a cookie:

export default (_request: Request, context: any) => {
  context.cookies.set({
    name: "visited",
    value: "true"
  })

  return new Response("Cookie set")
}

You can also read or delete cookies using get() and delete().

Environment variables and Deno

Netlify Edge Functions run on Deno, not Node.js. This is important to know.

To read environment variables, use:

Deno.env.get("MY_VARIABLE")

Example:

export default () => {
  const value = Deno.env.get("MY_VARIABLE")
  return new Response(value ?? "No value set")
}

This confirms that Edge Functions use the Deno runtime and standard Web APIs.

When to use Netlify Edge Functions

Netlify Edge Functions are a great fit for:

• Geolocation based content
• Localization and language redirects
• A/B testing
• Auth checks and lightweight middleware
• Smart redirects and rewrites

Many frameworks like Next.js, Remix, and SvelteKit already use Edge Functions under the hood when deployed on Netlify.

Conclusion

Netlify Edge Functions add dynamic behavior to otherwise static sites, without sacrificing performance.

To recap:

• They run close to the user on the CDN edge
• They use standard Web APIs and Deno
• They are fast, scalable, and easy to set up
• They work well for personalization and routing logic

Even if you do not use them directly today, chances are you already benefit from Netlify Edge Functions when deploying modern frameworks. Learning how they work gives you more control and opens up powerful new use cases on Netlify.