## Stripe Apps Documentation

This documentation set covers the development and management of Stripe Apps, a platform that allows developers to extend Stripe's functionality and embed custom user experiences directly within the Stripe Dashboard.

### Core Concepts

*   **Stripe Apps Overview:** Provides a high-level introduction to Stripe Apps, their capabilities, and how they integrate with the Stripe platform.
*   **How Stripe Apps Work:** Explains the fundamental architecture and components of Stripe Apps, including frontend and backend interactions.
*   **Common Use Cases:** Illustrates various scenarios and business needs that can be addressed by building Stripe Apps, categorized by app type (backend, frontend, full-stack).

### Building Your App

*   **Getting Started with Stripe Apps:** Guides users through the initial steps of building a simple Stripe App, including setting up the development environment.
*   **Build an App:** General guidance on the app development process.
*   **Build a UI:** Details on creating custom user interfaces within the Stripe Dashboard using React and Stripe's UI Extensions SDK.
    *   **How UI extensions work:** Explains the sandboxed iframe environment for UI extensions.
    *   **Next generation UI components:** Introduces upcoming UI component updates.
    *   **Component hierarchy constraints:** Outlines rules for composing UI components.
    *   **UI testing:** Provides tools and methods for testing your app's UI.
    *   **UI extension developer tools:** Details the bundled tools for type checking, linting, and testing.
    *   **Upgrade Stripe's UI extension SDK:** Guides on updating to the latest SDK versions and managing breaking changes.
*   **Add server-side logic:** Explains how to integrate a self-hosted backend for secure third-party integrations, webhook handling, and long-lived app logic.
*   **API Authentication Methods:** Describes the different ways your app can authenticate requests to the Stripe API.
    *   **OAuth 2.0:** Details the industry-standard OAuth 2.0 flow for authentication.
    *   **Restricted API key authentication:** Explains how to use permissioned API keys for secure access.
*   **App Manifest Reference:** Provides a comprehensive guide to the `stripe-app.json` file, detailing all available fields, types, and descriptions.
*   **Permissions Reference:** Lists available events and their required permissions for your app.
*   **Extension SDK API Reference:** Documents the context props and utility functions available to UI extensions.

### App Types and Examples

*   **Back-end app example:** A guide to building a Stripe App that performs backend processing without a user interface.
*   **Front-end app example:** A guide to building a Stripe App that renders a user interface in the Stripe Dashboard.
*   **Full-stack app example:** A guide to building a Stripe App with both a user interface and backend functionality.
*   **Sample apps:** A collection of working examples to help developers understand design and code implementation.

### UI Components

This section provides detailed documentation for each UI component available in the Stripe Apps UI toolkit:

*   **UI Components:** An overview of the component library.
    *   **Accordion:** For collapsible content.
    *   **Badge:** To indicate state.
    *   **Banner:** For alerts and messages.
    *   **BarChart:** For visualizing data with bars.
    *   **Box:** A versatile container for styling and layout.
    *   **Button:** For user actions and directing attention.
    *   **ButtonGroup:** For managing layout of multiple buttons.
    *   **Checkbox:** For indicating or controlling boolean values.
    *   **Chip:** For displaying and manipulating values.
    *   **ContextView:** The root view for apps rendering in a drawer.
    *   **DateField:** For collecting date information.
    *   **DetailPageModule:** For rendering apps in Stripe dashboard pages.
    *   **DetailPagePropertyList:** For rendering apps in Stripe dashboard pages.
    *   **DetailPageTable:** For rendering apps in Stripe dashboard pages.
    *   **Divider:** For rendering a horizontal rule.
    *   **FocusView:** For dedicated task completion spaces.
    *   **FormFieldGroup:** For grouping form fields.
    *   **FullPageTabs:** For displaying sections of content.
    *   **FullPageView:** For implementing the full-page viewport.
    *   **Icon:** To display icon graphics.
    *   **Img:** For displaying images.
    *   **Inline:** For styling inline content.
    *   **LineChart:** For visualizing data as a line.
    *   **Link:** For navigation and subtle actions.
    *   **List:** For displaying collections of information.
    *   **Menu:** To present a group of actions.
    *   **OnboardingView:** For implementing onboarding flows.
    *   **OverviewPage:** For implementing overview-style layouts.
    *   **PropertyList:** For displaying data as key-value pairs.
    *   **Radio:** For mutually exclusive selections.
    *   **SearchField:** For searching and filtering content.
    *   **Select:** For picking from dropdown options.
    *   **SettingsView:** For allowing users to change app settings.
    *   **SignInView:** For rendering a sign-in screen.
    *   **Sparkline:** For succinct data visualization.
    *   **Spinner:** To indicate loading states.
    *   **Switch:** For indicating or controlling boolean values.
    *   **Table:** For displaying tabular data.
    *   **Tabs:** For displaying sections of content.
    *   **TaskList:** For tracking user progress through tasks.
    *   **TextArea:** For multi-line text input.
    *   **TextField:** For single-line text input.
    *   **Toast:** To inform users of temporary status.
    *   **Tooltip:** To provide additional contextual information.

