Mesh locations

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.

Locations are defined in the integration manifest that tells Uniform:

  • Which locations your integration implements
  • Which URLs to use for each location
  • Configuration options for each location

Each location is served by a URL, which can be unique to that location or shared across several locations.

When a location URL 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 to help you build the UIs for your locations.

Each location receives two types of data:

Value - The main data object that your location can view and modify

  • Contains the primary information your location is responsible for editing
  • Example: For a Data Source location, the value contains the Data Source definition (name, configuration, settings)
  • Your location can request changes to this data through the Mesh SDK

Metadata - Supporting information provided for context (read-only)

  • Contains related data to help your location function properly
  • Example: For a Data Type editor, metadata includes the current project ID and a copy of the parent Data Source
  • This data cannot be modified by your location

Locations are grouped into the following categories:

These are locations that define how the integration appears in the Integration settings page and how it can be configured when installing it in a project.

The Install location is shown in a drawer when you are about to install an integration. The content of the drawer is defined by the integration manifest. In addition to the integration name and logo, the Install location allows specifying a description and a documentation link.

Unlike other locations, the Install location is not rendered in an iframe.

Install location for the Bynder integration.
Example: Install location for the Bynder integration.

Manifest configuration:

{ "locations": { "install": { "description": [ "Describe your mesh integration", "Each array element will create a new paragraph on the install dialog." ], "informationUrl": "https://yoursite.com/info-about-this-mesh-app" } } }

The Settings location is shown after the integration is installed in a project or when you are editing the integration settings. It allows you to define various integration settings that can be configured for the concrete integration instance of the current project.

Settings location for a custom integration.
Example: Settings location for a custom integration.

Common settings include various display options or authentication settings to external systems if the integration needs to access them in client-side code.

Manifest configuration:

{ "locations": { "settings": { "url": "/reference/settings" } } }

Managing API credentials

If your integration defines it's own data connectors to data sources for edge-based data fetching, then do not save the access credentials in the Settings location. Instead store them in the Data source location that has a secure way to store them on the edge.

The data connectors in a Mesh integration enables you to define and configure data sources in Uniform. For each data source you can specify archetypes, such as Query or Single item, which determine how data is fetched from external systems using data resources that are instances of data types.

The data connector locations provide the user interfaces needed for setting up and configuring data sources, data types and data resources within the Uniform dashboard.

Data connectors have the following locations:

  • Data source - Defines a specific API of an external system, including the base URL of the API and the common connection details and authentication credentials.
  • Data type - Defines the configuration UI for a specific data query to an endpoint of a data source and defines the URL and query parameters that are used when performing the data query. A data type is based on an archetype that represent different kinds of data.
  • Data resource - Defines an instance of a data type that is used on a composition or entry, such as a specific blog post or a list of products.

Manifest configuration:

{ "locations": { "dataConnectors": [ { "type": "your-data-source-id", "badgeIconUrl": "https://uniform.app/uniform.png", "displayName": "Custom CMS", "dataArchetypes": { "singleItem": { "displayName": "Single item", "dataEditorUrl": "/data-resource", "typeEditorUrl": "/data-type" }, "query": { "displayName": "Query", "dataEditorUrl": "/data-resource", "typeEditorUrl": "/data-type" } }, "dataSourceEditorUrl": "/data-source" } ] } }

HTTP fallback behavior

If any location of a data connector is is not specified in the integration manifest, the UI from the standard HTTP Request data connector will be used in its place automatically. This enables integration developers to produce fewer UIs if only looking to customize part of a data connector.

The Data Source location allows you to extend the Uniform Data Source configuration with custom UI and provides you with methods to securely manage the connection details and authentication credentials of the data source.

This location is rendered when creating or editing a data source of the type defined in the data connector.

Data source editor for the commercetools integration.
Example: Data source editor for the commercetools integration.

Manifest configuration:

The data source location is configured as part of the data connector:

{ "dataConnectors": [ { "dataSourceEditorUrl": "/reference/dataSource" } ] }

