DocsIntegrationsApps

Apps Quick Start

BigCommerce Apps Quick Start

In this quick start tutorial, you will create a single-click app using Node.js, React, Next.js, and BigDesign.

Prerequisites

To successfully complete this tutorial, you will need the following:

Get started

  1. Start by forking the starter-sc-app-next repository.
  2. Navigate to the root directory of your project and install packages.
pnpm install
  1. Copy the sample environment file. You will fill in its values in a later step.
cp .env.example .env.local

Expose your local server over HTTPS

You will need a publicly accessible HTTPS URL to connect the draft app to BigCommerce. BigCommerce calls your app back over the internet and renders it in a control panel iframe, so a bare http://localhost:3000 will not work.

This tutorial uses ngrok, a tool that lets you expose local servers like localhost:3000 to the public internet over secure tunnels. The starter app also documents VS Code port forwarding and GitHub Codespaces as alternatives.

  1. In a new terminal window, install ngrok using Homebrew.
brew install ngrok/ngrok/ngrok
ngrok config add-authtoken <TOKEN>

You can obtain your authtoken by going to https://dashboard.ngrok.com/get-started/your-authtoken.

  1. Expose the web server to the internet.
cd ~/path/to/starter-sc-app-next # Make sure you're in your project directory.
ngrok http 3000              # Start the tunnel
  1. Copy the https://<subdomain>.ngrok-free.app Forwarding URL. This tutorial refers to it as your app origin.

Most free tunneling services issue a new URL every time you restart the tunnel. When the URL changes, you must update both APP_ORIGIN and the callback URLs in the Developer Portal, then restart the dev server. Keeping the tunnel running for the length of a work session saves a lot of re-editing.

Register the app

Next, create a draft app profile in the Developer Portal using the following steps:

  1. Sign in to the Developer Portal.
  2. Click Create an app.
  3. Give the app a name.
  4. Click Technical.
  5. Enter the Auth Callback URL as https://{app_origin}/api/app/auth. For example, https://12345.ngrok-free.app/api/app/auth. You can get the app_origin from the terminal that is running ngrok http 3000.
  6. Enter the Load Callback URL as https://{app_origin}/api/app/load.
  7. Enter the Uninstall Callback URL as https://{app_origin}/api/app/uninstall.
  8. If your app supports multiple users, locate the App Features section. Select Multiple Users, then enter the Remove User Callback URL as https://{app_origin}/api/app/remove_user.
  9. Set the OAuth scopes the starter app requires: Customers modify, Marketing modify, Channel Settings read-only, Channel Listings read-only, Information & Settings read-only, and App Extensions manage. To learn more about the available OAuth scopes, see OAuth scopes.
  10. Click Update & Close.
  11. Click View Client ID to view this app’s client ID and client secret, or app-level API account.

Keep this tab open for the next step.

The Auth callback URL must match APP_ORIGIN exactly. The app sends it back to BigCommerce as the OAuth redirect_uri during the token exchange, and BigCommerce rejects a mismatch.

Scope changes only take effect for a store on the next install. If you change scopes later, uninstall and reinstall the app.

Configure environment variables

After registering the draft app, add its credentials and app origin to your project’s environment variables file.

  1. Open the .env.local file you created in the root directory of your project.

  2. Set the following variables.

.env.local
# Get the Client ID and Secret from the Developer Portal
BIGCOMMERCE_CLIENT_ID={app client id}
BIGCOMMERCE_CLIENT_SECRET={app secret}
# Your public HTTPS tunnel URL, with no trailing slash
APP_ORIGIN=https://{app_origin}
# Signs this app's own session cookie
SESSION_SECRET={secret}
# Encrypts stored store access tokens at rest
CREDENTIALS_ENCRYPTION_KEY={secret}
# Look up a per-store API token from durable storage
DATA_MODE=MULTITENANT
# Store credentials in a local SQLite file
CREDENTIALS_STORE_DRIVER=SQLITE

See code in GitHub

  1. Replace the BIGCOMMERCE_CLIENT_ID and BIGCOMMERCE_CLIENT_SECRET with the app’s client ID and client secret from the Developer Portal.

  2. Update APP_ORIGIN with your tunnel URL, omitting any trailing slash. You can get it from the terminal that is running ngrok http 3000.

  3. Generate the SESSION_SECRET and CREDENTIALS_ENCRYPTION_KEY values.

Secret generation

  • Each secret should be at least 32 random bytes.
  • You can generate a random key using the following command in your terminal:
openssl rand -base64 32

Run the command once per variable so the two secrets get different values. SESSION_SECRET signs this app’s own session cookie, and CREDENTIALS_ENCRYPTION_KEY encrypts stored store access tokens at rest. Neither is interchangeable with BIGCOMMERCE_CLIENT_SECRET, which only verifies BigCommerce’s inbound signed payloads.

Ensure not to share these keys publicly. If you change CREDENTIALS_ENCRYPTION_KEY, previously stored tokens can no longer be decrypted — delete data/credentials.sqlite and reinstall the app.

  1. Set DATA_MODE to MULTITENANT. This scopes every request to a store through the /store/[storeHash] route segment, authenticates it with the app’s session cookie, and sources API tokens from the credentials store rather than mock or static data.

  2. Leave CREDENTIALS_STORE_DRIVER set to SQLITE. The database is a plain file at ./data/credentials.sqlite, created automatically on first use and gitignored. No migration step or external service is needed.

SQLite is a local development choice only. Because it is a single file on one machine’s disk, it cannot be shared across the multiple instances a real deployment runs. For a hosted environment, see the starter app’s Vercel deployment guide.

Start dev environment

In a separate terminal from ngrok, start the app’s dev environment.

pnpm dev

Restart the dev server after any change to .env.local. A running server does not pick up environment variable changes, and APP_ORIGIN is read at startup to allow-list Server Action origins.

Ngrok configuration

Although you can use the ngrok npm package without creating an account, any unauthenticated tunnels you create will expire after two hours. For the best development experience, create a free ngrok account, find your ngrok authtoken, and add the authtoken to your global ngrok configuration.

Install the app

Finally, install the draft app on any store registered to the same email as your Developer Portal account using the following steps:

  1. Confirm the tunnel is up and public by opening your app origin in a browser. In MULTITENANT mode, you should see the “unauthorized” root route warning rather than an error. That means the app is reachable and correctly refusing to serve an unscoped route.
  2. Sign in to the store, navigate to Apps > Develop, and install the app, then approve the requested scopes.
  3. If everything is configured correctly, BigCommerce calls /api/app/auth, which exchanges the code for a token, saves the store, mints a session cookie, and redirects into /store/{store_hash}/. The app then renders inside the control panel iframe.
  4. Navigate back to My Apps to see the list of installed apps.
  5. Click Launch on the draft app to test the /api/app/load callback, which verifies BigCommerce’s signed payload and issues a fresh session.
  6. Navigate back to My Apps and click Uninstall to test the /api/app/uninstall callback.

Congrats! You’ve created and installed a BigCommerce draft app.

Becoming a partner

Interested in sharing or selling your app? Learn more about becoming a BigCommerce partner and getting your app approved.

Next steps

Resources