Skip to content

Latest commit

 

History

History
136 lines (90 loc) · 5.81 KB

README.md

File metadata and controls

136 lines (90 loc) · 5.81 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 3000

Choose Yes when asked if the app should be installed.

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

lsof -i :3000

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 and CHECKOUT_APP_URL env variables from the root of the monorepo are used for these values. If you want to customise them, you can add a separate .env.local file which won't be stored in the git repository.

PROTIP 💡: If you need Saleor instance for tesitng, create one using Saleor CLI:

npx saleor project create && npx saleor environment create

This will create new Saleor sandbox in Saleor Cloud

⚠️ You need to use the same Saleor instance in saleor-app-checkout. Make sure you have the same value of NEXT_PUBLIC_SALEOR_API_URL variable in apps/saleor-app-checkout/.env.local

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:3000/checkout-spa?checkout= in your browser and add the your token to the url.

More info

See checkout-storefront package for more information.