Skip to content
Tutorials Center
My learning

Topics

Lesson 3 of 28 ยท Getting Started

Setting Up a Development Environment

Set up for BigCommerce development: a sandbox store, an API account, Stencil CLI, Node versions, curl or Postman, and safe handling of secrets in env files.

A good development setup makes everything else in this course easier, and a careless one is how tokens end up on GitHub. In this lesson you prepare four things: a sandbox store to experiment on, an API account that gives you credentials, the Stencil CLI for theme work, and a safe place to keep secrets.

All of the steps that touch BigCommerce happen in your browser or terminal and are shown read-only here. The runnable part is a small Node.js validator that checks an environment file the way a well-behaved script should before it makes any request. The validator is our own stand-in code, not part of any BigCommerce tool.

A sandbox store

Never test on a merchant's live store. Create a separate store for development: a trial store or a developer sandbox, depending on what BigCommerce offers when you sign up (the sign-up flow and trial rules change, so follow the current instructions on the developer site). You want a store where you can create a hundred test products, place test orders and delete everything without anybody noticing.

Good sandbox habits:

  • Name it clearly (for example "dev-yourname") so you never confuse it with a client store.
  • Add a handful of sample products with variants, a couple of categories and a test customer. Many lessons later assume you have these.
  • Enable a test payment mode so you can place test orders. Do this from the control panel's payment settings, and never reuse a real payment method.
  • Keep one sandbox per project when projects might change global settings.

API accounts and the store hash

To call the APIs on your sandbox you create an API account in the control panel (under the advanced settings, in the API accounts section). You choose a name and the OAuth scopes (permissions) and BigCommerce shows the credentials once: a client id, a client secret and an access token. Lesson 2010, API Accounts, Tokens and Scopes, explains scopes in detail. For now remember two facts: the token is shown only at creation, and your store hash is part of the API path shown on that screen.

You will end up with three values that every script needs:

TEXT
BC_STORE_HASH=abc123xyz
BC_ACCESS_TOKEN=<token shown once at creation>
BC_API_BASE=https://api.bigcommerce.com/stores/abc123xyz

Tools you need

  • Node.js and npm. The Stencil CLI and most BigCommerce JavaScript tooling run on Node. The CLI supports specific Node versions, and the supported range changes over time, so read the CLI's current requirements before installing. A version manager such as nvm (or fnm) lets you switch versions per project.
  • Git. Themes and apps live in repositories.
  • A way to send HTTP requests. curl for quick checks and Postman or a similar client for exploring. In code, Node's built-in fetch is enough.
  • Stencil CLI. Installed globally from npm (read-only):
Terminal
npm install -g @bigcommerce/stencil-cli
stencil --version

The CLI's commands (stencil init, stencil start, stencil bundle, stencil push) are covered in Stencil CLI and the Cornerstone Theme. For apps, you also create an account on the BigCommerce Developer Portal; see App Types and the OAuth Flow.

Your first request

With the variables exported in your shell, this call (read-only) checks that your credentials work. It asks for a single product:

Terminal
curl -s "$BC_API_BASE/v3/catalog/products?limit=1" \
  -H "X-Auth-Token: $BC_ACCESS_TOKEN" \
  -H "Accept: application/json"

A 200 with a data array means success. A 401 means the token is wrong or missing. A 403 means the token is valid but lacks the scope for that endpoint. A 404 can mean a wrong store hash or path. Learn these four outcomes; they solve most day-one problems.

Keeping secrets out of your code

An access token is a password to a store. Treat it like one:

  1. Put secrets in a .env file (or your host's secret manager) and never commit it. Add .env and, for Stencil, the .stencil file to .gitignore. The .stencil file created by stencil init can hold a token.
  2. Commit a .env.example with the names but without values, so teammates know what to set.
  3. Read configuration once at start-up, validate it, and fail fast with a clear message.
  4. Never print tokens in logs, and never put them in URLs. Use the header.
  5. Use a separate API account per project, with the smallest scopes needed. If a token leaks, you revoke only that account.

For the wider picture of why shops get attacked through leaked keys, see Shop Security Basics.

flowchart LR
    E[".env file<br/>(not in git)"] --> L["Load at start-up"]
    L --> V["Validate shape and presence"]
    V -->|"ok"| R["Make API calls"]
    V -->|"problem"| X["Stop with a clear error<br/>(no secret printed)"]

Validate configuration before the first request, and never echo the secret.

A configuration validator

The stand-in below parses an env-file text (like the contents of .env), checks that required names exist, that the store hash and base URL are consistent, and that the token looks plausible, and prints a safe report with the secret masked. Real tokens have no fixed public format, so we only check that it is present, has no spaces and is not a placeholder. Run it, then break the sample text to see the errors.

Node.js Validate a BigCommerce env file

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

The report prints the token with only its first and last two characters visible, so logs stay safe, and the broken sample lists three separate problems at once instead of failing on the first. That "collect all problems" style is friendlier than throwing at the first error.

Choosing the call style

The second stand-in shows how a small API client reads that validated configuration and builds a request, without sending it. This is how most scripts in this course are structured: one place builds URLs and headers, so the token never gets scattered through the code.

Node.js Build requests from validated config

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Observe that query values like name:like are encoded by URLSearchParams, and that the token is hidden whenever a request is described for logging. Both habits will matter when you write the product sync project.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Why use a sandbox store for development?

    Mistakes in development are free on a sandbox and costly on a live store.
  2. 2. A request returns 403 with a valid token. What is the most likely cause?

    401 means unauthenticated, 403 means authenticated but not permitted. Check the API account's scopes.
  3. 3. Which file should be added to .gitignore in a Stencil project because it can hold a token?

    stencil init writes a .stencil file with connection details. Keep it out of version control.
  4. 4. Where does the access token belong in a request?

    URLs end up in logs and browser history. Headers do not, so the token goes in a header.

Summary

  • Develop on a sandbox store with sample data and test payments, never on a live store.
  • An API account gives you the store hash, client credentials and an access token (shown once).
  • Install Node (a version the CLI supports), Git, an HTTP client and the Stencil CLI.
  • Verify credentials with a small GET and learn 200, 401, 403 and 404.
  • Keep secrets in uncommitted env files, validate them at start-up, mask them in logs, and use one API account per project.

Next: API Accounts, Tokens and Scopes