Skip to content

NetlifyExtension

The NetlifyExtension provides different methods to help create your extension.

Review TypeScript definitions in the SDK

When you install the Netlify SDK, you have access to the TypeScript definitions directly in the @netlify/sdk package. You can browse through the definition files individually or review the type definition inline depending on your code editor.

Usage example

src/index.ts
import { NetlifyExtension } from "@netlify/sdk";
const extension = new NetlifyExtension();
// Adding a build event handler
extension.addBuildEventHandler("onPreBuild", () => {
console.log("This is my first build event handler!");
});

Type parameters

NameType
SiteConfigSchemaZodSchema, undefined
TeamConfigSchemaZodSchema, undefined
BuildContextZodSchema, undefined
BuildConfigSchemaZodSchema, undefined

Methods

addBuildEventContext

addBuildEventContext(func)

Used to add a build context to the extension that can be used in a build event handler.

Parameters

NameType
handlerfunc

Returns

Returns a promise with an object.


addBuildEventHandler

addBuildEventHandler(type, func)

Used to add a build event handler to the extension.

Parameters

NameType
typeBuildHookType, one of the build events
funcfunc

Returns

void


addConnector

addConnector(config, { defineOptions: fn }, { initState: fn })

Used to create and initialize a connector for the extension and to define the configuration options that users will complete when they use your connector.

Parameters

NameType
configConnectorConfig
defineOptionsConnectorDefineOptions
initStateConnectorInitState
defineOptions

Properties:

NameTypeDescription
zodobjectUse to create and return a Zod object that contains your options. Supported options are outlined below.

Learn more about configuring options for the Netlify UI.

Supported option methods

Netlify supports the following methods:

MethodDescription
{option_type}Define the option’s type using the related Zod method.
optional()(optional) Marks the option as optional.
  • Option type

    zod.{option_type}()

    Define the option’s type using the related Zod method, for example zod.string().

    Supports object(), string(), number(), and boolean(). Arrays are not supported.

  • optional

    zod.{option_type}().optional()

    Marks the option as optional when called. No parameters required.

Usage example
// Defines a required `API token` string option
// and defines an optional `Page limit` string option
extension.addConnector({
defineOptions: ({ zod }) => {
return zod.object({
apiToken: zod.string(),
pageLimit: zod.string().optional(),
});
}
})
initState

Properties:

NameTypeDescription
optionsobjectContains the configuration values set for options defined using defineOptions.

The function returns an object containing initialization state that you can use throughout your connector.

Usage example
extension.addConnector({
initState: ({ options }) => {
const apiClient = new CustomCMSAPIClient({
url: options.apiURL,
token: options.apiToken,
});
return {
apiClient // this will be available as state.apiClient in other connector APIs
};
}
})

Note that the returned state object is specific to each connector instance. If a data layer contains multiple instances of your connector, each will run its own extension.addConnector({ initState: fn }) lifecycle with the relevant configuration options for that instance and store its own state object.

Returns

A NetlifyConnector.


addEdgeFunctions

addEdgeFunctions(path, options)

Used to inform the extension that you want to inject edge functions into the user’s site.

Parameters

NameType
pathstring
optionsEdgeFunctionsOptions

Returns

void


addFunctions

addFunctions(path, options)

Used to inform the extension that you want to inject functions into the user’s site.

Parameters

NameType
pathstring
optionsFunctionsOptions

Returns

void

Got it!

Your feedback helps us improve our docs.