Create an Edge Functions integration

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.

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

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 Functions, a framework first 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 in netlify/edge-functions.

The generated function must be compatible with the Deno runtime. This means the function cannot use any Node built-in modules and all npm modules must be bundled in the function or changed to use URL imports. The generated file should use ES Modules format. If your bundler supports build targets, it should target browser or worker.

# Generate declarations

Then, the framework creates a manifest file declaring the edge functions at .netlify/edge-functions/manifest.json.

Avoid collisions between integrations

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

The manifest file is a JSON object with the same structure as the edge_functions object from netlify.toml, with a few additional properties.

{
  "functions": [
    {
      "path": "/admin",
      "function": "auth"
    },
    {
      "pattern": "^/foo(?:/([^/#\\?]+?))[/#\\?]?$",
      "function": "auth"
    },
    {
      "path": "/blog/*",
      "function": "rewriter"
    }
  ],
  "import_map": "./import_map.json",
  "version": 1
}
  • version is a required metadata property that tracks the version of the manifest format being used.

  • pattern is an alternative to the path property that allows for regex path matching. Note that the regex does not support lookahead or lookbehind assertions.

  • 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 example above 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.

# 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 in our Forums or contacting partners@netlify.com so we can help you.

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

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.