Develop a connector
After you add a connector to your extension, you need to develop the connector to work with your data source type.
This document provides information on the steps to develop your connector and the options available for each. We recommend that you start by reviewing the workflow.
For details on the APIs you need to define for your connector and examples of how to use them, refer to the NetlifyConnector API reference documentation.
Definitions
As you develop a connector, it might be helpful to review the following key terms:
- Data source: an external system or service that contains data, such as a content management system (CMS). Sometimes referred to as a content source.
- Data layer: in Netlify Connect, a data layer contains a real-time graph database with data synced from one or more data sources, and a GraphQL API to access that data. Netlify uses extensions to connect to data sources and sync data.
- Document model: a representation of the data that makes up an individual entity or document in your data source, such as a
PostorUser. Each document model includes various fields and each field has a type that references another defined model — such as a scalar, object, or union model. - GraphQL schema: defines the structure and data types that users can query using a data layer’s GraphQL API and that the Netlify Visual Editor uses to query content for sites. Netlify generates the schema using the data model that your connector defines.
- Sites with visual editing enabled: sites that are set up to use Netlify Visual Editor have visual editing enabled and can use extensions to sync data to and from data sources.
Workflow
When you develop the connector for your extension, you need to complete the following steps depending on which product you want to support.
Note that if you build a connector with visual editor support, you can also use the same connector with Connect.
- Define your data model
- Define document models for your connector, including the related fields and types. You can also define cross-reference fields and types.
- Specify how to insert documents and process updates when syncing data to Netlify
- Define the configuration options that should appear in the Netlify UI when Connect users use your extension
- (Optional) Add support for localization
The above steps are for creating a static connector. For Connect, you also have the option to configure a dynamic connector instead.
- Specify logic to confirm that the user has the necessary permissions to update content in the data source.
- Define your data model
- Define document models for your connector, including the related fields and types. You can also define cross-reference fields and types.
- Define editor settings for documents, fields, and objects to specify how Netlify should render them in the visual editor
- Specify how to insert documents and process updates when syncing data to Netlify
- Specify how to write document updates back to your data source
- Specify how to upload assets to your data source
- Define the configuration options that should appear in the Netlify UI when visual editor and Connect users use your extension
- (Optional) Add support for localization
- (Optional) Specify how to handle scheduled publishing (also known as scheduled actions)
After a visual editor user installs your extension, they can extend the content model in stackbit.config.ts to add further customizations and properties that enhance the visual editing experience.
Next steps
After you work through the above workflow to develop your connector, you can debug and test locally and then publish your connector to test in production.