Gatsby Boilerplate for React Ecommerce
The boilerplate provides an easy starting point for building an eCommerce store with Crystallize and Gatsby. You can also check out this boilerplate as a live eCommerce demo.
React + Gatsby
This document acts as a reference guide on how to set up an eCommerce store using Gatsby, a static site generator for React, and finally deploying it to Vercel. Currently, the boilerplate uses V2, with support for V3 coming in the near future.
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
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 Gatsby 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.
Running the Project
Running the project in development is very straightforward. Running the following command will start up the development server:
npm run dev
Accessing the Development Site
Once the development server is running, you will be able to browse to http://localhost:8000.
This section would provide you with a better understanding of the app structure.
The logos and other images are placed here.
This is where you'll add translations. We've already provided translations for a few languages here including English, Norwegian, and Greek.
attribute-list: attribute-list here relates to the attributes that shows up in the basket if you have selected a different variant instead of the default one.
basket: the basket folder contains everything basket related including the query you'll send to get the basket data
layout: this folder contains the components that are bound to be used in every page. It includes the header, the footer, the aside component (contains the details of the items inside the basket).
social: all the social media icons that are being used on the articles page are located here.
list-format: this folder dictates how a an element is displayed in a list depending upon its type (article, folder or product). A good example of this would be the collection of different items seen on the homepage.
grid: as the name suggests, you can edit the files in this folder to edit the grids being displayed throughout the application.
shape-components: all the reusable components being shared across the application are located in this folder.
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 page-templates folder where each of these have their own specified folders.
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 shape-components folder that is in components.
Aside from some fixed pages such as the frontpage, most of the pages are being generated via the data that is being received using GraphQL. This is being done in the gatsby-node.js file. To learn more about how to generate pages programmatically in Gatsby, head over to the Gatsby Documentation.
Browser and SSR APIs
If you'd like to pass something to every page you have in your application (a good example would be the context providers). Gatsby makes this easier by providing you a Browser API as well as the Server Side Rendering APIs to achieve this task. In the project directory, you'll find two files named: gatsby-browser.js and gatsby-ssr.js. Edit these accordingly.
URL to query from
Although, you will probably not need to add in or modify the URL you want to query from. In case you do need to add an additional URL, you can do so in the gatsby-config.js file.
Editing the styling
The styling for the components is defined in three manners: the global styles (contained in the UI folder), the styles in the component file itself, and then every page has its own defined styles in its specific folder.
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:
There are two environment variables you need to set:
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:
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:
Next steps: Service API
In order to manage a fully operational ecommerce, you need to manage user authentication, basket validation, payment and such.