> This page is for Developer.

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.bigcommerce.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.bigcommerce.com/_mcp/server.

# Introduction

> Build a BigCommerce single-click app with Next.js, BigDesign, and the BigCommerce REST API, from a mock-data UI through a fully authenticated multitenant app.

This tutorial demonstrates how to build a BigCommerce single-click app using Next.js, React, and BigDesign, BigCommerce's library of React components.

You will learn how to connect your app to BigCommerce, integrate an API client, and set up a database to store app data. You will use BigDesign to give your app a native BigCommerce visual style and behavior.

The example feature you'll build in this tutorial is a **gift certificates manager** — a working admin interface for viewing, updating, and refilling a store's gift certificates. The application exercises the auth, session, API client, and storage layers that all apps need.

**By the end of this tutorial, you will have:**

* A Next.js app styled with [BigDesign](https://developer.bigcommerce.com/big-design), BigCommerce's React design system
* Real BigCommerce REST API calls against a live store
* A complete single-click app OAuth install and launch flow
* Session cookies and per-request authorization
* Per-store access tokens persisted to a local SQLite or deployed Postgres database

The tutorial is based on the [BigCommerce starter single-click app](https://github.com/bigcommerce-edu/starter-sc-app-next).

> **Info**
>
> #### Run the finished app first
>
> If you'd rather skip straight to installing the example app rather than following the step-by-step guide, use the following quick start commands:
>
> ```shell title="Run the example app in MOCK mode" showLineNumbers={false}
> git clone https://github.com/bigcommerce-edu/starter-sc-app-next.git
> cd starter-sc-app-next
> pnpm install
> cp .env.example .env.local
> pnpm dev
> ```
>
> Browse to `http://localhost:3000` or the localhost port shown in your terminal. By default, this runs the app in "MOCK" mode, with no real API calls, no storage, and no requirement of a single-click app context. See the [full setup steps](https://github.com/bigcommerce-edu/starter-sc-app-next/blob/main/docs/RUN-EXAMPLE-APP.md)
> in the repository documentation for the necessary config/setup to run the app in other modes. The repo docs also include a full [Vercel deployment guide](https://github.com/bigcommerce-edu/starter-sc-app-next/blob/main/docs/VERCEL-DEPLOYMENT.md).

## Prerequisites

To complete this tutorial you need:

* Experience with [JavaScript](https://developer.mozilla.org/en-US/docs/Web/JavaScript), [TypeScript](https://www.typescriptlang.org/), and [React](https://react.dev/). Familiarity with [Next.js](https://nextjs.org/) is helpful but not required — the app uses the App Router, Server Components, and Server Actions, and the tutorial explains the patterns it relies on.
* [Node.js](https://nodejs.org/) and [pnpm](https://pnpm.io/). The repository includes an `.nvmrc` file specifying the tested Node version.
* A [BigCommerce sandbox store](/developer/docs/overview/sandboxes) or [trial store](https://www.bigcommerce.com/essentials/), with control panel access as a user who can install apps. Required once you start integrating real store data.
* A free [Developer Portal account](https://build.bigcommerce.com/) for registering the app. Required once you start building the single-click install flow. Creating an account doesn't require a partnership — that's only needed to publish to the BigCommerce App Marketplace. See [Beginning development](/developer/docs/integrations/apps/guide/beginning-development) for the wider context.
* A tunneling or port-forwarding service that can expose your local dev server at a public HTTPS URL. Also required for the single-click install flow, and covered in detail when you get there.

## Set up your project

The tutorial starts from a boilerplate project with a number of layers scaffolded which are not the focus of the guide. Follow the steps below to create a clean copy of the boilerplate and run the initial app state.

### Install `degit`

**`Install degit`**

```shell title="Install degit" showLineNumbers={false}
npm install -g degit
```

### Copy the start branch

Copy the `e-start` branch into your own working directory, replacing the path with your own:

**`Copy the project`**

```shell title="Copy the project" showLineNumbers={false}
degit https://github.com/bigcommerce-edu/starter-sc-app-next#e-start <new-project-directory>
```

Your new project should contain the directory `src/components/gift-certs-manager`.

### Initialize a Git repo

**`Git repo and dependencies`**

```shell title="Git repo and dependencies" showLineNumbers={false}
cd <new-project-directory>
git init
git add .
git commit -m "Initial project files"
```

### Create your environment file

**`Copy the example environment file`**

```shell title="Copy the example environment file" showLineNumbers={false}
cp .env.example .env.local
```

`.env.example` is the reference for every environment variable the app reads, with commentary on each one. Each exercise in the tutorial shows the additions and changes you need to make to `.env.local`, mirroring how they appear in `.env.example`.

> **Warning**
>
> `.env.local` holds API tokens and secrets. It's gitignored — keep it that way, and never commit credentials to your repository.

### Install dependencies and start the dev server

**`Install and run`**

```shell title="Install and run" showLineNumbers={false}
pnpm install
pnpm run dev
```

Browse to `http://localhost:3000` or the localhost port shown in your terminal. You should see a basic welcome message.

![Starter app boilerplate](/_fern-img/70a0c6f352c0dad5acd8467dc6a10c31a8e41da56d8a8ed084e34ac10289ef9e.webp)

> **Note**
>
> Each exercise in this tutorial begins from the state the previous one ended in. If you need to start an exercise fresh — or you want to skip ahead — the starter repository has a tagged branch for the beginning of each exercise. The links are in the [repository documentation](https://github.com/bigcommerce-edu/starter-sc-app-next/blob/main/docs/TUTORIAL.md).

## The boilerplate

A number of layers that are not the focus of this tutorial are already present in your project boilerplate. These include:

* **Third-party libraries**: Most [third-party packages](https://github.com/bigcommerce-edu/starter-sc-app-next/compare/e-depend-start...e-depend-complete?diff=split) used in the tutorial are installed in the boilerplate. BigDesign and `styled-components` are the exception — you'll install those yourself in the first exercise.
* **File stubs**: To better facilitate the explanation diffs you'll see linked throughout the tutorial, all files are already stubbed. You'll flesh these placeholders out rather than creating new files.
* **Error handling**: Default error page routes and error handling utilities
* **Basic UI**: UI primitives for the shell layout and placeholder content
* **Mock data**: [Mock data](https://github.com/bigcommerce-edu/starter-sc-app-next/compare/e-mock-data-start...e-mock-data-complete?diff=split) for gift certificates, along with data access layer functions you'll refactor later. The initial tutorial steps will flesh out the UI while relying on mock data.
* **Routing primitives**: A ["root" group](https://github.com/bigcommerce-edu/starter-sc-app-next/compare/e-root-start...e-root-complete?diff=split) defines pass-through routes used for URLs without a store hash in "MOCK" mode.
* **Control panel syncing**: A client component loads the [BigCommerce SDK](https://www.npmjs.com/package/@bigcommerce/app-sdk-js) and subscribes to its `onLogout` event, clearing the app's own session when the user logs out of the control panel. See [Manage user session timeouts](/developer/docs/integrations/apps/guide/following-best-practices#manage-user-session-timeouts) for more on this practice.

View the [full boilerplate](https://github.com/bigcommerce-edu/starter-sc-app-next/compare/e-boilerplate-start...e-boilerplate-complete?diff=split) for details.

## Data modes

The app reads a `DATA_MODE` environment variable that selects one of three modes everywhere data is fetched. You'll move through different data modes during the tutorial, so let's review the concept before getting started.

| Mode          | Data source                                                                | Authentication                             | URL Routes                                      |
| ------------- | -------------------------------------------------------------------------- | ------------------------------------------ | ----------------------------------------------- |
| `MOCK`        | In-memory mock data; no network calls                                      | None                                       | Root-level (`/gift-certs`)                      |
| `STATIC`      | Real API calls against one store, using a token from environment variables | None                                       | Root-level (`/gift-certs`)                      |
| `MULTITENANT` | Real API calls, with a per-store token looked up from durable storage      | Full single-click install and session flow | Store-scoped (`/store/{store_hash}/gift-certs`) |

Only `MULTITENANT` is a production mode. `MOCK` and `STATIC` are development affordances, and the app displays a warning banner in both to make that obvious.

After your initial setup, your store should be running in "MOCK" mode with mock gift certificate data.

## Architecture reference

The starter repository's [architecture documentation](https://github.com/bigcommerce-edu/starter-sc-app-next/blob/main/docs/ARCHITECTURE.md) describes the full design and the reasoning behind it: data modes, the install and session flow, two-tier authorization, credentials storage, the API clients, caching, and error handling. Refer to it whenever you want more depth than a tutorial step provides.

Ready to begin? Start with [Build a UI with BigDesign](/developer/docs/integrations/apps/tutorial-single-click-app/1-bigdesign).