Listen up and be prepared! We’re about to ‘nerd out’ and get geeky about the actual build of the Stencil Cornerstone theme for BigCommerce.

If you’re looking for a less-technical look at Stencil for BigCommerce, check out our blog article about the differences and advantages of selecting: Blueprint vs Stencil for BigCommerce.

When we develop or maintain themes for BigCommerce stores using the Stencil framework, we can generate a file in the ZIP format, containing the full theme to be uploaded. This can be achieved by running the “stencil bundle” command.

It takes the HTML templates, SCSS stylesheets and JS scripts source files, and transforms them into a ZIP file, containing the theme files in the format expected by BigCommerce to be applied in a store and work. This transformation from the original source files into another set of files is what we call the “build” process.

The build process also happens when we use the “stencil push” command to automatically upload and apply a theme in a store, as well as the “stencil start” command to develop a theme in our own developer’s computer.

The fact is: what effectively is submitted as a theme to the store is slightly different from the code files we write to author it.

In some scenarios, it is important to know what exactly Stencil does when it builds a theme. What contents are there, in the ZIP file? How exactly they differ from the original source? How Stencil generates them? Can we interfere in the process?

When we know, in detail, the structure of the built theme, we can troubleshoot issues more efficiently, we have more alternatives of development, and we can manage and toggle between a theme’s repository and its corresponding ZIP format comfortably, with confidence.

These files and folders are copied from source into the theme’s “zip” file, unchanged:

• assets/**/*
• CHANGELOG.md
• config.json
• .eslintrc
• .eslintignore
• Gruntfile.js
• karma.conf.js
• lang/*
• meta/**/*
• package.json
• README.md
• .scss-lint.yml
• stencil.conf.js
• templates/**/*
• webpack.conf.js

Some files and folders from inside the “assets” folder are not included, according to these patterns:

• !assets/cdn/**
• !assets/**/*.js.map
• !assets/jspm_packages/**

All these paths are defined at: stencil-cli/lib/stencil-bundle.js ›

Before actually “building” the remaining of the output, two tasks are performed:

• Theme validation: it checks for required files (schema.json, config.json, etc), checks the size of the theme, checks the size of each individual image file (there is a limit!), and a bunch of other things.
• ESLint: it runs JavaScript linting using “ESLint”; the lint configuration is taken from the theme itself (.eslintrc and .eslintignore files)

These happen at: stencil-cli/lib/bundle-validator.js ›

After passing in these two validations, the core of the build begins.

The build is done through five tasks:

1. SCSS Parsing
2. Template Parsing
3. Language Files Parsing
4. Theme Schema File Building
5. “Theme task”

What happens in each step:

• Brings all from “assets/scss/*.scss” into “parsed/scss/*.json” (theme, checkout, optimized-checkout, invoice, maintenance)
• Brings all from “templates/**/*.html” into “parsed/templates/{md5(*)}.json” (currently 229 template files; they appear listed at manifest.json)
• Brings all from “lang/*.json” into a single file: “parsed/lang.json” (includes “en”)
• Transforms indented “schema.json” into one-liner “schema.json”
• Brings “assets/js/app.js” to “assets/dist/theme-bundle.main.js” + chunks, through Webpack.

There are a few details worth mentioning:

• Tasks from 1 to 4 (almost all tasks), including the “SCSS parsing”, are done by Stencil; the theme itself does not play a role here, except of providing the source files.
• Surprisingly, the SCSS source is uploaded to BigCommerce uncompiled. Like in Shopify, the SCSS is compiled server-side by BigCommerce store.
• Stencil does compile SCSS to provide the local development functionality. These locally compiled styles serve only for local development. They are not included in the zip!
• In the other hand, except by running ESLint before the build begins, Stencil does not do anything by itself to deal with JavaScript assets!
• At the “Theme task”, Stencil forks a worker process to run theme’s “stencil.conf.js”, and sends a “production” message to it.
• At the theme’s “stencil.conf.js”, there is a “process message listener”, which runs Webpack when the “production” message arrives.
• The main point here is: the bundling of the JavaScript assets is completely — 100% — determined by code in the theme. It is up to the theme to do (or don’t do) anything (or nothing). As explained above, Stencil only provides a hook, and does nothing else. It provides a specific hook: a “production” message sent to “stencil.conf.js”.
• Cornerstone’s “stencil.conf.js” reads Webpack configuration and runs it to bundle the JS assets (when “production” message arrives).
• It is at Cornerstone’s Webpack configuration which “assets/js/app.js” is defined as entry point, and “assets/dist/theme-bundle.main.js” as the output file. Chunks are also saved in the same “assets/dist” folder. It’s worth looking at “webpack.config.js” for more details.

There is a sixth task which runs after the previous five have been completed:

Manifest File Building

It generates a “manifest.json” file with two “mappings”:

• One specifying which “regions” are using which templates
• A listing of all template file paths

The current Cornerstone theme has 229 template files.

Need help building your BigCommerce Stencil theme?