Skip to main content

Quick start

This page will give you an introduction to the 80% of the concepts that you will most likely use. We recommended you familiarize yourself with the primary technologies used in GraphCommerce: React and Next.js.

Project file structure

(Almost) Every file in your project directory is meant for customization. It's standard to modify these files for every project.

  • ๐Ÿ“„ /graphcommerce.config.js GraphCommerce configuration
  • ๐Ÿ“ /components A set of components you most likely want to modify to your needs
  • ๐Ÿ“ /components/Layout The main layout components, like header, navigation, and footer
  • ๐Ÿ“ /pages A set of boilerplate pages, which handle URL routing
  • ๐Ÿ“„ /components/theme.ts Global styles
  • ๐Ÿ“ /locales Interface translation files that are auto generated
  • ๐Ÿ“ /plugins Directory for custom plugins
  • ๐Ÿ“„ /next.config.js Next.js configuration


GraphCommerce relies on Hygraph, the default integrated CMS. Hygraph is used for all static content (video, pages, images), allowing for high-quality components beyond Magento's CMS capabilities.

  • To start building, clone โ†— the Hygraph schema.
  • You can safely delete all content
  • Hygraph content is multilingual
  • A page's content field holds the components to display
  • If the page url matches a Magento category page url, it's content adds to the category page


The homepage's content field holds the components to display

Page routing

GraphCommerce uses Next.js file-based page routing โ†—. The files inside the ๐Ÿ“ /pages directory handle routing. Modify these files to meet your requirements or build a custom page.

  • Product pages: ๐Ÿ“„ /p/[...url].tsx
  • Homepage: ๐Ÿ“„ /index.tsx
  • Category pages: ๐Ÿ“„ /[...url].tsx (also used for category home page)
  • Hygraph content pages: Modify ๐Ÿ“„ /index.tsx


Modify the layoutProps in ๐Ÿ“„ /newsletter/index.tsx to change the newsletter page layout


GraphCommerce is build using MUI coreโ†— components.

๐Ÿ‘‰ To change your storefront's global colors, typography and styles, modify ๐Ÿ“„ /components/theme.ts

To style a Graphcommerce component to your liking, add the sx prop:

sx={{ color: 'red' }}

Target child elements with css selectors:

sx={{ '& .MuiBox-root': { background: 'blue' }}}

Pass the theme object to use global values

sx={(theme)=>({ margin: theme.spacings.lg, color: theme.palette.text.secondary })}


There are several ways to customize your storefront to a greater extent. The optimal method varies based on the desired modification.

๐Ÿ‘‰ Local modifications - Every file in your project directory is meant for customization. E.g., you can directly modify files in the ๐Ÿ“ /pages and ๐Ÿ“ /folder directories, as wel as your ๐Ÿ“„ /components/theme.ts file.

๐Ÿ‘‰ Plugin - Creating a plugin is straightforward and surprisingly uncomplicated. Plugins are recommended for retaining maximum upgradability.

๐Ÿ‘‰ Patch - Directly edit a component in ๐Ÿ“ /node_modules and generate a patch using patch-package. Patches, stored in the ๐Ÿ“ /patches directory, auto-reapply during development or production environment builds.

โ—๏ธ Local copy - Duplicate the component from ๐Ÿ“ /node_modules to e.g., ๐Ÿ“ /components/, update all references to it, and edit locally. Using local copies marginally complicates upgrading.


What are the benefits of choosing GraphCommerce for a react ecommerce project?

What are the benefits of choosing GraphCommerce for a reactjs ecommerce project?

React is a very suitable framework for magento reactjs ecommerce projects. Magento 2 is a well established, widely used open source e-commerce solution. GraphCommerce brings the best of both, and includes the structure, components, and tooling you need to get started with react ecommerce. Using GraphCommerce minimizes the development effort required to launch a full featured reactjs e-commerce storefront with features like cart, search, layered navigation and category, product, account, checkout pages.

Why use the GraphCommerce magento reactjs ecommerce template

Why use the GraphCommerce magento-graphcms reactjs ecommerce template

The GraphCommerce magento-graphcms template contains all needed components like cart, search, and layered navigation for a full-featured e-commerce storefront. It's easy to customize and includes the structure, components, and tooling you need to get started. With the extensive documentation, it is more efficient to understand and customize the template for your next react Magento 2 project, than to start from scratch.

Next steps

  • ๐ŸŽ‰ By now, you know the basics to begin building your storefront.
  • Set up VS Code and install usefull extensions for an optimal development experience.
  • Start customizing to go from "Hello World" to a fully built GraphCommerce custom storefront.