famdone/.agents/skills/stripe-apps/references/workflow.md

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:

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

stripe version

Step 2 — Create the app

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

pnpm install

Step 4 — Build and test (UI apps)

For apps with a UI extension, compile TypeScript and run tests:

pnpm build
pnpm test

Backend-only apps without TypeScript can skip this step.

Step 5 — Develop locally

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)

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

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

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