Development Setup

Complete guide to setting up a local development environment for the Baits BigCommerce theme.

Prerequisites

Required Software

Node.js: Version 20 (specified in .nvmrc)
npm: v8+ (comes with Node.js)
Git: For version control
Code Editor: VS Code, WebStorm, or Sublime Text

Optional Tools

nvm (Node Version Manager): Manage multiple Node versions
BigCommerce Store: Access to store for testing
Stencil CLI: Installed globally or via npx

Initial Setup

1. Clone Repository

# Clone from repository
git clone <repository-url> baits
cd baits

Or use existing local repository:

cd Z:\Repos\baits

2. Install Node.js

Using nvm (Recommended)

# Install nvm (if not installed)
# Windows: Download from https://github.com/coreybutler/nvm-windows
# Mac/Linux: curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash

# Use Node version from .nvmrc
nvm install
nvm use

# Verify version
node --version  # Should show v20.x.x

Direct Installation

Download Node.js v20 from https://nodejs.org/

3. Install Dependencies

npm install

This installs:

Dependencies: Runtime libraries (jQuery, Swiper, etc.)
DevDependencies: Build tools (Webpack, Babel, Grunt, etc.)

Note: Initial install may take 2-5 minutes depending on connection speed.

4. Configure Stencil CLI

Install Stencil CLI

Already included in package.json dependencies.

Verify installation:

npx stencil --version
# Should show 8.10.4 or similar

Initialize Stencil

npx stencil init

You'll be prompted for:

