storefront
storefront copied to clipboard
Saleor Storefront built with React 18, Next.js 14, App Router, TypeScript, GraphQL, and Tailwind CSS.
Next.js Storefront
Next.js Storefront: Your open-source frontend starter pack for building performant e-commerce experiences with Saleor.
Saleor Checkout: Extensible Next.js checkout application and payment integrations powered by Saleor API.
Motivation
modern & fast: The project focuses on best practices for e-commerce, like: SSR & ISR, image optimization.
easily customizable: TailwindCSS can be easily extended and tweaked, or completely replaced with 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
Quickstart
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/cli
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
attribute:
saleor storefront create --demo
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
: Next.js e-commerce storefront starter pack -
apps/saleor-app-checkout
: a Next.js Saleor app with a dashboard for managing settings and theme, backend for Checkout, and the Checkout Storefront – ready to be extended/modified
Packages
-
packages/ui-kit
: UI kit for Storefront and Checkout -
packages/config-checkout
:eslint
configuration -
packages/config-storefront
:eslint
configuration -
packages/tsconfig
:tsconfig.json
s used throughout the monorepo -
packages/checkout-storefront
: Checkout storefront 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 the 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=<ID> and add 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 the 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 SaleorExample:
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 Saleor App CheckoutExample:
https://saleor-app-checkout.vercel.app
See guide below on how to deploy the Saleor App Checkout
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
Saleor App Checkout supports two payment gateways that you can configure:
You can configure the payment gateways in the Saleor App Checkout inside the Saleor dashboard. Go to Apps > Third party apps > Checkout.
You can toggle, which payment gateway handles each different payment options per channel:
To use a payment gateway, you need to provide its credentials. You can do that by clicking the settings icon on the 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
- packages/ui-kit storybook: http://localhost:6006