Headless Storefront Quick Start Guide

Follow these steps to get the headless reference storefront up and running in minutes.

Prerequisites

Install the following prerequisites:

• Node.js version 18.0 or later
• Yarn
  note

  Yarn is the preferred package manager over npm for the reference storefront.

Start the development server

1. Install the required dependencies:

   yarn install
2. Add a .env.local file to the root folder with the environment variables set appropriately.
3. Run the GraphQL codegen:

   yarn generate
4. Run the development server:

   yarn dev
5. View your site at http://localhost:3000

---

Configuration

You must set up environment variables, whitelist your domain, and set up your marketplace configuration file for the application to function properly.

Environment variables

Environment variables can be added to a .env.local or .env file in the root path, or by passing them in the command line with your build command.

You must set the following environment variables for the application to work:

Environment variable	Description
NEXT_PUBLIC_API_URI	The URL to the GraphQL API endpoint, including a trailing slash.
HOST	The domain name where the website is being served. It is used for creating structured data for SEO and for setting the absolute URLs in emails sent by the application (e.g., account confirmation, password reset).

See the following example environment file:

NEXT_PUBLIC_API_URI=https://api-example.mpconsole.com/graphql/
HOST=http://localhost:3000

Marketplace configuration

The src/config/mpconfig.ts file is where you can specify options on how your reference storefront is built and what features are enabled.

See the following example mpconfig.ts:

import { MarketplaceConfigurationCurrencyEnum } from '@/graphql/_generated/types'

const mpconfig = {
  defaultCurrency: MarketplaceConfigurationCurrencyEnum.Usd,
  currencyList: ['CAD', 'USD'],
  defaultLocale: 'en-US',
  defaultCountryOverride: 'CA',
  quoteoutEnabled: true, 
  quoteoutShowBuyerShippingOption: true, 
  checkoutEnabled: true, 
  clarityTrackingId: 'h52kl4gp9b', 
  gtagAnalyticsId: 'G-XXX', 
  maxOrderTotalForCreditCard: 25000,
  checkoutMinimumAmount: 100,
  quoteoutMinimumAmount: 100,
  guestCheckoutEnabled: true,
} as const

export default mpconfig

Show more ↓

The following table describes the options you can specify in your mpconfig.ts file:

Configuration option	Description
defaultCurrency	Sets the default currency for the marketplace.
currencyList	List of supported currencies in the marketplace.
defaultCountryOverride	To override the default IP-based customer location detection and specify the country directly, set this to the 2-letter country code.
defaultLocale	Sets the default locale/language for the marketplace.
quoteoutEnabled	Enables or disables the quote checkout flow.
quoteoutShowBuyerShippingOption	If enabled, shows the option for buyers to self-organize shipping during the quote checkout flow.
checkoutEnabled	Enables or disables the standard checkout flow.
clarityTrackingId	Tracking ID for Clarity analytics. Get your own at Clarity.
gtagAnalyticsId	Google Analytics tracking ID. Get your own at Google Analytics.
maxOrderTotalForCreditCard	To enforce a maximum order subtotal for credit card checkout, set the maximum number.
checkoutMinimumAmount	To enforce a minimum order subtotal before allowing buyers to checkout, set the minimum number.
quoteoutMinimumAmount	To enforce a minimum order subtotal before allowing buyers to request a quote, set the minimum number.
builderPublicApiKey* (Deprecated)	Public API key for Builder.io. As of the Dec 2023 update, the latest reference storefront no longer uses Builder.

---

Directory structure

Directory/File	Description
public	Stores static files, including the logo, favicon, and robots.txt.
src	Contains the application's source code including components, utility functions, hooks, contexts, and more.
src/pages	Contains the application's pages. Each file corresponds to a route based on its file name.
├──src/pages/api	Holds the serverless functions which act as the backend for frontend (BFF) layer.
src/components	Holds reusable React components that are used across different pages.
src/config	Holds configuration files, such as mpconfig.ts.
src/contexts	Contains React Context files that can be used to manage and share state across multiple components in the application.
src/styles	Contains CSS files for styling the application.
src/lib	Contains utility functions or configuration for libraries.
src/hooks	Contains custom hooks, which are reusable functions to contain state and side-effects.
src/graphql	Contains files and assets related to GraphQL operations and integrations, such as schema definitions, resolvers, client queries, and mutations.
├──src/graphql/_generated	GraphQL types and SDK generated from the codegen tool.
├──src/graphql/fragments	Fragments which components might rely upon, many components rely on fragment types for their prop typing.
├──src/graphql/mutations	Mutations which are both used server-side and client-side.
├──src/graphql/pages	Page Queries, these are used on SSR fetches, in getServerSideProps.
├──src/graphql/get*.gql	Client-side queries, small subsets which are used to perform client-side queries via react-query.
src/utils	Contains utility functions and modules used throughout the application, such as graphqlSdk.ts that facilitates interaction with the GraphQL API.

---

Deployment and hosting

The reference storefront can be hosted on any cloud hosting provider of your choice. For ease of deployment, our team can help you get setup with the base reference storefront with CI/CD on Fly.io.

This is a great way to get started and build your minimum viable platform (MVP) and have continuous deployment setup. It may also be the solution you want to continue to use as your permanent hosting solution.

Fly.io

A fly.toml app configuration file is included in the root folder by default, in case you decide to use Fly.io as your hosting provider.

See the Fly.io documentation on App Configuration (fly.toml).

info

Before deploying with Fly.io, you must increase the memory to 512mb. See the Fly.io documentation for instructions.

Docker

A Dockerfile is included in the root folder by default. See the Docker documentation on building a Dockerfile.

---