Query string and header values, as well as any variable values on a data source, are encrypted secrets. Only users with manage data source or admin permissions may decrypt secrets. All others can use them via delegation when fetching data types, without seeing the secret values.

This secure approach ensures that sensitive authentication credentials and API keys are properly protected while still allowing authorized users to configure and use the data source.

The Data Type location provides a custom interface for configuring how data is retrieved from your external systems. While a data source defines the connection to your API, a data type specifies the exact endpoint, query parameters, and request structure needed to fetch specific kinds of content.

This location appears when you create or edit a data type that belongs to your data connector. Common use cases include:

  • Configuring API endpoints for different content types (e.g., /api/products, /api/reviews)
  • Setting up query parameters and variables for the API endpoint
  • Defining request headers

When rendering this location, you receive useful metadata including the project ID and a copy of the parent data source to provide context for your configuration interface.

Data type editor for the commercetools integration.
Example: 'Single item' data type editor for the commercetools integration.

Manifest configuration:

The data type location is configured within the data archetype:

{ "dataArchetypes": { "type-id": { "displayName": "Type name", "typeEditorUrl": "/data-type" } } }

Data type security

Data types are not intended to contain secret values such as authentication tokens. Values stored in data types are viewable by any user of your Uniform project with common permissions. To store secret values, please use Data Sources which are secured.

The Data Resource location defines the user interface that content authors use to select or query data from external systems for a specific data archetype. This location typically has the greatest impact on the authoring experience, as it is the primary way users interact with external data in Uniform.

This location is rendered when creating or editing a data resource of the data archetype defined in the integration in a composition, component pattern, composition pattern, entry, or entry pattern.

Product picker for a commercetools data resource.
Example: Product picker for a commercetools data resource.

Manifest configuration:

The data resource location is configured within the data archetype:

{ "dataArchetypes": { "type-id": { "displayName": "Archetype name", "dataEditorUrl": "/data-resource" } } }

Typical features of the data resource location include:

  • Item pickers for selecting one or more items (for example, choosing a product from a list)
  • Query builders for dynamic data queries
  • Search and filter options to make it easier to find the right data
  • Paging and sorting controls
  • Deep links to edit data directly in the external system

In the Mesh manifest, the canvas group contains several individual locations that you can implement to customize the authoring experience of Uniform.

The Parameter Type location allows you to provide custom input controls for component parameters or entry fields.

This location is rendered in the property panel when a component parameter includes a parameter type that is defined in the integration manifest.

Custom input controls from the Design Extensions integration.
Example: Custom input controls from the Design Extensions integration.

Manifest configuration:

{ "locations": { "canvas": { "parameterTypes": [ { "type": "parameter-type-id", "editorUrl": "/parameter-type", "displayName": "Parameter type name", "configureUrl": "/parameter-type-config", "renderableInPropertyPanel": true } ] } } }

The Parameter Type Configuration location defines the configuration UI for a custom parameter type inside of the component definition.

The configuration options typically include:

This location is rendered when creating or editing a parameter that is using a custom parameter type that was defined in the integration manifest.

Configuration UI for the custom spacing parameter type from the Design Extensions integration.
Example: Configuration UI for the custom spacing parameter type from the Design Extensions integration.

Manifest configuration:

The configuration location is defined as part of the parameter type:

{ "parameterTypes": [ { "type": "parameter-type-id", "configureUrl": "/parameter-type-config" } ] }

Editor tools allow you to extend the functionality of the Uniform's visual editor. These tools appear as additional menu items in the left side rail of the visual editor.

Editor tools can be enabled for the following contexts:

  • Compositions and Composition patterns
  • Component patterns
  • Entries
  • Entry patterns

It is possible to provide custom URLs for each of the contexts.

Editor tool of the AI Translation integration in the visual editor.
Example of the editor tool of the AI Translation integration in the visual editor.

Manifest configuration:

{ "locations": { "canvas": { "editorTools": { "composition": { "url": "/editor-tool" }, "componentPattern": { "url": "/editor-tool" }, "entry": { "url": "/editor-tool" }, "entryPattern": { "url": "/editor-tool" } } } } }

