NextJS Sample App

This starter app includes all the files necessary to get started with a basic, hello world app. This app uses NextJS, BigDesign, Typescript, and React.

Running the app in development

To get the app running locally, follow these instructions:

1. Use Node 18+ and NPM 8+. To check the running versions, use the following commands:

node -v
npm -v

2. Clone and/or fork the repo and install npm packages:

git clone git@github.com:bigcommerce/sample-app-nodejs.git my-bigcommerce-app
cd my-bigcommerce-app
npm install

3. To expose your app server using an HTTP tunnel, install ngrok globally, then start the ngrok service.

Starting a local HTTP tunnel with ngrok requires you to create an ngrok account and add your ngrok authtoken to the ngrok config file.

ngrok config add-authtoken $YOUR_AUTHTOKEN

You can use npm to install ngrok:

npm install -g ngrok

Alternatively, MacOS users can use the homebrew package manager:

brew install ngrok

Start ngrok on port 3000 to expose the default Next.js server:

ngrok http 3000

4. Use the BigCommerce Developer Portal to register a draft app. For steps 5-7, enter callbacks as 'https://{ngrok_url}/api/{auth || load || uninstall}'. Get the ngrok_url from the ngrok terminal session.

https://12345.ngrok-free.app/api/auth # auth callback
https://12345.ngrok-free.app/api/load # load callback
https://12345.ngrok-free.app/api/uninstall # uninstall callback

5. Copy .env-sample to .env.

cp .env-sample .env

6. In the .env file, replace the CLIENT_ID and CLIENT_SECRET variables with the API account credentials in the app profile. To locate the credentials, find the app's profile in the Developer Portal, then click View Client ID.

7. In the .env file, update the AUTH_CALLBACK variable with the auth callback URL from step 4.

8. In the .env file, enter a secret JWT_KEY. To support HS256 encryption, the JWT key must be at least 32 random characters (256 bits).

9. Configure the data store. This project was written to use Firebase or MySQL

   In the .env file, specify the DB_TYPE.

   If using Firebase, copy the contents of your Service Account JSON key file into the sample-firebase-keys.json file. This file can be generated by:

   1. Creating a new project in Firebase
   2. Adding a Cloud Firestore
   3. And generating a new Private Key under Project Settings > Service Accounts See the Firebase quickstart (Google) for more detailed information.

   If using MySQL, supply the MYSQL_ config keys listed in the .env file, then do the initial database migration by running the following npm script: npm run db:setup

10. Start your dev environment in a dedicated terminal session, separate from ngrok.

npm run dev

If you relaunch ngrok, update the callbacks in steps 4 and 7 with the new ngrok_url. You can learn more about persisting ngrok tunnels longer (ngrok).

11. Consult our developer documentation to install and launch the app.

Production builds

In production, you must build and run optimized version of the code. Use the following commands to get started:

When you run the start script, specify a port number using the -p flag. Otherwise, the process will fail.

npm run build
npm run start -p 3000