To get started with Netlify Connect, create and configure your first data layer.
A data layer allows you to sync and combine data from multiple sources into a single real-time graph database that you can query against with a GraphQL API. When you set up a data layer, you add data sources to sync data from. You also connect sites and add webhooks to notify whenever data updates.
Here are some key terms that are useful to understand as you get started with Connect:
Data layer: contains connections to one or more data sources, a real-time graph database containing all data synced from those sources, and a GraphQL API to access that data. It also supports connecting to sites and custom webhooks to trigger builds or send notifications as your data changes.
Data revisions: every successful sync to a data layer generates a new data revision that represents the GraphQL schema and data at that point in time. By default, a data layer’s GraphQL API uses the latest data revision, but you can also pin a different revision instead. You can query a specific data revision using the revision’s GraphQL sandbox or its unique API URL.
Data source: an external system or service that contains your data, such as a content management system (CMS). Connect has built-in support for a number of data source types and you can add support for your own custom data source with the Netlify SDK.
Data integration: an integration built using the Netlify SDK that allows you to sync data from a custom data source to Connect. Data integrations use the Connectors component of Netlify Integrations.
Type prefix: required when you want to add multiple data sources of the same type to a data layer, such as two Contentful CMS instances. When Netlify generates the GraphQL schema for your data layer, it will add the prefix to all GraphQL types from that data source.
Cross-reference: a link that you can create between fields across data sources. Netlify automatically resolves cross-references when you query, so you can retrieve combined data through one query instead of a series of queries.
GraphQL API: allows web clients to query and receive data from a data layer on Connect. A data layer’s GraphQL API defaults to use the latest data revision unless you pin a different data revision. Each data revision has a specific GraphQL schema based on your data sources, and you use this schema to construct queries and API requests.
GraphQL sandbox: an isolated environment in the Netlify UI that you can use to build and test queries against a data layer’s GraphQL API. Netlify creates a unique sandbox for each data layer that you create and for each data revision that results from a successful sync.
Connected sites: sites in your Netlify team that will automatically build and deploy when data changes. We use build hooks to trigger these builds.
Custom webhooks: external webhooks that you can add to your data layer. Netlify will notify these webhooks when data changes.
Sync events:activities that occur in Connect when you add a data source and when data changes. These events include Sync from all data sources, Sync from {data source type}, and Sync to database.
Team Owners and Developers can set up data layers for your team. This includes creating the data layer, adding data sources, connecting Netlify sites, and adding custom webhooks — activities that Netlify automatically logs to the team audit log.
You can create more than one data layer to fit your needs. For example:
One data layer for production data and sites to use, and another for staging data and sites to use
Different data layers for different departments or products across your organization
Once you create a data layer, you can add one or more data sources to sync data from. You can select from the data sources Netlify officially supports as well as custom data sources supported through integrations built with the Netlify SDK.
The Netlify UI includes a guided flow to help you create and configure a new data layer. To get started, add a data layer.
Need to add a new data source to an existing data layer?
If you want to add a new data source, site, or custom webhook to an existing data layer, you can do this from the data layer settings page. To learn more, review our manage data layers doc.
The second step in the data layer configuration flow is to add one or more data sources to your data layer. We recommend that you add at least one data source now, but you will have the option to add more after you complete this flow.
Each supported data source type has different credentials, options, and set up instructions.
Already using the Contentful Integration on Netlify?
Connect is separate from the Contentful Integration, and we currently do not leverage that integration to sync data. To use your Contentful instance with Connect, you need to add it here as a data source.
To use Contentful with Netlify Connect, complete the following steps:
Take the following steps on your Contentful space before you add it to your data layer:
In the Contentful web app, navigate to
Settings > API keys
, and select Add API key to create an API key and generate access tokens for the space you want to sync. Netlify will need one of these tokens to access your data.
In the Contentful web app, navigate to
Settings > CMA tokens
, and select Create personal access token to generate a Content Management API access token. Copy this token and store it in a safe place. Netlify will need this token to automatically set up a webhook in your Contentful space that will notify Connect whenever data changes in your CMS.
You’ll need to enter these tokens when you set up your Contentful data source in the Netlify UI.
(Optional) Enter a Type prefix for this data source. The prefix must start with an uppercase letter, and can only consist of alphanumeric characters and underscores.
The prefix will be added to all data types synced from this data source in the GraphQL schema and you will use it when you query the GraphQL API. For example, ContentfulPost with the prefix Marketing becomes MarketingContentfulPost in the schema.
Note that Type prefix becomes a required field when you add more than one Contentful instance to the same data layer.
Enter the Access token for your Contentful instance. To sync published content, enter the Content Delivery API access token. To sync preview content instead, enter the Content Preview API access token.
Enter the Space ID for your Contentful instance.
Enter the Content Management API access token for your Contentful instance. Netlify will use this token to automatically set up a webhook in your Contentful space that will notify Connect whenever data changes in your CMS.
(Optional) Select the Host URL for your Contentful instance. The default is cdn.contentful.com. To use the Contentful Preview API, select preview.contentful.com.
(Optional) Enter the Contentful Environment to sync data from. The default is master.
(Optional) Enter a Page limit to specify the number of entries to fetch per page when syncing data from Contentful. The default is 1000.
(Optional) Select Enable Contentful Tags if your Contentful instance uses the Contentful Tags feature. Note that if you enable this option, you cannot use the content type name tags at this time.
Select Save to add this data source.
When you add a new data source, Netlify automatically connects to it and starts syncing data to your data layer.
Take the following steps on your Contentstack instance before you add it to your data layer:
In your Contentstack account, navigate to
Settings > API Tokens
for your stack, and generate a delivery token for the environment you want to sync. You’ll need to enter this token when you set up your Contentstack data source in the Netlify UI, and Netlify will use this token to access your data.
To enable automatic syncing to Netlify, add your data layer webhook to your Contentstack instance:
In your Contentstack account, navigate to
Settings > Webhooks
for your stack, and select New Webhook.
Add the following webhook to the URL To Notify field. Make sure to replace the placeholder with your data layer ID.
Under When, add a Condition for each content type and event that you wish to sync. At minimum, you should configure the webhook to trigger when the Entry type is Created, Updated, and Deleted. For more information on how to configure webhook conditions, refer to the Contentstack docs.
(Optional) Enter a Type prefix for this data source. The prefix must start with an uppercase letter, and can only consist of alphanumeric characters and underscores.
The prefix will be added to all data types synced from this data source in the GraphQL schema and you will use it when you query the GraphQL API. For example, ContentstackPost with the prefix Marketing becomes MarketingContentstackPost in the schema.
Note that Type prefix becomes a required field when you add more than one Contentstack instance to the same data layer.
Enter the API key for your stack.
Enter the read-only Delivery token for your stack environment.
Enter the stack Environment to sync data from. For example, the production environment.
(Optional) Enter the Region to sync data from. Valid options are na-aws, eu-aws, na-azure, and eu-azure. The default is na-aws.
(Optional) Specify the Locales to sync entries from. For example, en-us, fr-ch.
(Optional) When entries aren't available for the specified locale, you can sync them in the fallback language instead. Select Include Fallback Locale to enable this. The default is false.
(Optional) Enter a Limit to specify the number of entries or assets to sync per page. The default is 50.
(Optional) Enter the Content Types to sync from Contentstack. For example, author, book.
(Optional) Enter the Content Types to exclude from Contentstack syncs.
Select Save to add this data source.
When you add a new data source, Netlify automatically connects to it and starts syncing data to your data layer.
Take the following steps on your DatoCMS project before you add it to your data layer:
In your DatoCMS account, navigate to
Project settings > API tokens
for your project. Follow the prompts to generate a token with the Admin role and with access to the Content Management API. You’ll need to enter this token when you set up your DatoCMS data source in the Netlify UI, and Netlify will use this token to access your data.
To enable automatic syncing to Netlify, add your data layer webhook to your DatoCMS project:
In your DatoCMS account, navigate to
Project settings > Webhooks
for your project, and select Add a new webhook.
Add the following webhook to the URL field. Make sure to replace the placeholder with your data layer ID.
Under Triggers, add a trigger for each entity and event that you wish to sync. At minimum, you should configure the webhook to trigger when the events are Create, Update, and Delete. For more information on how to configure webhook conditions, refer to the DatoCMS docs.
(Optional) Enter a Type prefix for this data source. The prefix must start with an uppercase letter, and can only consist of alphanumeric characters and underscores.
The prefix will be added to all data types synced from this data source in the GraphQL schema and you will use it when you query the GraphQL API. For example, DatoArticle with the prefix Marketing becomes MarketingDatoArticle in the schema.
Note that Type prefix becomes a required field when you add more than one DatoCMS project to the same data layer.
Enter the DatoCMS API Token for your project. This token requires the Admin role within your DatoCMS project and must have access to the Content Management API.
Enter the DatoCMS Environment to sync. For example, main.
Select Save to add this data source.
When you add a new data source, Netlify automatically connects to it and starts syncing data to your data layer.
Under Entity types to send to Gatsby Preview and Build Server, select the types you wish to sync. At minimum, you should select the Content type.
Select Save configuration to finish.
Navigate to
Manage > People > Permissions
to add the following permissions for data syncing:
Add Sync Gatsby Fastbuild log entities permissions. If your Drupal instance does not use authentication, then select Anonymous user. Otherwise, select the appropriate Drupal role.
Add View Gatsby log entity entities permissions. If your Drupal instance does not use authentication, then select Anonymous user. Otherwise, select the appropriate Drupal role.
(Optional) Add a Type prefix for this data source. The prefix must start with an uppercase letter, and can only consist of alphanumeric characters and underscores.
The prefix will be added to all data types synced from this data source in the GraphQL schema and you will use it when you query the GraphQL API. For example, DrupalPost with the prefix Marketing becomes MarketingDrupalPost in the schema.
Note that Type prefix becomes a required field when you add more than one Drupal instance to the same data layer.
Enter the Drupal URL for your Drupal site, including the trailing slash.
(Optional) If your Drupal instance has basic authentication enabled, enter the HTTP Basic Auth username and HTTP Basic Auth password.
(Optional) Enter the Gatsby Image CDN placeholder style name. The default is placeholder.
(Optional) Enter the JSON:API base to use as the relative path to the JSON:API root. The default is /jsonapi.
(Optional) Enter the Headers used for Drupal API to apply specific headers for the API.
(Optional) Enter a Timeout value. This is the time in milliseconds before requests to Drupal will time out. The default is 30000.
(Optional) Enter the number of Concurrent API requests a user can make to the Drupal API. The default is 20.
(Optional) Enter the Filters used for Drupal API to specify what content to sync. This will allow you to control the data you receive from Drupal. For example, {"recipe": "filter[tags.name][value]=British"}.
(Optional) Enter the Default language of your Drupal site. This will determine what language content to sync from Drupal. The default is to sync the English language content.
(Optional) Enter the Enabled languages for your Drupal site. This will allow you to sync different translations from Drupal, depending on what languages your site has enabled.
(Optional) Select Filter by language to filter the data you sync from Drupal based on the current language.
(Optional) Enter the Translatable entities to specify what entities to sync translations for. For example, node--page, node--article.
(Optional) Enter the Non-translatable entities from your Drupal site. These entities will use the default language of your site. For example, taxonomy_term--tags, taxonomy_term--categories.
Select Save to add this data source.
When you add a new data source, Netlify automatically connects to it and starts syncing data to your data layer.
Take the following steps on your Sanity project before you add it to your data layer:
Deploy a Sanity GraphQL API for the project. To deploy a GraphQL API on Sanity, use the Sanity CLI to run sanity graphql deploy in the Sanity Studio project folder. Learn more about deploying GraphQL APIs on Sanity.
Note: You should redeploy the Sanity GraphQL API every time you make changes to the schema that you want to use in Netlify Connect
To enable automatic syncing to Netlify Connect, add your data layer webhook to the Sanity project.
In Sanity, navigate to
API > Webhooks
in your Sanity settings. Under GROQ-powered Webhooks, select Create webhook.
Enter a name for the webhook and then add the following webhook URL to the URL field. Make sure to replace the placeholder with your data layer ID.
Once you have prepared your Sanity project, take the following steps in the Netlify UI to add it to your data layer:
Select Add a data source.
Enter a Name for this data source.
Select Sanity as the Data source type.
(Optional) Enter a Type prefix for this data source. The prefix must start with an uppercase letter, and can only consist of alphanumeric characters and underscores.
The prefix will be added to all data types synced from this data source in the GraphQL schema and you will use it when you query the GraphQL API. For example, SanityPost with the prefix Marketing becomes MarketingSanityPost in the schema.
Note that Type prefix becomes a required field when you add more than one Sanity project to the same data layer.
Enter the Project ID for your Sanity project.
Enter the name of the Dataset to sync.
(Optional) If you deployed the Sanity GraphQL API with a tag, enter the GraphQL tag name. For example, if you used --tag experiment for the deploy, enter experiment. The default is default.
(Optional) If your dataset is private, enter the API authentication token to use for syncing data. The token must have Viewer permissions.
Select Save to add this data source.
When you add a new data source, Netlify automatically connects to it and starts syncing data to your data layer.
To add a Shopify store to your data layer in Netlify Connect, first you need to set up a custom Shopify app that we can use to access Shopify’s Admin API and sync data. You will need the Admin API access token to set up your Shopify data source in Netlify Connect.
Log in to your Shopify store as the store owner and search for Apps and sales channels.
Enable custom app development. To do this, select Develop apps, then Allow custom app development. After reading the warning and information provided, select Allow custom app development.
Create a custom app. From the App development section, select Create an app. Enter an app name and developer, then select Create app.
Set admin API scopes for the app. On the custom app page, select Configure Admin API scopes. Enable the read_products, read_product_listings, and read_files scopes, and then select Save.
You can use this data integration to proxy directly to the Shopify GraphQL API as well. To allow additional CRUD operations through the proxy, enable the admin API scopes for these operations, such as write_products.
Install the app and get the API access token. Select the API credentials tab and select Install app under Access tokens. Follow the prompts to install the app on your Shopify store.
Next, under the Admin API access token section, select Reveal token once to access the token. Store the token in a safe place as you will need it to set up the data source connection.
(Optional) Add a Type prefix for this data source. The prefix must start with an uppercase letter, and can only consist of alphanumeric characters and underscores.
The prefix will be added to all data types synced from this data source in the GraphQL schema and you will use it when you query the GraphQL API. For example, ShopifyProduct with the prefix Marketing becomes MarketingShopifyProduct in the schema.
Note that Type prefix becomes a required field when you add more than one Shopify store to the same data layer.
Enter the Store URL for your Shopify store. This is the myshopify.com URL, excluding https:// and the trailing slash.
Enter the Admin API access token. This is the access token for the custom Shopify app you created in the prepare your store step. The token starts with shpat_.
Select Save to add this data source.
When you add a new data source, Netlify automatically connects to it and starts syncing data to your data layer.
In your WordPress admin dashboard, navigate to Plugins and then select Add New Plugin.
Select Upload Plugin and follow the prompts to upload the netlify-connect-wp-plugin.zip file that you downloaded in step 1.
Select Install now.
In your WordPress admin dashboard, navigate to
Edit Profile > Application Passwords
and create an application password. You’ll need to enter this as your token when you set up your WordPress data source in the Netlify UI, and Netlify will use this token to access your data.
To enable automatic syncing to Netlify, add your data layer Webhook URL in your WordPress plugin settings for Connect:
In your WordPress admin dashboard, navigate to
Settings > Netlify Connect
.
Add the following webhook to the Data layer Webhook URL field. Make sure to replace the placeholder YOUR-DATA-LAYER-ID with your data layer ID.
If you need to customize your setup further, you can configure the following optional settings during the setup process:
Type prefix: add a prefix for this data source. The prefix must start with an uppercase letter and can only consist of alphanumeric characters and underscores.
Connect will add the prefix to all data types synced from this data source in the GraphQL schema, which you will use when you query the GraphQL API. For example, Post with the prefix Marketing becomes MarketingPost in the schema.
Instance ID: add an instance ID for this data source to uniquely identify it.
Per page: specify the number of nodes to fetch per page when syncing data from WordPress. The default is 100.
Request concurrency: set the number of concurrent requests to make during node sourcing. You can lower this if your WordPress server experiences issues during data sourcing. The default is 15.
Types to exclude globally: specify the slugs of post types, taxonomies, or other content types to exclude from sourcing, listed as comma-separated values.
To use a custom data source, an integration must already exist for it
If a data integration doesn’t already exist for your custom data source type, create one with the Netlify SDK. Data integrations use the Connectors component to specify the data model and logic for syncing data from a custom data source. Once you publish your data integration, you can start using it in Netlify Connect.
To use a custom data source with Netlify Connect, complete the following steps:
To enable automatic syncing to Netlify, you need to manually add a webhook to your custom data source instance. The exact instructions vary for each system but you need to do the following:
Log in to your data source and navigate to the webhook settings.
Follow the prompts to create a new webhook and add the following to the URL field. Make sure to replace the placeholder with your data layer ID.
If the options are available, select the data types and events that should trigger the webhook. We suggest including any create, edit, and delete events for all content types that you wish to store in your data layer.
Under Data source type, select the data integration that you enabled.
Fill in the configuration fields with the values for your data source instance. For example, you may need to provide the API key for your CMS instance.
Select Save to add this data source.
When you add a new data source, Netlify automatically connects to it and starts syncing data to your data layer.
In the meantime, you can add another source or select Continue to move to the next step in the data layer configuration flow.
If you want to add cross-references between your data sources, you can configure them after you complete the data layer configuration flow.
The third step in the data layer configuration flow is to set up connections to sites on Netlify that should automatically build and deploy when data changes in this data layer.
We recommend that you connect any sites that use static site generation (SSG) to ensure they always have access to the latest data. All other site types should skip this step. Learn more about when to connect your site.
For Netlify to automatically build and deploy your site when data changes, your site must be linked to a Git repository to enable continuous deployment, and it must have active builds.
To connect a site to this data layer:
Select Search by site name or domain and start entering the name or domain of the site you want to connect.
When the site appears in the results list, select the site. The connected site will appear in the Connected sites list.
Once you connect a site, the build hooks for the site will include a Netlify Connect - Data layer build hook with the data layer ID as the value. This provides a convenient way on the site level to check whether a site is connected to a data layer.
Repeat the above steps to connect as many sites as needed. Once you’re done, select Continue to move to the last step.
The final step in the flow allows you to add custom webhooks to notify external services whenever data changes in your data layer. For example, you may want to add a webhook to notify a Slack channel when your data layer updates.
To add a custom webhook:
Select Add a custom webhook.
Enter a Name for this webhook.
Enter the URL for this webhook.
Select Create custom webhook.
Repeat these steps to add as many custom webhooks as needed.
Once you’re done, select Finish data layer configuration to complete the set up process.
Once you finish the configuration flow for a new data layer, you can review sync events while Netlify completes the initial data sync from your data sources.
After the sync events are successful, you need to generate an API token for the GraphQL API. Once you do that, you can access the data with the GraphQL sandbox or through the GraphQL API in your app.
If the sync events are not successful, review our troubleshooting tips for support.
If you need to, you can now pin a data revision so that your data layer’s API always uses that specific data revision.
You can also review and modify the data layer to add or update configured data sources, sites, and webhooks. After you configure more than one data source on the data layer, you can add cross-references to create links between fields across data sources and retrieve the combined data through a single query.
