Skip to content
Tutorials Center
My learning

Topics

Lesson 21 of 28 ยท Quality and Production

Performance, Security and Launch

Get a BigCommerce app or theme ready for production: theme performance, efficient API use, secrets and CSP, marketplace review, versioning, deployment and monitoring.

Working code is not yet launch-ready code. A theme that scores badly on speed loses sales, an app that wastes API calls hits rate limits on the first big merchant, and one leaked token can expose a whole store. Launch also has a human side: reviewers, versioning, deployments you can undo, and alerts that wake you before customers write angry emails.

This lesson is a checklist you can reason about. It covers theme performance, API efficiency, secrets and Content Security Policy, preparing an app for App Marketplace review, versioning and deployment, and monitoring. The platform cannot run here, so configuration is shown read-only, and the two runnable stand-ins are a secret scanner and a performance-budget check written in Node.js. Their rules are our own simplified ones, not an official tool.

Theme performance

Speed in a storefront comes mostly from sending less and sending it later. A sensible order of attack:

  1. Images. Product photos are the heaviest part of most pages. Stencil's image helper and the platform's image CDN produce resized versions; ask for the size you display, use srcset for different screens, add width and height to avoid layout shift, and lazy-load images below the fold. See Images and Responsive Design for the browser side.
  2. JavaScript. Every script blocks something. Keep the theme bundle lean, load page-specific code only on that page type (Cornerstone already splits by page), and audit third-party tags added through Script Manager: analytics, chat and review widgets often cost more than your whole theme.
  3. CSS. Remove unused components and avoid huge font sets. Two font weights are usually enough.
  4. Render path. Avoid layout work during load, defer non-critical scripts, and preconnect to origins you must use.
  5. Measure real users. Lab tools (Lighthouse) find problems; field data shows what shoppers experience. Watch Largest Contentful Paint, Interaction to Next Paint and Cumulative Layout Shift.

A performance budget turns this into a rule you can automate: "the main script stays under 150 KB compressed, the largest image under 200 KB". A build that exceeds the budget fails, so slowness cannot creep in unnoticed.

API efficiency

Apps pay for inefficiency twice: in latency and in rate limits (see Orders, Customers and the V2/V3 Split for backoff). The big wins:

  • Fetch less. Use include_fields, filters and limit so you ask only for what you need, as in The Catalog API (V3).
  • Batch. One batch write of ten products beats ten single writes.
  • Avoid N+1. Loading a list and then calling the API once per row is the most common mistake. Use id:in filters or include to get related data in one call.
  • Cache with care. Catalog data changes rarely; cache it for minutes and invalidate on webhooks. Never cache per-customer prices without including the customer in the key.
  • Do heavy work later. Return 200 to a webhook quickly and process in a queue; a slow handler causes retries and eventually deactivation.
  • Respect limits. Read the rate-limit headers the API returns and slow down before you are refused.

Secrets and Content Security Policy

An app handles several secrets: the client secret of the app, each store's access token, webhook signing material, and your own database and cloud credentials. Rules that prevent most disasters:

  • Secrets live in environment variables or a secret manager, never in the repository, in front-end bundles or in logs.
  • Use separate secrets per environment and rotate them when a person leaves or a leak is suspected.
  • Give each API account the fewest scopes it needs (API Accounts, Tokens and Scopes).
  • Never log full request headers or token values; log store hashes and request IDs.
  • Run a secret scanner in CI so a pasted key fails the build. Shop Security lists the wider habits.

For storefront pages, a Content Security Policy (CSP) limits where scripts, styles and frames may load from, which blunts cross-site scripting. BigCommerce lets you manage a store-level CSP, and apps that inject scripts or iframes must work inside it. A policy is a header such as this one (read-only, example values):

TEXT
Content-Security-Policy: default-src 'self'; script-src 'self' https://cdn.example.com; img-src 'self' data: https://cdn.example.com; frame-ancestors 'self'

Roll a new policy out in report-only mode first, read the violations, then enforce it. For apps shown inside the control panel, remember that the platform embeds your page in an iframe, so your own frame-ancestors setting must allow the control panel and nothing else.

flowchart LR
    C["Code change"] --> L["Lint, tests,<br/>secret scan"]
    L --> B["Budgets:<br/>bundle size, images"]
    B --> S["Sandbox<br/>smoke test"]
    S --> R["Release<br/>(versioned)"]
    R --> M["Monitor:<br/>errors, latency,<br/>webhook failures"]
    M -->|"regression"| RB["Roll back"]

