Skip to content
Nerden's Docs

BigCommerce Stencil Theme Development with Docker (Windows)

This guide will help you set up a development environment for BigCommerce Stencil themes on a Windows machine using Docker Desktop. We will containerize the Stencil CLI (BigCommerce’s theme development toolkit) with Node.js, enable live reloading for efficient theme development, and integrate Tailwind CSS and React into a Stencil theme. Using Docker ensures a consistent Node environment and avoids common setup issues on Windows (Dockerizing BigCommerce’s Stencil CLI | by Aglensmith | BigCommerce Developer Blog | Medium).

1. Installing Docker Desktop on Windows

Section titled “1. Installing Docker Desktop on Windows”

Follow these steps to install Docker Desktop on Windows:

  1. Download Docker Desktop: Visit the official Docker site and download the Docker Desktop Installer for Windows (Docker provides an installer .exe) (Install Docker Desktop on Windows Home | Docker Documentation).
  2. Run the Installer: Double-click the downloaded installer and follow the prompts. Enable WSL2 integration when prompted during setup (Install Docker Desktop on Windows Home | Docker Documentation) (this ensures better performance and file system compatibility).
  3. Finish Installation: Complete the installation wizard and close it when done (Install Docker Desktop on Windows Home | Docker Documentation).
  4. Start Docker Desktop: Launch Docker Desktop from the Start menu (search for “Docker Desktop”). Wait until the Docker whale icon in the system tray stops spinning and becomes stable, indicating Docker is running (Install Docker Desktop on Windows Home | Docker Documentation).
  5. Verify Installation: Open a new terminal (PowerShell or Command Prompt) and run docker --version to confirm Docker is installed and responding.

Note: WSL2 (Windows Subsystem for Linux 2) is highly recommended for Docker on Windows. It provides a Linux kernel and file system features that Docker uses for performance. Docker Desktop will handle enabling WSL2 if you selected that option. (On Windows Home, WSL2 is required (Install Docker Desktop on Windows Home | Docker Documentation).) Using WSL2 will also allow file change notifications to propagate into containers, which is important for live reload (more on this below).

2. Setting up a Docker Container with Node.js and Stencil CLI

Section titled “2. Setting up a Docker Container with Node.js and Stencil CLI”

Next, we’ll create a Docker container that has Node.js and the BigCommerce Stencil CLI installed, and use it to develop your theme.

2.1 Prepare Your Theme Files

Section titled “2.1 Prepare Your Theme Files”

Make sure you have a BigCommerce Stencil theme on your machine. If you don’t have one yet, you can use BigCommerce’s base theme (Cornerstone) as a starting point. For example, you can download or clone the Cornerstone theme from BigCommerce’s repository. Place the theme files in a directory on your computer (e.g., C:\BigCommerce\cornerstone). This directory will be mounted into the Docker container for development.

2.2 Create a Dockerfile for Stencil CLI

Section titled “2.2 Create a Dockerfile for Stencil CLI”

In your theme directory, create a file named Dockerfile with the following content:

# Use official Node.js (LTS) image as the base
FROM node:18


# Set working directory in container
WORKDIR /theme


# Install BigCommerce Stencil CLI globally
RUN npm install -g @bigcommerce/stencil-cli


# (Optional) Expose ports used by Stencil CLI
EXPOSE 3000 3001 3002

This Dockerfile uses the Node.js 18 image (which is supported by Stencil CLI (stencil-cli/Dockerfile at master · bigcommerce/stencil-cli · GitHub)) and installs the Stencil CLI globally inside the container. We expose port 3000 (the default preview port) and additional ports 3001, 3002 for BrowserSync (live reload) as needed (Hot reload not working with Bigcommerce/Stencil on docker - Stack Overflow).

Why containerize Stencil CLI? The Stencil CLI requires specific Node versions and dependencies, which can be tricky to manage on your host system. By using a Docker container, we isolate those requirements. This makes it easier to get started and avoids Node environment conflicts (Dockerizing BigCommerce’s Stencil CLI | by Aglensmith | BigCommerce Developer Blog | Medium).

2.3 Build the Docker Image

