React Storefront & Checkout

Live demo / Explore and run the code in CodeSandbox

React Storefront: Open-source frontend e-commerce platform from the Saleor team.

Saleor Checkout: Extensible, checkout and payment integrations powered by Saleor API.

Motivation

modern & fast: Project is focusing on best practices for e-commerce, like: SSR & ISR, image optimization.

easily customizable: TailwindCSS can be easily extended and tweaked, or completely changed to your favorite css solution.

works out-of-the-box: Pre configured tools for DX.

Stack

• Next.js
• TypeScript
• GraphQL with Apollo Client
• Tailwind CSS
• Saleor Checkout

Quick Setup

Supercharge your development with our CLI tool and free developer account at Saleor Cloud. To download and install Saleor CLI, run the following command:

npm i -g saleor@latest

Set up your local storefront development environment by running the storefront create command. It will take you through the process of creating a new Saleor API instance (or choosing an existing one) and connecting it to your freshly cloned local storefront setup:

saleor storefront create

If you don't want to customize available options, you can also spawn a fully functional local storefront development environment, using--demo switch:

saleor storefront create --demo

Learn more about Saleor CLI

---

Setup

Monorepo structure

Here's the list of each app and shared package in the monorepo (click to see a README of that project)

Apps

• apps/storefront: frontend e-commerce platform
• apps/saleor-app-checkout: a Next.js Saleor app with dashboard for managing settings and theme, backend for Checkout, and the Checkout Storefront – ready to be extended/modified
• apps/checkout: an SPA React 18 checkout app, currently deprecated (kept for backward compatibility)

Packages

• packages/ui-kit: UI kit for checkout and React Storefront
• packages/config-checkout: eslint configuration
• packages/config-storefront: eslint configuration
• packages/tsconfig: tsconfig.jsons used throughout the monorepo
• packages/checkout-storefront: Checkout store front component
• packages/checkout-common: Common types and utils

Install dependencies

This monorepo uses PNPM as a package manager and Turborepo for building packages. In order to install pnpm, run:

npm install -g pnpm

Then install dependencies:

pnpm i

And start all the dev servers:

pnpm dev

The apps will start on different ports.

Development

Configuration

Instructions how to configure the application (e.g. change the graphql API URL) can be found here.

Build

To build all apps and packages, run the following command:

pnpm run build

You can also build a specific app or package by running this command:

pnpm run build --filter=saleor-app-checkout

In this example, we'll only build apps/saleor-app-checkout

Develop Saleor App

Create a tunnel for saleor-app-checkout:

cd apps/saleor-app-checkout && npx saleor app tunnel 3001

Note: the process needs to be running in the background

Before you start the server, you need to change default environment variables. Create .env.local file in each app:

• apps/saleor-app-checkout

To run the development server for all the apps, use the following command:

pnpm run dev --filter=saleor-app-checkout...

Develop Checkout Storefront

When in dev, a special development server is also running for checkout-storefront on port 3002. Check out localhost:3002?checkout= and add the your token to the url.

Code style

Before committing the code, Git pre-hooks will check staged changes for following the code styles. If you would like to format the code by yourself, run the command:

pnpm lint

Other

You can also run only a specific app by running this command:

pnpm dev --filter=saleor-app-checkout

Deployment

GraphQL Schema

To generate GraphQL code based on latest schema from Saleor instance defined in SALEOR_API_URL env variable run this command:

pnpm run generate

You need to run this command after each change in *.graphql files

Env variables

Change environment variables inside .env file:

• SALEOR_API_URL — GraphQL endpoint of your Saleor

  Example:

  https://my-env.eu.saleor.cloud/graphql/
  

  To run sandbox Saleor environment in Saleor Cloud use this command:

  npx saleor project create && npx saleor environment create

  You can also run Saleor locally. See Saleor docs for more instructions

• CHECKOUT_APP_URL — URL of deployed Checkout App

  Example:

  https://saleor-app-checkout.vercel.app
  

  See guide below on how to deploy the Checkout App

There are more environment variables available in each app. Go to their README's to learn more

Other tools

Debugging using VS Code

The repository contains ready to use VS Code debugger configuration (.vscode/launch.json).

Start server in debug mode

pnpm debug

Add breakpoints, and start debugging session in your editor.

VS Code GraphQL Extension

GraphQL extension for VSCode adds syntax highlighting, validation, and language features like go to definition, hover information and autocompletion for graphql projects. This extension also works with queries annotated with gql tag.

VS Marketplace link

Vercel

Read Vercel deployment guide in docs/vercel.md

Payment gateways configuration

Checkout app supports two payment gateways that you can configure:

Payment gateways can be configured in the Checkout app inside Saleor dashboard. Go to Apps > Third party apps > Checkout.

You can toggle, which payment gateway handles each different payment options per channel:

To use payment gateway, you need to provide its credentials. You can do that by clicking settings icon in channel configuration page

Mollie

Read setup guide in docs/mollie.md

Adyen

Read setup guide in docs/adyen.md

FAQ

Read FAQ in docs/faq.md

Ports

• apps/react-storefront: http://localhost:3000
• apps/saleor-app-checkout: http://localhost:3001
• packages/checkout-storefront: http://localhost:3002
• apps/checkout: http://localhost:3003
• packages/ui-kit storybook: http://localhost:6006