Skip to content

Latest commit

 

History

History
203 lines (131 loc) · 7.38 KB

README.md

File metadata and controls

203 lines (131 loc) · 7.38 KB
Raw

Checkout App

Checkout App

Extensible, checkout and payment integrations powered by Saleor API.

Note This app uses older flow for making payments in Saleor.

Current version of checkout uses Payment Apps instead

Setup

Prerequisites

Make sure you've set SALEOR_API_URL in the root of the monorepo to your Saleor instance. You can also use other Saleor instance than the one defined in .env in root of monorepo.

Development

Run the development server:

pnpm dev

To develop saleor-app-checkout app locally, you need to create a tunnel for it. The tunnel will enable you to display it within your Saleor Dashboard. If you want to read more about Saleor Apps architecture, see the documentation.

To create a tunnel, run:

npx saleor app tunnel 3001

where 3001 is the port on which saleor-app-checkout runs by default. Alternative ways of creating a tunnel are described here.

Note
Argument --force-install is required only the first time you run the command in order to install the application inside Saleor Dashboard and save the token.

Open the app by using the tunnel URL received from saleor app tunnel (example: https://saleor-app-checkout-xyz-my-org.saleor.live) in your browser to see the result.

Warning
The tunnel needs to be running in the background. Please don't kill it during the development.

Note
Tunnel might break if you change your Internet connection. If you can't access the app from tunnel please restart it

Alternative way to obtain the token

Token can also be generated using the CLI command:

npx saleor app token

Now, create an empty JSON file named .saleor-app-auth.json and paste the token there. The file should look like this:

{
  "token": "(your application's auth token)",
  "domain": "(your Saleor GraphQL API URL)"
}

Production

To build for production, run the following command:

cd ../.. && pnpm run build:saleor-app-checkout

Note
The command needs to be run from root of the monorepo. Otherwise Turborepo won't be able to build the app

The deployed app needs to have auth token set manually by an environment variable. Install the app in Saleor and use Saleor CLI to generate the token:

saleor app token

Then set the SALEOR_APP_TOKEN environment variable value to the token you've received from Saleor and redeploy the app.

Other

Alternatives to saleor app tunnel

You can also use ngrok, but you would need to update env variables each time you open tunnel (on free plan) with new domain ngrok assigned you.

After you do that use saleor app install to install the app in your Saleor instance.

The tunnel needs to use https protocol with valid SSL certificate, otherwise you won't receive webhook calls.

Env Variables

Environment variables contain secrets that can lead to compromising your store data

When deploying to Vercel you can set them on the configuration page

When running app locally you can use the .env.local file. It should not be included in your git repository.

Backend variables

  • SALEOR_APP_TOKEN — App's token generated by Saleor after the app was installed
  • SETTINGS_ENCRYPTION_SECRET — Random string used for encrypting apps configuration

To generate a random secret you can use OpenSSL:

openssl rand -hex 256

Learn more about installing third-party apps in Saleor docs

  • DEBUG_APP_URL - URL to the deployed checkout app. Used when running app locally and tunneling requests by using saleor tunnel

Warning
This variable should be used for local development only! It will be ignored in production deployment.

In production this URL is taken from Host header in each request

Frontend variables

Each variable starting with NEXT_PUBLIC is exposed to frontend

Testing

To test React components you must use jsdom runtime (the default is node). Add this comment at the top of the test file:

/** @jest-environment setup-polly-jest/jest-environment-node */

Mocking requests

Mocking configuration works both in browser and Node environment

Recording

For mocking requests made in tests we use Polly.js. By default, if requests are made in tests and are not mocked the test will fail.

To record requests run tests by using the test:record command:

pnpm run test:record

This command sets POLLY_MODE env variable to record.

Recordings are stored in recordings folder.

Manual mocks

To write manual mocks we use Mock Service Worker library. Any REST API route or GraphQL operation that is mocked using msw won't be recorded by Polly.js.

Mocks for msw are located in mocks/handlers

Checkout Storefront

Checkout Storefront is available at /checkout-spa/?saleorApiUrl=<YOUR_SALEOR_API_URL>.

You'll need a token to use the checkout. A new checkout session can be generated either in your storefront or in the GraphQL Playground. You could use a preexisting checkout as well.

Warning
If a given checkout has customer already attached, it'll become private, and you won't be able to fetch its data from the api without the same customer being logged in your current browser. Checkout uses Saleor SDK for authentication.

To generate checkout in GraphQL API and retrieve its id:

mutation {
  checkoutCreate(
    input: {
      channel: "default-channel"
      lines: [{ variantId: "UHJvZHVjdFZhcmlhbnQ6MjE0", quantity: 1 }]
    }
  ) {
    checkout {
      id
    }
  }
}

Learn more about creating checkout sessions in Saleor docs

Copy http://localhost:3001/checkout-spa/?saleorApiUrl=<YOUR_SALEOR_API_URL>&checkout=<TOKEN>, replace YOUR_SALEOR_API_URL with a URL to Saleor GraphQL endpoint, TOKEN with the token of your checkout session and opne it in your browser.

More info

See checkout-storefront package for more information.