## Documentation for Stripe Apps Development

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

---

### Core Concepts and Getting Started

*   **Stripe Apps Overview**: An introduction to Stripe Apps, their capabilities, and how they can be used to authenticate users, listen for events, or automate workflows. It also covers designing custom user interfaces within the Stripe Dashboard.
*   **Getting Started with Stripe Apps**: A guide to building your first Stripe App, including setting up the Stripe CLI and creating a basic "Hello, world!" app with a UI extension.
*   **How Stripe Apps Work**: Explains the fundamental architecture of Stripe Apps, including their frontend (UI extensions) and backend components, and how to build apps for personal use or for the Stripe App Marketplace.
*   **Common Use Cases**: Demonstrates how to build Stripe Apps for various business needs, covering backend-only, frontend-only, and full-stack applications, with examples for different authentication methods.

### Building Your Stripe App

*   **Build an App**: General guidance on the app development process.
*   **Build a UI**: Instructions on creating custom user interfaces for your Stripe App using TypeScript, React, and Stripe's UI Extensions SDK and UI toolkit. This includes information on views, viewports, and UI components.
    *   **UI extensions**: Details on how UI extensions function within the Stripe Dashboard.
    *   **Next generation UI components**: Information on early access to updated UI components.
    *   **Component hierarchy constraints**: Rules governing how UI components can be composed.
    *   **UI testing**: Utilities and helpers for testing your app's UI.
    *   **Developer tools**: Information on bundled tools for type checking, linting, and testing.
    *   **Style your app**: Guidance on styling UI components using provided design tokens for consistency with the Stripe Dashboard.
    *   **Design your app**: An overview of design tools, guidelines, and philosophy for building Stripe Apps.
*   **Add server-side logic**: How to incorporate backend code for validating user actions, processing data, integrating with third-party systems, and handling webhooks.
*   **API authentication methods**: Explains the different methods for authenticating requests to the Stripe API, including Platform key, OAuth 2.0, and Restricted API keys (RAKs).
    *   **OAuth 2.0**: Detailed guide on implementing OAuth 2.0 for authentication.
    *   **Restricted API key authentication**: Information on using RAKs for secure API access.
*   **Add authorization flows**: How to implement PKCE OAuth workflows within your Stripe App.
*   **Store secret credentials and tokens**: Guidance on using the Secret Store API to securely persist sensitive data like authentication credentials.
*   **App settings page**: How to create a configuration page for users to customize their app settings within the Stripe Dashboard.
*   **Handle different modes**: Adapting your app to work seamlessly in both live mode and sandbox environments.
*   **Enable sandbox support**: How to enable your public app for installation in Stripe's testing environments.
*   **Enable local network access**: Instructions for enabling local network access for app previewing during development.

### UI Components Reference

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

*   **UI components**: An overview of the component library for building user interfaces.
*   **Accordion**: For organizing content into collapsible sections.
*   **Badge**: To indicate the state of an item or object.
*   **Banner**: For displaying alerts or important messages.
*   **BarChart**: To visualize data using bars.
*   **Box**: A versatile container for styling and layout.
*   **Button**: For user actions and directing attention.
*   **ButtonGroup**: To manage the layout of multiple buttons.
*   **Checkbox**: For indicating or controlling boolean values.
*   **Chip**: To display and manipulate values, often used for filtering.
*   **ContextView**: The root view component for apps, allowing side-by-side context with Stripe content.
*   **DataTable**: For displaying tabular data.
*   **DateField**: To collect date information from users.
*   **DetailPageModule**: For rendering apps within Stripe dashboard detail pages.
*   **DetailPagePropertyList**: For rendering property lists within Stripe dashboard detail pages.
*   **DetailPageTable**: For rendering tables within Stripe dashboard detail pages.
*   **Divider**: To render a simple horizontal rule.
*   **FocusView**: For opening a dedicated space to complete a specific task.
*   **FormFieldGroup**: To group related form fields.
*   **FullPageTabs**: For displaying sections of content using tabs.
*   **FullPageView**: To implement the full-page viewport in Stripe Apps.
*   **Icon**: To display icon graphics.
*   **Img**: For displaying images.
*   **Inline**: For styling inline content like text.
*   **LineChart**: To visualize data as a line.
*   **Link**: For navigation and subtle actions.
*   **List**: To display collections of information.
*   **Menu**: To present a group of actions.
*   **OnboardingView**: To implement an onboarding flow for your app.
*   **OverviewPage**: To implement overview-style layouts.
*   **PropertyList**: To display data as key-value pairs.
*   **Radio**: For making selections from a set of mutually exclusive options.
*   **SearchField**: To allow users to search and filter content.
*   **Select**: To pick from a set of options in a dropdown.
*   **SettingsView**: To allow users to change app settings.
*   **SignInView**: To render a sign-in screen.
*   **Sparkline**: A simple line chart for succinct data display.
*   **Spinner**: To indicate that something is loading.
*   **Switch**: For indicating or controlling boolean values.
*   **Table**: To display data in a table format.
*   **Tabs**: To display sections of content.
*   **TaskList**: To help users track progress through tasks.
*   **TextArea**: For multi-line text input.
*   **TextField**: For single-line text input.
*   **Toast**: To inform users of temporary status updates.
*   **Tooltip**: To provide additional contextual information.

