Skip to content
Netlify SDK Docs Netlify SDK Docs 3.0.0

Get started with connectors

This page will help you get started with creating an extension using a connector. It describes how to install and generate the boilerplate code, how to add a connector to your extension, and how to start development.

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 extension:

pnpm create @netlify/sdk@latest

Then, follow the prompts to add the boilerplate for a connector.

The Netlify SDK will scaffold the basic structure needed for your connector and output the required files. Learn about the required files in the anatomy of an extension doc.

The following sections go over how to create a connector, start developing the code for it, and then run it locally. You can copy the examples as a quick way to get started and test the functionality.

Create a connector

Now that you have the boilerplate code, the first step is to add a connector to your extension by calling addConnector().

For example, add the following code to the generated src/index.ts file to build a connector for Connect:

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


const extension = new NetlifyExtension();


// Adds a connector to the extension
const connector = extension.addConnector({
  typePrefix: "Example",
  supports: {
    connect: true, // change this to false if you’re not supporting Connect
  },
});


export { extension };

Both typePrefix and supports are mandatory fields. Specify the Netlify features that your connector supports by setting the supports.connect value appropriately. Learn more about the accepted values in the reference docs.

Develop your connector

Once you add a connector to your extension, you need to define a data model on the connector and specify how to handle data updates on initial and subsequent syncs.

For example, add the following code to the generated src/index.ts file:

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


const extension = new NetlifyExtension();




// This connector specifies that it supports Netlify Connect only
const connector = extension.addConnector({
  typePrefix: "Example",
  supports: {
    connect: true,
  },
});


// Use the Connector API on the `connector` object
// to define a model with a single document model on it
connector.model(async ({ define }) => {
  define.document({
    name: "Post",
    fields: {
      title: {
        type: "String",
        required: true,
      },
    },
  });
});


// Use the Connector API to configure how data should
// be handled on initial and subsequent syncs. In this example,
// we’re passing in sample data in line.
connector.sync(async ({ models, isInitialSync }) => {
  switch (true) {
    case isInitialSync: {
      models.Post.insert([
        {
          id: "1",
          title: "This is my example post",
        },
      ]);
      break;
    }
    case !isInitialSync: {
      models.Post.insert([
        {
          id: "1",
          title: "This is my example post",
        },
      ]);
    }
  }
});


// export the valid extension object
export { extension };

Along with the above code, you will also need to define the configuration options and the related extension UI to display in the Netlify UI. To help with auto-generating the extension UI, follow the steps outlined here.

To learn more about how to configure your connector, review the develop a connector doc and the NetlifyConnector API reference documentation.

Run locally

With the Netlify SDK commands, you can run your extension locally as you develop. If you used the SDK to generate boilerplate when you started, the commands are automatically installed in your extension and added to your package.json.

Specify configuration options

If you defined configuration options for your connector, you may need to set values before you can use the extension locally. Learn how to set configuration values for local development.

Run the connector

Once you have the tools installed, run the following command:

pnpm run dev

This command bundles your extension code and starts a local GraphQL server at http://localhost:8000/__graphql.

Follow the prompts to open the GraphiQL UI for Connect.

Make sure your project has a dev script

When you use the SDK’s guided set-up flow to create an extension, we automatically add a script to your project that runs the netlify-extension dev command. If you skipped the guided set-up flow, make sure you install the Netlify SDK in your project, and manually update your package.json to include "dev": "netlify-extension dev"

For example, if you start local development with the example code that’s documented in the develop your connector section above, you can run a query for the id and title of allExamplePost in the GraphiQL UI and the local server will return the data we created. Note that Netlify makes the ID globally unique.

Example query in a local GraphiQL UI

When you save your code, the local development server will automatically restart and pick up your changes. If you use Node debuggers and the process pauses on a breakpoint, saving your code will kill the debugger and start a new one.

Next steps

Once you have generated the boilerplate code, review the develop a connector documentation to learn more about the workflow and how to use the NetlifyConnector API to customize your extension. As you develop, reference our documentation on how to build and debug and test your code.

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

Got it!

Your feedback helps us improve our docs.