Automate your BigCommerce Theme Configuration for Different Environments

In Supercharge your BigCommerce Theme Workflow with GitHub Actions, Rachael Thompson demonstrated how to automate deployments of a Stencil theme to a BigCommerce store using the built-in Github actions template. This article expands on that work to automate the theme configuration using a custom deploy script and GitHub actions.

The Use Case

Imagine that you work for a full-service ecommerce agency and you have built a spectacular theme that your clients love. In fact, many of your clients love it and want to use it. There are aspects of each merchant’s store that are not shared, so it’s not appropriate to code them into the theme. Consider things like an ID for an analytics property, a client API key for a payment integration, or the endpoint URL for a custom service you’ve developed. You could keep those values in the theme’s configuration by hard-coding them into config.json or using the BigCommerce control panel to configure the theme settings, or you could store the values somewhere else in BigCommerce like in Scripts Manager. But wouldn’t it be nice if you could store those values as environment variables in your theme’s repo(s) and configure them automatically when you commit changes?

This article will demonstrate how to write a deployment script that you can execute with Github Actions to automate the configuration of some environment variables when you use Github Actions to deploy a Stencil theme to a BigCommerce store.

Important!

This approach is only intended to be used for variables that are safe to expose to the browser. Server to server API keys or other secrets should not be stored or written to the Stencil theme’s config.json file.

The Solution

This approach uses the same GitHub workflow file that Rachael describes in her article and introduces a new .js file that Github will execute during deployment. The .js file will read a value from the repo’s secrets or environment variables and use it to populate a setting in the theme’s config.json. You can then reference the setting from config.json in your theme’s HTML template files with Handlebars as part of the {{theme_settings}} object.

Prerequisites

• Stencil CLI
• a Stencil theme
• a Github account
• a Github repo for your theme

If you do not have Stencil CLI or a theme, see the BigCommerce documentation for more information on configuring those items.

If you do not already have a Github account, sign up for one for free here: https://github.com/signup.

If you do not already have a repo for your theme, create one or begin by forking the Cornerstone theme at https://github.com/bigcommerce/cornerstone.

Write the Deployment Script

In your theme directory, create a new file. I named mine deploy.js. The filename will be important later, so take note of it now. In deploy.js, add the following simple Node.js script that writes an environment variable as a custom setting named mySetting in the theme’s config.json file:

Next, update the theme’s package.json file to declare a new script that will execute your deployment script. In this example, the script’s name is config. Add the following to the scripts object in package.json:

Example in the context of the entire package.json file: https://gist.github.com/hatertron3000/896ed8ca7e90084d2788e6016345b239#file-package-json-L73

Test the Deployment Script

To test the deployment script, run the following command which will execute the script that you configured in package.json in the previous step using an environment variable that you set in the command:

After you run the script, check config.json where you should now see settings.mySetting with the value you set in the previous command:

Configure Actions Secrets

In your Github repo, navigate to Settings > Secrets and create three secrets:

• MY_SETTING: Any text value that you want to use to demo your deploy script
• STENCIL_ACCESS_TOKEN_PRODUCTION: The API access token used to initialize Stencil CLI with the stencil init command
• STENCIL_STORE_URL_PRODUCTION: The storefront URL for the BigCommerce including protocol. Example: https://store.example.org

Note: You could use an Environment to store the MY_SETTING variable if preferred. When I created this example, the repo was private so Environments were not available. If your repo is public or if you have a Github Enterprise account, you may use an Environment instead. To learn more about Github Environments, see the Github documentation: https://docs.github.com/en/actions/reference/environments

Create the Workflow

Important!

After completing these steps, the theme will be applied to your storefront. If you do not wish to apply the theme to your storefront, modify the stencil push command in the workflow file, or perform these steps with a sandbox store.

Copy the example workflow found at .github/workflow-examples/automatic_deployment_production.yml in the Cornerstone theme to .github/workflows/automatic_deployment_production.yml. Add the following step somewhere before the last step in the workflow named “Push theme live, automatically deleting oldest theme if necessary”:

I like to put it before the “Install Stencil CLI Dependency” so that I can see the result without having to wait to install Stencil CLI. You can check out my example workflow here: https://github.com/hatertron3000/config-json-demo/blob/main/.github/workflows/automatic_deployment_production.yml

Your workflow will execute once you commit this workflow to your theme’s main branch. You can view the results on the Actions tab of your github repo:

Example results: https://github.com/hatertron3000/config-json-demo/runs/3293994017

Once the workflow has finished executing and assuming it finished successfully, the theme should be applied to your store and you should see the secret/environment variable that you configured in Github in your theme’s config.json file when you view it from the BigCommerce control panel:

Conclusion

Configuring environment variables for themes doesn’t have to be a painful process, and you don’t have to maintain separate repos to do it. Using a bit of JavaScript, continuous deployment tools like Github Actions, and environment variables you can use one codebase to deploy the same theme to multiple environments.