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

Name	Type
SiteConfigSchema	ZodSchema, undefined
TeamConfigSchema	ZodSchema, undefined
BuildContext	ZodSchema, undefined
BuildConfigSchema	ZodSchema, undefined

Methods

addBuildEventContext

addBuildEventContext(func)

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

Parameters

Name	Type
handler	func

Returns

Returns a promise with an object.

---

addBuildEventHandler

addBuildEventHandler(type, func)

Used to add a build event handler to the extension.

Parameters

Name	Type
type	BuildHookType, one of the build events
func	func

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

Name	Type
config	ConnectorConfig
defineOptions	ConnectorDefineOptions
initState	ConnectorInitState

config

Object that contains the following Connector properties:

Name	Type	Description
supports	{ key: boolean }	Specifies functionality that the connector supports. Possible keys are connect for Netlify Connect, visualEditor for Netlify Visual Editor, and deltaSync for cache settings.
typePrefix	string	The prefix to use for all types defined by the connector.
localDevOptions	{ [key: string]: string | boolean | number } | undefined	Optional configuration options for local development.

defineOptions

Properties:

Name	Type	Description
zod	object	Use 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:

Method	Description
{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(),
      instanceID: zod.string().optional(),
    });
  }
})

initState

Properties:

Name	Type	Description
options	object	Contains 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

Name	Type
path	string
options	EdgeFunctionsOptions

Returns

void

---

addFunctions

addFunctions(path, options)

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

Parameters

Name	Type
path	string
options	FunctionsOptions

Returns

void

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