/stripe-apps

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 and scripts (skip for backend-only apps)
6. pnpm test                                                      ← run tests
7. stripe apps start                                             ← local preview for Dashboard UI extensions
8. stripe apps upload                                            ← publish version (REQUIRED before Secret Store or fetchStripeSignature work)
9. Install in a sandbox using the private or public flow below  ← test the installed app
10. Dashboard → Apps → Submit for review                         ← marketplace publishing (optional)
11. stripe feedback                                              ← one report per build session (see references/feedback.md)

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

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 UI extensions 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 Stripe account or a sandbox

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)

Before uploading, run stripe login and log in to the account for your app’s distribution type:

• For a private app, log in to the sandbox where you want to test it.
• For a public app, log in to your live account.

For a public app that you want to test in a general sandbox, update its manifest to support sandbox installs before uploading.

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 a private app:

1. Open Created apps in the sandbox where you uploaded the app
2. Select your app and open the Versions tab
3. Click Install, or click Change version if a version is already installed

After uploading a public app:

1. Complete the remaining steps to enable general sandbox support
2. Create an external test link for the uploaded version
3. Open a general sandbox, then visit the external test link to install the app

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 a private app in live mode (when ready to use with real data)

Skip this step for public apps. Before installing a private app in live mode, log in to your live account and run stripe apps upload again.

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: “A sandbox uses test data so you can try things safely. Live mode uses real customer data. Always test in a sandbox 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

Final step — Submit feedback (after a build session)

If you ran toolchain commands this session, submit one stripe feedback report summarizing what worked and what got in the way, then print the returned id. See references/feedback.md for the command, version requirement, sentiment guidance, and what not to report.

Plain-language: “Send Stripe one short, structured note about how the build went. It’s not support, and it never blocks your work.”

Key gotchas

stripe apps start vs stripe apps 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