bubble-icon

Developer preview
This is a developer preview of GraphCommerce. The documentation will be updated as GraphCommerce introduces new features and refines existing functionality.

GraphCommerce magento-graphcms example overview

GraphCommerce offers a magento-graphcms example that provides an approachable path to building GraphCommerce custom Magento e-commerce storefront. This guide describes what's included in the magento-graphcms example and how you can begin exploring it.

How it works

Most of the files that you'll work on within your GraphCommerce project are located in the /components or /pages directories.

  • A minimal set of components you would most likely modify for your project
  • The main layout component, which renders header, navigation, and footer
  • A set of boilerplate pages, which handle URL routing
  • Basic global styles in theme.ts provided by Mui ↗
  • Interface translation files
File structure of the graphcommerce-magento example

├── components
    └── Layout
        └── Footer.tsx
        └── LayoutFull.tsx
    └── GraphCMS
        └── Asset
        └── RowHeroBanner
        └── RowQuote
    └── theme.ts
    └── ...
├── graphql
    └── CategoryPage.graphql
    └── PageLink.graphql
    └── ...
├── pages
    └── product
        └── [url].jsx
        └── ...
    └── page
        └── [...url].jsx
    └── [...url].tsx
    └── [cart].tsx
    └── _app.tsx
    └── _document.tsx
    └── ...
├── locales
    └── en.po
    └── nl.po
    └── ...

Components

The GraphCommerce magento-graphcms example provides a series of components that you can use as a starting point for development. These components query the Magento GraphQL API for efficient data-fetching. Most components have a .graphql file that contains the GraphQL query fragment.

Modifying components

By default, the components that you would most likely modify are located in the /components directory. You can directly modify these components and customize styles.

Others components are imported where needed, and can be recognized by their namespace @graphcommerce/. There are different ways to customize styles ↗ of importend components. The most common way is by adding an sx prop: sx={{color:'red'}}.

If you want to extend a component's behavior or built your own, you can duplicate a @graphcommerce/ component to your /components directory. You'll need to update all imports with the new location of your local component. This also applies if you want to modify a component's or page's query.

Component overview

Local
/AssetSource[Documentation]
/BlogSource[Documentation]
/LayoutSource[Documentation]
/ProductListItemsSource[Documentation]
/UspsSource[Documentation]
Packages (/node_modules directory/)
@graphcommerce/framer-next-pagesSource
@graphcommerce/googleanalyticsSource
@graphcommerce/googlerecaptchaSource
@graphcommerce/googletagmanagerSource
@graphcommerce/graphcms-uiSource
@graphcommerce/graphqlSource
@graphcommerce/graphql-meshSource
@graphcommerce/imageSource
@graphcommerce/lingui-nextSource
@graphcommerce/magento-cartSource
@graphcommerce/magento-cart-billing-addressSource
@graphcommerce/magento-cart-checkoutSource
@graphcommerce/magento-cart-couponSource
@graphcommerce/magento-cart-emailSource
@graphcommerce/magento-cart-itemsSource
@graphcommerce/magento-cart-payment-methodSource
@graphcommerce/magento-cart-shipping-addressSource
@graphcommerce/magento-cart-shipping-methodSource
@graphcommerce/magento-categorySource
@graphcommerce/magento-cmsSource
@graphcommerce/magento-customerSource
@graphcommerce/magento-customer-accountSource
@graphcommerce/magento-customer-orderSource
@graphcommerce/magento-graphqlSource
@graphcommerce/magento-newsletterSource
@graphcommerce/magento-payment-includedSource
@graphcommerce/magento-productSource
@graphcommerce/magento-product-bundleSource
@graphcommerce/magento-product-configurableSource
@graphcommerce/magento-product-downloadableSource
@graphcommerce/magento-product-groupedSource
@graphcommerce/magento-product-simpleSource
@graphcommerce/magento-product-virtualSource
@graphcommerce/magento-reviewSource
@graphcommerce/magento-searchSource
@graphcommerce/magento-storeSource
@graphcommerce/browserslist-config-pwa
@graphcommerce/eslint-config-pwa
@graphcommerce/next-config
@graphcommerce/next-ui
@graphcommerce/prettier-config-pwa
@graphcommerce/react-hook-form
@graphcommerce/typescript-config-pwa

GraphCMS

GraphCMS is integrated as a Content Management System. It is used to store all static content and provides a user-friendly interface for managing it.

The magento-graphcms example offers a number of components to render this content in different ways, for example in the form of a page-wide hero banner, a list of USPs or grid of text columns.

To get started with the magento-graphcms example, cloning the demo GraphCMS project GraphQL schema and its content is recommended.

Pages

GraphCommerce uses Next.js file-based routing ↗, built on the concept of pages. A page is a React Component exported from a .tsx file in the /pages directory. When a file is added to the /pages directory, it's automatically available as a route.

All routes of the app contain a URL segment that corresponds with a directory in the /pages directory. Magento category routes are handled by the /pages/[...url].tsx page and therefore do not contain a URL segment. As a result, the category URL structure of the app matches your default Magento frontend 1-on-1.

Page structure of the graphcommerce-magento example

├── pages
    └── about
    └── account
    └── api
    └── blog
    └── checkout
    └── customer
    └── modal
    └── page
    └── product
    └── search
    └── service
├── _app.tsx
├── _document.tsx
├── [...url].tsx
├── 404.tsx
├── cart.tsx
├── index.tsx
├── switch-stores.tsx

GraphQL API

GraphCommerce is built and optimized to use data coming from Magento's GraphQL API. GraphCommerce uses GraphQL Mesh, which adds the ability to add extra (micro)services as data sources. In the magento-graphcms example, a headless CMS called GraphCMS is integrated.

By default, the GraphQL Mesh endpoint runs on route /api/graphql. You can query both the Magento GraphQL schema and the GraphCMS GraphQL schema. Try out the GraphCommerce demo GraphQL Explorer ↗ with the following example query:

query {
  products(search: "sock", pageSize: 3) {
    items {
      url_key
    }
  }
  availableStores {
    store_name
    store_code
  }
}

Query fragments

Every component that requires data from Magento or GraphCMS has its own .graphql file, containing a GraphQL query fragment. GraphQL Code Generator (codegen) is used to convert query fragments to both the GraphQL document (query or mutation) and Typescript type definitions, both captured in .gql(.ts) files. .gql(.ts) are generated at build time.

Pages run queries in the getStaticProps function and pass the response as props. Pages have a single page query, that combines multiple query fragments from components. These accumulating page queries are located in the /components/GraphQL directory.

With the use of fragments and GraphQL Mesh, GraphCommerce retrieves all data from both Magento and GraphCMS in a single GraphQL query. This improves performance.

GraphQL queries in the graphcommerce-magento example

├── GraphQL
    └── CategoryPage.graphql
    └── PageLink.graphql
    └── DefaultPage.graphql
    └── PagesStaticPaths.graphql
    └── FooterQueryFragment.graphql
    └── PageContentQueryFragment.graphql
    └── ProductPage.graphql

FAQ

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

  • Get started with GraphCommerce and begin building a custom storefront.