diff --git a/docs/apl.md b/docs/apl.md index f6acb68..1a09968 100644 --- a/docs/apl.md +++ b/docs/apl.md @@ -14,7 +14,7 @@ APL is an interface for managing auth data of registered Apps. Implementing it d ## Example implementation -Let's create an APL, which uses redis for data storage: +Let's create an APL, which uses Redis for data storage: ```ts import { createClient } from "redis"; @@ -66,3 +66,74 @@ const handler = async (request) => { // the middleware will reject request if it's domain has not been registered export default withRegisteredSaleorDomainHeader({ apl: redisAPL })(handler); ``` + +### Using different APL depending on the environment + +Depending on the environment your app is working on, you may want to use a different APL. For example during local development you might like to use `FileAPL`, because it does not require any additional infrastructure. Deployed apps on the other hand need more robust solution. + +To handle both scenarios, initialize the proper APLs in your code based on it's environment. In your application code: + +```ts +// lib/saleorApp.ts + +import { FileAPL, VercelAPL } from "@saleor/app-sdk/APL"; + +// Based on environment variable the app will use a different APL: +// - For local development store auth data in the `.auth-data.json`. +// - For app deployment on Vercel with Saleor CLI, use vercelAPL. +export const apl = process.env.VERCEL === "1" ? new VercelAPL() : new FileAPL(); +``` + +Now you can use it for in your view: + +```ts +import { SALEOR_DOMAIN_HEADER } from "@saleor/app-sdk/const"; +import { withRegisteredSaleorDomainHeader } from "@saleor/app-sdk/middleware"; +import type { Handler } from "retes"; +import { toNextHandler } from "retes/adapter"; +import { Response } from "retes/response"; + +// import created APL +import { apl } from "@lib/saleorApp"; + +const handler: Handler = async (request) => { + const saleorDomain = request.headers[SALEOR_DOMAIN_HEADER]; + + // Get auth data + const authData = apl.get(saleorDomain); + + // view logic... + + return Response.OK(); +}; + +export default toNextHandler([withRegisteredSaleorDomainHeader({ apl }), handler]); +``` + +## Available APLs + +### FileAPL + +File based storage of auth data, intended for local development. Data are stored in the `.saleor-app-auth.json` file. You'll be able to develop app without additional dependencies or infrastructure. + +Please note: this APL supports single tenant only (new registrations overwrite previous ones) and should not be used on production. + +### VercelAPL + +Single tenant APL dedicated for apps deployed on Vercel. Apps deployed from Marketplace and CLI automatically set up Vercel project for this APL (`SALEOR_REGISTER_APP_URL` and `SALEOR_DEPLOYMENT_TOKEN` variables). + +The auth data are stored using environment variables: + +```mermaid +sequenceDiagram + participant SI as Saleor Instance + participant A as App + participant SSI as Saleor x Vercel integration + participant V as Vercel + + SI->>+A: Register + A->>SSI: Update auth data + A->>-SI: Register completed + SSI->>V: Set auth data as environment variables + V->>A: Redeploy the application +```