@backpackjs/cms-env

🌎 Backpackjs CMS-ENV

Backpack's Content Management System Environment module (CMS-ENV) is the first (1) command executed during the backpack storefront initialization lifecycle. It is executed in both development and production modes (i.e in both backpack dev & build).

Backpackjs CMS-ENV is primarily responsible for:

• Detecting the current CMS environment branch (production or feature)
• Managing the creation, update and deletion of CMS environment branches (via a cli prompt), and
• Providing the default CMS environment branch context to the storefront (via the CMS_ENV env var)
  

CMS Environment

A CMS environment is the content management instance of a storefront. The instance's default schema includes a set of pre-defined content types that allow end-users to store and manage both meta and front-end content entry for all common e-commerce content endpoints.

CMS Environment Content Types

TYPE	FIELDS	DESCRIPTION
📃 Page	• handle • seo [title, description and image] • content [local, global sections]	A page is a route representing a single page i.e /pages/about-us
🗂 Blog	• handle • seo [title, description and image] • content [local, global sections]	A blog is a route representing a collection of articles i.e /blogs/news
📝 Article	• handle • seo [title, description and image] • article [author, blog, excerpt, category, tags] • content [local, global sections]	An article represents a single blog post CMS entry i.e /blogs/news/we-are-live
🛍 Collection	• handle • seo [title, description and image] • content [local, global sections]	A collection is a route representing a collection of products i.e /collection/new-arrivals
👜 Product	• handle • seo [title, description and image] • content [local, global sections]	A product content type is a route a single product content entry i.e /products/crew-neck-tee

CMS Environment Branches

An important feature of backpack CMS environments is the concept of content branches. A content branch, is an isolated clone of the full CMS instance for a given storefront.

There are two types of content branches:

TYPE	DEFAULT	# BRANCHES	CONFIGURABLE	DESCRIPTION
🌎 production branch	"main"	1	no	The "main" branch is your live/production content branch
🚧 feature branches	any git branch name i.e "staging"	1-7 maxBranches	yes	Any git branch such as "staging", "new-hero", "new-landing-page" etc..

Content isolation enables full separation of content management concerns between production and development content branches and between development branches themselves.

This means that developers can develop, configure, deploy and preview new complex features without worrying on it's impact on the production content branch or any other concurrent development branches.

Backpack feature branches provide similar but much improved functionality to Shopify themes development workflows via duplicated theme instances.

CMS feature branches (content) vs. Git branches (codebase)

All CMS content branches have a 1-to-1 relationship with storefront git branches. This ensures a correct association between code and content branches `. i.e A deployed "staging" git branch using the "staging" CMS content branch as data source.

• Production Branch: By default backpack CMS creates its production branch under the name main which means that the storefront's git repository must have main as it's primary/master branch.
• Feature Branch(es): Each feature branch i.e "new-homepage-hero" starts a clone of the main production branch (at the time of creation).

Feature branches

Feature content branches (can be) very dynamic by nature - just like git branches. That is, you can easily create , delete or update (soon) any feature branch.

Depending on your storefront cms-env configuration's maxBranches you will have up to 7 isolated and fully previewable feature branches to work with at any given time.

Although you may be limited to 7 concurrent feature branches, this does not mean that you can't have multiple developers collaborating within individual feature branch at the same time.

Since most features branches are likely to come and go, we provide you with a prompt-based cli interface that guides you throughout the feature management lifecycle.

Feature branch lifecycle

When a storefront is first created, it will have only the "main/production" content branch. This is because your storefront git repository will have no other branches.

As you start working on new features, you may want to develop these in separate git branches.

Creating content branches is closely tied with creating regular git branches.

1. Creating your first feature branch

• Create and new git branch
• Switch to your newly created branch
• Run yarn dev
• Because this is the first time you are running yarn dev on this new git branch, backpack CMS doesn't have yet have a matching content branch for it. The cli will prompt you wether you want to create a new content branch

• Choose "yes" to create a new branch and then press enter

Any subsequent calls to yarn dev or yarn build on this branch won't require this step.

You must always create a new content branch via the cli, before a feature build preview can be successfully deployed. This is because a build will fail if there is no matching content branch for a given git branch.

2. Creating additional branches

To create any additional branches simply follow the previous steps. When you have reached your allocated number of feature branches, the cli may prompt you wether you want to delete an existing content branch in order to create a new one.

3. Creating a new content branch by replacing an existing content branch

Replacing an existing branch with a new one, is also managed via the cli. To replace an existing branch simply:

• Create and new git branch
• Switch to your newly created branch
• Run yarn dev - You should see: 🌎 Initializing Backpack environments...
• Choose the old branch you want to delete
• Confirm the deletion
• Confirm the creation of the new content branch

Any subsequent calls to yarn dev or yarn build on this branch won't trigger the cli. Instead you should see:

🌎 Setting [configs-doc] as active environment [CMS_ENV]

4. Updating a feature branch (TODO)

This is the use case were I like working on say a jp branch. The branch gets out of sync with main.. Need to build the branch update prompt / feature.

Content branching workflow and caveats

Recommended workflow

• Talk about the ideal workflow. Don't re-use all branches whose content may be stale.

Caveats

• Currently content changes created on a feature branch can't be merged back into other branches. This includes the production branch. Although this may sound limiting at first, it doesn't have to be. This is because storefront content sections provide powerful default settings which should be used to easily transport new content section data into the production content branch. This is also a good practice, because the end users will be able to preview new content sections with any set of text, image and video defaults.

Forcing a given content branch

Although not recommended, a storefront can be forced to initialize with a "non-matching"/"detected" feature content branch. This can be achieved by configuring the forceEnv option on backpack.init.js