Skip to content
This repository has been archived by the owner on Jul 29, 2022. It is now read-only.

Latest commit

 

History

History
158 lines (99 loc) · 6.21 KB

README.md

File metadata and controls

158 lines (99 loc) · 6.21 KB
Raw

Checkout App

Saleor App for payment gateways configuration and layout customisation of Saleor Checkout

Setup

Development

Run the development server:

pnpm dev

Start tunnel, so that Checkout App is available from Internet for webhooks:

Note: 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 - add NEXT_PUBLIC_SALEOR_API_URL env variable in apps/saleor-app-checkout/.env.local file with URL to your Saleor GrpahQL API endpoint

npx saleor app tunnel 3001

Choose Yes when asked if the app should be installed.

Warning: Make sure that the app is running on port 3001 otherwise it won't be available from the tunnel

lsof -i :3001

Note: 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

After the app is installed in Saleor, a .auth_token file should be created with token used for authenticating requests made to your Saleor instance.

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.

Production

To build for production, run the following command:

cd ../.. && pnpm run build:payments-app

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 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.

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

Note: by default SALEOR_API_URL env variable from root of monorepo is used for the value. If you want to customise it, you can add a separate .env.local file, which won't be stored in git repository

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.

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.

⚠️ Note that 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: "UHJvZHVjdFZhcmlhbnQ6MjAz", quantity: 1 }]
    }
  ) {
    checkout {
      id
    }
  }
}

Learn more about creating checkout sessions in Saleor docs

Open localhost:3001/checkout-spa?checkout= in your browser and add the your token to the url.

More info

See checkout-storefront package for more information.