Store URL: Your BigCommerce store URL (e.g., https://store-abc123.mybigcommerce.com)
API Token: Stencil API token from BigCommerce control panel
Port: Local development port (default: 3000)

Getting API Token:

Log into BigCommerce control panel
Go to Advanced Settings > API Accounts
Create API Account:
- Name: Stencil CLI
- OAuth Scopes:
  - store_v2_content - modify
  - store_v2_information - read-only
Copy Access Token (shown once)

Configuration File: .stencil (gitignored)

{
    "normalStoreUrl": "https://store-abc123.mybigcommerce.com",
    "port": 3000,
    "username": "stencil",
    "token": "your-api-token-here",
    "customLayouts": {}
}

5. Build Assets

# Development build
npm run buildDev

# Or production build
npm run build

Outputs to assets/dist/:

theme-bundle.main.js
theme-bundle.head_async.js
theme-bundle.font.js
theme-bundle.polyfills.js
Source maps (.map files)

Development Workflow

Starting Development Server

npx stencil start

Or use the alias:

npm start  # If configured in package.json

Server starts on: http://localhost:3000

Features:

Live Reload: Auto-refresh on file changes
Store Data: Syncs with live BigCommerce store
HTTPS: SSL certificate for secure testing
BrowserSync: Synchronized browser testing

Development Process

Start Server: npx stencil start
Open Browser: Navigate to http://localhost:3000
Make Changes: Edit files in assets/, templates/, etc.
Auto-Reload: Browser refreshes automatically
Test: Verify changes work as expected
Build: Run npm run build when ready
Commit: Git commit your changes

File Watching

Stencil CLI watches for changes in:

Templates: templates/**/*.html
Sass: assets/scss/**/*.scss
JavaScript: assets/js/**/*.js (requires rebuild)
Config: config.json, schema.json
Lang: lang/**/*.json

Note: JavaScript changes require manual Webpack rebuild (npm run buildDev).

Development Commands

Build Commands

# Development build (fast, with source maps)
npm run buildDev

# Production build (minified, optimized)
npm run build

# Bundle theme for upload
npm run bundle

Code Quality

# Lint Sass
npm run stylelint

# Fix Sass issues automatically
npm run stylelint:fix

# Lint JavaScript
grunt eslint

# Default Grunt task (ESLint + SVG sprites)
grunt

Theme Management

# Start development server
npx stencil start

# Download current theme from store
npx stencil download

# Push theme to store
npx stencil push

# Bundle theme
npx stencil bundle

# Release theme (production)
npx stencil release

Project Structure

Key Directories

Z:\Repos\baits\
├── assets/                 # All asset files
│   ├── dist/              # Compiled JavaScript (gitignored)
│   ├── icons/             # SVG icons for sprite
│   ├── img/               # Image assets
│   ├── js/                # Source JavaScript
│   │   ├── theme/
│   │   │   ├── baits/    # Custom Baits modules
│   │   │   ├── cart/
│   │   │   ├── common/
│   │   │   ├── global/
│   │   │   ├── product/
│   │   │   └── roots/
│   │   ├── app.js        # Main entry point
│   │   └── polyfills.js
│   ├── lib/               # Third-party libraries
│   ├── scss/              # Sass stylesheets
│   │   ├── baits/        # Custom Baits styles
│   │   ├── common/
│   │   ├── components/
│   │   ├── layouts/
│   │   ├── roots/
│   │   ├── settings/
│   │   └── theme.scss    # Main Sass entry
│   └── slideout-variant-selector/  # React module
├── config/                # Grunt task configs
├── lang/                  # Translation files
│   └── en.json           # English translations
├── meta/                  # Theme metadata
├── templates/             # Handlebars templates
│   ├── components/
│   │   ├── baits/        # Custom Baits components
│   │   ├── cart/
│   │   ├── common/
│   │   ├── products/
│   │   └── ...
│   ├── layout/
│   │   └── base.html     # Master layout
│   └── pages/
│       ├── home.html
│       ├── product.html
│       ├── category.html
│       └── ...
├── .eslintrc              # ESLint configuration
├── .nvmrc                 # Node version specification
├── .stylelintrc           # Stylelint configuration
├── CHANGELOG.md           # Version history
├── config.json            # Theme configuration
├── Gruntfile.js          # Grunt task runner
├── package.json          # Dependencies and scripts
├── README.md             # Theme documentation
├── schema.json           # Theme settings schema
├── webpack.common.js     # Webpack base config
├── webpack.dev.js        # Development config
└── webpack.prod.js       # Production config

Gitignored Files

.stencil                  # Local Stencil config (API tokens)
secrets.stencil.json      # Store secrets
config.stencil.json       # Stencil store config
node_modules/             # Dependencies
assets/dist/              # Compiled JavaScript
.DS_Store                 # Mac OS files
Thumbs.db                 # Windows files

Making Changes

Modifying Templates

Edit Handlebars files in templates/:

{{!-- templates/pages/product.html --}}
<div class="productPage">
    <h1>{{product.title}}</h1>
    <p>{{product.description}}</p>
</div>

Auto-reload: Immediate browser refresh

Modifying Styles

Edit Sass files in assets/scss/:

// assets/scss/baits/_custom.scss
.productView {
    &-title {
        font-size: 2rem;
        color: $brand-primary;
    }
}

Auto-reload: Stencil recompiles and refreshes

Modifying JavaScript

Edit JS files in assets/js/:

// assets/js/theme/baits/custom-feature.js
export default class CustomFeature {
    constructor() {
        this.init();
    }
    
    init() {
        console.log('Custom feature initialized');
    }
}

Manual rebuild required: Run npm run buildDev

Adding Custom Baits Features

Create JS module: assets/js/theme/baits/new-feature.js
Create Sass file: assets/scss/baits/_new-feature.scss

Import in page class:

import NewFeature from './baits/new-feature';

export default class Product extends PageManager {
    onReady() {
        new NewFeature();
    }
}

Import styles: Add to assets/scss/theme.scss:
```
@import "baits/new-feature";
```
Rebuild: npm run buildDev
Test: Verify functionality in browser

Testing

Browser Testing

Test in multiple browsers:

Chrome: Primary development browser
Firefox: Standards compliance
Safari: Mac/iOS compatibility
Edge: Windows compatibility

Use BrowserSync for synchronized testing:

# Stencil start includes BrowserSync
npx stencil start

# Open multiple browser windows
# All sync scroll, clicks, form inputs

Device Testing

Test responsive design:

Chrome DevTools:
- Open DevTools (F12)
- Click device icon (or Ctrl+Shift+M)
- Select device or custom dimensions
Real Devices:
- iPhone (Safari)
- Android (Chrome)
- Tablet (iPad, Android tablet)
BrowserStack (if available):
- Test on real devices remotely
- Multiple OS/browser combinations

Accessibility Testing

# Run Lighthouse audit
npm run lighthouse

Or in Chrome DevTools:

Open DevTools
Go to Lighthouse tab
Check Accessibility
Click Generate report

Manual Testing:

Keyboard Navigation: Tab through site
Screen Reader: NVDA (Windows), JAWS, VoiceOver (Mac)
Color Contrast: WebAIM Contrast Checker

Performance Testing

# Lighthouse performance audit
npm run lighthouse

Metrics to Check:

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

Cart & Checkout Testing

Test critical e-commerce flows:

Add to Cart: Product → Add to Cart → Cart Preview
Cart Page: Update quantities, remove items, apply coupons
Checkout: Complete order (use test mode)
Payment: Test payment methods (test card: 4111 1111 1111 1111)
Order Confirmation: Verify order details

Debugging

Browser DevTools

Console: View errors and logs

console.log('Debug message');
console.error('Error message');
console.table(data);  // Tabular data view

Network: Monitor requests

Filter by type (JS, CSS, Img)
Check response status
Inspect headers and payload

Sources: Debug JavaScript

Set breakpoints
Step through code
Inspect variables
Edit and reload

Source Maps

Development builds include source maps for easier debugging:

// Compiled code in assets/dist/theme-bundle.main.js
// Source maps point to original files in assets/js/

Browser shows original source files, not compiled bundles.

Common Issues

Stencil Start Fails

Error: Port 3000 is already in use

Solution:

# Kill process on port 3000
npx kill-port 3000

# Or use different port
npx stencil start --port 3001

JavaScript Not Updating

Problem: Changes don't appear in browser

Solution:

Rebuild: npm run buildDev
Hard refresh: Ctrl+Shift+R (Chrome)
Clear cache: DevTools > Network > Disable cache

Sass Compilation Error

Error: Undefined variable: $color-primary

Solution: Check variable imports in theme.scss:

// Must import settings before using variables
@import "settings/colors";
@import "settings/global";

// Then import components
@import "components/buttons";

Template Not Found

Error: Error: template not found: components/custom/my-component.html

Solution: Check file path and case sensitivity:

{{!-- Correct --}}
{{> components/custom/my-component}}

{{!-- Wrong (missing .html is OK, Handlebars adds it) --}}
{{> components/custom/My-Component}}

Deployment

Push to Store

Test theme on live store without activating:

npx stencil push

Options:

-a or --activate: Activate theme immediately
-c CHANNEL or --channel=CHANNEL: Push to specific channel
-d or --delete: Delete oldest unpublished theme if limit reached

Example:

# Push and activate
npx stencil push --activate

# Push to specific channel
npx stencil push --channel mobile

Upload via Control Panel

Bundle theme:
```
npm run bundle
```
Login to BigCommerce:
- Go to Storefront > My Themes
Upload:
- Click Upload Theme
- Select .zip file from project root
- Wait for processing
Activate:
- Click Apply on uploaded theme
- Confirm activation

Version Control

Commit changes regularly:

# Stage changes
git add .

# Commit with message
git commit -m "feat: Add slideout variant selector"

# Push to remote
git push origin main

Commit Message Format:

feat: New feature
fix: Bug fix
style: CSS/formatting changes
refactor: Code restructuring
docs: Documentation updates
test: Test additions/changes
chore: Build process, dependencies

Environment-Specific Settings

Development Environment

// Check if in development
if (window.location.hostname === 'localhost') {
    console.log('Development mode');
}

Production Environment

// Production optimizations
if (process.env.NODE_ENV === 'production') {
    // Disable console logs
    console.log = () => {};
}

Set via Webpack mode:

// webpack.prod.js
mode: 'production'  // Sets process.env.NODE_ENV

Best Practices

Code Organization

Modular: Keep files focused and single-purpose
Naming: Use descriptive, consistent names
Comments: Explain "why", not "what"
DRY: Don't Repeat Yourself - reuse code

Performance

Optimize Images: Compress before adding
Lazy Load: Use Lazysizes for images
Code Splitting: Dynamic imports for large modules
Minimize Dependencies: Only include needed libraries
Bundle Size: Keep under 300KB per bundle

Version Control

Commit Often: Small, focused commits
Descriptive Messages: Explain what and why
Branch Strategy: Feature branches for new work
Pull Before Push: Avoid merge conflicts

Testing

Cross-Browser: Test all major browsers
Mobile First: Start with mobile, scale up
Real Devices: Test on actual phones/tablets
Accessibility: Keyboard and screen reader testing

Resources

Documentation

BigCommerce Stencil: https://developer.bigcommerce.com/stencil-docs/
Roots Theme: https://themesupport.weizenyoung.com/help/roots-theme-manual
Handlebars: https://handlebarsjs.com/
Webpack: https://webpack.js.org/
Sass: https://sass-lang.com/

Support

Theme Support: [email protected]
BigCommerce Support: https://support.bigcommerce.com/
Developer Community: https://developer.bigcommerce.com/community

Tools

VS Code Extensions:
- Handlebars (syntax highlighting)
- ESLint (linting)
- Stylelint (Sass linting)
- GitLens (Git visualization)
- Prettier (code formatting)
Chrome Extensions:
- Lighthouse (auditing)
- React Developer Tools (if using React components)
- Redux DevTools (if using Redux)
- WAVE (accessibility evaluation)

Troubleshooting

Get Help

Check Console: Browser DevTools console for errors
Check Logs: Stencil CLI output for build errors
Search Documentation: BigCommerce and Roots docs
Ask Support: Contact theme or platform support
Community: BigCommerce developer forums

Common Error Solutions

Error	Solution
`Module not found`	`rm -rf node_modules && npm install`
`Port already in use`	`npx kill-port 3000` or use different port
`Stencil init fails`	Check API token and permissions
`Template syntax error`	Check Handlebars syntax, closing tags
`Undefined variable`	Import settings before use in Sass
`JavaScript not loading`	Rebuild with `npm run buildDev`
`Out of memory`	Increase Node memory: `NODE_OPTIONS=--max-old-space-size=4096`

Debug Mode

Enable verbose logging:

# Stencil with debug output
DEBUG=* npx stencil start

# Webpack with progress
npx webpack --config webpack.dev.js --progress --profile

Advanced Setup

Docker Development (Optional)

Theme includes Docker configuration:

# Start Docker container
npm start

# Access container shell
npm run bash

Dockerfile (if exists):

FROM node:20
WORKDIR /opt/stencil
COPY package*.json ./
RUN npm install
COPY . .
EXPOSE 3000
CMD ["npx", "stencil", "start"]

Multi-Store Setup

Manage multiple stores:

# Initialize with different config files
npx stencil init --config .stencil-store1
npx stencil init --config .stencil-store2

# Start specific store
npx stencil start --config .stencil-store1

Continuous Integration

Automate testing and deployment with CI/CD:

GitHub Actions (.github/workflows/build.yml):

name: Build and Test

on: [push, pull_request]

jobs:
  build:
    runs-on: ubuntu-latest
    
    steps:
      - uses: actions/checkout@v2
      
      - name: Setup Node.js
        uses: actions/setup-node@v2
        with:
          node-version: '20'
      
      - name: Install dependencies
        run: npm ci
      
      - name: Lint
        run: |
          grunt eslint
          npm run stylelint
      
      - name: Build
        run: npm run build
      
      - name: Bundle
        run: npm run bundle
      
      - name: Upload artifact
        uses: actions/upload-artifact@v2
        with:
          name: theme-bundle
          path: ./*.zip

Quick Reference

Essential Commands

# Setup
npm install                  # Install dependencies
npx stencil init            # Configure Stencil CLI

# Development
npx stencil start           # Start dev server
npm run buildDev            # Build JavaScript (dev)
npm run build               # Build JavaScript (prod)

# Code Quality
grunt eslint                # Lint JavaScript
npm run stylelint           # Lint Sass
npm run stylelint:fix       # Fix Sass issues

# Deployment
npm run bundle              # Create theme bundle
npx stencil push            # Push to store
npx stencil push --activate # Push and activate

File Locations

JavaScript: assets/js/theme/baits/
Sass: assets/scss/baits/
Templates: templates/components/products/baits/
Compiled JS: assets/dist/
Config: .stencil, config.json, schema.json

URLs

Local Dev: http://localhost:3000
Store Admin: https://store-abc123.mybigcommerce.com/manage
Theme Docs: https://themesupport.weizenyoung.com/help/roots-theme-manual

Prerequisites​

Required Software​

Optional Tools​

Initial Setup​

1. Clone Repository​

2. Install Node.js​

Using nvm (Recommended)​

Direct Installation​

3. Install Dependencies​

4. Configure Stencil CLI​

Install Stencil CLI​

Initialize Stencil​

5. Build Assets​

Development Workflow​

Starting Development Server​

Development Process​

File Watching​

Development Commands​

Build Commands​

Code Quality​

Theme Management​

Project Structure​

Key Directories​

Gitignored Files​

Making Changes​

Modifying Templates​

Modifying Styles​

Modifying JavaScript​

Adding Custom Baits Features​

Testing​

Browser Testing​

Device Testing​

Accessibility Testing​

Performance Testing​

Cart & Checkout Testing​

Debugging​

Browser DevTools​

Source Maps​

Common Issues​

Stencil Start Fails​

JavaScript Not Updating​

Sass Compilation Error​

Template Not Found​

Deployment​

Push to Store​

Upload via Control Panel​

Version Control​

Environment-Specific Settings​

Development Environment​

Production Environment​

Best Practices​

Code Organization​

Performance​

Version Control​

Testing​

Resources​

Documentation​

Support​

Tools​

Troubleshooting​

Get Help​

Common Error Solutions​

Debug Mode​

Advanced Setup​

Docker Development (Optional)​

Multi-Store Setup​

Continuous Integration​

Quick Reference​

Essential Commands​

File Locations​

URLs​

Prerequisites

Required Software

Optional Tools

Initial Setup

1. Clone Repository

2. Install Node.js

Using nvm (Recommended)

Direct Installation

3. Install Dependencies

4. Configure Stencil CLI

Install Stencil CLI

Initialize Stencil

5. Build Assets

Development Workflow

Starting Development Server

Development Process

File Watching

Development Commands

Build Commands

Code Quality

Theme Management

Project Structure

Key Directories

Gitignored Files

Making Changes

Modifying Templates

Modifying Styles

Modifying JavaScript

Adding Custom Baits Features

Testing

Browser Testing

Device Testing

Accessibility Testing

Performance Testing

Cart & Checkout Testing

Debugging

Browser DevTools

Source Maps

Common Issues

Stencil Start Fails

JavaScript Not Updating

Sass Compilation Error

Template Not Found

Deployment

Push to Store

Upload via Control Panel

Version Control

Environment-Specific Settings

Development Environment

Production Environment

Best Practices

Code Organization

Performance

Version Control

Testing

Resources

Documentation

Support

Tools

Troubleshooting

Get Help

Common Error Solutions

Debug Mode

Advanced Setup

Docker Development (Optional)

Multi-Store Setup

Continuous Integration

Quick Reference

Essential Commands

File Locations

URLs