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:

BigCommerce sandbox store (required to develop and test apps)
Developer Portal Account (required to register apps)
Experience using npm
The most recent LTS version of Node.js and its highest corresponding npm version

Get started

Start by forking the sample-app-nodejs repository.
Navigate to the root directory of your project and install npm packages.

npm install

Add and start ngrok

You will need a publicly accessible URL to connect the draft app to BigCommerce. To add network access while in the development phase, you can use ngrok, a free tool that lets you expose local servers like localhost:3000 to the public internet over secure tunnels.

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.

Expose the web server to the internet.

cd ~/path/to/sample-app-nodejs # Make sure you're in your project directory.
ngrok http http://localhost:8080              # Start the app

Register the app

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

Sign in to the Developer Portal.
Click Create an app.
Give the app a name.
Click Technical.
Enter the Auth Callback URL as https://{ngrok_url}/api/auth. For example, https://12345.ngrok.io/api/auth. You can get the ngrok_url from the terminal that is running ngrok http http://localhost:8080.
Enter the Load Callback URL as https://{ngrok_url}/api/load.
Enter the Uninstall Callback URL as https://{ngrok_url}/api/uninstall.
If your app supports multiple users, locate the App Features section. Select Multiple Users, then enter the Remove User Callback URL as https://{ngrok_url}/api/remove_user.
Because you will be using the API to modify the store’s products, set the Products OAuth scope to modify. To learn more about the available OAuth scopes, see OAuth scopes.
Click Update & Close.
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.

Configure environment variables

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

Alternate Heroku environment setup

If deploying on Heroku, skip the .env setup. Instead, enter env variables in the Heroku App Dashboard under Settings > Config Vars.

Create a .env file in the root directory of your project.
Copy the contents of .env-sample to .env.

.env-sample

# Get the Client ID and Secret from the Developer Portal
CLIENT_ID={app client id}
CLIENT_SECRET={app secret}
# Test locally with ngrok
# /developer/docs/apps/guide/development#testing-locally-with-ngrok
AUTH_CALLBACK=https://{ngrok_url}/api/auth
# Replace jwt key with a 32+ random character secret
JWT_KEY={SECRET}
# Specify the type of database
DB_TYPE=firebase
# If using firebase, enter your config here
FIRE_API_KEY={firebase key}
FIRE_DOMAIN={firebase domain}
FIRE_PROJECT_ID={firebase project id}
# If using mysql, enter your config here and change DB_TYPE to mysql
MYSQL_HOST={mysql host}
MYSQL_DATABASE={mysql database name}
MYSQL_USERNAME={mysql username}
MYSQL_PASSWORD={mysql password}
MYSQL_PORT={mysql port *optional*}
API_URL=api.bigcommerce.com

See code in GitHub

Replace the CLIENT_ID and CLIENT_SECRET with the app’s client ID and client secret from the Developer Portal.
Update the AUTH_CALLBACK with the ngrok_url. You can get the ngrok_url from the terminal that is running ngrok http 3000.
Enter a JSON Web Token (JWT) secret. To learn more about JWT, see the Internet Engineering Task Force documentation.

JWT key length & Generation

JWT key should be at least 32 random characters (256 bits) for HS256.
You can generate a random key using the following command in your terminal:

openssl rand -base64 32

This will provide a random 32 character output in the terminal that you can use as your JWT key.

Ensure not to share this key publicly as it is used to sign and verify JWT tokens for your app.

Specify DB_TYPE:

If using Firebase, enter your project’s Firebase config keys. For information on how to set up Cloud Firestore, see Firebase quick start.
If using MySQL, enter your project’s MySQL database config keys (host, database, user/pass and optionally port).
If using Heroku with ClearDB, the database should create the necessary Config Var, namely, CLEARDB_DATABASE_URL.

If you’re using MySQL, set up the initial tables by navigating to the root directory of your project, then run the database migration using the following npm script:

Initial database migration

npm run db:setup

Start dev environment

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

npm run dev

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:

Sign in to the store, navigate to Apps > Develop, and install the app.
If everything is configured correctly, you should get an Authorization Successful message.
Navigate back to My Apps to see the list of installed apps.
Click Launch on the draft app to test the /load callback.
Navigate back to My Apps and click Uninstall to test the /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

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:

