Skip to main content

Architecture Overview

The Baits.com site is built on BigCommerce's Stencil framework using the Roots Theme as a foundation with extensive customizations for the fishing tackle retail market.

Platform: BigCommerce Stencil​

Stencil Framework​

  • Version: Stencil CLI 8.10.4
  • Template Engine: Handlebars v4
  • Base Theme: Cornerstone v6.1.1
  • Theme: Roots Theme v1.7.14 by Weizen Young
  • License: MIT

Theme Philosophy​

The Roots theme is built as a modern, production-ready BigCommerce theme with:

  • Performance-First: Webpack 5 optimization, lazy loading, tree-shaking
  • Mobile-First: Responsive breakpoints starting at mobile
  • Modular Architecture: Component-based templates and JavaScript modules
  • Extensible: Custom feature integration without core modifications
  • E-commerce Focused: Advanced product selectors, filtering, and conversion optimization

CSS Architecture​

Preprocessor​

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

Directory Structure​

assets/scss/
├── theme.scss              # Main entry point
├── settings/               # SCSS variables and configuration
│   ├── _colors.scss
│   ├── _foundation.scss
│   ├── _global.scss
│   └── _typography.scss
├── tools/                  # Mixins and functions
│   ├── _breakpoint.scss
│   ├── _clearfix.scss
│   ├── _grid.scss
│   └── _utilities.scss
├── common/                 # Shared base styles
│   ├── _alerts.scss
│   ├── _forms.scss
│   ├── _icons.scss
│   └── _typography.scss
├── components/             # UI components
│   ├── _buttons.scss
│   ├── _carousel.scss
│   ├── _cards.scss
│   ├── _faceted-search.scss
│   ├── _modals.scss
│   ├── _pagination.scss
│   └── _product-grid.scss
├── layouts/                # Page layout styles
│   ├── _footer.scss
│   ├── _header.scss
│   ├── _navigation.scss
│   └── _sidebar.scss
├── baits/                  # Custom Baits overrides
│   ├── _brand-page.scss
│   ├── _product-page.scss
│   ├── _swiper.scss
│   └── _variant-selector.scss
├── roots/                  # Roots theme specific
└── vendor/                 # Third-party styles
    ├── _foundation.scss
    └── _slick.scss

Responsive Breakpoints​

$screen-small: 551px;
$screen-medium: 801px;
$screen-large: 1261px;
$screen-xlarge: 1441px;

Breakpoint Strategy: Mobile-first with min-width media queries

JavaScript Architecture​

Module System​

  • ES6 Modules with dynamic imports for code splitting
  • Babel transpilation for browser compatibility (@babel/preset-env)
  • Tree-shaking with Lodash plugin for optimized bundle size
  • Lazy loading for page-specific modules

Entry Points​

Defined in webpack.common.js:

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

Core Libraries​

{
  "jquery": "3.6.1",
  "foundation-sites": "5.5.3",
  "@bigcommerce/stencil-utils": "6.15.1",
  "lodash": "4.17.21",
  "swiper": "11.1.15",
  "slick-carousel": "1.8.1",
  "sweetalert2": "9.17.2",
  "lazysizes": "5.2.2"
}

Page-Specific Module Loading​

The theme uses dynamic imports for page-specific JavaScript:

const pageClasses = {
    product: () => import('./theme/product'),
    category: () => import('./theme/category'),
    cart: () => import('./theme/cart'),
    // ... other page types
};

Benefits:

  • Reduces initial bundle size
  • Loads only necessary code per page
  • Improves Time to Interactive (TTI)

Custom Baits Modules​

Located in assets/js/theme/baits/:

baits/
├── reviews.js       # BazaarVoice shadow DOM styling
├── sezzle.js        # Sezzle payment integration
├── swatches.js      # Slideout variant selector initialization
└── swiper.js        # Swiper carousel configurations

Template Architecture​

Handlebars Template Engine​

BigCommerce Stencil uses Handlebars v4 with custom helpers and partials.

Template Hierarchy​

templates/
├── layout/
│   └── base.html              # Master layout
├── pages/
│   ├── home.html
│   ├── product.html           # Product detail page
│   ├── category.html          # Category listing
│   ├── cart.html
│   └── ...
└── components/
    ├── common/
    │   ├── header.html
    │   ├── footer.html
    │   ├── navigation.html
    │   └── breadcrumbs.html
    └── products/
        ├── product-view.html  # Main product display
        ├── card.html          # Product card
        ├── add-to-cart.html
        ├── options/
        │   ├── swatch.html
        │   └── ...
        └── baits/             # Custom Baits templates
            ├── product-main.html
            ├── product-featured.html
            ├── product-related.html
            └── product-reviews.html

Custom Template Overrides​

Baits-specific templates in templates/components/products/baits/ override default behavior:

  • product-main.html: Custom product page layout
  • product-featured.html: Featured products with Swiper carousel
  • product-related.html: Related products carousel
  • product-reviews.html: BazaarVoice integration container
  • product-tabs.html: Custom product information tabs

Handlebars Helpers​

Custom helpers extend template functionality:

