Create a GraphCommerce storefront

You're ready to create a GraphCommerce storefront. You want to set up your development environment so that you can begin development.

In this tutorial, you'll create a GraphCommerce app locally to begin developing a full-featured storefront. GraphCommerce is a front-end framework used for building headless Magento e-commerce PWA's.

What you'll learn

After you've finished this tutorial, you'll have accomplished the following:

  • Set up your local development environment
  • Generated a new project based on the magento-graphcms example

GraphCommerce magento-graphcms example category page

GraphCommerce magento-graphcms example category page

GraphCommerce magento-graphcms example product page

GraphCommerce magento-graphcms example product page


You've familiarized yourself with React ↗, Next.js ↗, and Mui ↗. GraphCommerce is a front-end React framework that uses Next.js for server-side rendering.

Install dependencies

If you want to test a GraphCommerce storefront using a pre-configured Magento demo store and a pre-configured GraphCMS project with demo content, then you need to only install the dependencies. This is the quickest approach.

  • Install and use node 14/16/18: nvm install 16 or nvm use 16
  • Install yarn: corepack enable (for node 16/18) or npm install --global yarn (for node 14)

Step 1: Create a new GraphCommerce app


GraphCommerce installation

Download the example

  1. git clone -b main --depth 1 https://github.com/graphcommerce-org/graphcommerce.git clone repository
  2. mkdir my-project create project folder
  3. cp -R graphcommerce/examples/magento-graphcms/. my-project && rm -rf graphcommerce copy example, delete repo
  4. cd my-project change directory to project folder
  5. cp -R .env.example .env create .env file
  6. rm CHANGELOG.md remove changelog

Step 2: Magento and GraphCMS API keys

By default, the .env file is configured with API keys from a demo Magento store and a demo GraphCMS project. If you want to test your GraphCommerce app using the demo store, then you can start the development environment. Only proceed with the following steps if you want to develop a GraphCommerce storefront using your own Magento store and/or GraphCMS project.


To order to be able to connect your GraphCommerce app to your Magento backend and/or GraphCMS project, you'll need:

  • Magento 2.4.3 - Clean install, a production or a development environment
  • GraphCMS - A GraphCMS project with the required schema. Clone the demo GraphCMS project ↗ as your starting point.


To connect your GraphCommerce app to your Magento backend and/or GraphCMS project, you need to update variables in the /.env file. The .env file contains useful information about your storefront.

Magento 2 API URL, located at http://<magento2-server>/graphql.

Comma-separated list of image domains. Add media.graphcms.com as default.

GraphCMS API URL. Once logged in, copy it from Project Settings > Api Access > Content API

NEXT_PUBLIC_LOCALE_STORES='{"en-us": "default", "en-ca": "canada"}'
List of routes and store_codes:

  • When the user switches to the Canadian storeview, the suffix /en-ca is added to the URL.
  • The first storeview in the object is loaded by default. No suffix is added to the URL.
  • The key (en-ca) is used to load the storeview translation
  • When a users' browser language matches a storeviews' locale (Admin > Store > Configuration > General > General > Locale), the user is automatically redirected to the corresponding storeview.

If you need to fetch a list of available store_codes, run yarn dev when you entered your MAGENTO_ENDPOINT. The app won't build, but the GraphQL explorer will start at http://localhost:3000/api/graphql. Enter the following query:

query {
  availableStores {

Step 3: Start the development environment

  • yarn Install the dependencies
  • yarn codegen Converts all .graphql files to typescript files
  • yarn dev Run the app

Visit the development environment running at http://localhost:3000
Visit the GraphQL Playground running at http://localhost:3000/api/graphql

No success? Refer to common build errors or ask your question in the public Slack community ↗ chat

Next steps