Every gate on the way to production is automated; rollback is part of the plan.

A secret scanner

This stand-in scans text for strings that look like secrets: long values assigned to names such as token, secret or password, and a few well-known key shapes. Everything is invented and the rules are deliberately simple, so a real scanner will find more and also report different false positives. It prints the line number and masks the value, because a scanner that prints secrets is itself a leak.

Node.js Scan files for leaked secrets

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 scanner flags two lines and passes process.env reads and the empty .env.example template, which is exactly the pattern you want: names of variables in the repository, values elsewhere. If a real secret was ever committed, deleting it is not enough. Revoke and replace it, because it remains in the history.

Performance budgets

The second stand-in checks measured sizes against budgets, the way a CI step would after a build. The numbers are invented. It sets a hard limit per asset type, compares, prints a table and decides whether the build passes.

Node.js Fail the build when a performance budget is broken

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.

Two budgets are broken, so the build fails. The value of this check is the conversation it forces: either optimize the CSS and the page, or raise a budget on purpose and write down why.

App Marketplace readiness

If you plan to list an app on the BigCommerce App Marketplace, the app goes through a review. Review rules and forms change, so always read the current requirements in the Developer Portal. In general, reviewers look for the same things a careful merchant would:

  • The install, load and uninstall callbacks work, and uninstall removes the store's data as promised (App Types and the OAuth Flow).
  • The app asks only for the scopes it needs and explains why.
  • The UI is clear, accessible and consistent with the control panel (BigDesign helps).
  • The listing has accurate screenshots, pricing, support contact and a privacy policy.
  • Errors are handled gracefully, and the app does not break stores under load.

Prepare a test store and written test instructions so a reviewer can try every feature quickly.

Versioning and deployment

  • Version everything. Tag releases in Git with semantic versions, and keep a changelog. For themes, each stencil push creates a theme version in the store, so you can activate an older one if the new one misbehaves.
  • Separate environments. Development, staging (connected to a sandbox store) and production, each with its own credentials and callback URLs.
  • Automate deploys. A pipeline runs tests, builds, deploys and runs a smoke test. Deploying by hand at 5 p.m. on a Friday is how outages begin.
  • Migrate carefully. Database changes ship in steps that old and new code can both tolerate, so a rollback does not corrupt data.
  • Roll out gradually. For apps, deploy to a small set of stores first when you can; for themes, preview before activating, and never edit the active theme directly.
  • Plan the rollback. For every release, know the exact command that returns to the previous version, and rehearse it.

Monitoring

You cannot fix what you cannot see. Track:

  • Errors with context (store hash, route, request ID) but without secrets or customer data.
  • Latency of your endpoints and of calls to the platform API, plus the rate-limit headroom.
  • Webhook health: deliveries failing, handler duration, queue backlog, and whether the platform has deactivated a hook.
  • Business signals: installs, uninstalls, orders processed. A sudden drop in webhook volume is as important as an error spike.
  • Real-user performance for storefronts: Core Web Vitals by page type.

Alert on symptoms users feel, not on every exception, or the alerts will be ignored. Keep a runbook: where to look first, how to roll back, who to contact. See also Architecture and Scaling.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. Which approach causes an N+1 problem?

    One call for the list plus one per row multiplies requests. Use filters, includes or batches instead.
  2. 2. A real API token was committed to Git and then deleted in the next commit. What must you do?

    Anyone with the history can still read the old value. Revoking the credential is the only real fix.
  3. 3. Why roll out a new Content Security Policy in report-only mode first?

    Report-only logs violations without blocking, so you can fix the policy before enforcing it.
  4. 4. What does a performance budget do?

    A budget is an automated limit; it prevents slow growth by turning performance into a pass or fail check.
  5. 5. Why should a webhook handler return quickly and process work in a queue?

    The platform expects a fast response. Acknowledge first, work afterwards, and make the work idempotent.

Summary

  • Make storefronts fast by sending less: sized images, lean scripts and CSS, careful third-party tags, and real-user measurements.
  • Use budgets to stop performance from slipping.
  • Make API use efficient: fetch less, batch, avoid N+1, cache with invalidation and respect limits.
  • Keep secrets out of code and logs, scope tokens tightly, scan in CI and rotate after any leak.
  • Roll out a CSP in report-only mode before enforcing it.
  • Prepare for Marketplace review with working lifecycle callbacks, minimal scopes and clear documentation.
  • Version releases, automate deploys, rehearse rollbacks and monitor errors, latency and webhook health.

Next: Project: Product Sync Tool