Skip to content

fcakyon/claude-codex-settings / plugins/stripe-skills/skills/stripe-apps

stripe-apps

Verified

Build, modify, or review Stripe Apps and extensions using the relevant documentation and reference guides. Use for custom Stripe Dashboard UI, stripe-app.yaml, @stripe/ui-extension-sdk, @stripe/extensibility-sdk, script extensions, extension interfaces, custom workflow actions, and apps that authenticate to Stripe or react to events. Also use when deciding whether a Stripe extension can support the user's billing or workflow requirements.

references/publishing.md

View on GitHub
# Publishing — versioning, releases, sandboxes, live mode, marketplace

## Publishing

How to version, release, and publish your Stripe App.

## Sandboxes and live mode

**Plain-language:** “A sandbox uses test data so you can try things safely. Live mode uses real customer data. Always build and test in a sandbox first.”

| Mode | Data | When to use |
| --- | --- | --- |
| Sandbox | Test data (test cards, test customers) | Development and QA |
| Live mode | Real customer and payment data | Production |

**Workflow:** Upload → install in a sandbox → test thoroughly → install in live mode.

**Don’t skip sandbox testing.** Even if your app looks correct locally with `stripe apps start`, you must install it in a sandbox and verify it works with the actual install flow before going live.

## Versioning

Bump `version` in `stripe-app.yaml` before each upload:

```yaml
id: com.example.my-app
version: 1.0.1
name: My App
```

Use semantic versioning:

- `1.0.0` — initial release
- `1.0.1` — bug fix
- `1.1.0` — new feature (backward compatible)
- `2.0.0` — breaking change or major feature

**Rules:**

- 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
- You can have multiple uploaded versions; you choose which one to install
- Stripe auto-upgrades installed users to the latest release — they don’t need to do anything **unless** you changed permissions

## Upload and release workflow

```bash
# 1. Bump version in stripe-app.yaml, then:
stripe apps upload

# 2. Go to Dashboard → Apps → your app → version history
# 3. Click the version you want to release
# 4. Click "Set as external test version" or "Release" (live mode)
```

## When you change permissions

This is a common source of bugs. When you add new permissions:

1. Update `stripe-app.yaml` with the new permissions
2. Bump the version and upload
3. Existing users are notified by email
4. The **“Review Permissions”** button appears — but only on the **Apps workload page** ([dashboard.stripe.com/apps](https://dashboard.stripe.com/apps)), **not on the app itself**
5. The app returns an **invalid-request error** for the new permissions until the user clicks “Review Permissions” and re-authorizes

**Always warn users about this step** when you change permissions. Many users miss the notification and think the app is broken.

**How to notify users:** Consider adding a banner in your app UI that detects when a required permission is missing and guides the user to re-authorize.

## Publishing to the Stripe Apps Marketplace

For public apps — making your app available to all Stripe users.

### Requirements

Before submitting:

- Verified email address on your Stripe account
- Business details filled in (legal name, address)
- App passes [review requirements](https://docs.stripe.com/stripe-apps/review-requirements.md)
- Connect platform accounts can’t publish marketplace apps

### Submission

1. Go to [Dashboard → Apps](https://dashboard.stripe.com/apps)
2. Select your app
3. Click **Submit for review**

Stripe reviews your app for security, functionality, and compliance with their guidelines.

### Review requirements overview

- App must work correctly in supported sandboxes and live mode
- No prohibited content or misleading claims
- Privacy policy URL required
- Support contact required
- App icon and screenshots required

### After approval

Your app appears in the [Stripe Apps Marketplace](https://marketplace.stripe.com/). Any Stripe user can install it.

## Troubleshooting uploads

**Successful upload looks like:**

```
Uploading... Done
Your app has been uploaded to version 0.0.1.
```

**Common upload failures and fixes:**

| Error | Cause | Fix |
| --- | --- | --- |
| `Invalid manifest` / validation failed | Missing required fields or malformed YAML | Check indentation; ensure `id:`, `version:`, `name:` are present |
| `Build failed` / TypeScript errors | UI component has type/import errors | Run `pnpm build` locally first to see the exact error |
| `Version already exists` | Already uploaded this version number | Bump `version` in stripe-app.yaml (for example, 0.0.1 → 0.0.2) |
| `Permission denied` / `Not authenticated` | CLI not logged in or wrong account | Run `stripe login` and verify with `stripe config --list` |
| `connect-src` / CSP error | App calls a URL not declared in content_security_policy | Add the URL to `content_security_policy.connect-src` in stripe-app.yaml |
| `extensions field required` | Missing `extensions: []` in stripe-app.yaml | Add `extensions: []` even if you have no backend extensions |
| `Component not found` | Viewport references a component name that doesn’t match your export | Ensure `component:` in stripe-app.yaml matches your default export name |

**Debugging steps when upload fails:**

1. Read the full error message — it usually says exactly what’s wrong
2. Run `pnpm build` to check for TypeScript/build errors locally
3. Validate your stripe-app.yaml has all required fields (id, version, name, declarations)
4. Check that file paths match (ui/src/views/App.tsx, not a renamed file)
5. If still stuck: `stripe apps upload --verbose` for detailed output

## Sandboxes for app development

Sandboxes provide isolated environments for safe app development and testing.

**Benefits of using Sandboxes:**

- Isolated from your live account — test destructive operations safely
- Each sandbox has its own app installation and signing secrets
- Useful for testing onboarding flows, uninstall/reinstall cycles, and permission changes

**How to use:**

1. Create a sandbox from Dashboard → Sandboxes
2. Run `stripe apps start` targeting the sandbox
3. Upload and install your app in the sandbox to test the full install flow
4. When ready, upload to your main account for production use
brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation).Stars: 322kUpdated Claude CodeCodexVerifiedInstall
brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK).Stars: 198kUpdated Claude CodeCodexVerifiedInstall