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

Hygraph

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

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

Styling

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 })} 

Customization

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.

FAQ

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.