> This page is for Developer.

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.bigcommerce.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.bigcommerce.com/_mcp/server.

# Next.js Commerce Quick Start

> **Note**
>
> This is archived documentation. Next.js Commerce integration is no longer actively maintained. For current storefront options, see [Catalyst](/developer/docs/storefront/catalyst/getting-started) or [Headless](/developer/docs/storefront/headless).

## Overview

BigCommerce offers cloud-based multi-channel ecommerce solutions. We also offer themes with powerful design tools and features that let you build and host your storefront on our servers.

> **Note**
>
> This article is deprecated. Next.js Commerce has released a v2 with breaking changes. For Next.js Commerce v1, you can [view the code (GitHub)](https://github.com/vercel/commerce/tree/v1) and [read the release notes (GitHub)](https://github.com/vercel/commerce/releases/tag/v1) at Vercel, and use this article to get started. The original `commerce-v1.vercel.store` demo is no longer publicly available.
>
> To work with the improved v2, see our article on [Next.js + BigCommerce](/developer/docs/storefront/headless).

### Headless BigCommerce

BigCommerce's flexibility allows for headless architecture, the ability to integrate storefront frontends with the BigCommerce backend. Some of the headless setups have the advantage of providing the following:

* Customize your frontend technologies without migrating your database
* Preserve your legacy frontend while switching to BigCommerce as your ecommerce engine
* Power multiple stores on multiple sales channels from a single BigCommerce dashboard.

### Next.js Commerce

Next.js Commerce is a headless integration to BigCommerce. Created in partnership with the Next.js and Vercel teams, Next.js Commerce showcases how powerful Next.js is when partnered with our open SaaS ecommerce platform.

## Getting started

To get started with Next.js Commerce, you can develop locally by cloning the v1 branch of the `vercel/commerce` repo. The following steps walk you through the process.

### Prerequisites

* An IDE
* Knowledge of [Next.js (nextjs.org)](https://nextjs.org/)
* Knowledge of [BigCommerce APIs](/developer/docs/overview/quick-start)
* A hosted Git repository account, such as GitHub, Bitbucket, or GitLab
* Git and Node/NPM

### Developing locally

#### Clone the repository

Clone the v1 version using the following command:

```shell showLineNumbers={false}
git clone -b v1 https://github.com/vercel/commerce
```

#### Generate a store-level API account

Use the steps in our [Guide to API Accounts](/developer/docs/overview/api-fundamentals/api-accounts#creating-store-level-api-credentials), and make sure to download and keep the text file with the API credentials. In a development sandbox, you can grant the account all scopes. In a production store, grant the token only the scopes necessary to operate the storefront you build. If you think you may change the scopes, use an [app-level API account](/developer/docs/overview/api-fundamentals/api-accounts#app-level-api-accounts).

#### Create a dedicated sales channel

Use the [Create a channel](/developer/api-reference/rest/admin/management/channels/create-channel) endpoint to get started. To learn more about channels, see the [Channel Overview](/developer/docs/integrations/channels).

#### Create a customer impersonation token

Use your API account and your channel ID to create a GraphQL Storefront customer impersonation token for your storefront. Use the [Create a customer impersonation token](/developer/api-reference/rest/admin/authentication-apis/storefront-api-tokens/customer-impersonation-token/create-token-with-customer-impersonation) endpoint to get started.

#### Set up environment variables

Navigate to the local project's root directory and create a copy of the `.env.template` file. Rename the newly created file `.env.local` and add environment variables using the following reference:

```bash showLineNumbers={false}
cd commerce
cp .env.template .env.local
```

**`.env.local`**

```bash title=".env.local" showLineNumbers={false}
COMMERCE_PROVIDER=bigcommerce
BIGCOMMERCE_STOREFRONT_API_URL="https://store-${STORE_HASH}-${CHANNEL_ID}.mybigcommerce.com/graphql"
BIGCOMMERCE_STOREFRONT_API_TOKEN=${STOREFRONT_TOKEN}
BIGCOMMERCE_STORE_API_URL="https://api.bigcommerce.com/stores/${STORE_HASH}"
BIGCOMMERCE_STORE_API_TOKEN=${API_ACCOUNT_ACCESS_TOKEN}
BIGCOMMERCE_STORE_API_CLIENT_ID=${API_ACCOUNT_CLIENT_ID}
BIGCOMMERCE_CHANNEL_ID=${CHANNEL_ID}
BIGCOMMERCE_STORE_URL=https://store-${STORE_HASH}.mybigcommerce.com
BIGCOMMERCE_STORE_API_STORE_HASH=${STORE_HASH}
```

| Environment variable       | Description                                                                                                                                                                                                |
| :------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `STORE_HASH`               | A unique identifier for your store. See the API PATH in your API account text file; the store hash is in the following position in the path string. `https://api.bigcommerce.com/stores/${STORE_HASH}/v3`. |
| `API_ACCOUNT_ACCESS_TOKEN` | See the ACCESS TOKEN in your API account text file from step 2.                                                                                                                                            |
| `API_ACCOUNT_CLIENT_ID`    | See the CLIENT ID in your API account text file from step 2.                                                                                                                                               |
| `CHANNEL_ID`               | Use the ID of the channel you created in step 3.                                                                                                                                                           |
| `STOREFRONT_TOKEN`         | Use the Storefront customer impersonation token you created in step 4.                                                                                                                                     |

#### Install dependencies

Install the project's dependencies using npm.

```shell showLineNumbers={false}
npm install
```

#### Start the development server

Next.js's dev script loads the environmental variables from `.env.local`, starts a local server, and compiles your project. When dependencies have finished installing, get things started by running the following:

```shell showLineNumbers={false}
npm run dev
```

> **Note**
>
> Note: By default, Next.js runs on port 3000. If that port is not available in your environment, [consult the Next documentation (nextjs.org)](https://nextjs.org) to modify the start command.

#### View the storefront

To see your Next.js Commerce storefront running locally, open a browser window to the following address:

```shell showLineNumbers={false}
http://localhost:3000
```

## Application

The architecture for Next.js Commerce is standard for a Next.js application. To learn Next.js basics, visit [the official Next.js tutorial (nextjs.org)](https://nextjs.org/learn).

To understand how Commerce generates pages and updates product information on your storefront, continue reading.

### Pre-rendering pages

One of the main advantages of Next.js is the fast page load times you can achieve by pre-rendering your content. By default, Next.js pre-renders all pages.

Next.js allows you to choose how pages are pre-rendered:

* **Static Generation:** Next.js generates the HTML at build time and reuses on each request.
* **Server-side Rendering:** Next.js generates the HTML on each request.

Next.js Commerce statically generates pages while still keeping store information updated by using Incremental Static Regeneration.

**Static Page Generation**

Next.js pre-renders static content by calling the `getStaticProps()` function at build time on the server-side. Since `getStaticProps()` does not run on the client-side, you can do direct database queries or run other functions without exposing them to the client. To verify what Next.js eliminates from the client-side bundle, use Vercel's [Code Elimination (now.sh)](https://next-code-elimination.now.sh/) tool.

**Incremental Static Regeneration**

With `getStaticProps()`, you may still use dynamic content on your statically generated pages. Incremental Static Regeneration (ISR) updates existing pages by re-rendering them in the background when triggered by site traffic after a set timeout period. By default, data revalidation runs at most once every four hours, though you may customize this frequency.

For more information and a demonstration on how ISR works, visit Vercel's [Static Reactions Demo (vercel.app)](https://reactions-demo.vercel.app/).

By default, Next.js Commerce revalidates and updates product information from BigCommerce at most once every four hours.

### Fetching and populating store data

Next.js Commerce uses [storefront-data-hooks (GitHub)](https://github.com/bigcommerce/storefront-data-hooks) to connect your Next.js frontend with the BigCommerce backend. The package contains code-split React hooks for data fetching using [SWR (swr.vercel.app)](https://swr.vercel.app/) (stale-while-revalidate). SWR is a layer on top of React Hooks that automates cache management. Data can be transitively stale, but SWR re-fetches and synchronizes the correct data from BigCommerce.

Storefront Data Hooks has helper functions to handle common user actions such as login, logout, and register.

SWR uses FETCH for data fetching: [vercel/fetch: Opinionated fetch (with retrying and DNS caching) optimized for use inside microservices (GitHub)](https://github.com/vercel/fetch).

## Application settings

### SSL/TSL Certificate

To use BigCommerce's [redirected checkout](/developer/docs/storefront/headless/cart-and-checkout/checkout#redirecting-to-the-bigcommerce-checkout), make sure your Next.js Commerce storefront has an SSL/TSL certificate installed and you are using URL beginning with `https://`. You also need to [Create a channel site](/developer/api-reference/rest/admin/management/channels/site/create-channel-site) and [Upsert the site checkout URL](/developer/api-reference/rest/admin/management/channels/site-checkout-url/update-checkout-url) to add the URL where you want to host the checkout.

### Next SEO

Next.js Commerce includes the [Next SEO (GitHub)](https://github.com/garmeeh/next-seo) plugin to simplify SEO settings so that Next.js Commerce appears correctly in search results and is more readily shareable on social media. To learn how to configure Next SEO settings, visit the [Next SEO GitHub repository (GitHub)](https://github.com/garmeeh/next-seo).

### Component styling

Next.js Commerce uses [Tailwind (tailwindcss.com)](https://tailwindcss.com/) to style components. Next.js Commerce's root directory contains a `tailwind.config.js` file where you can customize much of the project's styling. For more information on how to configure the `tailwind.config.js` file, visit [Tailwind CSS - Configuration (tailwindcss.com)](https://tailwindcss.com/docs/configuration).

### Internationalized routing

Next.js supports internationalized (i18n) routing and Next.js Commerce uses [sub-path routing (nextjs.org)](https://nextjs.org/docs/advanced-features/i18n-routing#sub-path-routing) which puts the locale in the URL path. By default, the `next.config.js` file has US English (`en-US`) and Spanish (`es`) set as locales. `en-US` is the preset default.

```javascript showLineNumbers={false}
i18n: {
   locales: ['en-US', 'es'],
   defaultLocale: 'en-US',
}
```

For more information on i18n routing in Next.js, see the Next.js documentation on [internationalized routing (nextjs.org)](https://nextjs.org/docs/advanced-features/i18n-routing).

## Resources

* [Next.js Commerce (nextjs.org)](http://nextjs.org/commerce)
* [Next.js Commerce Framework (GitHub)](https://github.com/vercel/commerce-framework)
* [BigCommerce Storefront Data Hooks (GitHub)](https://github.com/bigcommerce/storefront-data-hooks)