BigCommerce sandbox store (required to develop and test apps)
Developer Portal Account (required to register apps)
Experience using npm
The most recent LTS version of Node.js and its highest corresponding npm version

Get started

Start by forking the sample-app-nodejs repository.
Navigate to the root directory of your project and install npm packages.

npm install

Add and start ngrok

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.

Expose the web server to the internet.

cd ~/path/to/sample-app-nodejs # Make sure you're in your project directory.
ngrok http http://localhost:8080              # Start the app

Register the app

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

Sign in to the Developer Portal.
Click Create an app.
Give the app a name.
Click Technical.
Enter the Auth Callback URL as https://{ngrok_url}/api/auth. For example, https://12345.ngrok.io/api/auth. You can get the ngrok_url from the terminal that is running ngrok http http://localhost:8080.
Enter the Load Callback URL as https://{ngrok_url}/api/load.
Enter the Uninstall Callback URL as https://{ngrok_url}/api/uninstall.
If your app supports multiple users, locate the App Features section. Select Multiple Users, then enter the Remove User Callback URL as https://{ngrok_url}/api/remove_user.
Because you will be using the API to modify the store’s products, set the Products OAuth scope to modify. To learn more about the available OAuth scopes, see OAuth scopes.
Click Update & Close.
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.

Configure environment variables

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

Alternate Heroku environment setup

If deploying on Heroku, skip the .env setup. Instead, enter env variables in the Heroku App Dashboard under Settings > Config Vars.

Create a .env file in the root directory of your project.
Copy the contents of .env-sample to .env.

.env-sample

# Get the Client ID and Secret from the Developer Portal
CLIENT_ID={app client id}
CLIENT_SECRET={app secret}
# Test locally with ngrok
# /developer/docs/apps/guide/development#testing-locally-with-ngrok
AUTH_CALLBACK=https://{ngrok_url}/api/auth
# Replace jwt key with a 32+ random character secret
JWT_KEY={SECRET}
# Specify the type of database
DB_TYPE=firebase
# If using firebase, enter your config here
FIRE_API_KEY={firebase key}
FIRE_DOMAIN={firebase domain}
FIRE_PROJECT_ID={firebase project id}
# If using mysql, enter your config here and change DB_TYPE to mysql
MYSQL_HOST={mysql host}
MYSQL_DATABASE={mysql database name}
MYSQL_USERNAME={mysql username}
MYSQL_PASSWORD={mysql password}
MYSQL_PORT={mysql port *optional*}
API_URL=api.bigcommerce.com

See code in GitHub

Replace the CLIENT_ID and CLIENT_SECRET with the app’s client ID and client secret from the Developer Portal.
Update the AUTH_CALLBACK with the ngrok_url. You can get the ngrok_url from the terminal that is running ngrok http 3000.
Enter a JSON Web Token (JWT) secret. To learn more about JWT, see the Internet Engineering Task Force documentation.

JWT key length & Generation

JWT key should be at least 32 random characters (256 bits) for HS256.
You can generate a random key using the following command in your terminal:

openssl rand -base64 32

This will provide a random 32 character output in the terminal that you can use as your JWT key.

Ensure not to share this key publicly as it is used to sign and verify JWT tokens for your app.

Specify DB_TYPE:

If using Firebase, enter your project’s Firebase config keys. For information on how to set up Cloud Firestore, see Firebase quick start.
If using MySQL, enter your project’s MySQL database config keys (host, database, user/pass and optionally port).
If using Heroku with ClearDB, the database should create the necessary Config Var, namely, CLEARDB_DATABASE_URL.

If you’re using MySQL, set up the initial tables by navigating to the root directory of your project, then run the database migration using the following npm script:

Initial database migration

npm run db:setup

Start dev environment

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

npm run dev

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:

Sign in to the store, navigate to Apps > Develop, and install the app.
If everything is configured correctly, you should get an Authorization Successful message.
Navigate back to My Apps to see the list of installed apps.
Click Launch on the draft app to test the /load callback.
Navigate back to My Apps and click Uninstall to test the /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.