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

Hygraph

Hygraph 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 Hygraph 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 Hygraph is integrated.

By default, the GraphQL Mesh endpoint runs on route /api/graphql. You can query both the Magento GraphQL schema and the Hygraph 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
    └── DefaultPage.graphql
    └── PageLink.graphql
    └── DefaultPage.graphql
    └── PagesStaticPaths.graphql
    └── ProductPage.graphql
    └── ProductPage2.graphql

FAQ

Next steps

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