### Design and Patterns

*   **Design your app:** Guidelines and philosophy for designing Stripe Apps.
*   **Style your app:** Information on styling UI components using provided design tokens.
*   **Design patterns for Stripe Apps:** Recommended patterns for consistent, clear, and scalable app design.
    *   **Full page apps:** Building custom Stripe Dashboard pages.
    *   **Action buttons:** Placement and usage of action buttons.
    *   **Onboarding flow:** Designing user onboarding experiences.
    *   **Additional context:** Providing extra information during onboarding.
    *   **Back link:** Implementing navigation to previous pages.
    *   **Communicating state:** Guiding users with feedback and status updates.
    *   **Demo content:** Tips for displaying app demonstrations.
    *   **Empty state:** Informing users when no data is available.
    *   **Filter controls:** Using chips for filtering table rows.
    *   **Lists:** Displaying collections of information.
    *   **Loading:** Using spinners for data loading indicators.
    *   **Progress stepping:** Guiding users through multi-step tasks.
    *   **Redirects:** Creating clear redirects for users.
    *   **Settings sign in:** Onboarding users on a settings page.
    *   **Sign in template:** Using the `SignInView` component.
    *   **Sign out:** Enabling users to sign out of the app.
    *   **Waiting screens:** Informing users about wait times and next steps.

### App Management and Distribution

*   **Create an app:** Basic steps to create a new Stripe App.
*   **Upload and install your Stripe App:** Instructions for making your app available to team members.
*   **Distribution options:** Ways to share your Stripe Apps with users (publicly or privately).
*   **Test your app externally:** Setting up and distributing test versions before publication.
*   **Enable sandbox support for your public app:** Configuring your app for sandbox installations.
*   **Handle different modes:** Adapting your app for live mode and sandboxes.
*   **Enable local network access:** Allowing local network access for app preview.
*   **Manage your app's versions and releases:** Understanding app versioning and releases.
*   **How to publish an app to the Stripe App Marketplace:** Guide to getting your app approved for the marketplace.
*   **Stripe Apps quality requirements:** Understanding the quality standards for marketplace apps.
*   **Promote your app:** Information on partnering with Stripe for app growth.
*   **Using install links:** Allowing users to install public apps outside the Stripe App Marketplace.
*   **Add deep links:** Creating deep links to navigate users to your Stripe app.
*   **Using roles in UI extensions:** Tailoring functionality based on user roles.
*   **App settings page:** Creating a page for users to configure app settings.
*   **Store secret credentials and tokens in your app:** Using the Secret Store API for secure data persistence.

### Migration

*   **Migrate an extension to Stripe Apps:** Reasons and steps for migrating legacy extensions to Stripe Apps.
*   **Migrate a plugin to Stripe Apps or Stripe Connect:** Understanding migration options for third-party integrations.
*   **Migrate a plugin to an OAuth 2.0 app:** Steps to migrate plugins to OAuth authentication.
*   **Migrate a plugin to a RAK app:** Steps to migrate plugins to Restricted API Key authentication.

### Reference

*   **Stripe Apps CLI reference:** Information on installing and using the command-line interface for managing Stripe Apps.
*   **Viewports reference:** A list of available viewports for Stripe Apps UI extensions.
*   **Authorization flows:** Implementing PKCE OAuth workflows.

### Legacy Extensions

*   **Legacy extensions:** Information about the deprecated extensions integration pattern and historical reference. This section clarifies that **Stripe Apps replaces extensions**, and new extensions cannot be built. Users with existing legacy extensions are directed to migrate to Stripe Apps.