Ampersand React library

Overview

Ampersand is a declarative platform for SaaS builders who are creating product integrations.

This repository contains the Ampersand React library, a set of React components that allow your end users to install and manage Ampersand integrations.

Prerequisites

• React version 18+

Next.js App Router

This library uses React hooks, browser APIs, and client-side dependencies throughout, making it a client-side library. When using Next.js App Router (v13+), ensure that components importing from @amp-labs/react are within a client boundary.

The library includes the 'use client' directive at its entry points, so it should work automatically in most cases. If you encounter SSR-related errors, wrap your usage in a client component:

'use client';

import { AmpersandProvider, ConnectProvider } from '@amp-labs/react';

export function MyIntegrationComponent() {
  return (
    <AmpersandProvider options={options}>
      <ConnectProvider /* ... */ />
    </AmpersandProvider>
  );
}

Legacy (@amp-labs/react 1.x.x)

Requires

• Chakra 2.4.4 - 2.10 (https://chakra-ui.com/getting-started)
• Chakra peer dependencies: @emotion/react, @emotion/styled, framer-motion

Installation

In your repo, use npm or yarn to install the package @amp-labs/react:

npm install @amp-labs/react

yarn add @amp-labs/react

Migrating to @amp-labs/react 2.0+ from 1.x.x

@amp-labs/react 2.0+ no longer requires chakra as a dependency. Chakra dependencies (@chakra-ui/react @emotion/react @emotion/styled framer-motion) are no longer required.

@amp-labs/react now ships with its own stylesheet which also allows users to override colors, fonts, and other css variables. See Usage changes

Legacy (@amp-labs/react 1.x.x)

If you are using yarn, you'll have to also install the peer dependencies.

yarn add @amp-labs/react @chakra-ui/react @emotion/react @emotion/styled framer-motion

Usage

Please visit our documentation to learn more about how to use this library.

Changes with 2.0

In addition to importing components, the default stylesheet must also be imported. You may also override --amp css variables from default styles by importing your own stylesheet.

import { AmpersandProvider } from '@amp-labs/react';
import '@amp-labs/react/styles'; // amp-labs style sheet
import './App.css'; // optional: your own css override 

const options = {
  project: 'PROJECT', // Your Ampersand project name or ID.
  apiKey: 'API_KEY',// Your Ampersand API key.
};

function App() {
  return (
    // Wrap all your components inside AmpersandProvider.
    // You can either do this at the App level,
    // or further down in the component tree.
    <AmpersandProvider options={options}>
        // You can use any of the Ampersand components here.
        ...
    </AmpersandProvider>
  )
}

License

This repository is licensed under the MIT license.

To read this license, please see LICENSE.md.

Local Development

Please see CONTRIBUTING.md.