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.
- Node.js 18.19.0 or later
- Netlify CLI
- TypeScript
Install
To get started, run the following command to create a new extension:
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 these required files:
The following sections provide detail on the boilerplate code for each file and the required configuration in each.
package.json
The automatically generated package.json
includes the following required fields:
name
: the name of your extension.main
: the entry file for your extension. This file is where you add a connector to your extension and specify how it should work.type
: the package type, which must always bemodule
.
It also automatically includes the @netlify/sdk
dependency.
For example:
src/index.ts
The Netlify SDK automatically generates a src/index.ts
file and specifies it as the main
entry file in the package.json
. The SDK uses this file as the entry point to load and bundle your extension.
If you update the file name, you must ensure that you update the main
field of the package.json
. For example, the filename may be src/entry.ts
, and the package.json
would include it as "main": "src/entry.ts"
.
The main entry file is where you include all of the code that configures your extension, including the connector and its functionality. The file must export a valid NetlifyExtension
object.
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:
Both typePrefix
and supports
are mandatory fields. Specify the Netlify features that your connector supports by setting the supports.connect
and supports.visualEditor
values 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:
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.
If your connector supports the visual editor, you will need to update the supports.visualEditor
value and then add logic for checking permissions, uploading assets, writing document updates back to the data source, and more. You may also want to configure editor-specific settings on your models.
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.
Specify a frontend site
For use with Netlify Visual Editor only.
If you’re developing a connector for the visual editor, you can specify a frontend site for the visual editor to use while running locally. This allows you to simulate the experience a user of your connector will have with frontend site editing in the visual editor. If you don’t configure this, you can still interact with your connector in the local visual editor, but the frontend site preview will be empty.
The frontend site you use should be configured for use with the visual editor.
To specify a frontend site, update the extension configuration file extension.yaml
to include the port
, command
, and directory
under local-frontend
. If the file doesn’t exist already, create one at the root of your project.
For example, if the project is in ./dev-app
:
Run the connector
Once you have the tools installed and specified a site for the visual editor (if applicable), run the following command:
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 or to open the visual editor.
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.
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.