Retail eCommerce Next.js
The furniture boilerplate is a fully-featured eCommerce boilerplate built using Next.js and Crystallize. The boilerplate was developed with performance, a good developer experience, and best practices in mind.
There are two ways to set up the project - one would be to directly clone the repository. Another, better one is to use the Crystallize CLI (command line interface). Open the terminal and run the following command:
npx @crystallize/cli-next@latest install ~/my-projects/my-ecommerce
The CLI gives you the option to bootstrap your tenant with all the demo data the furniture store has.
Once the development server is running, you will be able to browse to http://localhost:3000/en.
The app is contained within the src folder that is located in the applications folder.
The assets folder has all the icons that are being used in the application. All of these are SVG files and you can add or remove these as required.
As the name suggests, this folder has all the styles being used in the application. So if you would like to change the colors and the font, the default.css file in the tailwind folder is where you would go to edit those. Additional component styles are defined in the index.css file present in this folder.
The translation folder contains the translation files.
This is all the “Use Cases.” Everything that is business-related, you can see that as the “Domain” folder. There is no connection to the UI nor to the framework in this folder. You will mainly find functions that do meaningful actions like `fetchSomething`, `pushSomething`, `doSomething`. For instance, it contains all the queries used to fetch data from the APIs, in addition to functions that enable you to push customers and orders to Crystallize, while the latter contains everything related to the Service API.
The user interface. This folder contains all the components and the pages as well as the hooks and providers.
The app folder contains all the pages the application has. There are some predefined routes such as shop, checkout, orders, etc. However, we also have what Next.js refers to as a catch-all segment that would render a page based on whatever shape it has: product, document, or folder. This folder is really framework-specific and connected to Next.js.
Let’s take a deeper look at the core folder in this section.
The first folder in core contains the forms you will see throughout the site, namely on the checkout page. This includes the user information page on checkout.
The layout for components specific to Crystallize, such as the paragraph collection, the properties tables, and the file component, can be found here. You can find these components on the product and the individual story pages in the app.
The boilerplate contains curated products that are part of curated stories. Once a user selects a curated product, they can then select different variants for it. To edit the layout there, you will edit the index file in this folder.
Each category in the shop contains various filters that are used to filter through products based on colors, price range, stock, etc. The filter components and the logic behind those can be edited within this folder.
We have various types of items in the boilerplate - product, curated product, document. On root categories, they are shown in a list view. This folder contains individual files to change the layout of these items.
With the boilerplate, you get multiple payment integrations such as Stripe and QuickPay (more to come!) in addition to the “Crystal” method, which is purely for testing purposes. You can remove the integrations you don’t require from this folder.
The header has a search component. This makes a call to the Search API in Crystallize and returns all the products that match the search term entered in the input field. To change anything about that input field, the file in this folder would be edited.
Let’s say you want to export a PDF invoice, or your catalogue, or information about the product itself as a PDF file. The boilerplate comes with this functionality right from the start. The styles for the PDF generated and the information displayed for each of these is defined within this folder. Examples: PDF for a product, PDF for a folder.
Any grid found in the demo application is made up of tiles in addition to items such as a product or a document. A tile could be one of the following: a banner, an embedded component, a slider, or a hero slider. To change the layout for any of the tiles, you can head over to this folder. Example: the entire front page is a grid made up of tiles.
Time to take a look at the API routes. Located within the app folder, you will find API routes for cart, orders, payments, and webhooks. Let’s go through these one by one.
First, you will notice that there is `[langstore]` and `api` folders. This is because the Boilerplate is multilingual. All the routes underneath `[langstore]` can get access to the language and the store from the URL.
The files here take care of handling and placing the cart.
You can fetch orders by either the order ID or the customer identifier. The difference between the two is the former allows you to fetch a particular order, while the latter allows you to fetch every order placed by a customer. This route takes care of both scenarios.
The server-side logic for all the payment providers can also be found here.
Crystallize provides you with webhook functionality. This allows you to create and customize webhooks that fire off on events such as order creation, order update, item publish, and so much more. The boilerplate takes care of use cases for when a new order is created: an email is sent to the user confirming their order. The created.tsx file here is where you can change the layout of that email.
As this is an open source project, contributions are welcome. A guide on how to contribute is present in the readme for the repository.