BigCommerce Translations App

This is a BigCommerce App built using Next.js that enables merchants to translate their catalog into multiple languages per storefront. It uses:

• App Extensions to create a native editing experience within the product list
• The BigCommerce GraphQL Admin API to fetch and update catalog localization data

For merchant documentation on how to use this app, please see the User Guide.

Getting Started

Requirements

• Node.js 20 or later

  # Using nvm (Node Version Manager)
  nvm use

Environment Variables Setup

1. Copy the sample environment file:

   cp .env.sample .env.local

2. Update the following required variables in .env.local:

   • CLIENT_ID and CLIENT_SECRET: Get these from the BigCommerce Developer Portal
   • APP_ORIGIN: Your app's URL (for local development, this will be your ngrok URL)
   • JWT_KEY: A secure random string of 32+ characters
   • DATABASE_URL: Your database connection string (see Database Setup below)
   • BLOB_READ_WRITE_TOKEN: Your Vercel Blob storage token (get this from your Vercel project settings)
   • CRON_SECRET: A secure random string for protecting the cron endpoint

Database Setup

This app uses Neon (serverless Postgres) with Drizzle ORM for database management. It's also compatible with MySQL and SQLite with a tiny change to environment variables.

Option 1: Postgres via Neon (Recommended for Production)

1. Create a Neon database through Vercel's marketplace:

   • Visit Neon on Vercel Marketplace
   • Click "Add Integration"
   • Follow the setup instructions

2. Set up your environment variables:

   # Pull environment variables from Vercel
   vercel env pull .env.local

   This will populate your .env.local file with the necessary DATABASE_URL variable.

3. Ensure DB_TYPE=postgres is set in .env.local

Option 2: SQLite (Great for development)

1. Set your environment variables in .env.local:

   DB_TYPE=sqlite
   DATABASE_URL=sqlite:./local.db

Option 3: MySQL

1. Set your environment variables in .env:

   DB_TYPE=mysql
   DATABASE_URL=mysql://user:password@host:port/database

Database Management

After setting up your database, run these commands:

1. Install dependencies:

   npm run dev

2. Create the required tables within your database:

   npm run db:push

3. (Optional) Use Drizzle Studio to manage your data:

   npm run db:studio

Run the App Locally

npm run dev

Open http://localhost:3000 with your browser to see the result.

Debugging

The app uses the debug package for detailed logging of API operations. Each client has its own namespace:

• bigcommerce:admin - Admin API client operations
• bigcommerce:graphql - GraphQL API client operations
• bigcommerce:auth - Auth client operations

To enable debugging, set the DEBUG environment variable:

# Debug everything
DEBUG=bigcommerce:* npm run dev

# Debug specific clients
DEBUG=bigcommerce:auth,bigcommerce:admin npm run dev

# Debug with timestamps
DEBUG=bigcommerce:*,bigcommerce:admin:* npm run dev

The debug output includes:

• Request details (URL, method, headers)
• Response details (status, headers)
• Rate limit information
• GraphQL queries and variables
• JWT operations (encode, decode, verify)
• OAuth handshake details
• Error details with full context

Example debug output:

bigcommerce:admin Initialized BigCommerce Admin client with config: +0ms
bigcommerce:admin Making request: { url: "https://api.bigcommerce.com/stores/hash/v2/store.json" } +2ms
bigcommerce:admin Received response: { status: 200, headers: {...} } +150ms
bigcommerce:graphql Making GraphQL request: { query: "query { store { ... } }" } +0ms
bigcommerce:auth Verifying BigCommerce JWT +1ms

Todo

• Move server side locale transforms in api route into graphql client
• Add ability to update url path (dependent on platform update)