Skip to content
Netlify SDK Docs Netlify SDK Docs 1.38.2

Create a new integration

To build an integration with the Netlify SDK, you can either start with the guided setup flow in the command line, or start with an existing integration template.

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.

Start with guided setup in the command line

To create a new integration with the Netlify SDK, run the create command using npm, pnpm, or yarn.

pnpm create @netlify/sdk@latest

Follow the prompts:

  • Install the @netlify/create-sdk package.
  • Supply integration information, this includes:
    • A slug which is a unique identifier for your integration. This is used to create the package name, and once it’s set you can’t change it.
    • A description that is a brief summary of the integration and its functionality. This will be displayed in the Netlify UI.
  • Select any boilerplate code you want to include. If you prefer not to use a boilerplate, select none and follow the prompts to provide the following:
    • The integration level your integration will work on: site, team, or team-and-site.
    • Permission scopes that the integration needs to function properly.
Need to install the following packages:
  @netlify/create-sdk@version
Ok to proceed? (y) y
? Where do you want to create the integration? (.)
? What is the slug of the integration? (e.g. my-integration)
? Summarize what your integration does. This will be shown on the integration's card on the Integrations page.
? Which boilerplate should be included? (Use arrow keys)
? What level will this integration be installed on?
? Which package manager do you want to use? (Use arrow keys)
? Select your permission scopes (space to select) (Press <space> to select, <a>
to toggle all, <i> to invert selection, and <enter> to proceed)
? Do you want to link a Netlify site to your integration? This
will help you test your integration and will be used to host
your integration.
Installing dependencies...

When the process completes, your selected directory will have the files you need to start building your integration:

├── integration.yaml
├── netlify.toml
├── node_modules
├── package-lock.json
├── package.json
├── src
│ ├── index.ts
│ └── edge-functions
│   └── hello-world.ts
│ └── functions
│   └── hello-world.mts
│ └── ui
│   └── index.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 edge functions in, with a sample edge function (hello-world.ts) included. Note that the Netlify SDK creates this file only when the Edge Function Injection boilerplate is selected.
  • src/functions/ - The folder to store serverless functions in, with a sample function (hello-world.mts) included. Note that the Netlify SDK creates this file only when the Function Injection boilerplate is selected.
  • src/ui/index.ts - The entrypoint for developing the integration’s UI. Note that the Netlify SDK creates this file only when the ui boilerplate is selected.

Start with an integration template

To create an integration and deploy it in one step, you can use one of our pre-made integration templates. To start, we have a template that contains a build event handler but more templates are coming soon.

Select the Deploy to Netlify button in the section below and follow the steps in your browser to create a new integration. Netlify will automatically deploy and publish the template as a private integration when you complete the flow.

Build event handler

This template is a good starting point for integrations that need to respond to build events.

Deploy the build event handler integration template to Netlify

Next steps

Depending on which template or boilerplate components you selected for your new integration, visit the component docs to continue developing the functionality for your integration:

You can also configure your integration for OAuth to allow users to authenticate with an OAuth identity provider.

To learn more about how users will discover and enable your integration, visit the following docs:

For a detailed guide and example, check out our developer guide: how we built an Upstash integration in 1 (and a bit) days.