{"id":19409,"plugin_id":"plugins_6a986dc5b2d88191aa3fbe81033fb978","kind":"skill","collection_source":null,"comparison_source":null,"observed_at":"2026-09-30T23:15:33.207Z","digest":"08a9991d698c3b2bad9ffff1644c92794c87287be2c00fd7b5c28aa8b2d3bca1","against":null,"payload":{"description":"Building Uniform Mesh integrations end to end — scaffold with the CLI, define the mesh-manifest, implement locations, register/install and deploy — plus how to discover and use @uniformdev/design-system components for composing location UI. Covers custom data connectors, Canvas parameter editors, editor tools, personalization algorithms, asset library providers, dashboard/project tools, and edgehancers, on Next.js Page Router (canonical) and App Router (with client-component boundaries). Use when building, scaffolding, or extending a custom Mesh integration, or when choosing and using Uniform design-system components inside a Mesh location.","included_files":[{"relative_path":"agents/openai.yaml","size_in_bytes":170},{"relative_path":"references/build-workflow.md","size_in_bytes":7183},{"relative_path":"references/custom-edgehancers.md","size_in_bytes":8011},{"relative_path":"references/data-connector.md","size_in_bytes":11116},{"relative_path":"references/design-system.md","size_in_bytes":4535},{"relative_path":"references/editor-state.md","size_in_bytes":3149},{"relative_path":"references/identity-delegation.md","size_in_bytes":7146},{"relative_path":"references/manifest.md","size_in_bytes":2539},{"relative_path":"references/use-case-recipes.md","size_in_bytes":3567}],"name":"uniform-mesh","skill_md_contents":"---\nname: uniform-mesh\ndescription: Building Uniform Mesh integrations end to end — scaffold with the CLI, define the mesh-manifest, implement locations, register/install and deploy — plus how to discover and use @uniformdev/design-system components for composing location UI. Covers custom data connectors, Canvas parameter editors, editor tools, personalization algorithms, asset library providers, dashboard/project tools, and edgehancers, on Next.js Page Router (canonical) and App Router (with client-component boundaries). Use when building, scaffolding, or extending a custom Mesh integration, or when choosing and using Uniform design-system components inside a Mesh location.\nlicense: MIT\n---\n\n# Uniform Mesh integrations\n\nBuild a custom Uniform Mesh integration from a plain use case. A Mesh integration is a\nNext.js web app you host, described by a `mesh-manifest.json`, that renders custom UI into\nspecific **locations** in the Uniform dashboard over iframe messaging. This skill covers\nthe whole path: turn a use case into the right locations, scaffold, implement with the mesh\nSDK and the Uniform design system, and register it. For the exact manifest structure,\nalways rely on the manifest JSON schema (see `references/manifest.md`) rather than\nmemorized field lists.\n\n## Build loop\n\n1. **Clarify the use case** — what external system or authoring need, and what the author\n   does in the UI (pick a record? edit a value? browse assets?).\n2. **Map it to location types** — see the map below and `references/use-case-recipes.md`.\n3. **Scaffold or extend** — in a *new* project, `npx @uniformdev/cli@latest new-integration`\n   (Page Router Next.js app, API keys, initial registration). In an *existing* project, skip\n   the scaffold: add the dependencies and wire the app in place, leaving the existing\n   `package.json`, `tsconfig.json`, and framework config intact — merge into them, never\n   overwrite them or drop entries you did not add. See `references/build-workflow.md`.\n4. **Wire the app** — `MeshApp` provider (Page Router `_app.tsx`, or an App Router client\n   provider). Add one page/route per location.\n5. **Author the manifest** — per-environment `mesh-manifest.{local,canary,stable}.json`;\n   declare each location under `locations`. Validate against the manifest JSON schema\n   (`references/manifest.md`).\n6. **Implement locations** — `useMeshLocation<'...'>()` for value/metadata; build the UI\n   from `@uniformdev/design-system`.\n7. **Register + install** — `uniform integration definition register` then\n   `uniform integration install <type>`. An integration must be registered to a team and\n   installed to a project before it can be tested.\n8. **Deploy** — host on HTTPS, point the manifest `baseLocationUrl` at it, re-register.\n\n## Location types → use case (quick map)\n\nWhich location serves which use case. The exact manifest keys and fields for each are\ndefined by the manifest JSON schema — **validate against it** (`references/manifest.md`);\nthey change across SDK versions, so don't trust field lists memorized here.\n\n| Use case | Location |\n|---|---|\n| Connect an external system as a data source | data connector |\n| Custom Canvas component parameter | parameter type editor |\n| Toolbar/tool inside the Canvas editor | editor tool |\n| Custom personalization | personalization algorithm |\n| External asset provider | asset library / asset parameter |\n| Integration-wide config | settings |\n| Install-time description | install |\n| Tool in the project nav | project tool |\n| Tool in the dashboard nav | dashboard tool |\n\n## Two things to always get right\n\n- **The design system is required.** Build all location UI from `@uniformdev/design-system`\n  (`Input`, `InputSelect`, `Callout`, `LoadingOverlay`, `ScrollableList`, …) so the\n  integration matches the dashboard. Do not hand-roll raw `<input>`/`<select>`/`<button>` or\n  add another UI kit. The installed package is the source of truth for what exists and what\n  props it takes — `references/design-system.md` shows how to look it up.\n- **Secrets go in the data source only.** Store API keys/tokens in the data source value\n  (`custom` and header/parameter values are encrypted). Never put secrets in `settings` or\n  data type values, and never hard-code them.\n\n## Next.js Routers\n\n- **Page Router is canonical** — the CLI scaffolds it and every shipped integration uses\n  it. Prefer it.\n- **App Router works but is unofficial.** Because locations rely on `useMeshLocation` hooks\n  and iframe `postMessage`, every location component must be a client component\n  (`\"use client\"`), and `MeshApp` must be wrapped in a client provider. See\n  `references/build-workflow.md`.\n\n## Resources\n\nSee `references/` for detailed guidance:\n- [Manifest](references/manifest.md) — the manifest JSON schema is the source of truth for\n  structure and fields; validate against it instead of hardcoding\n- [Build workflow](references/build-workflow.md) — scaffold → manifest → app setup (both\n  routers) → register → deploy, with CLI verbs and scripts\n- [Design system](references/design-system.md) — how to discover which `@uniformdev/design-system` component\n  to use, real snippets, error/loading/validation/dialog patterns, storybook links\n- [Use case recipes](references/use-case-recipes.md) — use case → locations → components →\n  example pointers\n- [Data connector](references/data-connector.md) — deep dive: the data source / data type /\n  data resource editors and the picker pattern\n- [Custom edgehancers](references/custom-edgehancers.md) — edge hooks for a connector:\n  `preRequest` for auth, draft/published and cache control; `request` for batching, OAuth and\n  response shaping — with the batching helpers, deployment and testing\n- [Identity delegation](references/identity-delegation.md) — call Uniform APIs as the signed-in\n  author: the session-token → BFF exchange → sealed-cookie flow, expiry recovery, the CSRF and\n  CORS rules that must not be broken, plus manifest/runtime authorization\n- [Editor state API](references/editor-state.md) — `editorState`: read and mutate the\n  surrounding composition/entry from a location, so configuration done in your UI writes real\n  parameters. Which locations expose it, the `updateNodeProperty` contract, and the traps\n"},"changes":[],"summary":"First saved snapshot. No earlier version is available for comparison.","summary_kind":"deterministic","summary_metadata":{}}