Backpackjs CLI

Backpack CLI is a NodeJs command line interface responsible for initializing a backpack storefront.

Commands

• backpack build: initializes a storefront build
• backpack dev: initializes storefront in local development mode on port 8080. http://localhost:8080

Overview

backpack dev|build are executed every time that an npm script such as yarn build or yarn dev is run. At its core, the backpack cli command is responsible for orchestrating all storefront's init lifecycle modules.

Storefront Init Lifecycle

The storefront initialization lifecycle is comprised of the following steps:

1. 🌎 Getting or setting the CMS environment branch that will act as content source for the build (CMS_ENV).
2. 🛫 Validating all required storefront env vars are present.
3. 🔄 Synchronizing Shopify products and collections.
4. 🚸 Creating redirects.
5. 🔎 Creating fuse search indexes for all articles, blogs, pages, products and collections.
6. 🛍 Creating an xml products feed.
7. 🕸 Creating the sitemap.
8. 🗿 Generating metas, styles, fonts and scripts <head/> tags.
9. 🎒 Initializing nextjs with backpack's custom nextjs plugin.
10. 🎒 Passing the active CMS env branch CMS_ENV into nextjs. i.e Executing nextjs as:
    • CMS_ENV=main next dev - When executing yarn dev within git's main branch
    • CMS_ENV=staging next build - When executing yarn build within git's staging branch
    • CMS_ENV=my-feature next dev - When executing yarn dev within git's my-feature branch
    • or any other combination...

Storefront init config

Each storefront's init sequence can be customized by adding a backpack.init.js config file at the root of the project. If no config is provided, the storefront will fallback to its default init configuration file.

Here is a list of all available settings:

backpack.init.js (default)

export const config = {
  verbose: false,

  dev: {
    port: 8080,
  },

  cms: {
    enabled: true,
    create: true,
    delete: true,
    forceEnv: false,
    maxBranches: 7,
    customizeToolbar: true,
    branchSwitching: true,
    publishing: true,
    drafting: true,
    verbose: false,
  },

  preflight: {
    enabled: true,
    validateEnVars: true,
    verbose: false,
  },

  sync: {
    enabled: true,
    resolveFirst: 12, // Todo: Doc internal - 0 resolves all products with "Product Item" versions
    verbose: false,
  },

  redirects: {
    enabled: true,
    verbose: false,
  },

  search: {
    enabled: true,
    indexes: ['pages', 'blogs', 'articles', 'products', 'collections'],
    verbose: false,
  },

  feed: {
    enabled: true,
    verbose: false,
  },

  sitemap: {
    enabled: true,
    verbose: false,
  },

  head: {
    enabled: true,
    verbose: false,
  },

  next: {
    enabled: true,
    customEnvVars: null,
    verbose: false,
  },
};

---

🧑🏽‍💻 Cli options

| default | options | description :--- | --- | --- | --- | verbose | true | true or false | enable/disable additional backpack cli logging information

---

🧑🏽‍💻 Dev options

dev	default	options	description
port	8080	a valid port	The port backpack dev should run on.

---

🌎 CMS env options

cms	default	options	description
enabled	true	true or false	enable or disable cms environment detection (CMS_ENV)
force	false	false or "branch-name"	bypass the automatic CMS_ENV detection by forcing a valid CMS content branch as default. i.e: "staging"
create	true	true or false	enable content branches creation
delete	true	true or false	enable content branches deletion
maxBranches	7	1-7	Limit the number of cms environments a given project can have
customizeToolbar	true	true or false	enable the toolbar that shows the branch being previewed and to easily access customize mode from development mode
branchSwitching	true	true or false	enable the branches switching selector inside the customizer. Other conditions may also determine wether branch switching is allowed.
publishing	true	true or false	globally enable or disable content publishing inside the customizer. Other conditions may also determine wether publishing is allowed or not.
drafting	true	true or false	globally enable or disable draft content saving inside the customizer. Other conditions may also determine wether publishing is allowed or not.
verbose	false	true or false	enable additional console logs for debugging cms-env

Verbose enabled example

CMS init with default values on a "config-docs" branch

CMS init with verbose enabled on a "config-docs" branch

---

🛫 Pre-flight options

preflight	default	options	description
enabled	true	true or false	enable or disable the pre-flight module
validateEnVars	true	true or false	enable required environment variables validation
verbose	false	true or false	log all available environment variables

---

🔄 Sync options (initialization)

sync	default	options	description
enabled	true	true or false	enable the synchronization module
resolveFirst	12	0	n
verbose	false	true or false	enable additional console logs for debugging sync

For additional runtime sync options see @backpackjs/sync configuration backpack.sync.default.js

---

🚸 Redirects options (initialization)

redirects	default	options	description
enabled	true	true or false	enable the redirects creation module
verbose	false	true or false	enable additional console logs for debugging redirects

Redirects can be create via the backpack admin

For additional information on redirects see @backpackjs/build-scripts

---

🔎 Search options (initialization)

redirects	default	options	description
enabled	true	true or false	enable search indexes creation module
indexes	['pages', 'blogs', 'articles', 'products', 'collections']	[...'endpoint']	List of endpoints you want a fuse search index created for at build time. Indexes are available as json endpoints at i.e /json/articles-index.json & /json/articles-list.json
verbose	false	true or false	enable additional console logs for debugging search indexes

For additional information on search indexes see @backpackjs/build-scripts

---

🛍 Products Feed options (initialization)

redirects	default	options	description
enabled	true	true or false	enable the products feed creation module
verbose	false	true or false	enable additional console logs for debugging the products feed

For additional runtime product feeds options see @backpackjs/products-feed configuration file backpack.feed.js

---

🕸 Sitemap options (initialization)

redirects	default	options	description
enabled	true	true or false	enable the sitemap module
verbose	false	true or false	enable additional console logs for debugging the sitemap

For additional runtime sitemap options see @backpackjs/sitemap configuration file backpack.sitemap.js

---

🗿 Head options (initialization)

head	default	options	description
enabled	true	true or false	enable the head generation module
verbose	false	true or false	enable additional console logs for debugging head

For additional runtime head options see @backpackjs/head configuration file backpack.head.js

---

🎒 Next options (initialization) [todo]

next	default	options	description
enabled	true	true or false	enable nextjs initialization
customEnvVars	null	null or { ANALYZE: true, ...}	provide custom env vars to nextjs
verbose	false	true or false	enable additional console logs for debugging next

For additional runtime backpack nextjs options see @backpackjs/nextjs-backpack configuration backpack.next.js