### Design Patterns

*   **Design patterns for Stripe Apps**: General guidance on recommended design patterns for a consistent and scalable app experience.
*   **Action buttons**: Where to place action buttons for optimal user visibility and interaction.
*   **Additional context**: How to provide extra information during onboarding.
*   **Back link**: Implementing navigation to previous pages.
*   **Communicating state**: Guiding users through actions and providing feedback.
*   **Demo content**: Tips for showcasing your app's functionality.
*   **Empty state**: Informing users when no data is available.
*   **Filter controls**: Using chips to filter table rows.
*   **Full page apps**: Building complete, multi-view interfaces within the Stripe Dashboard.
*   **Loading**: Using spinner components to indicate data loading.
*   **Lists**: Displaying collections of information.
*   **Onboarding flow**: Creating effortless, customizable, and relevant onboarding experiences.
*   **Progress stepping**: Guiding users through multi-step tasks.
*   **Redirects**: Creating clear redirects for users.
*   **Settings sign in**: Onboarding users through a settings page.
*   **Sign in template**: Using the `SignInView` component for user authentication.
*   **Sign out**: Enabling users to sign out of your app.
*   **Waiting screens**: Informing users about wait times and next steps.

### Distribution and Management

*   **Distribution options**: Information on making your Stripe Apps publicly available or sharing them privately.
*   **Upload and install your Stripe App**: Steps to upload and install your app for team members or for public distribution.
*   **Migrate an extension to Stripe Apps**: Guidance on migrating legacy extensions to the modern Stripe Apps platform.
    *   **Migrate a plugin to an OAuth 2.0 app**: Specific steps for migrating plugins to OAuth 2.0 authentication.
    *   **Migrate a plugin to a RAK app**: Specific steps for migrating plugins to Restricted API Key authentication.
    *   **Migrate a plugin to Stripe Apps or Stripe Connect**: An overview of migration options.
*   **Test your app externally**: Setting up and distributing test versions of your app before publication.
*   **Publish your app to the Stripe App Marketplace**: A guide to getting your app approved for the Stripe App Marketplace.
*   **Stripe Apps quality requirements**: Understanding the quality standards for apps on the App Marketplace.
*   **Manage your app's versions and releases**: Information on app versioning and managing changes over time.
*   **App analytics**: Accessing data to understand app performance.
*   **Embedded Stripe Apps integration guide**: Using embedded components to allow customers to manage payments data in third-party applications.
    *   **Marketing software integrations**: Embedding marketing software integrations like Mailchimp.

### Reference and Tools

*   **App manifest reference**: A comprehensive guide to the fields, types, and descriptions for your app manifest file (`stripe-app.json`).
*   **Stripe Apps CLI reference**: Information on installing and using the Stripe Apps command-line interface to manage your app.
*   **Permissions reference**: A list of available events and their required permissions for your app.
*   **Extension SDK API reference**: Documentation for the Extension SDK API, including context props and utility functions.
*   **Viewports reference**: A list of available viewports for Stripe Apps and how they appear to end users.
*   **Route descriptors**: Navigating within the Dashboard using soft, context-preserving navigation.
*   **Sample apps**: Working examples of Stripe Apps from design to code, available on GitHub.