BigCommerce Development

intermediate

Local development for BigCommerce storefronts.

Overview

Node.js is a JavaScript runtime built on Chrome's V8 engine that enables server-side JavaScript execution, originally created by Ryan Dahl in 2009 to address the limitations of traditional web servers in handling concurrent connections. Its event-driven, non-blocking I/O model makes it particularly well-suited for building scalable network applications and has become the backbone of modern web development toolchains. This BigCommerce development environment leverages Node.js to power local storefront development, providing developers with the runtime needed to execute BigCommerce's Stencil CLI, manage npm dependencies, and run development servers for both traditional Stencil themes and modern headless commerce applications. The combination addresses the complexity of setting up BigCommerce development environments by containerizing the Node.js runtime with pre-configured environment variables for store authentication and API access. Frontend developers working on BigCommerce storefronts, agencies building custom themes for multiple clients, and teams developing headless commerce solutions will find this stack valuable for its ability to isolate BigCommerce projects, maintain consistent development environments across team members, and simplify the onboarding process for new developers joining BigCommerce projects.

Key Features

Node.js 20 Alpine Linux base for lightweight container footprint and latest JavaScript features
Pre-configured BigCommerce API authentication via environment variables for store hash, access tokens, and client ID
Hot reload development server on port 3000 with automatic file watching for Stencil theme changes
Volume mounting for persistent storefront code changes between container restarts
BigCommerce Stencil CLI compatibility for theme development, bundling, and store synchronization
GraphQL Storefront API integration for headless commerce implementations
REST API access for comprehensive BigCommerce resource management including products, orders, and customers
npm ecosystem access for BigCommerce-specific packages and modern frontend tooling

Common Use Cases

1Developing custom Stencil themes for BigCommerce stores with live preview capabilities
2Building headless commerce applications using BigCommerce as a backend API
3Agency workflows requiring isolated development environments for multiple client stores
4Team collaboration on BigCommerce projects with consistent Node.js runtime versions
5Prototyping BigCommerce integrations and testing API endpoints before production deployment
6Educational environments for learning BigCommerce development without local Node.js installation
7CI/CD pipelines for automated BigCommerce theme testing and deployment

Prerequisites

BigCommerce store with API access and generated store hash from the control panel
BigCommerce API credentials including access token and client ID with appropriate scopes
Docker Engine 20.10+ and Docker Compose V2 for container orchestration
Minimum 512MB RAM allocation for Node.js runtime and development server
Port 3000 available on host system for development server access
Basic understanding of BigCommerce Stencil templating system and Handlebars.js

For development & testing. Review security settings, change default credentials, and test thoroughly before production use. See Terms

docker-compose.yml

1services: 
2  bigcommerce-app: 
3    image: node:20-alpine
4    container_name: bigcommerce-app
5    restart: unless-stopped
6    working_dir: /app
7    command: npm run dev
8    environment: 
9      BIGCOMMERCE_STORE_HASH: ${STORE_HASH}
10      BIGCOMMERCE_ACCESS_TOKEN: ${ACCESS_TOKEN}
11      BIGCOMMERCE_CLIENT_ID: ${CLIENT_ID}
12    volumes: 
13      - ./storefront:/app
14    ports: 
15      - "3000:3000"

.env Template

.env

1STORE_HASH=your-store-hash
2ACCESS_TOKEN=your-access-token
3CLIENT_ID=your-client-id

Usage Notes

1Docs: https://developer.bigcommerce.com/docs/
2Development server at http://localhost:3000
3Get store hash and API tokens from BigCommerce control panel
4Stencil CLI for theme development: npm install -g @bigcommerce/stencil-cli
5REST API for products, orders, customers, carts
6GraphQL Storefront API for headless commerce builds

Quick Start

terminal

1# 1. Create the compose file
2cat > docker-compose.yml << 'EOF'
3services:
4  bigcommerce-app:
5    image: node:20-alpine
6    container_name: bigcommerce-app
7    restart: unless-stopped
8    working_dir: /app
9    command: npm run dev
10    environment:
11      BIGCOMMERCE_STORE_HASH: ${STORE_HASH}
12      BIGCOMMERCE_ACCESS_TOKEN: ${ACCESS_TOKEN}
13      BIGCOMMERCE_CLIENT_ID: ${CLIENT_ID}
14    volumes:
15      - ./storefront:/app
16    ports:
17      - "3000:3000"
18EOF
19
20# 2. Create the .env file
21cat > .env << 'EOF'
22STORE_HASH=your-store-hash
23ACCESS_TOKEN=your-access-token
24CLIENT_ID=your-client-id
25EOF
26
27# 3. Start the services
28docker compose up -d
29
30# 4. View logs
31docker compose logs -f

One-Liner

Run this command to download and set up the recipe in one step:

terminal

1curl -fsSL https://docker.recipes/api/recipes/bigcommerce-dev/run | bash

Troubleshooting

EADDRINUSE error on port 3000: Kill existing processes with 'lsof -ti:3000 | xargs kill -9' or change the port mapping
BigCommerce API 401 Unauthorized responses: Verify STORE_HASH, ACCESS_TOKEN, and CLIENT_ID environment variables match your BigCommerce control panel settings
Stencil CLI bundle command fails: Ensure your storefront directory contains a valid .stencil configuration file and package.json
Node modules installation errors: Delete node_modules and package-lock.json, then restart container to trigger fresh npm install
Hot reload not working for theme changes: Check that volume mounting path ./storefront matches your local directory structure
GraphQL Storefront API queries returning empty results: Confirm your access token has Storefront API scope enabled in BigCommerce settings

Community Notes

Loading notes...

Download Recipe Kit

Get all files in a ready-to-deploy package

Includes docker-compose.yml, .env template, README, and license

Components

node

Related Recipes

Ad Space

Shortcuts: C CopyF FavoriteD Download