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.

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 ngrok_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. In the .env file, specify the DB_TYPE.

   The DB type must be either firebase or mysql.

   If using Firebase, supply the FIRE_ config keys listed in the .env file. See the Firebase quickstart (Google).

   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 ngrok expires, 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.

Webhook Management

This app automatically manages webhooks for BigCommerce stores. Webhooks are essential for real-time inventory management when bundle products are purchased.

Automatic Webhook Registration

The app automatically creates and manages webhooks during the app lifecycle:

1. During App Installation (/api/auth): Creates webhooks for new store installations
2. During App Loading (/api/load): Ensures webhooks exist for existing installations (safety check)
3. During App Uninstall (/api/uninstall): Cleans up webhooks when the app is removed

Webhook Configuration

The app registers the following webhook:

• Event: store/order/created
• Destination: {APP_URL}/api/webhooks/orders
• Purpose: Updates inventory levels for bundle products when orders are placed

Manual Testing

For development and testing purposes, you can use the provided scripts:

Test Webhook Management

node scripts/test-webhook.js

This script will:

• List existing webhooks for your store
• Test the webhook creation process
• Verify webhook configuration

Legacy Manual Creation (Development Only)

node scripts/create-webhook.js

Note: The manual script is only needed for local development. In production, webhooks are automatically managed by the app.

Webhook Lifecycle

• Creation: Webhooks are automatically created when a store installs the app
• Validation: Each app load checks if webhooks exist and recreates them if missing
• Cleanup: Webhooks are automatically removed when the app is uninstalled
• Resilience: Webhook creation failures don't prevent app installation (logged for debugging)

BigCommerce Webhook Behavior

• Webhooks remain active as long as the store is active
• Webhooks are automatically disabled after 90 days of store inactivity
• The app's safety checks ensure webhooks are recreated if they become missing
• No token refresh is needed for webhooks (they use the destination URL)

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