{{getImageSrcset image sizes}}
{{#filter collection 'property' value}}
{{#or condition1 condition2}}
{{#unless condition}}
{{cdn path}}
{{lang 'translation.key'}}

Frontend Foundation​

Foundation Framework​

Version: Foundation 5.5.3

The theme uses Foundation's grid system and components:

<div class="container">
    <div class="row">
        <div class="column small-12 medium-6 large-4">
            <!-- Content -->
        </div>
    </div>
</div>

Grid System​

  • 12-column grid
  • Gutter: 20px default
  • Breakpoint-based: small, medium, large, xlarge

Foundation Components Used​

  • Grid system
  • Button styles
  • Form elements
  • Alert boxes
  • Dropdown menus
  • Modals (customized)
  • Tabs (customized)
  • Accordion (for mobile navigation)

Asset Pipeline​

Build Process​

  1. JavaScript: Webpack 5 with Babel transpilation
  2. CSS: Sass compilation with Autoprefixer
  3. Icons: SVG sprite generation with Grunt
  4. Images: Lazy loading with Lazysizes
  5. Fonts: Async loading with WebFont Loader

Output Structure​

assets/dist/
├── theme-bundle.main.js              # Main application
├── theme-bundle.head_async.js        # Lazy image loader
├── theme-bundle.font.js              # Font loader
├── theme-bundle.polyfills.js         # IE11 polyfills
├── theme-bundle.chunk.[name].js      # Dynamic imports
├── theme-bundle.main.js.map          # Source maps
└── ...

Performance Optimizations​

Code Splitting​

  • Dynamic imports for page-specific modules
  • Lazy loading of non-critical JavaScript
  • Tree-shaking to eliminate dead code
  • Minification in production builds

Image Optimization​

// Lazy loading configuration
import 'lazysizes';

// Responsive images in templates
{{> components/common/responsive-img
    image=product.main_image
    lazyload=theme_settings.lazyload_mode
}}

Bundle Analysis​

Webpack Bundle Analyzer generates reports:

npm run build
# Opens bundle analysis in ./assets/dist/report.html

Performance Targets​

  • First Contentful Paint: < 1.5s
  • Time to Interactive: < 3.5s
  • Largest Contentful Paint: < 2.5s
  • Cumulative Layout Shift: < 0.1
  • First Input Delay: < 100ms

Browser Support​

Based on Autoprefixer configuration:

  • > 1% global usage
  • Last 2 versions of major browsers
  • Firefox ESR (Extended Support Release)

Effectively supports:

  • Chrome 90+
  • Firefox 88+
  • Safari 14+
  • Edge 90+
  • iOS Safari 14+
  • Android Chrome 90+

IE11: Partial support with polyfills (being phased out)

State Management​

BigCommerce Context​

Page context injected via window.stencilBootstrap():

window.stencilBootstrap(pageType, contextJSON);

Context includes:

  • Customer data
  • Product information
  • Cart state
  • Category data
  • Theme settings

Custom State​

For complex features like the slideout variant selector:

// Global product options
window.productOptions = [ /* variant data */ ];
window.variantData = [ /* GraphQL variant data */ ];

// Events for communication
document.dispatchEvent(
    new CustomEvent('product/variant-selector/init', { detail })
);

API Integration​

BigCommerce Storefront API​

Accessed via Stencil Utils:

import utils from '@bigcommerce/stencil-utils';

// Add to cart
utils.api.cart.itemAdd(formData, (err, response) => {
    // Handle response
});

// Update cart
utils.api.cart.itemUpdate(itemId, quantity, callback);

// Search
utils.api.search.search(query, params, callback);

GraphQL Storefront API​

Used for variant pricing data:

// Injected via template
const variantData = {{{json product.variants}}};
window.variantData = variantData;

Security​

CSRF Protection​

Enabled in theme features:

"features": [
  "csrf_protection"
]

Content Security Policy​

BigCommerce handles CSP headers for Stencil themes.

Input Sanitization​

  • XSS Prevention: Handlebars auto-escapes output
  • HTML Entities: Use triple braces {{{ }}} only for trusted content
  • Form Validation: Client and server-side validation

Development Workflow​

Local Development​

# Start Stencil development server
stencil start

# Runs on http://localhost:3000
# Live reload on file changes
# Syncs with BigCommerce store

Build Commands​

# Development build
npm run buildDev

# Production build
npm run build

# Bundle for upload
npm run bundle

Code Quality​

# Lint JavaScript
grunt eslint

# Lint Sass
npm run stylelint

# Fix Sass issues
npm run stylelint:fix

Deployment​

Theme Upload​

# Create theme bundle
stencil bundle

# Upload to BigCommerce
# Via control panel: Storefront > My Themes > Upload Theme

Version Control​

  • Git repository: Local version control
  • Branching: Feature branches for development
  • Releases: Tagged versions in CHANGELOG.md

Monitoring & Analytics​

Enhanced E-commerce Tracking​

Theme supports GA4 Enhanced E-commerce:

"features": [
  "enhanced_ecommerce"
]

Data Layer Events​

  • Product impressions
  • Product clicks
  • Add to cart
  • Checkout steps
  • Purchases

Performance Monitoring​

Use Lighthouse for auditing:

npm run lighthouse

Generates JSON report of Core Web Vitals and performance metrics.