Create Custom BigCommerce Templates with React in Stencil

Scenario

As a Solution Architect at BigCommerce, I meet clients and agencies who want to incorporate React into their Stencil theme. Maybe you want to utilize your existing component library, or React is just your preferred front-end framework. In some cases, those projects end up going the headless route, where the website’s front-end lives outside of BigCommerce and integrates with BigCommerce APIs to manage catalog data, customer accounts, promotions, carts and even checkout. Other times, we combine React with Stencil so that BigCommerce hosts the front-end. I’ve seen a few approaches to incorporating React into a Stencil theme and each has its pros and cons. This article is intended to be a step-by-step guide to starting custom templates with React in a Stencil theme in a way that is scalable and reusable.

Source: Patrick Puente - Create Custom BigCommerce Templates with React in Stencil

What is React?

React is one of the most popular front-end frameworks available today. It allows developers to build reusable components with a self-contained state which can be composed into complex UIs. There are oodles of tutorials and examples of React available online, so I won’t spend a lot of time explaining it here.

This lab is intended for developers that are already familiar with the basic concepts of React. In this lab, you will create a React component that receives a context prop that contains information from Stencil about the category page, like the products it should display.

The Approach

This example leverages the pattern devised by sacr3dc0w to map a custom template to a custom JavaScript module. In this case, the module extends the PageManager class and uses its onReady method to render React inside of an element in the custom template. The custom template will retrieve information from Stencil utilizing Handlebars, and inject that into a global variable called context that is accessible by the JavaScript module via the PageManager constructor. The JavaScript module in turn passes the page context to React as a prop.

In this example, the actual React component will simply display the text “Hello World” followed by the data from Stencil.

Prerequisites

• Stencil Development Environment & Cloned theme
• BigCommerce Store
• Node and npm
• Stencil CLI
• Cornerstone Theme

Install Dependencies

1. Add React, ReactDOM, and the React preset for Babel to your project

npm install react react-dom @babel/preset-react

Configure Webpack

1. In webpack.common.js, add ['@babel/preset-react'] to modules.rules[0].use.options.presets

This is the presets array from the example:

presets: [
    ['@babel/preset-env', {
        loose: true,
        modules: false,
        useBuiltIns: 'usage',
        targets: '> 1%, last 2 versions, Firefox ESR',
    }],
    ['@babel/preset-react'],
],

See the whole webpack.common.js on github here.

Optional: Add CSS loader

While it’s not required for this example, you will want to also add loaders for CSS files if you intend to add CSS files to your React app, or plan to use a component library that includes CSS modules like React Toolbox. These steps have been tested for React Toolbox:

1. Install Dependencies:

npm install style-loader css-loader

2. Add the following to the modules.rules array in webpack.common.js:

{
    test: /\.css/,
    loader:[ 'style-loader', 'css-loader' ]
}

Create a Custom Template

1. Create a new folder at templates/custom/category

• Windows

mkdir templates\pages\custom\category

• Mac/Linux

mkdir templates/pages/custom/category

The resulting structure of the templates folder should look like this:

templates
∟ components
∟ layout
∟ pages
…
 ∟ custom
   ∟ category
…

2. Copy templates\pages\category.html to the new folder and rename it react-demo.html:

• Windows

copy templates\pages\category.html templates\pages\custom\category\react-demo.html

• Mac/Linux

cp templates/pages/category.html templates/custom/category/react-demo.html

3. In react-demo.html replace everything between {{#partial “page”}} and {{/partial}} with:

{{inject "category" category}}
<div id="root">Hello World!</div>

• The {{inject}} helper adds the category object from Stencil to the page context your custom JavaScript module will be able to access
• The <div> will display “Hello World!” so you can test to validate the template mapping. It will also serve as the mounting point for React

---
category:
    shop_by_price: true
    products:
        limit: {{theme_settings.categorypage_products_per_page}}
---
{{inject "categoryProductsPerPage" theme_settings.categorypage_products_per_page}}
{{#partial "head"}}
    {{#if pagination.category.previous}}
        <link rel="prev" href="{{pagination.category.previous}}">
    {{/if}}
    {{#if pagination.category.next}}
        <link rel="next" href="{{pagination.category.next}}">
    {{/if}}
{{/partial}}
{{#partial "page"}}
    {{inject "category" category}}
    <div id="root">Hello World!</div>
{{/partial}}
{{> layout/base}}

Map the Custom Template in config.stencil

In the project’s config.stencil file, you will map the custom page template file to a category page URL. This is so you can render your custom page template in your local environment. Once the theme is applied to a store, you will need to map specific categories to the template to use your custom template on the live site. For more on applying custom templates, see the BigCommerce documentation.

{
    "normalStoreUrl": "https://<store-domain>",
    "accessToken": "<api-token>",
    "port": 3000,
    "customLayouts": {
      "brand": {},
      "category": {
        "react-demo.html": "/shop-all/"
      },
      "page": {},
      "product": {}
    }
  }

Test the custom template

1. Confirm your template is mapped correctly by starting the local development server with Stencil CLI:

stencil start

2. Navigate to the mapped URL on localhost to ensure your template is rendered. For example: http://localhost:3000/shop-all/
3. You should see the global header and footer, and the text Hello World! in the main content area:

Create a Custom Module

The React app will live in assets\js\theme\custom\react-demo.js. Start by creating the folder.

1. Create a folder named custom

• Windows

mkdir assets\js\theme\custom

• Mac/Linux

mkdir assets/js/theme/custom

2. Create the file react-demo.js

3. In react-demo.js, import React, ReactDOM, and PageManager:

import React from 'react'
import ReactDOM from 'react-dom'
import PageManager from '../page-manager'

4. In react-demo.js, create a simple HelloWorld component that displays its props:

const HelloWorld = (props) => (
    <div>
        <p>Hello World from React!</p>
        <p>Here are my props:</p>
        <pre>{JSON.stringify(props, null, 2)}</pre>
    </div>
)

5. In react-demo.js, export a new child class that extends the PageManager class. This class is responsible for mounting the HelloWorld component in the div in the custom category template, and passing the page context to the component as a prop.

export default class ReactDemo extends PageManager {
    onReady() {
        const container = $('#root')[0]
        ReactDOM.render(<HelloWorld context={this.context}/>, container)
    }
}

Your file should look like this:

import React from 'react'
import ReactDOM from 'react-dom'
import PageManager from '../page-manager'
const HelloWorld = (props) => (
    <div>
        <p>Hello World from React!</p>
        <p>Here are my props:</p>
        <pre>{JSON.stringify(props, null, 2)}</pre>
    </div>
)
export default class ReactDemo extends PageManager {
    onReady() {
        const container = $('#root')[0]
        ReactDOM.render(<HelloWorld context={this.context}/>, container)
    }
}

Map the Custom Module to the Custom Template

1. Add a mapping to the customClasses object in assets/js/app.js

• Since the value of context.template in app.js may vary depending on the environment, the example maps the module to the value provided by both Windows and Mac/Linux environments:

const customClasses = {
    'pages\\custom\\category\\react-demo': () => import('./theme/custom/react-demo'), // Windows
    'pages/custom/category/react-demo': () => import('./theme/custom/react-demo'), // Mac/Linux
};

2. Observe result

• When you visit the category page in your local environment, you should now see a custom category template that renders React, and has access to the category page context supplied by Stencil:

Notice how context.category includes information from Stencil needed to render a product listing page. You could use the {{inject}} helper in templates\pages\custom\category\react-demo.html to add additional information to the page context. Or, you could follow the same pattern to load custom React modules into product, brand, or web pages.