## Building Stripe Apps: A Comprehensive Guide

This documentation set provides a comprehensive overview of building and managing Stripe Apps, a platform for extending Stripe's functionality and integrating third-party services directly into the Stripe Dashboard.

### Core Concepts and Getting Started

*   **Overview of Stripe Apps:** Understand the fundamental concepts behind Stripe Apps, including their purpose, capabilities, and how they can be used to authenticate users, listen for events, and automate workflows.
*   **Getting Started with Stripe Apps:** Learn the basics of app development by building, previewing, and updating a sample "Hello, world!" Stripe App. This includes setting up the Stripe CLI and understanding initial project structure.
*   **How Stripe Apps Work:** Delve into the architecture of Stripe Apps, understanding the interplay between frontend (UI extensions) and backend components, and how to leverage permissions for data access.

### Development and Building

*   **App Types:** Explore the different types of Stripe Apps you can build:
    *   **Back-end apps:** For background processing and data synchronization without a user interface.
    *   **Front-end apps:** For creating user interfaces within the Stripe Dashboard.
    *   **Full-stack apps:** Combining both frontend and backend functionalities.
*   **Building a UI:** Learn how to create custom user interfaces within the Stripe Dashboard using TypeScript, React, and Stripe's UI Extensions SDK and UI toolkit. This includes understanding views, viewports, and component hierarchy constraints.
*   **Adding Server-Side Logic:** Implement backend code to validate and process user actions and data, integrate with third-party systems, and handle webhook events.
*   **API Authentication Methods:** Choose and implement the appropriate authentication method for your app, including:
    *   **Platform Key:** For managing fewer keys per install.
    *   **OAuth 2.0:** An industry-standard protocol for secure authorization.
    *   **Restricted API Key (RAK):** For granting specific, limited permissions.
*   **Authorization Flows:** Implement secure authorization flows, including PKCE OAuth workflows, to allow users to grant your app access to their data.
*   **Storing Secrets:** Securely persist sensitive data like authentication credentials using the Secret Store API.
*   **App Settings Page:** Create a dedicated page within the Stripe Dashboard for users to configure their app settings.

### UI Components and Design

*   **UI Components Reference:** Access detailed documentation for all available UI components, including:
    *   **Layout and Structure:** `Box`, `Inline`, `Stack`, `Grid`, `Tabs`, `FullPageTabs`, `OverviewPage`.
    *   **Input and Interaction:** `Button`, `ButtonGroup`, `Checkbox`, `DateField`, `Radio`, `Select`, `Switch`, `TextArea`, `TextField`, `SearchField`.
    *   **Information Display:** `Accordion`, `Badge`, `Banner`, `BarChart`, `Chip`, `Divider`, `Icon`, `Img`, `LineChart`, `Link`, `List`, `Menu`, `PropertyList`, `Sparkline`, `Spinner`, `Table`, `DataTable`.
    *   **Task and Flow Management:** `ContextView`, `DetailPageModule`, `DetailPagePropertyList`, `DetailPageTable`, `FocusView`, `FormFieldGroup`, `OnboardingView`, `SignInView`, `TaskList`, `Toast`, `Tooltip`.
*   **Design Your App:** Understand Stripe's design philosophy, guidelines, and tools for creating a cohesive and user-friendly app experience.
*   **Style Your App:** Learn how to apply custom styles using design tokens and the provided CSS syntax to match the Stripe Dashboard's visual appearance.
*   **Design Patterns:** Follow recommended design patterns for common app functionalities like onboarding, authentication, navigation, and state management to ensure consistency and a high-quality user experience.

### Distribution, Testing, and Management

*   **Distribution Options:** Learn how to make your Stripe App available to users, either privately for your team or publicly through the Stripe App Marketplace.
*   **Upload and Install Your App:** Follow the steps to upload your app for testing and installation within your Stripe account.
*   **Testing Your App:** Implement strategies for testing your app, including external testing before public release.
*   **Enable Sandbox Support:** Configure your app to work seamlessly with Stripe's testing environments.
*   **Handle Different Modes:** Adapt your app to function correctly in both live and sandbox environments.
*   **Enable Local Network Access:** Configure your app for local development and previewing.
*   **Manage App Versions and Releases:** Understand app versioning and the release process for shipping updates.
*   **Publish Your App:** Learn the process of submitting your app to the Stripe App Marketplace and the associated review requirements.
*   **Stripe Apps Quality Requirements:** Familiarize yourself with the quality standards for apps listed on the Stripe App Marketplace.
*   **Promote Your App:** Discover opportunities for co-marketing and growth through the Stripe Partner Ecosystem.

### Migration and Legacy Information

*   **Migrating to Stripe Apps:** Guidance on migrating existing legacy extensions to the modern Stripe Apps platform.
*   **Migrate a Plugin:** Specific instructions for migrating plugins to OAuth 2.0 or Restricted API Key (RAK) based Stripe Apps.
*   **Legacy Extensions:** Information about the deprecated extensions integration pattern.

### Reference and Advanced Topics

*   **App Manifest Reference:** A detailed guide to the `stripe-app.json` file, outlining all available fields, types, and descriptions.
*   **Stripe Apps CLI Reference:** Learn how to use the command-line interface to manage your Stripe App development lifecycle.
*   **Permissions Reference:** Understand available events and their required permissions for your app.
*   **Extension SDK API Reference:** Documentation for the Extension SDK, providing context props and utility functions for UI extensions.
*   **Viewports Reference:** Information on available viewports within the Stripe Dashboard where your app's UI can be rendered.
*   **Route Descriptors:** Learn how to implement soft, context-preserving navigation within the Stripe Dashboard.
*   **Sample Apps:** Explore working examples of Stripe Apps to use as a starting point for your own development.