orcaqubits/bc-setup

BigCommerce Development Environment Setup

Before writing code

Fetch live docs:

1. Fetch https://developer.bigcommerce.com/ for the developer center overview
2. Web-search site:developer.bigcommerce.com stencil cli getting started for Stencil CLI setup
3. Web-search bigcommerce sandbox store trial for sandbox/dev store options

Developer Account & Store

Getting Started

• Create a free trial or sandbox store at bigcommerce.com
• Partner/Developer sandbox stores are available through the BigCommerce Partner Program
• Each store has a unique store hash (found in the API path or admin URL)

API Credentials

Create API credentials at Store Admin > Advanced Settings > API Accounts:

• API Path — https://api.bigcommerce.com/stores/{store_hash}/v3/
• Client ID — identifies your application
• Access Token — authenticates API requests (X-Auth-Token header)
• Client Secret — used in OAuth flow for apps
• OAuth scopes control access: products, orders, customers, content, etc.

Stencil CLI

Installation

npm install -g @bigcommerce/stencil-cli

Requires Node.js 18+ and npm.

Initializing a Theme

stencil init

Prompts for:

• Store URL (e.g., https://my-store.mybigcommerce.com)
• API Token (Stencil-CLI scope token)
• Port for local dev server (default 3000)

Stores config in .stencil file (add to .gitignore).

Key Commands

| Command | Description | |---------|-------------| | stencil start | Start local development server with live reload | | stencil bundle | Bundle theme for upload | | stencil push | Push theme to store (with options to activate) | | stencil pull | Download current live theme | | stencil release | Release theme update |

Theme Directory Structure

cornerstone/                 # Default theme (fork this)
├── assets/
│   ├── scss/                # Stylesheets
│   ├── js/                  # JavaScript modules
│   └── img/                 # Static images
├── templates/
│   ├── layout/              # Master layout templates
│   ├── pages/               # Page templates
│   ├── components/          # Reusable partials
│   └── ...
├── lang/                    # Internationalization JSON
├── config.json              # Theme configuration & variations
├── schema.json              # Theme Editor schema
├── package.json             # Node dependencies
└── .stencil                 # Local CLI config (gitignored)

Catalyst (Headless)

Setup

npx create-catalyst-storefront@latest my-store

Creates a Next.js 14+ application pre-configured with:

• BigCommerce GraphQL Storefront API integration
• Product listing, detail, cart, and checkout pages
• Authentication flows
• Tailwind CSS styling

Requires: Node.js 18+, BigCommerce store with Storefront API token.

App Development Setup

Local Tunnel

For OAuth callback during development:

• Use ngrok, cloudflared, or similar tunnel
• Expose local port to a public HTTPS URL
• Set callback URL in Dev Tools Portal

Developer Portal

Register apps at https://devtools.bigcommerce.com/:

• Set OAuth callback URL
• Configure required scopes
• Get Client ID and Client Secret

Environment Variables

Common Variables

BIGCOMMERCE_STORE_HASH=your_store_hash
BIGCOMMERCE_ACCESS_TOKEN=your_access_token
BIGCOMMERCE_CLIENT_ID=your_client_id
BIGCOMMERCE_CLIENT_SECRET=your_client_secret
BIGCOMMERCE_API_URL=https://api.bigcommerce.com/stores/{store_hash}/v3

Store in .env file (add to .gitignore). Never commit credentials.

Best Practices

• Use sandbox/trial stores for development — never develop against production
• Store all credentials in environment variables, never in code
• Add .stencil and .env to .gitignore
• Fork Cornerstone (the default theme) for custom Stencil themes
• Use Catalyst for new headless projects
• Keep Stencil CLI updated: npm update -g @bigcommerce/stencil-cli

Fetch the BigCommerce developer center and Stencil CLI docs for exact setup steps, supported Node.js versions, and current CLI options before setting up.