# Getting started with Stripe Apps

Learn the basics of app development by building, previewing, and updating a Stripe app.

In this guide, build a “Hello, world!” sample app with a *UI extension* (A set of APIs that allow you to inject user interface elements into the Stripe Dashboard using TypeScript and React) on the Customer details page in the Stripe Dashboard.

## Before you begin

1. If you have an existing *Connect* (Connect is Stripe's solution for multi-party businesses, such as marketplace or software platforms, to route payments between sellers, customers, and other recipients) extension, see [Migrate to Stripe Apps](https://docs.stripe.com/stripe-apps/migrate-extension.md).
1. Go to the [Stripe Dashboard](https://dashboard.stripe.com) to sign in or create an account.
1. If you haven’t already, install the [Stripe CLI](https://docs.stripe.com/stripe-cli.md) and log in using the same account.For additional install options, see [Get started with the Stripe CLI](https://docs.stripe.com/stripe-cli.md).
1. Verify that you’re using CLI version 1.12.4 or newer. You can check by running:
   ```bash
   stripe version
   ```
If your Stripe CLI version is older than 1.12.4, [update your Stripe CLI version to the latest version](https://docs.stripe.com/stripe-cli/upgrade.md).
1. Verify that [Node.js](https://nodejs.org/) is installed by running:
   ```bash
   node -v
   ```
Stripe Apps requires Node.js version `>=14`. We recommend using an [Active LTS version](https://nodejs.org/en/about/previous-releases) (18 or later). If you don’t have Node.js installed, [download and install it](https://nodejs.org/en/download/). You can manage your app’s dependencies with NPM or Yarn. If you plan to [publish your app to the App Marketplace](https://docs.stripe.com/stripe-apps/publish-app.md), there are additional restrictions:

- Your account must be [activated](https://docs.stripe.com/get-started/account/activate.md), with a verified email address and business details.
- A Connect platform account can’t publish an app on the Stripe Marketplace.

## Install the Stripe Apps CLI plugin

To start building a Stripe app, install the Stripe Apps CLI plugin:

```bash
stripe plugin install apps
```

If you already have the `apps` plugin installed, verify that you’re on version `1.5.12` or later.

```bash
stripe apps -v
# apps version 1.5.12
```

If you need to upgrade the `apps` plugin, you can run:

```bash
stripe plugin upgrade apps
```

## Create an app

1. Build the basic structure of your “Hello, world!” app:

   ```bash
   stripe apps create helloworld
   ```

1. Follow the prompts by entering the following information:

   - **ID**: You can accept the auto-generated app ID or customize one. This is how Stripe identifies your app. Your [app ID](https://docs.stripe.com/stripe-apps/reference/app-manifest.md#schema) must be globally unique.
   - **Display name**: Enter a display name. This is the name your Dashboard displays for your app. You can always change the name later.

### Your directory file structure is now:

- `src/views/`: Directory for your TypeScript files that creates UI elements in the Stripe Dashboard, also known as *views* (A view is a React component that creates UI extensions in the Stripe Dashboard).
  - `App.tsx`: The sample *view* (A view is a React component that creates UI extensions in the Stripe Dashboard) that the Customer details page renders in the Stripe Dashboard.
  - `App.test.tsx`: The test file to test the functionality of the `App.tsx` view.
- `stripe-app.json`: The *app manifest* (In a Stripe App, the app manifest is a stripe-app.json file in your app's root directory. It defines your app's ID, views, permissions, and other essential properties) file that describes how your app integrates with the Stripe platform.
- `package.json`: The file that contains metadata specifically to handle app dependencies.
- `yarn.lock`: The auto-generated file that lists the current versions of app dependencies.
- `jest.config.ts`: The configuration file to run test files.
- `images.d.ts`: The type declaration for supporting image files in your Stripe app.
- `tsconfig.json`: The configuration file for compiling TypeScript files.
- `.eslintrc.json`: The configuration file for linting TypeScript files.
- `.vscode/extensions.json`: The file that contains recommended VS code extensions.
- `.gitignore`: The file that tells git to ignore certain files or folders.

Stripe Apps only supports React 17. Make sure any dependency you install is compatible with this version. For more information see [How UI extensions work](https://docs.stripe.com/stripe-apps/how-ui-extensions-work.md#apps-cant-control-the-react-version).

## Preview your app

You can run your app locally, update it, and preview your changes in the Dashboard:

1. Go into the `helloworld` directory:

   ```bash
   cd helloworld
   ```

1. To preview your app, start your local development server:

   ```bash
   stripe apps start
   ```

1. Press **Enter** to open your browser.

   > Use a [browser that supports the Stripe Dashboard](https://docs.stripe.com/dashboard/basics.md). Safari doesn’t support the Dashboard. For more updates, see the [GitHub issue tracking browser support](https://github.com/stripe/stripe-apps/issues/146).

1. Click **Continue** to preview your app in your Stripe account:
![Screenshot of enabling preview mode](https://b.stripecdn.com/docs-statics-srv/assets/enable_app_preview.7d71712d107d581e0a25a4ebaf71484e.png)
   
   Enable app preview
![Hello World app](https://b.stripecdn.com/docs-statics-srv/assets/helloworld_app.7b1588ce22f93f72ab2ecd07c44dd041.png)
   
   Your app in the Dashboard

[Enable local network access](https://docs.stripe.com/stripe-apps/enable-local-network-access.md) before viewing your app.

## Build your app

While you’re previewing your app in the Dashboard, the local development server enables real-time updates on your app:

1. In your `App.tsx` file, change the title while you keep the Stripe Dashboard page open and your development server running. Save the file to see your changes in your app.

1. In the same file, remove `>` from the `</ContextView>` closing tag, and save the file to see an error:
![Hello World error](https://b.stripecdn.com/docs-statics-srv/assets/helloworld_error.ee7aeea9d33b54f1e17b108f61741e97.png)
   
   You can resolve the error in the Stripe Dashboard, your browser developer tools, or the Stripe CLI.

1. To stop the development server, **Ctrl+C** from your command line.

Your sample app is complete. Next, start adding more features to your Stripe app.

## See also

- [Build a UI extension](https://docs.stripe.com/stripe-apps/build-ui.md)
- [Add server-side logic](https://docs.stripe.com/stripe-apps/build-backend.md)
- [Distribution options](https://docs.stripe.com/stripe-apps/distribution-options.md)