Skip to main content
More in Learn

Next.js eCommerce storefront boilerplate

Next.js eCommerce storefront boilerplate screenshot

React + Next.js

This document acts as a reference guide on how to set up an eCommerce store using Next, a static site generator for React, and finally deploying it to Vercel.

What this guide covers:

  • How to set up your project using the CLI
  • Instructions for running the project
  • How to access the development site
  • The folder structure of the boilerplate
  • Where to edit the pages and reusable components
  • How to create pages
  • Where to add the query URL to get data
  • How to deploy the project on Vercel

Introduction video

Getting Started

To create a new project, we'll use the Crystallize CLI. In your terminal, type in the following command:

npx @crystallize/cli <your-project-name>

Running this command will allow you to add in the following:

  • The preferred boilerplate, which will be NextJS in this case.
  • The tenant: you can either enter your own tenant or go with the demo tenant to test everything out
  • Service API: you'll need to add in the Service API URI. You can learn more about the Service API by heading to the documentation page.

Prerequisites

In order to use Crystallize CLI and run our project, you will need to have the following installed on your computer:

You will also need to create a tenant with Crystallize by signing up and generating a Crystallize access token. The tenant identifier is required to retrieve the products related to your store and the access tokens are required for creating and retrieving orders.

If you are wanting to use Stripe for processing payments you will also need to sign up for a free Stripe account and get your test Stripe publishable and secret keys (you can also use the live keys in production).

You will need a free Vercel account in order to deploy your project to Vercel.

Running the Project

Running the project in development is very straightforward. Running the following command will start up the development server:

yarn dev

or
npm run dev

Accessing the Development Site

Once the development server is running, you will be able to browse to http://localhost:3000.

Frontend of the nextjs ecommerce deployment

App structure

This section would provide you with a better understanding of the app structure.


public

Static files like shop’s logo and payment gateway logos.

src

Src includes all the source files that implement all the website actions.

pages

Pages include the NextJS routes. Here you can edit the logic as to how you communicate with the Service API, alter the way of handling Crystallize data, create additional serverless functions and more. For more information, read the routing introduction in NextJS.

components

Components include the logic of every complementary component that is used in a page render, such as Basket. In every component dedicated folder you may find the logic and styling information respectively.

page-components

Page components include the render information of every page.

lib

The library includes assisting functions and logic shared across multiple files.

locales

In the locales folder, you can map languages and pricing information after they have been defined it in Crystallize

shapes

Includes layout information of page-components

ui

Includes more generic UI layout information

Editing the Pages

To edit any of the pages i.e. the frontpage, the article page, the product page or the folder page, you can:

  • Head over to the the shapes folder where you can select for each item what data you would like to query from Crystallize.
  • Edit the page/index.js file to handle the data fetched and/or add custom logic for that page
  • Edit the page/style.js file to handle the layout of the page

Editing reusable components

If you'd like to edit the reusable components that are being used across the pages, you can do so in the components folder.

Creating pages for different item shapes

Aside from some fixed pages such as the search or checkout page, most of the pages are being generated via the data that is being received using GraphQL. This is being done in the […catalogue] file. Here you can add logic to render different pages depending on the item shape, or that are under a specific folder, etc.

To do so you may:

  • Create a new page-component to handle your specific shape under /page-components
  • Create a new shape file under /shapes, that holds the GraphQL query and render information (logic, layout, etc.) of your item type
  • Alter the logic in the […catalogue] file to use your newly defined renderer based on the shape identifier. The default is querying by item type (folder, document, product)

Livestream multilingual setup

Configuring Tokens and Environment Variables for Deployment

There are two ways of deploying to Vercel.

The easiest is through the Vercel Github integration. Follow that guide to get automatic deployments for each git push.

Alternatively, you can also deploy manually from the command line. In order to enable that you need to install Vercel and login via the CLI:

vercel login

There are two environment variables you need to set:

NEXT_PUBLIC_CRYSTALLIZE_TENANT_IDENTIFIER=<your-tenant>
NEXT_PUBLIC_SERVICE_API_URL=<your-service-api>

We recommend that you set these using the Vercel dashboard.

Deploying the Project

Deploying your Crystallize project with Vercel is easy. If you have used the github integration, you simply push to GitHub and that’s it. A deployment will be initiated.

If you want to do it with the CLI, you execute a deployment with this command:

vercel

This will build the website and deploy it to Vercel. The terminal will say whether the deployment was successful or not. If it has succeeded, you will be given a URL where your site has been deployed.

If you are deploying to production, you can also use the following command to deploy your website to a production domain if you have configured one for your project within the dashboard of Vercel:

vercel --prod

Next steps: Service API

In order to manage a fully operational ecommerce, you need to manage user authentication, basket validation, payment and such.

For that, we have prepared a boilerplate for you, the Service API boilerplate, which you would want to add alongside your Next.js project. Follow our guide for how to set it up.

People showing thumbs up

Need further help?

Join and ask our
slack community.

Join our slack community