Section titled “2.3 Build the Docker Image”

Open a terminal in the directory where your Dockerfile (and theme) is located, and run the build command:

Terminal window
docker build -t bigcommerce-stencil .

This builds a Docker image named bigcommerce-stencil using the Dockerfile in the current directory. (The -t flag tags the image with a name for easy reference (Dockerizing BigCommerce’s Stencil CLI | by Aglensmith | BigCommerce Developer Blog | Medium).)

2.4 Initialize the Stencil CLI in the Container

Section titled “2.4 Initialize the Stencil CLI in the Container”

Before running the theme server, we need to configure the Stencil CLI for your BigCommerce store and install theme dependencies:

  1. Install Theme Dependencies: Ensure your theme’s Node dependencies are installed (like webpack, etc. used by the theme). You can do this on your host machine by running npm install in your theme directory, or you can do it inside the container. If you prefer doing it in Docker (to avoid installing Node on your host), we’ll handle it in the next step.

  2. Run Container in Interactive Mode: Start a container with an interactive shell, mounting your theme directory into the container, so we can run initialization commands. Use the following command:

    Terminal window
    # If using PowerShell, use ${PWD} for current directory. In Command Prompt, use %cd%.
    docker run -it -v "${PWD}:/theme" -p 3000:3000 -p 3001:3001 -p 3002:3002 bigcommerce-stencil /bin/bash

    Explanation: -it runs an interactive TTY, -v "${PWD}:/theme" mounts the current host directory into the container’s /theme directory, and -p 3000:3000 -p 3001:3001 -p 3002:3002 forwards the container’s ports to your host (Dockerizing BigCommerce’s Stencil CLI | by Aglensmith | BigCommerce Developer Blog | Medium). After this command, you will be inside the container’s bash shell (the prompt should change to something like root@<container_id>:/theme#). The /theme directory in the container is now synced with your theme files on the host.

  3. Install Dependencies in Container (if not done on host): If you didn’t run npm install on the host, you can do it now inside the container. In the container shell, run:

    Terminal window
    npm install

    This installs the theme’s npm packages inside the container (with the node_modules stored on your host via the mounted volume).

  4. Initialize Stencil: Still inside the container shell, run the Stencil initialization:

    Terminal window
    stencil init

    This command will prompt you for your BigCommerce store details (Store URL, username, API token, etc.) and generate a .stencil file with your configuration (Dockerizing BigCommerce’s Stencil CLI | by Aglensmith | BigCommerce Developer Blog | Medium). Follow the prompts:

    • You will need your store’s API credentials (go to your BigCommerce control panel to get a Stencil API token and the store hash/URL).
    • The .stencil file is saved in your theme directory (on host and container) and contains the URL and access credentials for live preview.

  5. Exit the Container: After stencil init completes, type exit in the container shell to stop and exit the container for now (Dockerizing BigCommerce’s Stencil CLI | by Aglensmith | BigCommerce Developer Blog | Medium). Your image is built and your theme is configured. We will run the server next.

3. Running the Development Server with Live Reload (Hot Reloading)

Section titled “3. Running the Development Server with Live Reload (Hot Reloading)”

With Docker set up and your theme initialized, you can run the Stencil development server inside the container. This will serve your BigCommerce storefront locally and watch for changes to reload automatically (hot reloading via BrowserSync).

3.1 Start the Stencil Server in Docker

Section titled “3.1 Start the Stencil Server in Docker”

From your host machine (in the theme directory), run the following command to start the container and launch the Stencil CLI server:

Terminal window
docker run -it -v "${PWD}:/theme" -p 3000:3000 -p 3001:3001 -p 3002:3002 bigcommerce-stencil stencil start

This will start the BigCommerce Stencil server inside the container and attach your terminal to its output. The stencil start command will build your theme assets and serve a live preview of your store (Dockerizing BigCommerce’s Stencil CLI | by Aglensmith | BigCommerce Developer Blog | Medium) (Hot reload not working with Bigcommerce/Stencil on docker - Stack Overflow). You should see log output ending with something like “Server running at: http://localhost:3000” and “BrowserSync is watching files…”.

Now open your web browser to http://localhost:3000. You should see your BigCommerce store front-end loading with your theme, powered by the local Stencil server (Using npm and React to Customize Your Theme | BigCommerce Dev Center). The Stencil CLI proxies to your live store for data, but uses your local theme files for templates and assets.

3.2 Live Reload in Action

Section titled “3.2 Live Reload in Action”

Try editing a template file (for example, change some text in one of the HTML/Handlebars templates in the templates/ folder) or a CSS/SCSS file in your theme. When you save the file, the Stencil server should detect the change, recompile assets if needed, and automatically refresh the browser. This is handled by BrowserSync which watches the files for changes and injects updates or reloads the page.

If the browser does not refresh automatically, you can type rs in the terminal where Stencil is running and press Enter to force a manual reload (this is a feature of the Stencil CLI’s live server, similar to Nodemon’s restart command) (GitHub - bigcommerce/stencil-cli: BigCommerce Stencil emulator for local theme development).

Important: On Windows, file system events might not propagate to the container if you’re using a mounted Windows filesystem with the older Hyper-V backend. For reliable hot-reloading, ensure Docker is using the WSL2 backend. Without WSL2, changes in mounted files may not trigger reloads due to missing file change notifications from the Windows FS (Hot Reload on Docker Desktop Windows - Docker Hub - Docker Community Forums). With Docker Desktop using WSL2 (Docker Desktop 3.2+ on Windows 10/11), this issue is resolved and live reload should work properly (Hot Reload on Docker Desktop Windows - Docker Hub - Docker Community Forums).

You can keep the stencil start process running as you develop. When you make changes to your theme files on the host, the container will pick them up (since the volume is mounted) and the live preview will update.

To stop the development server, press Ctrl+C in the terminal, which will stop the stencil start process and thereby stop the container (since we ran it interactively).

4. Integrating Tailwind CSS and React in a Stencil Theme

Section titled “4. Integrating Tailwind CSS and React in a Stencil Theme”

Modern frontend tools like Tailwind CSS and React can be used within a BigCommerce Stencil theme to enhance development and the user experience. Below are instructions to integrate both into your theme’s workflow. These steps assume you have the Stencil development environment from above up and running.

Note: The following steps should be done in your theme’s directory (on the host, which is synced to the container). You can make these changes using your code editor on Windows. The next time you run stencil start (in Docker), the new configuration will take effect.

4.1 Integrating Tailwind CSS

Section titled “4.1 Integrating Tailwind CSS”

BigCommerce’s Stencil uses Webpack and Sass for asset compilation, which we can extend to include Tailwind CSS (a utility-first CSS framework). The strategy is to use PostCSS with Tailwind to generate a CSS file that gets included in the theme.

Step 1: Install Tailwind and build tools – In your theme directory, install Tailwind CSS and the necessary Webpack loaders/plugins via npm:

Terminal window
npm install -D tailwindcss postcss-loader autoprefixer css-loader style-loader

This installs the Tailwind CSS package and related tools: the PostCSS loader, Autoprefixer (to automatically add vendor prefixes), and Webpack loaders for CSS (css-loader and style-loader) (GitHub - rodionpavlenko25/bigcommerce-cornerstone-tailwindcss-integration).

Step 2: Initialize Tailwind configuration – Still in the theme directory, generate a Tailwind config file by running:

Terminal window
npx tailwindcss init

This will create a tailwind.config.js file. Open this file and configure the content paths to include all of your theme templates and scripts, so Tailwind can tree-shake unused styles. For example, in tailwind.config.js set:

module.exports = {
    content: ['./templates/**/*.html', './templates/**/*.hbs', './assets/js/**/*.js'],
    theme: {
        extend: {},
    },
    plugins: [],
};

The above ensures Tailwind scans all .html/.hbs template files and .js files for class names (GitHub - rodionpavlenko25/bigcommerce-cornerstone-tailwindcss-integration), which is important for purging unused CSS in production builds.

Step 3: Configure PostCSS – Create a file named postcss.config.js in the root of your theme directory with the following content:

module.exports = {
    plugins: {
        tailwindcss: {},
        autoprefixer: {},
    },
};

This tells PostCSS to use Tailwind CSS and Autoprefixer as plugins (GitHub - rodionpavlenko25/bigcommerce-cornerstone-tailwindcss-integration).

Step 4: Update Webpack for Tailwind – Modify your theme’s Webpack configuration to process Tailwind CSS. Open the file webpack.common.js (in the theme’s build scripts, usually located in the root or a config folder) and add a rule to handle CSS files with PostCSS. For example, you can add a new rule in the module.rules array:

{
  test: /\.css$/,
  use: [
    'style-loader',
    'css-loader',
    'postcss-loader', // process CSS with PostCSS (Tailwind)
  ],
},

This instructs Webpack to use the style-loader and css-loader to bundle CSS, and then pipe it through postcss-loader (which will apply our postcss.config.js) for any imported .css files (GitHub - rodionpavlenko25/bigcommerce-cornerstone-tailwindcss-integration). (The theme’s existing SCSS pipeline will remain for Sass files; this rule is specifically for plain CSS files like the one we’ll create for Tailwind.)

Step 5: Create Tailwind CSS entry – Create a new CSS file that will serve as the entry point for Tailwind’s utilities. For example, create a file at assets/css/tailwind.css with the following content:

assets/css/tailwind.css
@tailwind base;
@tailwind components;
@tailwind utilities;

These lines include Tailwind’s base styles, components, and utilities into this CSS file. Next, include this CSS in your theme’s main JS bundle so that Webpack knows to process it. In your main JavaScript file (e.g., assets/js/app.js), add an import at the top:

// Import Tailwind CSS so Webpack processes it
import '../css/tailwind.css';

By importing this file in JS, Webpack will apply the rule we set up and run the CSS through Tailwind/PostCSS, outputting the generated styles into the final theme bundle (GitHub - rodionpavlenko25/bigcommerce-cornerstone-tailwindcss-integration).

Now you are ready to use Tailwind classes in your templates. You can add Tailwind utility classes in your theme’s templates and Sass files (Tailwind will generate the corresponding CSS). For example, you might add <div class="tw-bg-blue-500 ..."> (if you prefixed classes with tw-) or just Tailwind classes directly if no prefix. By default, Tailwind will generate lots of utility classes; the purge content config we set will ensure the final CSS only includes the classes you actually use in the content paths.

Step 6: Run the build – Restart your development server (stencil start via Docker as described earlier). Tailwind CSS will be processed as part of the build. You should see Tailwind’s styles applied on your storefront. If you add new Tailwind classes in your templates, you might need to restart the npm run tailwind watcher or simply restart the stencil server to regenerate the CSS (depending on your setup). In our simple integration, Webpack is handling it on each build, so just saving changes and allowing BrowserSync to refresh should reflect new styles.

Tip: Tailwind’s default configuration might conflict with existing Cornerstone styles. Some developers choose to prefix Tailwind classes (e.g., using a tw- prefix in the Tailwind config) to avoid naming collisions with existing CSS. This can be set in the tailwind.config.js (e.g., prefix: 'tw-') (GitHub - TrellisCommerce/bigcommerce-tailwind-starter-base: BigCommerce Cornerstone theme with Tailwind CSS & Prettier integrations) if needed.

4.2 Integrating React

Section titled “4.2 Integrating React”

You can enhance your BigCommerce theme with React for dynamic interactive components. Since Stencil uses Webpack and Babel, you can incorporate React components and bundle them into your theme’s JS. Below are the steps to add React:

Step 1: Install React and Babel packages – In your theme directory, install React, ReactDOM, and the Babel preset for React (plus a helper plugin):

Terminal window
npm install --save react react-dom
npm install --save-dev @babel/preset-react @babel/plugin-transform-object-assign

This will add React and ReactDOM to your project (for building UI components) and set up Babel to transform JSX syntax. The @babel/preset-react allows Babel to compile JSX and other React syntax, and plugin-transform-object-assign is a polyfill plugin often needed for older browser support (as recommended by BigCommerce) (Using npm and React to Customize Your Theme | BigCommerce Dev Center).

Step 2: Update Webpack/Babel config – Configure Babel to use the React preset. Open webpack.common.js (or wherever Babel loader options are defined). Locate the Babel loader configuration (it might have presets like @babel/preset-env already). Add the React preset to Babel. For example, your Babel config section might look like:

{
  test: /\.js$/,
  exclude: /node_modules/,
  use: {
    loader: 'babel-loader',
    options: {
      presets: [
        ['@babel/preset-env', {/* existing options */}],
        '@babel/preset-react'  // add this line to enable JSX/React transform
      ],
      plugins: [
        ... // other plugins
        '@babel/plugin-transform-object-assign'  // include if not already present
      ]
    }
  }
}

This ensures Babel will transpile React JSX code into standard JS that works in browsers (Using npm and React to Customize Your Theme | BigCommerce Dev Center) (Using npm and React to Customize Your Theme | BigCommerce Dev Center). If there’s a presets array, simply include '@babel/preset-react'. If BigCommerce’s Cornerstone already included a similar entry (in their docs it’s shown as '@babel/react' shorthand (Using npm and React to Customize Your Theme | BigCommerce Dev Center)), ensure it’s there.

Step 3: Create a React component – Decide where in your storefront you want a React component. For example, you might want a special interactive widget in the header or a product list. Create a directory for your React components, e.g., assets/js/components/. Then create a component file, for example HelloWidget.js:

assets/js/components/HelloWidget.js
import React from 'react';


export default function HelloWidget() {
    return <div className='hello-widget'>Hello from React!</div>;
}

You can create multiple components as needed, and even use libraries or UI frameworks by installing them via npm (as shown with Material-UI in BigCommerce’s example) (Using npm and React to Customize Your Theme | BigCommerce Dev Center).

Step 4: Import and render the component – Open your main JavaScript entry file (commonly assets/js/app.js in Stencil themes). Import React, ReactDOM, and your new component at the top of the file, then render the component into a DOM element:

import React from 'react';
import ReactDOM from 'react-dom';
import HelloWidget from './components/HelloWidget';


// ... other existing imports


// At the bottom of the file or wherever appropriate:
ReactDOM.render(<HelloWidget />, document.getElementById('hello-widget'));

This will mount our HelloWidget React component into an element with the ID “hello-widget” (Using npm and React to Customize Your Theme | BigCommerce Dev Center).

Step 5: Add a container element in HTML – Finally, add a placeholder element in your theme’s HTML for the React component to hook into. For example, if you want this widget in the storefront header, open the appropriate template (e.g., templates/layout/base.html or a specific component template) and add a <div> with the ID used above:

<div id="hello-widget"></div>

Place this in the HTML where you want the React component’s output to appear (it could be in base.html body, or a specific page template) (Using npm and React to Customize Your Theme | BigCommerce Dev Center). In our example, we might put it in base.html just before the closing </body> or wherever it fits the layout.

Now, rebuild or restart your stencil server (stencil start). When you load the site at localhost:3000, the React component will be initialized and should display “Hello from React!” where you placed the container div. You can now develop your React component further – any changes to the React component code will trigger Webpack to rebuild the JS bundle (and BrowserSync to reload the page), similar to other JS changes.

Step 6: Verify and refine – Check the browser console for any errors. If you see a Babel error, ensure that your webpack config changes to include the React preset are correct and that you restarted the dev server after making config changes. Once it’s working, you can use React freely to build more complex interactive features. Keep in mind that the entire React app you build will be part of the theme’s JS bundle, so use it judiciously (for example, for isolated widgets or complex interactions on specific pages). BigCommerce’s example uses React to build a coupon drawer component with Material-UI (Using npm and React to Customize Your Theme | BigCommerce Dev Center) (Using npm and React to Customize Your Theme | BigCommerce Dev Center) – you can take a similar approach for your needs.

With these steps, you have a full-fledged development environment for BigCommerce themes on Windows using Docker, along with modern tools like Tailwind CSS and React integrated into your Stencil workflow. You can now develop your theme with the confidence that your environment is consistent and easily reproducible. Happy coding!

Sources: