Skip to main content

Development Setup

Complete guide for setting up a local development environment for the Cold Steel BigCommerce theme.

Prerequisites​

Required Software​

Node.js & npm​

Verify installation:

node --version  # Should show v14.x.x or higher
npm --version   # Should show 6.x.x or higher

BigCommerce Stencil CLI​

npm install -g @bigcommerce/[email protected]

Verify installation:

stencil --version  # Should show 8.10.5

Git​

BigCommerce Store Requirements​

  1. Store Access

    • Admin account with Developer or Store Owner permissions
    • Store must be on a plan that supports Stencil (Standard or higher)

  2. API Credentials

    • Store API account with Themes scope
    • Available in: Advanced Settings → API Accounts

Repository Setup​

Clone Repository​

# Navigate to your projects directory
cd Z:\Repos

# Clone the repository
git clone [repository-url] coldsteel.com

# Navigate into directory
cd coldsteel.com

Install Dependencies​

# Install all npm packages
npm install

This will install:

  • BigCommerce Stencil CLI
  • Webpack and build tools
  • JavaScript dependencies (jQuery, Foundation, Swiper, etc.)
  • Development dependencies (Babel, ESLint, Grunt)

Expected time: 2-5 minutes depending on internet speed.

Stencil Configuration​

Initialize Stencil​

stencil init

You'll be prompted for:

  1. Store URL: https://your-store.mybigcommerce.com

    • Your BigCommerce store URL
    • Can be sandbox or production

  2. Access Token: Your API access token

    • From Advanced Settings → API Accounts
    • Should have Themes scope

  3. Port: Default 3000

    • Port for local development server
    • Press Enter to use default

This creates .stencil file with your store credentials.

Configuration Files​

After initialization, you should have:

coldsteel.com/
├── .stencil                    # API credentials (DO NOT COMMIT)
├── secrets.stencil.json        # Secret configuration (DO NOT COMMIT)
├── config.stencil.json         # Theme settings
└── stencil.conf.js             # Build configuration

Secrets Configuration​

If using custom API endpoints (like engraving API), create secrets.stencil.json:

{
  "engraving_api_key": "your-api-key-here",
  "engraving_api_url": "https://engraving-test.gsmoutdoors.com"
}

Important: Never commit .stencil or secrets.stencil.json to version control!

Local Development​

Start Development Server​

stencil start

This will:

  1. Compile assets with Webpack (development mode)
  2. Start local server at http://localhost:3000
  3. Enable hot reloading for template changes
  4. Watch for file changes

Output:

Compiled with warnings in 5432 ms

✔ Development Server Started
  URL: http://localhost:3000
  Store: https://your-store.mybigcommerce.com
  SSL: Enabled

Access Local Site​

Open http://localhost:3000 in your browser.

Features:

  • Live reload on template changes
  • HTTPS with self-signed certificate (you'll see a security warning - this is normal)
  • Connected to your BigCommerce store's data
  • Full e-commerce functionality

Development Workflow​

1. Template Development​

Edit Handlebars templates:

templates/
├── pages/product.html
├── components/elevate/header.html
└── ...

Changes are detected automatically and trigger reload.

2. JavaScript Development​

Edit JS modules:

assets/js/
├── app.js
├── theme/
│   ├── product.js
│   └── ...
└── ...

Webpack watches for changes and recompiles automatically.

3. Style Development​

Edit SCSS files:

assets/scss/
├── theme.scss
├── components/
└── ...

SCSS compiles to CSS automatically on save.

Hot Reloading​

Automatic Reload For:

  • Template changes (.html files)
  • JavaScript changes (.js files)
  • Style changes (.scss files)

Requires Manual Refresh:

  • Configuration changes (config.json)
  • Schema changes (schema.json)
  • Language changes (lang/ files)

Building Assets​

Development Build​

npm run buildDev

Creates development bundles:

  • Non-minified code
  • Source maps included
  • Faster compilation

Output: assets/dist/

Production Build​

npm run build

Creates optimized production bundles:

  • Minified JavaScript
  • Optimized CSS
  • Removed console logs
  • Tree-shaking applied

Bundle Analysis​

To analyze bundle sizes:

npm run build

Opens report.html showing:

  • Bundle composition
  • Size of each module
  • Dependency tree
  • Opportunities for optimization

Testing​

JavaScript Tests​

npm test

Runs Jest test suite (if configured).

Linting​

JavaScript Linting​

npx grunt eslint

Checks JavaScript files against ESLint rules.

SCSS Linting​

npx grunt scsslint

Checks SCSS files for style violations.

Run All Checks​

npx grunt

Runs: ESLint, Jest, SCSS Lint, SVG Store

Git Workflow​

Branch Strategy​

# Create feature branch
git checkout -b feature/engraving-updates

# Make changes and commit
git add .
git commit -m "Add engraving font options"

# Push to remote
git push origin feature/engraving-updates

Before Committing​

  1. Lint your code

    npx grunt eslint
    npx grunt scsslint

  2. Build assets

    npm run build

  3. Test on local store

    stencil start
    # Manually test changes

Deploying Changes​

Bundle Theme​

stencil bundle

Creates Cold Steel - [version].zip ready for upload.

Push to Store​

stencil push

Uploads theme to BigCommerce:

  1. Prompts for theme name
  2. Asks if it should be applied immediately
  3. Uploads ZIP file
  4. Theme becomes available in BigCommerce admin

Options:

# Push without applying
stencil push

# Push and apply immediately
stencil push --activate

# Push to specific store
stencil push --store your-store-hash

Upload via Admin​

Alternatively, upload manually:

  1. Run stencil bundle
  2. Go to Storefront → Themes in BigCommerce admin
  3. Click Upload Theme
  4. Select ZIP file
  5. Click Apply when ready

Debugging​

Enable Console Logging​

Development mode includes console logging:

// Automatically enabled in development
if (isDevelopment()) {
    console.log('Debug information');
}

Handlebars Debugging​

View page context:

{{#debug}}{{this}}{{/debug}}

Or specific variables:

{{#debug product}}{{/debug}}

Stencil CLI Debug Mode​

stencil start --verbose

Shows detailed logging:

  • File changes detected
  • Compilation times
  • API requests
  • Error stack traces

Browser DevTools​

Use browser DevTools to inspect:

  • Network requests
  • Console errors
  • Element styles
  • JavaScript execution

BigCommerce Logs​

Check store logs:

  • Settings → Store Logs
  • Shows API errors, theme errors, webhook failures

Environment Variables​

.env File (Optional)​

Create .env for local overrides:

STENCIL_CLI_PORT=3000
NODE_ENV=development
ENGRAVING_API_URL=https://engraving-test.gsmoutdoors.com

Environment Detection​

Code can detect environment:

const isDevelopment = () => {
    return window.location.hostname.includes('localhost') ||
           window.location.hostname.includes('loca.lt') ||
           window.location.hostname.includes('-sandbox.mybigcommerce.com');
};

Common Issues​

Port Already in Use​

Error: EADDRINUSE: address already in use :::3000

Solution:

# Use different port
stencil start --port 3001

SSL Certificate Warning​

Error: "Your connection is not private"

Solution: This is normal for local development. Click "Advanced" → "Proceed to localhost".

Module Not Found​

Error: Cannot find module 'lodash'

Solution:

# Delete node_modules and reinstall
rm -rf node_modules
npm install

Stencil CLI Won't Start​

Solution:

# Reinstall Stencil CLI globally
npm uninstall -g @bigcommerce/stencil-cli
npm install -g @bigcommerce/[email protected]

# Re-initialize
stencil init

Webpack Compilation Errors​

Solution:

# Clear webpack cache
rm -rf assets/dist
npm run buildDev

API Authentication Errors​

Solution:

  1. Verify API account in BigCommerce admin
  2. Check token has Themes scope
  3. Re-run stencil init with correct credentials

IDE Setup​

Install extensions:

  • Handlebars by Tobermory
  • ESLint by Microsoft
  • SCSS IntelliSense by mrmlnc
  • GitLens by GitKraken
  • Prettier by Prettier

VS Code Settings​

.vscode/settings.json:

{
  "editor.formatOnSave": true,
  "editor.codeActionsOnSave": {
    "source.fixAll.eslint": true
  },
  "files.associations": {
    "*.html": "handlebars"
  },
  "scss.lint.unknownAtRules": "ignore"
}

EditorConfig​

.editorconfig (if not present, create):

root = true

[*]
charset = utf-8
indent_style = space
indent_size = 4
end_of_line = lf
insert_final_newline = true
trim_trailing_whitespace = true

[*.{json,yml}]
indent_size = 2

[*.md]
trim_trailing_whitespace = false

Documentation Resources​

Next Steps​

After setup:

  1. Review Architecture documentation
  2. Understand Theme Customizations
  3. Explore Engraving Tool implementation
  4. Study Build Process
  5. Review Integrations