> ## Documentation Index
> Fetch the complete documentation index at: https://ampersand-24eb5c1a-jk-chargeover-docs-extension.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

> Clone a working React app with sample Ampersand integrations already wired up.

The [starter project](https://github.com/amp-labs/starter-project) is a small, working application you can clone and run. Use it when you would rather see a live integration first and read the details afterwards.

It contains two things:

<CardGroup cols={2}>
  <Card title="A React app" icon="react">
    A minimal React and Vite app that embeds the `InstallIntegration` component, so you can watch a customer connect their account.
  </Card>

  <Card title="Three integrations" icon="file-code">
    Pick between HubSpot, Salesforce, and GitHub, or add your own.
  </Card>
</CardGroup>

## Before you start

Setting up the accounts and credentials takes longer than running the app itself. Budget around twenty minutes for these steps the first time.

<Steps>
  <Step title="Create an Ampersand project">
    Sign up for a [free Ampersand account](https://dashboard.withampersand.com/sign-up) and follow the prompts to create a project.
  </Step>

  <Step title="Create an API key">
    In the dashboard, open [API keys](https://dashboard.withampersand.com/projects/_/api-keys) and create one. Since the key is used by the React app, choose **UI Library** when asked where you will use it. You will paste it into the app later.
  </Step>

  <Step title="Create a destination named `defaultWebhook`">
    In [Destinations](https://dashboard.withampersand.com/projects/_/destinations), create a webhook destination called `defaultWebhook`. If you do not have an endpoint to point it at, [play.svix.com](https://play.svix.com) gives you a disposable one that shows incoming payloads in the browser, which is ideal for a first run.
  </Step>

  <Step title="Set up the provider">
    You can start with any of the three included integrations. Each provider guide walks you through creating an account and an app:

    * **HubSpot** reads and writes contacts and companies. Follow the [HubSpot provider guide](/provider-guides/hubspot).
    * **Salesforce** reads and writes accounts and contacts. Follow the [Salesforce provider guide](/provider-guides/salesforce).
    * **GitHub** reads and writes gists. Follow the [GitHub provider guide](/provider-guides/github).

    You can also use another integrations from our [samples repo](https://github.com/amp-labs/samples), or browse [our provider guides](/provider-guides/overview) for all supported integrations. Learn more in [Make it yours](#make-it-yours).
  </Step>

  <Step title="Install the CLI">
    Install the [Ampersand CLI](/cli/overview) and run `amp login` to authenticate.
  </Step>
</Steps>

## Run it

<Steps>
  <Step title="Clone and install">
    ```bash theme={null}
    git clone https://github.com/amp-labs/starter-project.git
    cd starter-project
    npm install
    ```
  </Step>

  <Step title="Deploy the integration">
    ```bash theme={null}
    amp deploy integrations/hubspot -p <your-project-name>
    ```

    Swap `hubspot` for `salesforce` or `github` to deploy one of the other included integrations. This creates a [revision](/concepts#revision) of the integration from its `amp.yaml`. Nothing syncs yet, because no customer has installed it.
  </Step>

  <Step title="Point the app at your project">
    In `src/App.tsx`, replace the placeholders with your project name and API key:

    ```tsx theme={null}
    const options = {
      project: 'MY-PROJECT-NAME',
      apiKey: 'MY-API-KEY',
    };

    const integration = "hubspotCRM";
    ```

    If you deployed Salesforce or GitHub, set `integration` to `readAndWriteSalesforce` or `githubIntegration`, the `name` defined in that integration's `amp.yaml`.
  </Step>

  <Step title="Start the app">
    ```bash theme={null}
    npm run dev
    ```

    Open the app (`http://localhost:5173` by default) and use the embedded component to connect an account for the integration you deployed. Once installed, reads run on the schedule in the manifest.
  </Step>

  <Step title="Check that it worked">
    Results arrive at your `defaultWebhook` destination once there is data to read. If you used [play.svix.com](https://play.svix.com), they show up on that page. To see every read, write, and proxy call and whether it succeeded, go to **Integrations** in the dashboard, open your integration, and select the installation.
  </Step>
</Steps>

## What the code does

The whole integration surface is one component. `AmpersandProvider` holds your project credentials, and `InstallIntegration` renders the connect and configure flow your customers see:

```tsx src/App.tsx theme={null}
import { AmpersandProvider, InstallIntegration } from '@amp-labs/react'
import '@amp-labs/react/styles';

const options = {
  project: 'MY-PROJECT-NAME',
  apiKey: 'MY-API-KEY',
};

function App() {
  const integration = "hubspotCRM"; // must match the name in the amp.yaml you deployed

  return (
    <AmpersandProvider options={options}>
      <InstallIntegration
        integration={integration}
        consumerName="demo-user-name"
        consumerRef="demo-user-id"
        groupName="demo-company-name"
        groupRef="demo-company-id"
      />
    </AmpersandProvider>
  )
}
```

The `consumerRef` and `groupRef` values identify which of your customers is installing. In your own application these come from your user and account records, not hardcoded strings. See [Prebuilt UI components](/embeddable-ui-components) for the full set of props.

## Make it yours

<Steps>
  <Step title="Swap the integration">
    Add a new folder under `integrations/` with your own `amp.yaml`, or one from the [samples repository](https://github.com/amp-labs/samples), and deploy it the same way. See the [manifest schema](/manifest-reference) for every available field.
  </Step>

  <Step title="Keep the names aligned">
    Two names have to match: the integration name in `amp.yaml` and the `integration` variable in `App.tsx`, and the destination name in `amp.yaml` and the destination you created in the dashboard.
  </Step>

  <Step title="Redeploy after changes">
    Run `amp deploy` again whenever you edit the manifest. You only need one manifest for all your customers, and you can have multiple integrations in the same manifest.
  </Step>
</Steps>

## Where to go next

<CardGroup cols={3}>
  <Card title="How Ampersand works" icon="book" href="/concepts">
    Integrations, installations, revisions, and configs.
  </Card>

  <Card title="Actions" icon="bolt" href="/overview#actions">
    Read, write, subscribe, and proxy.
  </Card>

  <Card title="Prebuilt UI components" icon="window-maximize" href="/embeddable-ui-components">
    Props, theming, and the other components in the library.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.