Next JS eCommerce Boilerplate
Full-featured open source Next.js eCommerce template. This boilerplate provides an easy starting point for building a Jamstack eCommerce storefront with Crystallize and Next.js. You can also check out this boilerplate as a live eCommerce demo.
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 Netlify or 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 Netlify
- How to deploy the project on Vercel
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.
- Example data: if you would like your tenant to have the same data as the boilerplate, please select ‘Yes.’
- 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.
In order to use Crystallize CLI and run our project, you will need to have the following installed on your computer:
- Node.js (minimum version 10)
- Vercel CLI
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.
Once the development server is running, you will be able to browse to http://localhost:3000.
This section would provide you with a better understanding of the app structure.
Static files like shop’s logo and payment gateway logos.
Src includes all the source files that implement all the website actions.
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 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 include the render information of every page.
The library includes assisting functions and logic shared across multiple files.
In the locales folder, you can map languages and pricing information after they have been defined in Crystallize.
Includes layout information of page-components.
Includes more generic UI layout information.
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 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.
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)
There are two ways to deploy your project to Netlify. You can use GitHub integration by following the Netlify integration guide provided by GitHub, or you can do it using the CLI. To deploy using the CLI, make sure to install Netlify-cli:
npm install -g netlify-cli
Once that is installed, log in to Netlify by typing the following command. This redirects you to Netlify where you will be asked to log in.
After logging in, navigate to the root directory and initialize a new Netlify site:
- Select the ‘create and configure a new site’ option
- Choose your team
- The next step is to give your website a name, this is optional and can be changed later If no answer is provided, Netlify generates a random one
- Then, you will be asked to provide access to the GitHub account
- The build command can be set to ‘next build’
- Specify the directory you would like to deploy, in our case, it is the .next directory
- Lastly, you can specify the folder containing the Netlify function. Considering there is no folder for those at present, we can leave it blank
There are two environment variables you need to set:
We recommend that you set these using the Netlify dashboard. However, these can also be set in the netlify.toml file along with build settings and deploy settings.
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 log in via the CLI:
There are two environment variables you need to set:
We recommend that you set these using the Vercel dashboard.
Deploying your Crystallize project with Vercel is easy. If you have used the GitHub integration, you simply push to GitHub and that’s it. The deployment will be initiated.
If you want to do it with the CLI, you execute a deployment with this command:
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:
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.