add embedded checkout
This commit is contained in:
JCEEE
@@ -0,0 +1,191 @@
|
||||
# Workflow — end-to-end build order
|
||||
|
||||
## MANDATORY — Full development loop (quick reference)
|
||||
|
||||
Follow this exact sequence for every new app. Do NOT skip or reorder steps.
|
||||
|
||||
```
|
||||
1. stripe plugin install apps && stripe plugin install generate ← one-time CLI setup
|
||||
2. stripe generate app <name> && cd <name> ← scaffold (NOT `stripe apps create`)
|
||||
3. pnpm install ← install deps
|
||||
4. [modify scaffolded files + create missing ones] ← implement (only add what scaffold doesn't provide)
|
||||
5. pnpm build ← compile UI (skip for backend-only apps)
|
||||
6. pnpm test ← run tests
|
||||
7. stripe apps start ← local preview in Dashboard
|
||||
8. stripe apps upload ← publish version (REQUIRED before Secret Store or fetchStripeSignature work)
|
||||
9. Install in test mode from Dashboard → Apps ← test the installed app
|
||||
10. Dashboard → Apps → Submit for review ← marketplace publishing (optional)
|
||||
```
|
||||
|
||||
**BLOCKED:** Do NOT use `stripe apps create` — it does not scaffold correctly. Always use `stripe generate app`.
|
||||
|
||||
**MANDATORY:** Do NOT create files manually when `stripe generate app` provides them. The scaffold creates a V2 workspace: `stripe-app.yaml`, `package.json`, `pnpm-workspace.yaml`, and `ui/src/views/App.tsx` with the correct structure. Only create files that the scaffold doesn’t provide (e.g., `server.js` for your backend). Modify scaffolded files as needed — don’t rewrite them from scratch.
|
||||
|
||||
## End-to-end build order (detailed)
|
||||
|
||||
Follow this sequence exactly. Deviating from it is the #1 source of confusion when building Stripe Apps.
|
||||
|
||||
### Step 1 — Prerequisites (one-time setup)
|
||||
|
||||
Install the Stripe CLI, then install the required plugins:
|
||||
|
||||
```bash
|
||||
# Install the apps plugin (creates and manages apps)
|
||||
stripe plugin install apps
|
||||
|
||||
# Install the generate plugin (scaffolds new apps)
|
||||
stripe plugin install generate
|
||||
```
|
||||
|
||||
**Plain-language:** “These are tools that let the Stripe CLI create and manage apps. You only need to do this once.”
|
||||
|
||||
Verify your CLI version is 1.25.0 or newer:
|
||||
|
||||
```bash
|
||||
stripe version
|
||||
```
|
||||
|
||||
### Step 2 — Create the app
|
||||
|
||||
```bash
|
||||
stripe generate app <your-app-name>
|
||||
cd <your-app-name>
|
||||
```
|
||||
|
||||
This creates a new V2 workspace with the correct directory structure, `stripe-app.yaml` manifest, and example UI extension.
|
||||
|
||||
**What gets created:**
|
||||
|
||||
```
|
||||
<your-app-name>/
|
||||
├── stripe-app.yaml # V2 app manifest (YAML) — name, permissions, viewports
|
||||
├── package.json # workspace root
|
||||
├── pnpm-workspace.yaml # declares workspace packages
|
||||
├── ui/
|
||||
│ ├── package.json
|
||||
│ └── src/
|
||||
│ └── views/
|
||||
│ └── App.tsx # main UI component
|
||||
├── extensions/ # script extensions (one subdir per extension)
|
||||
└── README.md
|
||||
```
|
||||
|
||||
### Step 3 — Install dependencies
|
||||
|
||||
```bash
|
||||
pnpm install
|
||||
```
|
||||
|
||||
### Step 4 — Build and test (UI apps)
|
||||
|
||||
For apps with a UI extension, compile TypeScript and run tests:
|
||||
|
||||
```bash
|
||||
pnpm build
|
||||
pnpm test
|
||||
```
|
||||
|
||||
Backend-only apps without TypeScript can skip this step.
|
||||
|
||||
### Step 5 — Develop locally
|
||||
|
||||
```bash
|
||||
stripe apps start
|
||||
```
|
||||
|
||||
**Plain-language:** “This opens your app live in your Stripe Dashboard while you build it. Changes you save show up immediately — you don’t need to upload anything yet.”
|
||||
|
||||
**What this does:**
|
||||
|
||||
- Opens a browser to your Stripe Dashboard with your app running live
|
||||
- Watches for file changes and hot-reloads
|
||||
- Works against your live or test Stripe account
|
||||
|
||||
**Notes:**
|
||||
|
||||
- `stripe apps start` requires browser access; Safari is not supported — use Chrome or Firefox
|
||||
- This does **not** persist — your app is only visible while the command is running
|
||||
- The app is not installed on your account yet; it’s only previewed locally
|
||||
|
||||
### Step 6 — Upload a version (when ready to share or test permissions and secrets)
|
||||
|
||||
```bash
|
||||
stripe apps upload
|
||||
```
|
||||
|
||||
**What this does:**
|
||||
|
||||
- Creates a new version of your app in the Stripe Dashboard
|
||||
- Generates the signing secret needed for `fetchStripeSignature` and the Secret Store API
|
||||
- Makes the version available to install
|
||||
|
||||
**After uploading:**
|
||||
|
||||
1. Go to [Dashboard → Apps](https://dashboard.stripe.com/apps)
|
||||
2. Find your app
|
||||
3. Click **Install in test mode** to install it on your account
|
||||
|
||||
**When you need to upload before `stripe apps start`:**
|
||||
|
||||
- Using the Secret Store API
|
||||
- Using `fetchStripeSignature` to authenticate the UI to a backend
|
||||
- Testing permissions that require the app to be installed
|
||||
|
||||
### Step 7 — Install in live mode (when ready to use with real data)
|
||||
|
||||
1. Go to the [Dashboard → Apps page](https://dashboard.stripe.com/apps)
|
||||
2. Select your app
|
||||
3. Choose “Private to your account”
|
||||
4. Select the version to install
|
||||
5. Click Install
|
||||
|
||||
**Plain-language:** “Test mode uses fake data so you can try things safely. Live mode uses real customer data. Always test in test mode first.”
|
||||
|
||||
### Step 8 — Ship a new version
|
||||
|
||||
1. Bump `version` in `stripe-app.yaml` (use semantic versioning: `1.0.0`, `1.0.1`, `2.0.0`)
|
||||
2. Upload:
|
||||
```bash
|
||||
stripe apps upload
|
||||
```
|
||||
3. Go to Dashboard → Apps → your app → version history → install the new version
|
||||
|
||||
**Important:** Versions must be uploaded in order. If you upload `2.0.0` before `1.0.0`, `2.0.0` won’t be available for release.
|
||||
|
||||
### Step 9 — Publish to the marketplace (optional)
|
||||
|
||||
To submit your app for marketplace review:
|
||||
|
||||
1. Go to [Dashboard → Apps](https://dashboard.stripe.com/apps)
|
||||
2. Select your app
|
||||
3. Click **Submit for review**
|
||||
|
||||
**Requirements:**
|
||||
|
||||
- Verified email address on your Stripe account
|
||||
- Business details filled in
|
||||
- App passes [review requirements](https://docs.stripe.com/stripe-apps/review-requirements.md)
|
||||
|
||||
## Key gotchas
|
||||
|
||||
**`stripe apps start` vs `stripe apps upload`**
|
||||
|
||||
| | `stripe apps start` | `stripe apps upload` |
|
||||
| --- | --- | --- |
|
||||
| Purpose | Local development | Publish a version |
|
||||
| Persistence | Not persistent — only while command runs | Persists in Stripe Dashboard |
|
||||
| Secret Store | Not available | Available after upload |
|
||||
| `fetchStripeSignature` | Only works after at least one upload | Works after upload |
|
||||
|
||||
**After updating permissions:**
|
||||
|
||||
- Users must re-authorize the app
|
||||
- The “Review Permissions” button only appears on the **Apps workload page** — not on the app itself
|
||||
- The app returns an invalid-request error for undeclared permissions until the user re-authorizes
|
||||
- Always warn users about this step when you change permissions
|
||||
|
||||
**Sandboxes for app development:**
|
||||
|
||||
- Use sandboxes for safe testing — they provide isolated environments where you can test without affecting live data
|
||||
- Each sandbox has its own app installation and signing secrets
|
||||
- Useful for testing destructive operations or onboarding flows
|
||||
Reference in New Issue
Block a user