Skip to content
Netlify SDK Docs Netlify SDK Docs 1.38.2

Get started with edge function injection

This SDK functionality is in Beta.

This page provides information on how to create an integration that injects edge functions. It describes how to install and generate the boilerplate code, how to create edge functions for your integration, how to inject the edge functions, and how the edge functions are invoked in the consuming site.

Prerequisites

Windows users should run the Netlify SDK through WSL 2

Support for using the Netlify SDK on Windows is currently only available through WSL 2.

Install

  1. To get started, run the following command to create a new integration:

    pnpm create @netlify/sdk@latest

  2. Then, follow the prompts to add the Edge Functions Injection boilerplate. The Netlify SDK will scaffold the basic structure needed for your integration and output the required files:

    ├── integration.yaml
    ├── netlify.toml
    ├── node_modules
    ├── package-lock.json
    ├── package.json
    ├── src
    │ ├── index.ts
    │ └── edge-functions
    │   └── hello-world.ts
    └── tsconfig.json
    • integration.yaml - The integration configuration file. This is where you configure the integration name, description, and other metadata.
    • netlify.toml - The Netlify configuration file. This is where you configure the settings for your integration.
    • src/index.ts - The entrypoint for developing the integration.
    • src/edge-functions/ - The folder to store your edge functions in.
    • src/edge-functions/hello-world.ts - An example edge function.

    Configure VS Code for Edge Functions

    If you use Visual Studio Code, we recommend answering yes to the prompt to configure your editor to use Edge Functions. This will install the Deno runtime and configure your editor for a better development experience.

You now have a working integration that injects the example hello-world.ts edge function. Once you enable this integration on a site, then build and serve the site, the hello-world.ts edge function will execute on requests to the /hello path. You can test this integration locally now or follow the next sections to create and inject your own edge functions.

Create edge functions

Following the documentation for Netlify Edge Functions, create your edge functions in a dedicated edge functions folder within your integration code base. The boilerplate automatically includes a src/edge-functions folder for you but you can change this and specify a different location when you inject the edge functions.

For integrations, edge functions must be declared inline and can only use URL imports. Learn more about the limitations for edge functions in integrations.

For example:

src/edge-functions/hello-world.ts
export default () => new Response('Hello, world!');


export const config = {
  path: '/hello',
};

Limitations

Along with the integration-specific limitations that are listed below, make sure to review the operation and feature limits for Netlify Edge Functions.

Edge functions that you create and inject with an integration have the following limitations:

  • Only inline edge function declarations are supported. Declaring edge functions in a netlify.toml or manifest.json for your integration isn’t supported. You can only declare edge functions inline in an integration.
  • Only URL imports are supported. It’s not possible to use npm modules in your integration’s edge functions. To import a module in your integration’s edge functions, make a URL import directly. For example, import React from "https://esm.sh/react".
  • Import maps aren’t supported. It’s not possible to use import maps to import dependencies in your integration’s edge functions.
  • Node.js built-in modules aren’t supported. It’s not possible to use Node.js built-in modules in your integration’s edge functions. For example, import { randomBytes } from "node:crypto" is not possible.

Inject edge functions

Once you create your edge functions, use the addEdgeFunctions method in the integration’s src/index.ts file to specify the details for injecting the edge functions into the user’s site.

The addEdgeFunctions method receives two required arguments:

  • path: the path to the folder that contains the edge functions.
  • options: an object with a prefix property. The prefix property is used to namespace the edge functions and helps avoid conflicts between other edge functions in a user’s site that may have the same name.

This example injects all of the edge functions from the src/edge-functions folder, with the prefix YOUR_EF_PREFIX. Make sure to update the prefix to use a unique value, such as your integration slug.

src/index.ts
import { NetlifyIntegration } from "@netlify/sdk";


const integration = new NetlifyIntegration();


integration.addEdgeFunctions("./src/edge-functions", {
    prefix: "YOUR_EF_PREFIX", // update this prefix to use a unique value
});


export { integration };

Once you enable this integration on a site, Netlify will inject the edge functions into the site during the onPreBuild and onPreDev build events.

Note that if your integration includes custom build event handlers that run onPreBuild or onPreDev, Netlify injects the edge functions before your build event handlers run.

Invoke edge functions

After a user enables your integration on their site and Netlify injects the edge functions during the build step, the site is ready.

When a request is made for a path on the site, such as /hello, edge functions run according to the declaration processing order.

Next steps

Learn how to test your integration and edge function injection locally.

Once you’re ready, learn how to publish your integration.