Tutorial: Next.js starter app
Step 1: Set up your local environment

Step 1: Set up Your Local Environment

Start by setting up your local development environment.

Install Node

For this tutorial, you need Node.js version 18+. To check your version of Node.js, run the following command in your terminal:

Check Node.js version
node -v

If you do not have Node.js installed, you can download it from (downloads) (opens in a new tab).

Set up a project directory

  1. Create a new project directory.

  2. Navigate to the directory using the terminal.

Generate a package.json file

Node.js version and custom dependencies

  • Make sure that you are using Node.js version 18+ and npm version 8+.
  • This sample app uses custom dependencies and does not rely on the create-next-app CLI tool.
  1. To create the project's package.json file, enter the interactive initialization sequence (opens in a new tab). Run the following command in the terminal:
Initialize package.json
npm init

Press enter to continue prompts.

To write a package.json file with default values, run npm init -y instead. Descriptive fields will be blank.

Install npm packages

  1. Install big-design, big-design-icons, big-design-theme, dotenv, next, react, react-dom, and styled-components.
Install dependencies
npm install --save @bigcommerce/big-design @bigcommerce/big-design-icons @bigcommerce/big-design-theme dotenv next react react-dom styled-components
  1. Install dev dependencies.
Install devDependencies
npm install --save-dev babel-plugin-styled-components @types/node @types/react @types/react-dom @types/styled-components typescript

babel-plugin-styled-components (opens in a new tab) is a supplement to the styled-components library that, among other things, offers improved debugging and minification of styles.

@types/node (opens in a new tab) and @types/react (opens in a new tab) contain TypeScript type definitions for Node.js and React.js respectively.

View tested package versions

You can view a list of all the tested package versions in the package.json file on the Step 1 branch (opens in a new tab) of this sample app's repo.

Add scripts

  1. Open package.json in your text editor.

  2. Update the scripts property, by adding the dev, build, and start scripts.

Add npm scripts
  "scripts": {
    "dev": "next",
    "build": "next build",
    "start": "next start -p $PORT",
    "test": "echo \"Error: no test specified\" && exit 1"
  1. Save your changes.

Add the node and npm engines

  1. Open package.json in your text editor.

  2. Add an engines property with the following values:

Add engines
  "engines": {
    "node": ">=16 <20",
    "npm": ">=8 <10"
  1. Save your changes.

Create a starter page

  1. In the root directory of your project, create a pages folder.

  2. In the pages folder, create an index.tsx file. This is your app's homepage.

  3. Open index.tsx in your code editor.

  4. Add Panel and Text BigDesign imports at the top of the file.

Add imports index.tsx
import { Panel, Text } from '@bigcommerce/big-design';

The Panel component allows you to contain content in a structured format. To learn more about the BigDesign's Panel component, see Panel Developer Docs (opens in a new tab).

Text is one of the many predefined typography components in BigDesign. BigDesign offers multiple properties to customize the typographic palette. To view available typography components, see Typography (opens in a new tab).

  1. Add the Index functional component below the import statements. You can view index.tsx (GitHub) (opens in a new tab).
Add functional component index.tsx
const Index = () => (
    <Panel header="Homepage" margin="xxLarge">
        <Text>Hello world</Text>
export default Index;

Next.js associates each file in the pages folder with a route based on the file's name. Consequently, the Index React component you exported in pages/index.tsx will be accessible at /index.

Initialize BigDesign

Next.js allows you to use a theme provider and import CSS files from node_modules. In this tutorial, you integrate BigDesign (opens in a new tab) to give your app a distinct BigCommerce look and feel.

  1. Next.js uses the App component to initialize pages. To override the default App component, add the _app.tsx file to the pages folder. This is where you initialize BigDesign.

  2. Open _app.tsx and import GlobalStyles from BigDesign and AppProps from Next.js.

Add imports _app.tsx
import { GlobalStyles } from '@bigcommerce/big-design';
import type { AppProps } from 'next/app'

Importing the GlobalStyles component will set BigCommerce's base styles globally.

  1. Add the MyApp functional component below the import statements. You can view _app.tsx (GitHub) (opens in a new tab).
Functional component _app.tsx
const MyApp = ({ Component, pageProps }: AppProps) => (
       <GlobalStyles />
       <Component {...pageProps} />
export default MyApp;

The Component prop represents the active page. Consequently, it will change when you navigate between routes.

Initialize styled-components

Because BigDesign uses styled-components, we need to add additional configuration for both BigDesign and styled-components to function properly.

  1. Add a custom _document.tsx file to your pages folder.

  2. Import Document and DocumentContext, the built-in TypeScript types, from Next.js.

Import components Document and DocumentContext
import Document, { DocumentContext } from 'next/document';
  1. Import ServerStyleSheet from styled-components.
Import component ServerStyleSheet
import { ServerStyleSheet } from 'styled-components';
  1. Extend the Document class. You can view _document.tsx (GitHub) (opens in a new tab).
Extend class Document
export default class MyDocument extends Document {
  static async getInitialProps(ctx: DocumentContext) {
    const sheet = new ServerStyleSheet();
    const originalRenderPage = ctx.renderPage;
    try {
      ctx.renderPage = () =>
          enhanceApp: (App) => (props) => sheet.collectStyles(<App {...props} />),
      const initialProps = await Document.getInitialProps(ctx);
      return {
        styles: (
    } finally {

Start the development server

  1. Using the terminal, open the root directory of your app and start the development server.
Start development server
npm run dev
  1. Open http://localhost:3000 from your browser. You should see the text “Hello world” displayed under Homepage.

Hello world

Next: Connect Your App to BigCommerce

Did you find what you were looking for?