The Contentstack Bridge adds a layer between your application and Contentstack, to provide some much-needed conveniences.
Information on building and configuring the Contentstack Bridge
Information on the subcommands and CLI flags in the Contentstack Bridge CLI
Information on the built-in API server and endpoints
It’s pretty easy to set up the Contentstack Bridge. Let’s walk through the steps that are needed to set it up.
There’s two ways to get the application binary. One way is to build it locally. Instructions on how to do this can be found on Building.
Alternatively, pre-built binaries can be found on the releases page on GitHub.
Once you have a csb binary, you can verify that it works by running ./csb --help.
If this command outputs a help menu, you can move on to the next step.
For the application to be able to communicate with Contentstack and access its own database, a .env file is required.
An example .env file can be found in the GitHub repository.
Once the .env file has been configured, you can validate it by running ./csb check:health.
For more information about the possible configuration options, please see the Configuration options page.
Now that the application is configured, we can create the necessary database tables.
This can very easily be done by running ./csb migrate:db.
Once this is done, all of the database tables will be set up and ready to go.
Now that we have a database and tables, we need to populate the data.
We can do this by running ./csb remote:sync.
This will synchronise the remote data into the database.
This is needed for the built-in API to work, among other things.
This command should also be ran periodically, to keep the data up-to-date. When run again, the sync will continue where it left off, so only the initial synchronisation will be a heavy operation.
Building instructions for the application
Configuring the Contentstack Bridge
An overview of all possible configuration options
To build the application, simply run go build.
This will create a new file, called csb. Running it now will throw an error,
since there is no configuration yet.
Instructions on how to configure the application can be found on the Configuration page.
Configuration is done with a .env file. To start, copy the .env.example:
cp .env.example .envAn example .env file can also be found in the GitHub repository.
The Contentstack credentials can be obtained from the Contentstack settings.
To reach the settings, go to your stack and click on the settings icon from the left sidebar.
The API Key (CS_API_KEY) can be found on this page.
For the delivery token (CS_DELIVERY_TOKEN), click on “Tokens” in the settings page.
If no delivery token exists, please create one by clicking on the top right button first.
Once you have a delivery token, you can click on it, and find it in the field “Delivery Token”.
The region (CS_REGION) can be found directly in the URL.
It should look like <REGION>-app.contentstack.com. The <REGION> here is the region you need to use.
if the URL is app.contentstack.io, the region will be us.
When testing the application locally, the DB_* variables can be left as-is.
This will create a file called db.sqlite3. This can be handy for local testing.
For production use, databases like MySQL and Postgres are supported as well. For testing, alternative databases can quickly be spun up locally:
docker compose up -d| Key | Example value | Description |
|---|---|---|
CS_API_KEY | - | The API key for the Contentstack stack |
CS_DELIVERY_TOKEN | - | The Contentstack delivery token, used to fetch content |
CS_MANAGEMENT_TOKEN | - | The Contentstack management token, mainly used when creating content types in the CLI |
CS_BRANCH | main | The branch of the Contentstack stack to use |
CS_REGION | us / eu / azure-na / azure-eu | The region your Contentstack is located in. Visit Configuration for more information |
DB_CONN | file:db.sqlite3 | The database connection string |
DB_TYPE | sqlite3 / mysql / postgres | The type of the database to connect to |
DEBUG_AUTH_BYPASS | true / 1 | DEBUG: Disable authentication checks in the API server |
The Contentstack Bridge has a powerful CLI. It will allow you to:
An overview of all CLI options
--env-file.env file. Defaults to the location of the executable--quietwarning or above--verboseCheck the health of the application and the configuration. Useful when configuring or updating the application.
–
Perform database migrations. This will be needed during the initial setup, as well as during future updates.
--resetSynchronise all Contentstack entries into the database. By default, this will be incremental, meaning that every synchronisation action will continue where the last one left off.
--resetRun a webserver with a REST API. More information about the webserver can be found on the API Server page.
--port4000Create a new content type, with some standard fields.
--name--machine-nameThe API server allows the Contentstack Bridge to be used as an alternative to the Contentstack API. This has a couple of advantages:
/api/v1/get-entry-by-url
url (required)locale (required)/api/v1/get-entry-by-uid
uid (required)locale (required)/api/v1/content-types
–
{
data: { // Will be null if there's an error
// An array of alternative locales will always
// be returned alongside the entry itself.
alt_locales: {
uid: string,
content_type: string,
locale: string,
slug: string,
url: string,
}[],
// The entry is directly queried from Contentstack.
entry: {
ACL: unknown,
_in_progress: boolean,
_version: number,
created_at: string, // Timestamp string
created_by: string, // UID of the creator
locale: string,
parent: {
_content_type_uid: string,
uid: string,
}[],
publish_details: {
environment: string, // The environment UID
locale: string,
time: string, // Timestamp string
user: string, // The user UID
},
tags: string[],
title: string,
uid: string,
updated_at: string, // Timestamp string
updated_by: string, // The user UID
url: string,
// additional options for any other fields
},
},
error?: string // Will be null unless there's an error
}{
DEFAULT_ACL: unknown,
SYS_ACL: unknown,
_version: number,
abilities: {
create_object: boolean,
delete_all_objects: boolean,
delete_object: boolean,
get_all_objects: boolean,
get_one_object: boolean,
update_object: boolean,
},
created_at: string, // Timestamp string
description: string,
inbuilt_class: boolean,
last_activity: unknown,
maintain_revisions: boolean,
options: {
is_page: boolean,
publishable: boolean,
singleton: boolean, // Whether or not the content type supports multiple entries
sub_title: string[],
title: string,
url_pattern: string,
url_prefix: string,
// additional options for any other fields
},
schema: [
{
data_type: string,
display_name: string,
field_metadata: {
_default: boolean,
version: number,
},
mandatory: boolean,
multiple: boolean,
non_localizable: boolean,
uid: string,
unique: boolean,
}[]
],
title: string,
uid: string,
updated_at: string, // Timestamp string
}[]