Get started with function injection

This SDK functionality is in Beta.

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

For a detailed guide and example integration, check out our developer guide: integrations can now inject serverless functions to enhance any site. Here’s how.

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

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

pnpm create @netlify/sdk@latest

yarn create @netlify/sdk

npm create @netlify/sdk@latest

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

You now have a working integration that injects the example hello-world.mts function, with the my_unique_prefix prefix. Once you enable this integration on a site, then build and serve the site, the hello-world.mts function will execute on requests to the /.netlify/functions/my_unique_prefix_hello-world path. You can test this integration 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 integrations.

Following the documentation for Netlify Functions, create your JavaScript or TypeScript serverless functions in a dedicated functions folder within your integration 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:

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

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

When your integration 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:

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 integration code base, such as src/functions/.

For integrations, the cron expression for scheduled functions must be declared inline. Learn more about the limitations for serverless functions in integrations, 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 integration 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 integration-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 integration have the following limitations:

Only JavaScript and TypeScript are supported. Creating and injecting serverless functions written in Go isn’t supported for integrations.
Triggering functions on events isn’t supported. It’s not possible to trigger functions injected by integrations on Netlify events.
Netlify Identity is supported with limitations. You can access Netlify Identity information with functions injected by integrations 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 integrations, 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 integration’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 a prefix property. 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.

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

import { NetlifyIntegration } from "@netlify/sdk";

const integration = new NetlifyIntegration();

integration.addFunctions("./src/functions", {
  prefix: "YOUR_FUNCTIONS_PREFIX", // update this prefix to use a unique value
});

export { integration };

Once you enable this integration on a site, Netlify will inject the 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 functions before your build event handlers run.

Invoke functions

After a user enables your integration on their site and Netlify injects the functions during the build step, 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 integrations can’t be triggered on Netlify events and Identity events.

Next steps

Learn how to test your integration and function injection locally.

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