Netlify Docs
Ask Netlify

Contact

Platform primitives /Edge Functions /

Create an Edge Functions integration

It’s possible for frameworks and other tools to dynamically create edge function files and declarations through integrations with the build process. For inspiration, you can explore the framework-specific examples on the Edge Functions overview. The examples highlight different use cases for developing build-generated edge functions.

Not a framework author? Create edge functions using the Netlify SDK

If you want to build a tool or integration that is unrelated to a framework, we recommend using the Netlify SDK instead. You can develop an extension that injects edge functions during the build step for a site and take advantage of the other functionality and features that come with the Netlify SDK. Learn more about extending Netlify.

This page will help you learn how to integrate your framework with Edge Functions by generating edge function files and declarations. If your framework’s build process uses Vite, then you can use the Netlify Edge Functions Vite plugin to generate a catch-all edge function file and declaration to serve all requests.

# Generate function files

To generate edge function files, a framework emits one function file per edge function under .netlify/edge-functions. Build-generated edge function files go in this internal directory so as to not interfere with user-created files.

The generated function must be compatible with the Deno runtime. This means the following:

  • Imports of Node built-in modules must be prefixed with node:, for example import { randomBytes } from "node:crypto".
  • All npm modules must be bundled in the function or changed to use URL imports. You can make a URL import directly in the edge function, for example import React from "https://esm.sh/react", or by using an import map.
  • The generated file should use ES Modules format.
  • If your bundler supports build targets, it should target browser or worker.

# Generate declarations

The framework must generate declarations either inline in the function files or in a manifest file at .netlify/edge-functions/manifest.json. The manifest file is a JSON object with the same structure as the edge_functions object from netlify.toml.

Avoid collisions between integrations

If you expect your integration to be used in conjunction with other integrations, avoid overwriting declarations from other integrations and be mindful about declaration order.

Declarations for build-generated edge functions support additional properties not available to user-created edge functions. Which additional properties are supported depends on whether the function is declared inline or in manifest.json.

Build-generated property Supported inline Supported in manifest.json
generator ✓ ✓
name ✓ ✓
import_map ✓
version ✓

These additional properties are for the following purposes:

  • generator is an optional property for noting the integration that generated the edge function. Setting this for your integration helps Netlify’s observability; this does not affect the user experience. We recommend using a value with a format of @integration-name/plugin-name@1.2.3, where the plugin version is included at the end.
  • name is an optional property that allows you to set a display name for the function that appears in the Netlify UI.
  • import_map is an optional property for specifying the path to an import map file. If this path is relative, it will be resolved in relation to the manifest file itself. The manifest.json declaration example below uses an import map found at .netlify/edge-functions/import_map.json, for example:
     {
   "imports": {
     "example": "https://example.com",
     "netlify:edge": "this will be ignored, netlify: is a reserved prefix"
   }
 }
    Note that any imports prefixed with netlify: are reserved, and may be overridden by built-in definitions.
  • version is a required metadata property for manifest.json that tracks the version of the manifest format being used. Set this to 1 as demonstrated in the manifest.json example below.

Here are examples of build-generated declarations:

import type { IntegrationsConfig } from "@netlify/edge-functions";

export default async () => new Response("Hello, world!", {
		headers: {
			'cache-control': 'public, s-maxage=3600'
		}
	});

export const config: IntegrationsConfig = {
  path: "/hello",
  generator: "@cool-framework/nice-plugin@1.0.0",
  name: "greeting",
  cache: "manual",
  onError: "bypass"
};

{
  "functions": [
    {
      "path": "/admin",
      "function": "auth",
      "generator": "@cool-framework/nice-plugin@1.0.0",
      "name": "/admin auth handler",
      "onError": "/unavailable"
    },
    {
      "pattern": "^/dashboard(?:/([^/#\\?]+?))[/#\\?]?$",
      "function": "auth",
      "name": "/dashboard/* auth handler"
    },
    {
      "path": "/blog/*",
      "excludedPath": "/blog/img/*",
      "function": "rewriter",
      "cache": "manual",
      "onError": "bypass",
    },
    {
      "pattern": "/products/(.*)",
      "excludedPattern": "/products/things/(.*)",
      "function": "highlight"
    }
  ],
  "import_map": "./import_map.json",
  "version": 1
}

# Contact us

If you’d like to create an Edge Functions integration for a framework or other developer tool, we encourage you to let us know by reaching out through our technology partner program so we can help you.

We welcome your feedback on building integrations with this feature. Visit our Forums to join the conversation about Edge Functions.

← Usage & billing →