Skip to content
Netlify SDK Docs Netlify SDK Docs 2.15.0

Get started with edge function injection

This page provides information on how to create an extension that injects edge functions. It describes how to install and generate the boilerplate code, how to create edge functions for your extension, 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 extension:

    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 extension and output the required files:

    ├── extension.yaml
    ├── netlify.toml
    ├── node_modules
    ├── package-lock.json
    ├── package.json
    ├── src
    │ ├── index.ts
    │ └── edge-functions
    │   └── hello-world.ts
    └── tsconfig.json
    • extension.yaml - The extension configuration file. This is where you configure the extension name, description, and other metadata.
    • netlify.toml - The Netlify configuration file. This is where you configure the settings for building and deploying your extension.
    • src/index.ts - The entrypoint for developing the extension.
    • 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 extension that injects the example hello-world.ts edge function. After you install this extension on a team and then build and serve one of the team’s sites, the hello-world.ts edge function will execute on requests to the /hello path. You can test this extension 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 extension 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 extensions, edge functions must be declared inline and can only use URL imports. Learn more about the limitations for edge functions in extensions.

For example:

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


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

Limitations

Along with the extension-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 extension have the following limitations:

  • Only inline edge function declarations are supported. Declaring edge functions in a netlify.toml or manifest.json for your extension isn’t supported. You can only declare edge functions inline in an extension.
  • Only URL imports are supported. It’s not possible to use npm modules in your extension’s edge functions. To import a module in your extension’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 extension’s edge functions.
  • Node.js built-in modules aren’t supported. It’s not possible to use Node.js built-in modules in your extension’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 extension’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 prefix and shouldInjectFunction properties — we recommend you set both of these.
    • 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. For example, edge functions that a framework might inject.
    • The shouldInjectFunction property is for a function that you need to define to determine whether or not to inject an edge function into a site. Without it, Netlify will inject the edge function into all of a team’s sites during the onPreBuild and onPreDev build events.

This example conditionally 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 extension slug.

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


const extension = new NetlifyExtension();


extension.addEdgeFunctions("./src/edge-functions", {
  prefix: "YOUR_EF_PREFIX", // update this prefix to use a unique value
  shouldInjectFunction: ({ name }) => {
    const extensionConfigured = process.env.MY_EXTENSION_WAS_CONFIGURED_VARIABLE;
    if (extensionConfigured) {
      return true;
    }
    return false;
  },
});


export { extension };

The shouldInjectFunction checks for an environment variable that the extension creates when the user configures the extension. For an example of how to create environment variables using createOrUpdateVariables, refer to the extension-showcase repository.

Note that if your extension 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 installs your extension on their team and Netlify injects the edge functions during the build step for one of the team’s sites, 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 extension and edge function injection locally.

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

Got it!

Your feedback helps us improve our docs.