search

bigcommerce / sample-app-nodejs

A reference implementation of a BigCommerce single-click app, in Node.JS + Next.js/React
MIT License
59 stars 340 forks source link

readme

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
  1. 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
  1. 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
  1. 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
  1. Copy .env-sample to .env.
cp .env-sample .env

  1. 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.

  2. In the .env file, update the AUTH_CALLBACK variable with the ngrok_url from step 4.

  3. 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).

  4. 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
  1. 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).

  1. 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