CSI Module Methods

CSI Module Lifecycle#

The diagram below illustrates the lifecycle of a content source module, outlining the points at which Netlify Create calls its methods and when the content source instance should invoke Netlify Create callbacks.

The lifecycle of a content source module can be divided into three phases:

1. Initialization: This phase occurs when the Netlify Create project initializes or detects a change in stackbit.config.ts, leading to the creation of a new content source instance. During this phase, Netlify Create calls the "read" methods of the content source module to fetch the content, content schema, and assets stored within the underlying content source. At the end of the initialization phase, the content source module should start monitoring for content updates. Additionally, some steps of this phase may be repeated when the content source module invalidates the schema.
2. Content editing: The content source module remains in this phase until it is destroyed. During this phase, the module receives content change operations from Netlify Create while the content editor makes changes to the content through the Netlify Create user interface. The module monitors all content and schema changes in the underlying content source and informs Netlify Create when any such changes occur.
3. Cleanup: This phase is triggered when a change is detected in the stackbit.config.ts file, leading to the creation of a new content source instance and removal of the previous instance. During this phase, the content source module should stop monitoring for content changes, cease invoking Netlify Create callbacks, and release any resources and timeouts that may be holding the content source in memory.

Initialization#

As shown in the lifecycle diagram, Netlify Create loads stackbit.config.ts and executes the code within it. This code imports and instantiates the content source modules. Next, Netlify Create iterates over the contentSources array and calls the following methods in order for each content source:

1. getContentSourceType()
2. getProjectId()
3. init(options)
4. getVersion()
5. getSchema()
6. getDocuments()
7. getAssets()
8. getProjectManageUrl()
9. startWatchingContentUpdates()

At this point, the content source should begin monitoring for content and schema changes in the underlying content source, and then call one of the options.cache methods received in the init(options) method. There are two ways to implement content monitoring:

1. Direct communication mechanism: This involves establishing a communication channel between the content source module and the underlying content source, using methods such as server-to-server events, periodic API polling, long-polling, etc.
2. Webhooks-based monitoring: Webhooks can be created within the init(options) method, if they haven't already been created. In this case, the content source should use the options.webhookUrl passed to the init method.

Content Editing#

When the content editor performs different actions, Netlify Create calls the following methods of the corresponding content source module:

1. hasAccess(options)
2. createDocument(options)
3. updateDocument(options)
4. deleteDocument(options)
5. uploadAsset(options)
6. validateDocuments(options)
7. publishDocuments(options)

When one of the document "write" methods is called, the following sequence of events occur:

1. The method should convert the Netlify Create "write" operation into content source-specific API calls to update the content in the underlying content source.
2. The content source module should not immediately call options.cache.updateContent(). Instead, it should rely on content monitoring and wait for a notification from the underlying content source indicating that the content change is available for consumption via its API. By doing this, the module ensures that externally made content changes are treated the same as those made within Netlify Create, and that Netlify Create callbacks aren't called twice. This approach also guarantees that when Netlify Create notifies the website preview to reload the content, the website will render the updated content. If the content source uses webhooks to monitor content changes, Netlify Create will route the webhook to the content source and call its onWebhook() method. For content sources that use a file-system to store content, the onFilesChange() method can be implemented. Netlify Create sets up file watchers and calls this method when one of the project files is changed.
3. Finally, the content source module retrieves the updated content and updates Netlify Create cache by calling the options.cache.updateContent() method that was passed to the init(options) method.

When the content source module is notified of a change in the content schema, it should invoke the options.cache.invalidateSchema() method. In this case, Netlify Create will repeat part of the initialization phase and call the following methods in order

1. reset()
2. getSchema()
3. getDocuments()
4. getAssets()
5. getProjectManageUrl()

Cleanup#

When Netlify Create detects a change in stackbit.config.ts, it calls the following methods in order on the unloaded content source module

1. stopWatchingContentUpdates()
2. destroy()

Stateless Content Source Modules#

Content source modules should remain stateless with respect to the content and the schema fetched from the underlying content sources, except for certain metadata that does not change frequently.

Content source modules should not cache content or schema returned from methods such as getSchema, getDocuments, and getAssets. Netlify Create will take care of caching this data for you. To access this data, you can use similarly named methods on the options.cache object provided to the init(options) function.