## Stripe Apps: Building and Managing Integrations

This documentation set provides comprehensive guidance on developing, deploying, and managing applications within the Stripe ecosystem, referred to as "Stripe Apps." It covers everything from initial setup and authentication to UI development, distribution, and ongoing maintenance.

### Core Concepts and Getting Started

*   **Stripe Apps Overview**: Introduces the concept of Stripe Apps, their capabilities, and how they extend Stripe's functionality by embedding custom UIs or orchestrating the Stripe API. It also outlines the different types of apps you can build: back-end, front-end, and full-stack.
*   **Getting Started with Stripe Apps**: Guides new developers through the process of building a basic "Hello, world!" Stripe App, including setting up the Stripe CLI and creating a UI extension.
*   **How Stripe Apps Work**: Explains the fundamental architecture of Stripe Apps, including their frontend and backend components, and how they interact with the Stripe Dashboard and API.
*   **Common Use Cases**: Illustrates practical applications of Stripe Apps, categorized by app type (back-end, front-end, full-stack), providing examples of how to sync data, extend UIs, and automate workflows.

### Development and Customization

*   **Build a UI**: Details how to create custom user interfaces within the Stripe Dashboard using TypeScript, React, and Stripe's UI Extensions SDK and UI toolkit.
*   **UI Extensions**: Explains the system for rendering custom UIs within Stripe's products using TypeScript and React, highlighting differences from standard browser-based React applications.
*   **Component Hierarchy Constraints**: Outlines the rules and constraints that govern how UI components can be composed to ensure predictable and functional user interfaces.
*   **UI Components**: Serves as a reference for all available UI components in the Stripe Apps library, including detailed descriptions, props, and usage examples for elements like Buttons, Forms, Charts, and more.
    *   Specific component documentation includes: Accordion, Badge, Banner, BarChart, Box, Button, ButtonGroup, Checkbox, Chip, ContextView, DateField, DetailPageModule, DetailPagePropertyList, DetailPageTable, Divider, FocusView, FormFieldGroup, Icon, Img, Inline, LineChart, Link, List, Menu, OnboardingView, OverviewPage, PropertyList, Radio, SearchField, Select, SettingsView, SignInView, Sparkline, Spinner, Switch, Table, Tabs, TaskList, TextArea, TextField, Toast, Tooltip.
*   **Design Your App**: Provides guidelines, philosophy, and tools for designing Stripe Apps, emphasizing platform consistency, accessibility, and branding.
*   **Style Your App**: Explains how to style UI components using provided design tokens to match the Stripe Dashboard's visual appearance and ensure consistency.
*   **Next Generation UI Components**: Introduces early access to updated UI components that represent future SDK releases, aiming to provide new capabilities without breaking changes.

### Authentication and Authorization

*   **API Authentication Methods**: Details the different methods for authenticating requests to the Stripe API on behalf of users, including Platform keys, OAuth 2.0, and Restricted API keys.
*   **OAuth 2.0**: Explains how to use the industry-standard OAuth 2.0 for authenticating requests, including the user authentication flow and app development steps.
*   **Restricted API Key Authentication**: Describes how to use Restricted API Keys (RAKs) for secure authentication, providing users with keys that have specific, limited permissions.
*   **Add Authorization Flows**: Guides on implementing PKCE OAuth workflows within Stripe Apps to retrieve access tokens from OAuth providers directly from the Dashboard.
*   **Store Secret Credentials and Tokens**: Explains how to securely store sensitive data like authentication credentials using the Secret Store API.

### Backend and Logic

*   **Add Server-Side Logic**: Covers how to integrate self-hosted backend services to handle user actions, process data, and interact with webhooks.
*   **Back-end App Example**: Provides a guide for building a Stripe App that performs backend processing without a user interface.
*   **Front-end App Example**: Demonstrates how to build a Stripe App that renders a user interface in the Stripe Dashboard without backend processing.
*   **Full-stack App Example**: Shows how to build a Stripe App with both a user interface and backend functionality.

### Deployment and Distribution

