> ## Documentation Index
> Fetch the complete documentation index at: https://docs.salesive.com/llms.txt
> Use this file to discover all available pages before exploring further.

# App starter

> Clone a ready-made Salesive app and get the whole install → session → API flow running in minutes — React + Express on one port, scaffolded by one CLI command.

The fastest way to build a Salesive App is to start from the **app starter** — a complete,
runnable sample that already implements the OAuth 2.1 + PKCE install, a signed session, live
webhooks over socket.io, and a scoped proxy to the [Apps API](/apps-api/introduction). It's a
small **notes** app: a React + Tailwind front end and a Node/Express back end served on **one
port**, so there's a single thing to run and deploy.

<Note>
  The starter is a learning scaffold, not a framework. Everything is plain, commented code you
  own and edit — swap the notes UI for your product and keep the install/session/proxy plumbing.
</Note>

## Create your app

<Steps>
  <Step title="Install the CLI">
    The starter is scaffolded by the [Salesive dev tools](https://www.npmjs.com/package/salesive-dev-tools) CLI.

    ```bash theme={null}
    npm install -g salesive-dev-tools
    ```
  </Step>

  <Step title="Scaffold the app">
    `create-app` clones the starter, seeds `.env` from `.env.example`, and prints the next steps.

    ```bash theme={null}
    salesive create-app
    # or skip the prompts:
    salesive create-app --name my-app --package-manager npm
    ```

    <Note>
      Prefer not to use the CLI? Clone it directly instead:
      `git clone https://github.com/Eoion/salesive-app-starter my-app` — then copy `.env.example`
      to `.env` yourself.
    </Note>
  </Step>

  <Step title="Install dependencies">
    ```bash theme={null}
    cd my-app
    npm install
    ```
  </Step>

  <Step title="Add your credentials">
    Create your app in the dashboard (**Apps → Developer**, see [Build & publish](/apps/building-publishing))
    to get a `client_id` and `client_secret`, then fill them into `.env`.
  </Step>

  <Step title="Run it">
    ```bash theme={null}
    npm run dev
    ```

    The whole app — UI, API, OAuth, and webhooks — comes up on one port (default
    `http://localhost:3000`).
  </Step>
</Steps>

## Configure

The starter reads everything from `.env` (copied from `.env.example`). Only the first three are
required to complete an install.

| Variable                  | Required | What it is                                                                                                                                                  |
| ------------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `SALESIVE_CLIENT_ID`      | Yes      | Your app's client id (`app_…`), from **Apps → Developer**.                                                                                                  |
| `SALESIVE_CLIENT_SECRET`  | Yes      | Your app's client secret (`sk_…`). Server-side only — never ship it to the browser.                                                                         |
| `SALESIVE_WEBHOOK_SECRET` | Yes      | Signing secret (`whsec_…`) used to verify incoming webhooks.                                                                                                |
| `APP_BASE_URL`            | Yes      | Public URL where your app is reachable. The OAuth `redirect_uri` is `APP_BASE_URL/oauth/callback` and must **exactly** match a redirect URI you registered. |
| `SALESIVE_SCOPES`         | Yes      | Comma/space-separated scopes to request at install (the sample uses `READ_NOTES,WRITE_NOTES`). See [Scopes & permissions](/apps/scopes-permissions).        |
| `PORT`                    | No       | Port for the single server (default `3000`).                                                                                                                |
| `SESSION_SECRET`          | No       | Dedicated secret for signing the app's session cookie. Defaults to `SALESIVE_CLIENT_SECRET`.                                                                |
| `MONGODB_URI`             | No       | Set to persist installs in MongoDB. Unset = zero-config in-memory store.                                                                                    |
| `SALESIVE_API_BASE`       | No       | Salesive API host. Override only for staging/self-hosted.                                                                                                   |

<Warning>
  `.env` holds secrets and is git-ignored — never commit it. Only `.env.example` (placeholders)
  belongs in source control.
</Warning>

### Reaching your local app from Salesive

A real install has Salesive redirect the merchant's browser to your `redirect_uri`, so
`localhost` only works for installs you trigger from your own machine. For a real install, expose
your port with a tunnel (outray, ngrok, cloudflared, …), set `APP_BASE_URL` to the public HTTPS
URL, and register `APP_BASE_URL/oauth/callback` as a redirect URI in the Developer console.

## What's inside

Everything lives on one Express server that also serves the React app (Vite middleware in dev,
static `dist` in prod).

| Path                        | Responsibility                                                                                                       |
| --------------------------- | -------------------------------------------------------------------------------------------------------------------- |
| `server/routes/oauth.js`    | The [OAuth 2.1 + PKCE install](/apps/oauth-install): `/oauth/start` → consent, `/oauth/callback` → token exchange.   |
| `server/session.js`         | The signed, HttpOnly session cookie that proves a browser completed the install — the security anchor.               |
| `server/salesive.js`        | Token exchange, refresh (with rotation), and scoped calls to the Apps API. The `app_` token never leaves the server. |
| `server/routes/proxy.js`    | Forwards the app's `/api/*` routes to the Apps API with the store-scoped token and pipes the response back.          |
| `server/routes/webhooks.js` | Verifies the `X-Salesive-Hmac-SHA256` signature on incoming [webhooks](/apps-api/webhooks).                          |
| `server/store.js`           | Where installs + tokens live — in-memory by default, MongoDB when `MONGODB_URI` is set.                              |
| `src/`                      | The React app: install gate, session context, socket.io client, and the notes CRUD UI.                               |

## Storage

`server/store.js` ships with two interchangeable backends behind one interface:

* **In-memory** (default) — zero setup, but installs are lost on restart. Perfect for trying the
  starter.
* **MongoDB** — set `MONGODB_URI` to persist installs across restarts and share them between
  processes.

Swapping in Postgres, Redis, or your own database is just another object with the same handful of
methods.

## Before production

<CardGroup cols={2}>
  <Card title="Serve over HTTPS" icon="lock">
    The session cookie is `SameSite=None; Secure`, so it's only sent over HTTPS (localhost aside).
  </Card>

  <Card title="Persist installs, encrypt tokens" icon="database">
    Use a real database (set `MONGODB_URI`) and encrypt the stored `app_` tokens at rest.
  </Card>

  <Card title="Verify every webhook" icon="shield-halved">
    Keep the HMAC signature check and reject unsigned or mismatched deliveries before acting.
  </Card>

  <Card title="Consider App Bridge" icon="window">
    For embedded UI, a signed session token survives third-party-cookie blocking better than a
    cookie. See [App Bridge](/apps/app-bridge).
  </Card>
</CardGroup>

## Next steps

<CardGroup cols={2}>
  <Card title="Understand the install flow" icon="arrow-right-to-bracket" href="/apps/oauth-install">
    The full OAuth 2.1 + PKCE handshake the starter implements.
  </Card>

  <Card title="Pick your scopes" icon="key" href="/apps/scopes-permissions">
    Swap `READ_NOTES,WRITE_NOTES` for the permissions your app actually needs.
  </Card>

  <Card title="Call the Apps API" icon="plug" href="/apps-api/introduction">
    Read and write store data through the scoped proxy.
  </Card>

  <Card title="Build & publish" icon="rocket" href="/apps/building-publishing">
    Register your app and list it on the marketplace.
  </Card>
</CardGroup>