Custom Mesh integrations

Uniform Mesh is a framework that enables extending the Uniform user interface with custom extensions.

A Mesh integration is a web application hosted at URLs specified by the app author. These integrations are often built with Next.js, and Uniform offers a CLI to help you get started quickly.

A Mesh app can inject its own user interfaces in locations that are defined by the Mesh framework in the Uniform user interface. Each location represents an area of the Uniform dashboard that will be rendered by a Mesh integration app. The web app does the following:

  • Provides the user interface that's incorporated into the Uniform dashboard.
  • Implements logic to interact with an external system.
  • Implements logic to save values that are selected to Uniform.

Custom Mesh integrations let you connect to data sources that are not supported by Uniform's built-in integrations. This gives your authors a better and more tailored experience when working with external systems.

If your project has requirements that Uniform's standard integrations do not cover, you can build your own custom integration using the same Mesh framework that Uniform uses for its official integrations.

In addition to connecting to custom data sources, you can also extend the Uniform UI to improve the authoring experience or tailor it to your business processes.

Mesh integrations can define the locations that are implemented. These locations are defined in the integration manifest.

An integration is defined by a JSON-based manifest (see reference for the allowed schema) which defines each location the integration implements along with metadata about the integration such as hosting URLs, name and icons.

The manifest serves as the configuration that tells Uniform:

  • Integration metadata like name, description, and icons
  • Which locations your integration implements
  • Where to find your integration's UI (URLs)
  • Configuration options for each location

Locations in the Mesh framework define the areas of the Uniform dashboard that can be extended by a Mesh integration by rendering custom UI in an iframe.

Read more about the available locations in the locations guide.

To create your first integration, you will need to have Node.js installed.

Uniform provides a starter kit for new integrations. This starter kit is a Next.js application that includes a complete example of how to implement all locations, with reference code and detailed documentation in code comments.

To create a new integration, run the following command in a terminal:

npx @uniformdev/cli@latest new-integration

The Uniform CLI will guide you through the following steps:

  • Authenticating to Uniform (including creating an account if needed)
  • Choosing the team to register the integration to
  • Choosing or creating a project to install the integration to
  • Cloning the integration starter kit and examples files
  • Automatically configuring Uniform API keys and environment variables
  • What to do next

Team admin permission required

To register an integration, you must have the Team admin permission.

During development, you'll need to register your integration with Uniform so you can test it locally. This involves registering the integration manifest with local development URLs (like http://localhost:9000).

To use a custom Mesh integration in your team, you need to register and install it in a project:

tip

If you use the Uniform CLI to bootstrap your integration, it is automatically registered and installed in the project you choose.

Register your integration at the team level to make it available across all projects within the team. You can register the integration manifest in two ways:

  • Uniform dashboard: Navigate to Settings > Custom integrations in the team dashboard
  • Uniform CLI: Use the integration commands

Once registered, install the integration in specific projects where you want to use it. After installation, the integration's locations become available for use within that project.

Once you have completed local development and testing of your custom integration, you'll need to deploy it to make it available to your team members in production.

Mesh integrations can run on public or private domains as long as the browser accessing the app can access both the app's URL and the Uniform dashboard at https://uniform.app.

Mesh integrations don't require server-side rendering but can be built with it if needed. For most integrations we recommend using static site generation as this makes it easier to deploy and offers more flexibility when choosing the hosting provider.

Once you have your integration deployed, make sure to update the integration manifest with the correct URLs to point to the deployed integration instead of your local development URLs.

Keep environment-specific manifests

It is a good practice to maintain different manifest files for different environments, such as development and production in your codebase.

This allows you to easily maintain and deploy different versions of the integration for each environment.

The @uniformdev/mesh-sdk-react npm package includes full TypeScript typing information and JSDoc comments for all of its exports, which will be automatically used in supported editors such as VSCode.

Uniform provides comprehensive design system resources to help you build consistent user interfaces:

For more advanced scenarios, you can also implement custom edgehancers to run server-side JavaScript at the edge for data fetching, transformation, and caching.

Complete examples of how to implement all locations, with tips and tricks, are available in the Mesh integration starter kit.

Last modified
Next
Mesh locations