*   **Distribution Options**: Outlines the methods for sharing Stripe Apps with users, including publishing on the Stripe App Marketplace or distributing privately.
*   **Upload and Install Your Stripe App**: Guides on making your app available to team members by uploading it to the test mode sandbox.
*   **How to Publish an App to the Stripe App Marketplace**: Details the process of getting an app approved for the Stripe App Marketplace, including requirements and the review process.
*   **Stripe Apps Quality Requirements**: Lists the qualitative requirements for apps to be accepted onto the App Marketplace.
*   **Test Your App Externally**: Explains how to set up and distribute test versions of your app to other accounts before official publication.
*   **Manage Your App's Versions and Releases**: Covers app versioning and releases to manage changes and ship new versions of your app.

### Migration and Legacy

*   **Migrate an Extension to Stripe Apps**: Explains why and how to migrate legacy extensions to the newer Stripe Apps platform for better discoverability and permissions.
*   **Migrate a Plugin to Stripe Apps or Stripe Connect**: Provides guidance on migrating third-party integrations that previously relied on secret API keys.
*   **Migrate a Plugin to an OAuth 2.0 App**: Details the process of migrating a plugin to use OAuth 2.0 authentication within Stripe Apps.
*   **Migrate a Plugin to a RAK App**: Guides on migrating a plugin to use Restricted API Key (RAK) authentication within Stripe Apps.
*   **Legacy Extensions**: Provides historical reference information about the deprecated extensions integration pattern.

### App Configuration and Environment

*   **Enable Sandbox Support**: Details how to enable your public app for sandbox installation, allowing users to evaluate features in a testing environment.
*   **Handle Different Modes**: Explains how to adapt your app to handle both live mode and sandboxes, including considerations for webhooks.
*   **Enable Local Network Access**: Guides on enabling Local Network Access (LNA) for app previewing, which is necessary for downloading assets from a local HTTP server.
*   **App Settings Page**: Describes how to create a page for users to configure their app settings within the Stripe Dashboard.
*   **Onboarding**: Provides guidance and best practices for designing intuitive and polished onboarding flows for your app users.
*   **Post-Install Actions**: Explains how to support additional configurations that occur after a user installs your app.
*   **Deep Links**: Covers how to create deep links that navigate users directly to your Stripe App within the Dashboard.
*   **Install Links**: Details how to allow users to install public apps outside of the Stripe App Marketplace.

### Reference and Tools

*   **App Manifest Reference**: Documents all fields, types, and descriptions for your app manifest file (`stripe-app.json`), which describes how your app integrates with Stripe.
*   **Stripe Apps CLI Reference**: Introduces the command-line interface for creating, developing, configuring, and uploading Stripe Apps.
*   **Permissions Reference**: Lists available events and their required permissions, explaining how to manage app permissions in the manifest.
*   **Extension SDK API Reference**: Documents the context props and utility functions available to UI extensions for interacting with users and the Stripe Dashboard.
*   **Viewports Reference**: Lists available viewports for Stripe Apps and how they determine where your UI extension appears in the Dashboard.
*   **Route Descriptors**: Explains how to implement soft, context-preserving navigation between Dashboard pages from your Stripe App.
*   **Sample Apps**: Provides working examples of Stripe Apps on GitHub to serve as starting points for your own development.
*   **UI Extension Developer Tools**: Details the bundled developer tools for type checking, linting, and testing your app's code.
*   **Upgrade Stripe's UI Extension SDK**: Guides on upgrading your app to the latest version of the UI extension SDK, including information on breaking changes.
*   **Design Patterns**: Offers recommended design patterns for building Stripe Apps to ensure consistency, clarity, and scalability. This includes patterns for:
    *   Full Page Apps
    *   Action Buttons
    *   Onboarding Flow
    *   Additional Context
    *   Back Link
    *   Communicating State
    *   Demo Content
    *   Empty State
    *   Filter Controls
    *   Lists
    *   Loading
    *   Progress Stepping
    *   Redirects
    *   Settings Sign In
    *   Sign In Template
    *   Sign Out
    *   Waiting Screens
*   **UI Testing**: Explains how to test your Stripe App's UI using utilities and helpers provided by the Extension SDK.