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

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 | the number of json product items that should be pre-loaded on collections. i.e In a collection of 50 products, this would mean that 38 products would have to be lazy loaded. 12 is a good number as that's usually the number of products (max) that would be above the fold on a collection. 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