Custom mesh integrations

Uniform Mesh is a framework that enables extending the Uniform user interface with custom extensions. A Mesh integration app is a web application that's hosted on URLs that the app author defines. You may run Mesh integrations on public or private domains, including localhost, as long as the browser accessing the app can access both the app’s URL and https://uniform.app. Mesh integration apps don't require server-side rendering. The simplest way to start a new Mesh app is with a Next.js application.

A Mesh app can inject its own interfaces in locations that are defined 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 are a way to provide your authors with improved usability when connecting to data sources without a Uniform-provided integration. It's also useful when you have custom requirements that a standard integration won't meet. Uniform uses the same framework to build its own integrations with other composable platforms. Examples of Mesh apps might include:

• Adding a custom rich text parameter to a Canvas Component that uses a specific editor library
• Providing a way to select media items from a DAM system using a list
• Creating a new interface for authors to find data in an internal API to connect their content to

Extend Uniform to meet your needs#

Mesh apps can define the locations that are implemented. Each location is served by a URL, which can be unique to that location or shared across several locations. Uniform provides a design system to ensure the user interface for your custom integration are consistent with the rest of the Uniform dashboard. For more information, see the design system reference.

Locations#

Locations each have a value and metadata. The value is an object that the location is provided and may request to change. For example, with a Data Source location, the value is the definition of the Data Source. The metadata is supporting data that's collected and provided to the location to provide related data. For example the Data Type editor is provided with metadata such as the current project ID and a copy of its parent Data Source. Metadata is read-only.

The URL for each location is invoked it loads in an iframe. This iframe then performs communication through message events to the Uniform dashboard. Uniform provides the @uniformdev/mesh-sdk-react npm package which provides a simple and TypeScript-typed way to interact with Mesh locations from React apps. This SDK enables you to access the location type, metadata, value, set values and validation results, and manage dialog boxes the app may open. it's possible to use Mesh without React, but it's much simpler with the React SDK.

Custom edgehancers#

Integrations can define custom edgehancers, which enable execution of custom, fully-managed server side JavaScript code at the edge when resolving data resources for the integration's data connector(s). This can be used to perform advanced business rules and logic when a static HTTP request is insufficient, such as dynamic caching, request batching, OAuth token negotiation, and response alteration. Custom edgehancers are highly performant, adding only 1-2ms of overhead.

This diagram illustrates how custom edgehancers fit into the request lifecycle of a data resource:

To get started with custom integrations, follow the create an integration procedure below, and then check out edgehancer/README.md in the codebase that it creates. The example integration contains fully examples of how to build, operationalize, and test custom edgehancers.

Manage integrations#

You will register your integration with Uniform on the team level, making your integration available in any projects within the team. Integration is defined by a JSON-based manifest which defines each location the integration implements along with metadata. You can register the manifest in the Uniform team settings on the web, or via the Uniform CLI.

Once you register the app, you can install it in a project and its locations will become available to use.

Create an integration#

To create your first integration, you will need to have Node.js installed. Then at a terminal run:

The Uniform CLI will guide you through:

• 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

Next steps#

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

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 also publishes a Storybook with usage examples for the React Mesh SDK components, as well as the Uniform larger @uniformdev/design-system package’s Storybook to help accelerate app UI development.