Get started with function injection

This page provides information on how to create an extension that injects serverless functions. It describes how to install and generate the boilerplate code, how to create functions for your extension, how to inject functions, and how you can invoke the injected functions on a website.

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.

• Node.js 18.19.0 or later
• Netlify CLI
• TypeScript

Install

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

   pnpm

   pnpm create @netlify/sdk@latest

   yarn

   yarn create @netlify/sdk@latest

   npm

   npm create @netlify/sdk@latest

2. Then, follow the prompts to add the 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
   │ └── functions
   │   └── hello-world.mts
   └── 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/functions/ - The folder to store your functions in.
   • src/functions/hello-world.mts - An example function.

You now have a working extension that injects the example hello-world.mts function, with the my_unique_prefix prefix. After you install this extension on a team and then build and serve one of the team’s sites, the hello-world.mts function will execute on requests to the /.netlify/functions/my_unique_prefix_hello-world path. You can test this extension locally now or follow the next sections to create and inject your own functions.

Create functions

Before you begin, make sure to review the limitations for functions in extensions.

Following the documentation for Netlify Functions, create your JavaScript or TypeScript serverless functions in a dedicated functions folder within your extension code base. The boilerplate automatically includes a src/functions/ folder for you but you can change this and specify a different location when you inject the functions.

For example, saving the following code in /src/functions/hello-world.mts will create a function called hello-world:

src/functions/hello-world.mts

import { Config, Context } from "@netlify/functions";

export default async (req: Request, context: Context) => {
  return new Response("Hello, world!");
};

When your extension injects the function into a site, Netlify automatically creates a dedicated endpoint using the format:

https://<SITE DOMAIN>/.netlify/functions/<YOUR SF PREFIX>_<FUNCTION NAME>

You can configure the function to run on a path of your choice by defining a path property in the function’s config export. For example, to specify that the function should run on the /hello path:

src/functions/hello-world.mts

import { Config, Context } from "@netlify/functions";

export default async (req: Request, context: Context) => {
  return new Response("Hello, world!");
};

export const config: Config = {
  // this will ensure the function runs on the /hello path instead of /.netlify/functions/YOUR_SF_PREFIX_hello-world
  path: "/hello",
};

As you create your functions, make sure to monitor your dependency sizes. Learn more about how to manage dependency size.

Scheduled functions

Scheduled Functions is in Beta.

Netlify’s Scheduled Functions enable you to run functions on a regular and consistent schedule, much like a cron job.

Following the documentation, create a scheduled function in a dedicated functions folder within your extension code base, such as src/functions/.

For extensions, the cron expression for scheduled functions must be declared inline. Learn more about the limitations for serverless functions in extensions, and keep in mind the general limitations for scheduled functions.

Background functions

Background Functions is in Beta and is available on Core Pro and Core Enterprise plans.

Netlify’s Background Functions provide an option for serverless functions that run for up to 15 minutes and don’t need to complete before a visitor can take next steps on your site.

Following the documentation, create a background function in a dedicated functions folder within your extension code base, such as src/functions/.

Your function file should include -background in the filename to designate it as a background function. For example, src/functions/hello-background.mts.

Limitations

Along with the extension-specific limitations that are listed below, make sure to review the default deployment options for serverless functions and the limitations for scheduled functions.

Functions that you create and inject with an extension have the following limitations:

• Only JavaScript and TypeScript are supported. Creating and injecting serverless functions written in Go isn’t supported for extensions.
• Triggering functions on events isn’t supported. It’s not possible to trigger functions injected by extensions on Netlify events.
• Netlify Identity is supported with limitations. You can access Netlify Identity information with functions injected by extensions but you can’t trigger the functions on Identity events.
• Only inline scheduled function declarations are supported. Declaring a scheduled function’s cron expression in a netlify.toml isn’t supported. For extensions, the cron expression must be declared inline.

Manage dependency size

The dependencies you use in a function are bundled with the function code before it’s injected into the user’s site. This can increase the site’s size and the time it takes to build the site.

To reduce the size of your functions, consider using smaller dependencies or only including the dependencies that are necessary for the function to run.

For example, instead of importing a full library:

import _ from "lodash";
const result = _.kebabCase("fooBar");

Install just the subset of the library you need:

import kebabCase from "lodash.kebabCase";
const result = kebabCase("fooBar");

Inject functions

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

The addFunctions method receives two required arguments:

• path: the path to the folder that contains the functions.
• options: an object with prefix and shouldInjectFunction properties — we recommend you set both of these.
  • The prefix property is used to namespace the functions and helps avoid conflicts between other functions in a user’s site that may have the same name. For example, 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 a function into a site. Without it, Netlify will inject the function into all of a team’s sites during the onPreBuild and onPreDev build events.

This example conditionally injects all of the functions from the src/functions folder, with the prefix YOUR_FUNCTIONS_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.addFunctions("./src/functions", {
  prefix: "YOUR_FUNCTIONS_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 functions before your build event handlers run.

Invoke functions

After a user installs your extension on their team and Netlify injects the functions during the build step for one of the team’s sites, the site is ready.

In general, functions will run on GET requests to the function’s path. Background functions will run on POST requests to the function’s path.

By default, the path is https://<SITE DOMAIN>/.netlify/functions/<YOUR SF PREFIX>_<FUNCTION NAME>. If you want to customize the path that your function runs on, you can specify the path property in the function file.

Scheduled functions only run on published deploys and you can’t invoke them directly with a URL. But, you can test them locally. Learn more about developing and debugging scheduled functions.

Note that functions injected by extensions can’t be triggered on Netlify events and Identity events.

Next steps

Learn how to test your extension and function injection locally.

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

Did you find this doc useful?

Your feedback helps us improve our docs.

Don’t fill this out if you’re human:

Send

Got it!

Your feedback helps us improve our docs.

• Netlify
• Careers
• Blog
• Terms
• Privacy

© 2023 Netlify