Quickstart

The 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:

A React app

A minimal React and Vite app that embeds the InstallIntegration component, so you can watch a customer connect their account.

Three integrations

Pick between HubSpot, Salesforce, and GitHub, or add your own.

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.

Create an Ampersand project

Create an API key

In the dashboard, open 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.

Create a destination named defaultWebhook

In Destinations, create a webhook destination called defaultWebhook. If you do not have an endpoint to point it at, play.svix.com gives you a disposable one that shows incoming payloads in the browser, which is ideal for a first run.

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.
Salesforce reads and writes accounts and contacts. Follow the Salesforce provider guide.
GitHub reads and writes gists. Follow the GitHub provider guide.

You can also use another integrations from our samples repo, or browse our provider guides for all supported integrations. Learn more in Make it yours.

Install the CLI

Install the Ampersand CLI and run amp login to authenticate.

Run it

Clone and install

git clone https://github.com/amp-labs/starter-project.git
cd starter-project
npm install

Deploy the integration

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 of the integration from its amp.yaml. Nothing syncs yet, because no customer has installed it.

Point the app at your project

In src/App.tsx, replace the placeholders with your project name and API key:

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.

Start the app

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.

Check that it worked

Results arrive at your defaultWebhook destination once there is data to read. If you used 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.

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:

src/App.tsx

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 for the full set of props.

Make it yours

Swap the integration

Add a new folder under integrations/ with your own amp.yaml, or one from the samples repository, and deploy it the same way. See the manifest schema for every available field.

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.

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.

Where to go next

How Ampersand works

Integrations, installations, revisions, and configs.

Actions

Read, write, subscribe, and proxy.

Prebuilt UI components

Props, theming, and the other components in the library.

Get started

Actions

Data and schemas

UI library

Destinations

Notifications

Reference

Security

Resources

A React app

Three integrations

Before you start

Run it

What the code does

Make it yours

Where to go next

How Ampersand works

Actions

Prebuilt UI components

A React app

Three integrations

​Before you start

​Run it

​What the code does

​Make it yours

​Where to go next

How Ampersand works

Actions

Prebuilt UI components

Before you start

Run it

What the code does

Make it yours

Where to go next