Architecture Overview

Cold Steel's BigCommerce implementation is built on the Stencil theme framework with extensive customizations.

Platform: BigCommerce Stencil

Stencil Framework

• Version: Stencil CLI 8.10.5
• Template Engine: Handlebars
• Frontend Framework: Foundation 5.5.3
• Module System: ES6 with Webpack

Theme Base

• Name: Elevate by Above & Beyond Web Design
• Version: 1.9.21 (config), 1.7.45 (package.json)
• License: MIT
• Author: Above & Beyond Web Design ([email protected])
• Documentation: https://clients.abpages.com/index.php?rp=/knowledgebase/18/Elevate

CSS Architecture

Preprocessor

• SCSS (Sass) compilation
• Autoprefixer with browser targets: > 1%, last 2 versions, Firefox ESR
• Autoprefixer Cascade: Enabled

Structure

assets/scss/
├── theme.scss           # Main entry point
├── settings/            # SCSS variables
├── tools/               # Mixins and functions
├── utilities/           # Utility classes
├── components/          # Component styles
├── layouts/             # Layout-specific styles
├── coldsteel/           # Custom Cold Steel styles
├── elevate/             # Elevate theme styles
├── checkout.scss        # Checkout page styles
├── optimized-checkout.scss
└── vendor/              # Third-party styles

Theme Settings

• Highly customizable via schema.json (1000+ lines of configuration)
• Google Fonts integration (Montserrat, Saira, Roboto Slab, Teko, etc.)
• Color scheme system with primary, secondary, and accent colors
• Typography controls for headings, body text, and special elements

JavaScript Architecture

Entry Points

// webpack.common.js
entry: {
    main: './assets/js/app.js',           // Main application
    head_async: ['lazysizes'],             // Critical async scripts
    polyfills: './assets/js/polyfills.js', // Browser polyfills
}

Module System

• ES6 Modules with dynamic imports for code splitting
• Babel transpilation for browser compatibility
• Tree-shaking with Lodash plugin
• Lazy loading for page-specific modules

Core Libraries

{
  "jquery": "3.5.1",
  "foundation-sites": "5.5.3",
  "@bigcommerce/stencil-utils": "5.0.3",
  "lodash": "4.17.21",
  "swiper": "11.2.10",
  "slick-carousel": "1.8.1",
  "sweetalert2": "9.15.3",
  "@fancyapps/fancybox": "3.5.7"
}

Template Architecture

Handlebars Templates

templates/
├── layout/
│   └── base.html              # Master layout
├── pages/
│   ├── home.html              # Homepage
│   ├── category.html          # Category listing
│   ├── product.html           # Product detail
│   ├── cart.html              # Shopping cart
│   └── ...
├── components/
│   ├── common/                # Shared components
│   ├── elevate/               # Theme-specific
│   ├── coldsteel/             # Custom Cold Steel
│   ├── products/              # Product components
│   └── cart/                  # Cart components
└── coldsteel/
    └── components/            # Additional custom components

Widget Regions (manifest.json)

Elevate theme defines custom widget regions for BigCommerce Page Builder:

• header_bottom--global (global across site)
• header_bottom (page-specific)
• {page}_below_header
• {page}_below_content
• Per-page regions for: brands, blog, cart, category, product, etc.

State Management

Page Context

BigCommerce injects page context via {{inject}} helpers:

window.BCData = {
    cartId: '...',
    channelId: 1,
    productId: 123,
    storeHash: 'abc123',
    storefrontToken: '...',
    product_attributes: {...}
}

Stencil Utils API

Wrapper for BigCommerce REST APIs:

• utils.api.cart - Cart operations
• utils.api.product - Product data
• utils.api.productAttributes - Variant selection
• AJAX-based for dynamic updates without page reload

Data Flow

User Interaction
    ↓
jQuery Event Handler
    ↓
Stencil Utils API Call
    ↓
BigCommerce REST API
    ↓
Response Processing
    ↓
DOM Update (Template Re-render or Partial Update)

Asset Pipeline

Development

1. Source files in assets/js/ and assets/scss/
2. Webpack watches for changes (stencil.conf.js)
3. Babel transpiles JS
4. SCSS compiles to CSS
5. Assets output to assets/dist/
6. Stencil CLI serves with hot reload

Production

1. npm run build - Webpack production build
2. stencil bundle - Package theme as ZIP
3. Upload to BigCommerce Theme Marketplace or store
4. BigCommerce serves assets via CDN with {{cdn}} helper

Performance Optimizations

Code Splitting

// Dynamic imports per page type
const pageClasses = {
    category: () => import('./theme/category'),
    product: () => import('./theme/product'),
    cart: () => import('./theme/cart'),
    // ... only loads what's needed
};

Lazy Loading

• Images: Lazysizes library with LQIP (Low Quality Image Preview)
• Below-fold content: Intersection Observer API
• Modal content: Loaded on demand

Bundle Analysis

• Webpack Bundle Analyzer plugin
• Generates report.html showing bundle composition
• Helps identify large dependencies

CDN Integration

All assets served via BigCommerce CDN:

{{cdn 'assets/dist/theme-bundle.main.js'}}
{{cdn 'assets/scss/theme.css'}}

Benefits:

• Global edge network
• Automatic cache invalidation on deploy
• Reduced origin server load

Custom Extensions

SUMA Integration

• File: assets/js/suma.js (minified Preact app)
• Purpose: Custom UI components built with Preact
• Integration: Loaded in base layout, available globally

Cold Steel Modules

assets/js/theme/coldsteel/
├── swiper.js              # Custom Swiper configurations
└── components/
    └── sezzle.js          # Sezzle payment widget

Elevate Modules

assets/js/theme/elevate/
├── elevatecustom.js       # Theme-specific customizations
├── jquery.min.js          # jQuery copy
└── slick.min.js           # Slick carousel

Engraving System

Complete custom engraving tool with:

• Canvas-based image manipulation
• Real-time preview
• Font rendering
• API integration with GSM Outdoors engraving service

See Engraving Tool for full documentation.

API Integrations

BigCommerce APIs

• Storefront API (GraphQL) - Token: window.storefrontApiToken
• REST API - Via Stencil Utils
• Widgets API - Page Builder integration

Third-Party APIs

• GSM Outdoors Engraving API - Custom engraving
• Klaviyo API - Email marketing (company ID: TmN6vh)
• Klarna API - Financing widget
• Sezzle API - Financing widget

Browser Support

Targets defined in package.json:

{
  "autoprefixer_browsers": [
    "> 1%",
    "last 2 versions",
    "Firefox ESR"
  ]
}

Polyfills included:

• core-js for ES6+ features
• whatwg-fetch for Fetch API
• regenerator-runtime for async/await
• focus-within-polyfill for :focus-within CSS
• object-fit-images for object-fit CSS

Security

Content Security

• CSRF protection enabled (theme feature)
• BigCommerce handles PCI compliance
• HTTPS enforced

API Authentication

• Storefront API token scoped to read-only operations
• Store hash used for API requests
• No sensitive credentials in client-side code

SEO Features

• Schema.org markup for products (itemscope itemtype="http://schema.org/Product")
• Semantic HTML structure
• Lazy-loaded images with proper alt text
• Breadcrumb navigation
• Sitemap generation

Accessibility

• ARIA labels and roles
• Keyboard navigation support
• Focus management for modals
• Screen reader-friendly markup
• WCAG AAA guidelines targeted (per theme documentation)