Allows you to register custom algorithms for selecting variations for personalization components.

The location is rendered in the Context tab of the property panel of a personalization component when a custom matching method is configured.

Manifest configuration:

{ "locations": { "canvas": { "personalization": { "selectionAlgorithms": { "custom-personalization-algorithm-id": { "displayName": "Custom personalization algorithm", "description": "Description of the custom personalization algorithm", "criteriaEditorUrl": "/personalization-criteria-editor" } } } } } }

You can extend extend Uniform's asset management with custom asset libraries that connect to external DAM systems or asset sources.

The Asset Library allows you to browse the assets of a custom asset library that was defined in the integration manifest.

This location is rendered in the Experience > Assets section of the Uniform project.

Custom asset library.
Example of a custom asset library.

Manifest configuration:

{ "locations": { "assetLibrary": { "assetLibraryUrl": "/asset-library", "assetParameterUrl": "/asset-parameter" } } }

The Asset Parameter location provides a custom interface for selecting assets when using asset parameters in components or entry fields. This location is rendered inside the asset selection modal when authors are picking assets.

This location allows you to create a tailored asset selection experience that integrates with your external asset management system which enables search, filtering, and preview capabilities within the Uniform interface.

Custom asset selector for a asset parameter.
Example of a custom asset selector for a asset parameter.

Manifest configuration:

The asset parameter location is configured as part of the asset library:

{ "locations": { "assetLibrary": { "assetParameterUrl": "/asset-parameter" } } }

Project locations allow you to extend the Uniform project with custom applications and tools.

The Project Tools location allows you to embed full custom pages.

location-project-tools
Example of embedding a Storybook as a custom tool in a project.

Once an integration is installed that implements this location, the user will be able to access the custom page from the Tools section in the main navigation.

location-project-tools-nav
Main navigation with the custom tool enabled.

Manifest configuration:

{ "locations": { "projectTools": [ { "id": "example-tool", "name": "Example Project Tool", "url": "/project-tool", "iconUrl": "/tool-icon.png" } ] } }

Common use cases for the Project Tools location include:

  • Embedding of external applications like analytics tools
  • Provide custom editorial tools like a importers or editorial calendar
  • Add project specific documentation pages or a Storybook as a component reference

Add custom dashboards to the project dashboard page.

Once an integration is installed that implements this location, the user will be able to access the custom dashboard through a custom tab in the project dashboard.

location-dashboard-tools
Example of a custom dashboard tab in the project dashboard.

Manifest configuration:

{ "locations": { "dashboardTools": [ { "id": "custom-dashboard-id", "name": "Custom dashboard", "url": "/dashboard-tool", "iconUrl": "/dashboard-icon.png" } ] } }

Common use cases for the Dashboard tools location include:

  • Quick links to common content or content filters
  • Editorial dashboards for content editors that connect to external systems
  • Links to internal training or onboarding resources
  • Status or health dashboards for content operations

Since Mesh locations are rendered inside iframes, standard browser navigation doesn't work for moving between different sections of the Uniform dashboard. The Mesh SDK provides routing helpers that allow your integration to programmatically navigate users to other areas of the platform.

This is particularly useful when your integration needs to direct users to related content, such as opening a composition in the Canvas editor, navigating to settings pages, or linking to content in other projects.

The router is available through the useMeshLocation hook:

import { useMeshLocation } from '@uniformdev/mesh-sdk-react'; // adjust the type to the location you are using const { router } = useMeshLocation<'projectTool'>();

Navigate within the current project:

router.navigatePlatform(path);

The router automatically handles the project context, so you don't need to include the project ID in the path. For example, if you want to navigate to the entries of a project the path would be /dashboards/canvas/entries.

Open in a new tab:

router.navigatePlatform(path, { target: '_blank' });

Navigate to a different project:

router.navigatePlatform(path, { projectId: 'target-project-id', target: '_blank' });
Last modified
Next
Custom edgehancers