# BigCommerce Development

> Local development for BigCommerce storefronts.

- Category: E-Commerce & Business
- Difficulty: intermediate
- Components: node
- Tags: bigcommerce, storefront, development, headless
- Source: https://docker.recipes/ecommerce/bigcommerce-dev

## 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.

## 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

## Use cases

- Developing custom Stencil themes for BigCommerce stores with live preview capabilities
- Building headless commerce applications using BigCommerce as a backend API
- Agency workflows requiring isolated development environments for multiple client stores
- Team collaboration on BigCommerce projects with consistent Node.js runtime versions
- Prototyping BigCommerce integrations and testing API endpoints before production deployment
- Educational environments for learning BigCommerce development without local Node.js installation
- CI/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

## docker-compose.yml

```yaml
services:
  bigcommerce-app:
    image: node:20-alpine
    container_name: bigcommerce-app
    restart: unless-stopped
    working_dir: /app
    command: npm run dev
    environment:
      BIGCOMMERCE_STORE_HASH: ${STORE_HASH}
      BIGCOMMERCE_ACCESS_TOKEN: ${ACCESS_TOKEN}
      BIGCOMMERCE_CLIENT_ID: ${CLIENT_ID}
    volumes:
      - ./storefront:/app
    ports:
      - "3000:3000"
```

## .env

```bash
STORE_HASH=your-store-hash
ACCESS_TOKEN=your-access-token
CLIENT_ID=your-client-id
```

## Usage notes

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

## 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

