- handleUpdate({ apiUrl: e.currentTarget.value })}
- />
- handleUpdate({ apiKey: e.currentTarget.value })}
- />
-
- );
-};
-```
-
-**Secrets Management**: 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.
-
-#### Data Type Editor
-Configures how data is retrieved and processed.
-
-**Implementation Pattern:**
-```tsx
-import { useMeshLocation, DataTypeLocationValue } from '@uniformdev/mesh-sdk-react';
-
-const DataTypeEditor = () => {
- const { setValue, value } = useMeshLocation('dataType');
- const [selectedFields, setSelectedFields] = useState([]);
-
- useEffect(() => {
- setValue((prev: DataTypeLocationValue) => ({
- newValue: {
- ...prev,
- path: '/api/items/${itemId}',
- parameters: [
- {
- key: 'fields',
- value: selectedFields.join(','),
- omitIfEmpty: true
- }
- ],
- custom: { fields: selectedFields }
- }
- }));
- }, [selectedFields]);
-
- return (
-
-
- );
-};
-```
-
-#### Personalization Selection Algorithms
-Register custom algorithms for selecting variations in personalization components.
-
-**Manifest Configuration:**
-```json
-"canvas": {
- "personalization": {
- "selectionAlgorithms": {
- "custom-personalization-algorithm-id": {
- "displayName": "Custom personalization algorithm",
- "description": "Description of the custom personalization algorithm",
- "criteriaEditorUrl": "/personalization-criteria-editor"
- }
- }
- }
-}
-```
-
-### 4. Asset Library Integration
-Extends Uniform's asset management with external asset providers.
-
-**Manifest Configuration:**
-```json
-"assetLibrary": {
- "assetLibraryUrl": "/asset-library",
- "assetParameterUrl": "/asset-parameter"
-}
-```
-
-**Asset Library Implementation Pattern:**
-```tsx
-import { useMeshLocation } from '@uniformdev/mesh-sdk-react';
-
-const AssetLibrary = () => {
- const { metadata } = useMeshLocation('assetLibrary');
- const [assets, setAssets] = useState([]);
- const [searchQuery, setSearchQuery] = useState('');
-
- const fetchAssets = async (query: string) => {
- const response = await fetch(`/api/assets?q=${query}`);
- const data = await response.json();
- setAssets(data.results);
- };
-
- const handleAssetSelect = (asset: any) => {
- // Transform external asset to Uniform format
- const uniformAsset = {
- url: asset.src.large,
- title: asset.alt,
- description: asset.photographer,
- // Additional metadata
- };
-
- // Asset selection logic handled by Uniform
- };
-
- return (
- Custom Tools
- -
-
- {assets.map(asset => (
- handleAssetSelect(asset)}
- />
- ))}
-
-
- );
-};
-```
-
-**Asset Parameter Implementation Pattern:**
-```tsx
-const AssetParameter = () => {
- const { metadata } = useMeshLocation('assetParameter');
-
- return (
-
- {/* Custom asset selection interface for parameters */}
-
- );
-};
-```
-
-### 5. Project Tools
-Add custom tools to project navigation.
-
-**Manifest Configuration:**
-```json
-"projectTools": [
- {
- "id": "analytics-tool",
- "name": "Analytics Dashboard",
- "url": "/analytics",
- "iconUrl": "/analytics-icon.svg"
- }
-]
-```
-
-Common use cases include:
-- Embedding external applications like analytics tools
-- Custom editorial tools like importers or editorial calendar
-- Project-specific documentation pages or Storybook component reference
-
-### 6. Dashboard Tools
-Add custom dashboards to the project dashboard page.
-
-**Manifest Configuration:**
-```json
-"dashboardTools": [
- {
- "id": "custom-dashboard-id",
- "name": "Custom dashboard",
- "url": "/dashboard-tool",
- "iconUrl": "/dashboard-icon.png"
- }
-]
-```
-
-Common use cases 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
-
-## Routing in Mesh Locations
-
-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.
-
-### Using the Router
-
-The router is available through the `useMeshLocation` hook:
-
-```tsx
-import { useMeshLocation } from '@uniformdev/mesh-sdk-react';
-
-const { router } = useMeshLocation<'projectTool'>();
-```
-
-### Navigation Options
-
-**Navigate within the current project:**
-```tsx
-router.navigatePlatform(path);
-```
-The router automatically handles the project context. For example, to navigate to entries: `/dashboards/canvas/entries`.
-
-**Open in a new tab:**
-```tsx
-router.navigatePlatform(path, { target: '_blank' });
-```
-
-**Navigate to a different project:**
-```tsx
-router.navigatePlatform(path, {
- projectId: 'target-project-id',
- target: '_blank'
-});
-```
-
-## Development Workflow
-
-### Create an Integration
-
-To create a new integration, use the Uniform CLI:
-
-```bash
-npx @uniformdev/cli@latest new-integration
-```
-
-The 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
-
-### Register the Integration
-
-**Team Admin Permission Required**: To register an integration, you must have the Team admin permission.
-
-#### 1. Register at Team Level
-Register your integration to make it available across all projects within the team:
-
-- **Uniform Dashboard**: Navigate to `Settings > Custom integrations` in the team dashboard
-- **Uniform CLI**: Use the integration commands
-
-```bash
-uniform integration register --manifest mesh-manifest.json
-```
-
-#### 2. Install in Project
-Once registered, install the integration in specific projects where you want to use it.
-
-### Deploy an Integration
-
-#### Update Manifest for Production
-Once deployed, update the integration manifest with production URLs instead of local development URLs.
-
-**Best Practice**: Maintain different manifest files for different environments (development and production).
-
-#### Hosting Requirements
-- Mesh integrations can run on public or private domains
-- Browser must be able to access both the app's URL and https://uniform.app
-- HTTPS required for production (HTTP allowed for localhost development)
-- Configure appropriate CORS headers for API endpoints
-
-## Development Patterns and Best Practices
-
-> **⚠️ IMPORTANT**: After creating your integration, you MUST register it with Uniform before you can use it. See the "Installation and Deployment" section for detailed steps.
-
-### Required package
-Make sure to always install **Uniform CLI**: `@uniformdev/cli` as a developer dependency as it is required CLI package to work with integrations - register it within a team and install it within a given project.
-
-### Environment Setup
-```bash
-# Create new integration
-npx @uniformdev/cli@latest new-integration
-
-# Install dependencies
-npm install @uniformdev/mesh-sdk-react @uniformdev/design-system @uniformdev/cli
-
-# Set required environment variables for registration
-UNIFORM_API_KEY=your_api_key
-UNIFORM_TEAM_ID=your_team_id
-UNIFORM_PROJECT_ID=your_project_id
-
-# After development, register integration (see Installation and Deployment section)
-npm run register-to-team
-npm run install-to-project
-```
-
-### Validation Pattern
-```tsx
-import { ValidationResult } from '@uniformdev/mesh-sdk-react';
-
-const useValidation = (value: string): ValidationResult => {
- return useMemo(() => {
- if (!value || value.trim().length === 0) {
- return { isValid: false, validationMessage: 'Value is required' };
- }
-
- try {
- new URL(value);
- return { isValid: true };
- } catch {
- return { isValid: false, validationMessage: 'Invalid URL format' };
- }
- }, [value]);
-};
-
-// Usage in component
-const { value, setValue } = useMeshLocation('dataSource');
-const validation = useValidation(value.baseUrl);
-
-setValue((current) => ({
- newValue: { ...current, baseUrl: newValue },
- options: validation
-}));
-```
-
-### Dialog Management
-```tsx
-import { useOpenDialog, useCloseDialog } from '@uniformdev/mesh-sdk-react';
-
-const ComponentWithDialog = () => {
- const openDialog = useOpenDialog();
- const closeDialog = useCloseDialog();
-
- const handleOpenDialog = () => {
- openDialog({
- location: 'namedDialog',
- size: 'medium',
- title: 'Custom Dialog'
- });
- };
-
- return (
-
- );
-};
-```
-
-### Error Handling Pattern
-```tsx
-import { ErrorBoundary } from 'react-error-boundary';
-import { Callout } from '@uniformdev/design-system';
-
-const ErrorFallback = ({ error }: { error: Error }) => (
- Hero Component Content
;
-}
-
-registerUniformComponent({
- type: "hero",
- component: Hero,
-});
-```
-Conventionally Uniform components (like Hero.tsx above) are imported to a barrel file in `components/uniformComponents.ts` (e.g. `import 'componentFileName';`), and that barrel file is imported into `_app.tsx` (e.g. `import '../components/uniformComponents';`) to ensure the registrations are processed.
-
-#### Mapping Uniform Components to React Components
-
-React components that receive Uniform Component data are passed props that correspond to the shape of the component definition they render. The `ComponentProps` type can be used to make the mapping explicit:
-
-```tsx
-import {
- AssetParamValue,
- LinkParamValue,
- RichTextParamValue,
-} from "@uniformdev/canvas";
-
-type HeroProps = ComponentProps<{
- textParameter?: string;
- richTextParameter?: RichTextParamValue;
- linkParameter?: LinkParamValue;
- assetParameter?: AssetParamValue;
- // it is critical that all parameter props values are optional, because they can be undefined - even if 'required' on the component definition
-}>;
-
-function Hero(props: HeroProps) {
- return {props.textParameter}
;
-}
-```
-
-#### Rendering child slots
-
-If a Uniform Component definition has slots defined, the components in those slots can be rendered using the `UniformSlot` component.
-
-```tsx
-import { UniformSlot } from "@uniformdev/canvas-react";
-
-function Hero() {
- return (
-
-
- );
-}
-```
-
-#### Rendering parameter/field values
-
-##### Text parameters/fields
-
-When rendering a `text` type parameter, always use the `UniformText` component to render the value. This will enable authors to edit the value within the Uniform preview directly. Text parameters that do not have a visible component, such as alt text, should be rendered as their raw text value:
-
-```tsx
-import { UniformText } from "@uniformdev/canvas-react";
-
-function Hero() {
- return (
-
-
-
-
-
- {/* always specify placeholder text that an author will see in the visual editor when the value is empty */}
-
- );
-}
-```
-
-##### Rich text parameters/fields
-
-For richText parameters, always use the `UniformRichText` component to automatically render the rich text (stored as Lexical JSON) to HTML:
-
-```tsx
-import { UniformRichText } from "@uniformdev/canvas-react";
-
-function Hero() {
- return (
-
-
- );
-}
-```
-
-##### Asset parameters/fields
-
-When rendering asset parameters, use the `flattenValues` helper to simplify value access:
-
-```tsx
-import { AssetParamValue, flattenValues } from "@uniformdev/canvas";
-
-interface MyComponentProps {
- multipleImagesAssetParam: AssetParamValue;
- singleImageAssetParam: AssetParamValue;
-}
-
-function MyComponent({
- multipleImagesAssetParam,
- singleImageAssetParam,
-}: MyComponentProps) {
- // when multiple assets are allowed, flatten to an array
- const images = flattenValues(multipleImagesAssetParam);
- // when only one asset is allowed, flatten to a single object
- const image = flattenValues(singleImageAssetParam, { toSingle: true });
-
- return (
- <>
- {images?.map((img, index) => (
-
-
-
-
-
-
-```
-
-## Rendering Uniform Components with Svelte
-
-> IMPORTANT: before generating Uniform component code, always fetch available component definitions from Uniform to be aware of the schema.
-
-### Component Props Typing
-
-Use `ComponentProps
-
-
-
-```
-
-### Asset Parameters
-
-Use `flattenValues` helper to simplify asset value access:
-
-```svelte
-
-
-{#if img}
-
-
- {#if showCta}
-