@amp-labs/react
and provides a powerful foundation for managing connections and installations while giving you complete control over your UI implementation. This library is designed for developers who want to build custom user interfaces while leveraging robust connection, integration, and installation management capabilities.
AmpersandProvider
and InstallationProvider
.
The AmpersandProvider
needs to wrap all usages of headless hooks and functions as well as prebuilt UI components. See Ampersand Provider for more details.
The InstallationProvider
needs to wrap any code that interacts with a particular installation. This means that if your UI needs to handle multiple installations (e.g., one for Asana and one for Zendesk), then you need two instances of InstallationProvider
: one that wraps the code for Asana setup, and one that wraps the code for Zendesk setup.
InstallationProvider
requires the following props:
amp.yaml
.useConnection
hook provides access to the current connection state and management functions. It returns an object with the following properties:
connection
: The current Connection object, or null if there isn’t one.error
: Any error that occurred while fetching the Connection.isPending
: If true, there is no data yet.isFetching
: If true, the data is being fetched (including refetches).isError
: If true, an error occurred while fetching the connection.isSuccess
: If true, the last fetch was successful.useInstallation
hook provides access to the current installation state and management functions. It returns an object with the following properties:
installation
: The current Installation object, or null if not installed.error
: Any error that occurred while fetching the Installation.isPending
: If true, there is no data yet.isFetching
: If true, the data is being fetched (including refetches).isError
: If true, an error occurred while fetching the connection.isSuccess
: If true, the last fetch was successful.useCreateInstallation
useUpdateInstallation
useDeleteInstallation
useCreateInstallation
hook is used to create a new Installation. It returns the following:
createInstallation
: a tanstack-query mutation function to create a new Installation. Its signature is:isPending
: Boolean indicating if creation is in progress.error
: Any error that occurred during creation.errorMsg
: String message describing the error.isIdle
: If true, createInstallation
has not been called yet.isSuccess
: If true, installation was successfully created.useUpdateInstallation
and useDeleteInstallation
follow similar conventions.
Here’s an example of how you can use these hooks:
useManifest
hook provides the data that you need to build input forms for your users to help them configure the integration. This hook allows you to:
amp.yaml
).For now, you can only access your manifest’s Read Actions. Please note that you still create an Installation with Subscribe and Write Actions usinguseCreateInstallation
. For write actions, you can also useuseConfig
to construct the config object, see Manage write config.
getCustomerFieldsForObject
function returned by useManifest
allows you to retrieve the standard and custom fields that exist in your customer’s SaaS instance for a particular object.
useManifest
to build the UI for customers to configure the installation.
useConfig
hook simplifies local state management of the config object by providing flexible utilities to manipulate the config through a set of setters and getters. It maintains a draft state, which you can modify before committing changes to the installation.
It returns these fields:
setFieldSettings
to set all advanced write features at once for a field:
ReadObjectConfig
and WriteObjectConfig
components defined above, and makes a call to updateInstallation
with the config that has now been updated with both read actions and write actions.