Jump Start Your Apps with a New Next.js Starter

Key highlights:

• A new Next.js starter app helps developers build BigCommerce single-click apps faster.

• Use the app as a reference to study, a step-by-step tutorial to build from scratch, or a starter template for your own app.

• Flexible data modes let developers build and test UI and API integrations without dealing with the full single-click auth flow until they're ready.

Single-click apps are an invaluable tool in every BigCommerce developer's tool belt, whether you're building functionality for the public marketplace or only for your own stores. These apps allow you to embed custom tailored UI directly in the BigCommerce control panel, while allowing the core platform to handle unified user authentication. All apps share many of the same core patterns - auth endpoints, API interactions, and BigDesign-based UI - and the heavy lifting to bootstrap these layers is often an impediment to getting started on the features you really care about.

Commerce has released a new starter template to help accelerate your development of production-ready BigCommerce single-click apps. The Next.js app has been re-worked from the ground up, with patterns designed to improve the developer experience and demonstrate core architectural techniques.

Highlights:

• Modernized stack - The app is built on the Next.js App Router, React 19, and BigDesign 5.

• Multi-purpose - Use it as a reference, a tutorial, or a starter.

• Quick setup - Clone and run initially with no API token or external dependencies.

• Production-ready - Real-world patterns plus opt-in scaffolding for deployment to Vercel.

• Flexible developer experience - Build and test UI and API integration outside the single-click auth flow.

The app exercises core patterns with an example use case: a small Gift Certificates Manager that runs inside the BigCommerce control panel. The example is deliberately modest in scope but offers real functionality, including the ability to view registered customers' gift certificates, refill balances, and transfer gift balances to customer store credit. The example demonstrates key features like paginated API reads, update actions, caching and cache invalidation, and app extension registration.

View the reference app on GitHub.

Three ways to use the app

The same repository serves three different needs, so pick the entry point that matches what you're after.

• As a reference for core patterns. Clone it, run it, and examine the layers you care about — the single-click OAuth callbacks, session management, REST and GraphQL clients, and drivers for database storage. See Run the Example App for the quickest route to running the fully featured app.

• As a step-by-step tutorial. Start from scaffolded boilerplate and implement each layer yourself, learning core patterns each step of the way. We've overhauled our core single-click app tutorial in the DevDocs based on the new starter.

• As a starter for your own app. Core architectural layers relevant to all single-click apps are cleanly separated from the Gift Certificates Manager example, making the repository a viable starter template for your own apps rather than just a reference example. See Using This App as a Starter for a breakdown of the layers to add, remove, and update.

Fast setup

You can get the functional example up and running with a simple sequence of commands (Node.js and pnpm required), no API token or external services necessary:

Running as a functional, installable single-click app takes more configuration, but this quick setup lets you get hands-on with the UI and core patterns right away by using mock data. The app also supports local SQLite storage for dependency-free development even as you bring in the single-click auth flow.

These layers are designed to get you up and running as quickly as possible before you tackle wiring up the connection points that make production BigCommerce apps work.

Production patterns

The fully built app is not a happy-path demo. Patterns it demonstrates include:

• The complete callback set - install, launch, uninstall, and remove-user, including signed-payload verification and token exchange.

• Layered authorization - a cheap, DB-free proxy check on every route, plus an authoritative per-page/per-action check.

• Encrypted, pluggable credential storage - a CredentialsStore interface with SQLite and Postgres drivers, upsert semantics, and transactional cleanup.

• Resilient API clients - REST and Admin GraphQL clients with rate-limit retry, request timeouts, and sanitized error handling.

• Caching and invalidation - While caching might not be a fit for admin-facing apps, the starter demonstrates modern Next.js caching and invalidation patterns and gives you the configuration to enable them or not.

The core tutorial experience introduces only the most essential patterns, while the fully built application adds all production-ready layers. See the repository's own tutorial doc for segmented diffs of every enhanced feature.

Deploy readiness

Full tooling for a supported hosting provider is opt-in via a scaffolding command, rather than baked into the app, so the base starter stays provider-neutral and you can extend it to target any host.

Out of the box, the app supports deploying to Vercel using Postgres for DB storage. Scaffolding includes a DB migration script, a vercel-build command, and an example .env file to guide your production configuration.

Cloudflare (coming in the near future) will serve as a second supported hosting profile.

Flexible developer experience

For the vast majority of app development, the single-click auth workflow is incidental. When you're building out your core UI or wiring API calls, dealing with the install flow, tunnel, and session management often creates unnecessary points of friction. Three data modes in the new starter let you opt into that complexity only when it's what you're actually working on.

• MOCK - In-memory mock data, no credentials or live API calls required. Build mock data handlers following these patterns if you want to support this "UI-only" development mode while building your own app on the template.

• STATIC - Real API calls against one real store using a static store-level API token. No install flow, no DB-based credentials storage. Most app features can be developed in this mode.

• MULTITENANT - The real single-click app experience, involving authentication, credentials storage, and session management.

MOCK and STATIC modes allow you to focus on building your UI and core API integration points. Flip to MULTITENANT to fully test the experience in a store control panel and when deploying to production.

The final word

Building single-click apps for BigCommerce stores involves some complex layers, including patterns you will build the same way every single time. Our new reference app gives you those core layers so you can focus on developing your app's unique functionality. It also offers examples using modern Next.js techniques, plus the flexibility for quick setup and low-friction development.

Key resources:

• Starter single-click app

• Tutorial

• Learn about single-click apps