Canvas Client SDK

The Canvas Client (CanvasClient from @uniformdev/canvas) provides programmatic access to compositions and component definitions in a Uniform project. Use it for server-side data fetching, static site generation, build scripts, content migrations, or any scenario where you need to work with compositions outside of the standard rendering pipeline.

The client wraps the composition endpoints of the Uniform APIs; see the OpenAPI specification for the underlying API reference.

Installation#

The Canvas Client is part of the @uniformdev/canvas package:

npm install @uniformdev/canvas

Initializing the client#

Standalone usage#

import { CanvasClient } from "@uniformdev/canvas"; const canvasClient = new CanvasClient({ apiKey: process.env.UNIFORM_API_KEY, projectId: process.env.UNIFORM_PROJECT_ID, });

Option	Type	Description
`apiKey`	`string`	API key with read access to the project (write access for management operations)
`projectId`	`string`	The Uniform project ID
`apiHost`	`string`	Uniform API host, used when data resolution is skipped and for management operations. Default: `https://uniform.app`
`edgeApiHost`	`string`	Edge API host, used when fetching compositions with data resolution. Default: `https://uniform.global`
`disableSWR`	`boolean`	When `true`, disables stale-while-revalidate caching on the edge and always returns fresh data
`bypassCache`	`boolean`	When `true`, bypasses API caching entirely. `UncachedCanvasClient` is a shortcut for this

Within the App Router SDK#

There is only one Canvas Client implementation. The App Router SDK provides getCanvasClient, a factory that returns the same CanvasClient pre-configured for Next.js: credentials are read from environment variables, and a custom fetch wires composition requests into the Next.js data cache (per-composition cache tags, revalidate, and draft-mode cache bypass):

import { getCanvasClient } from "@uniformdev/next-app-router"; const canvasClient = getCanvasClient({ cache: { type: "no-cache" }, });

Use getCanvasClient in App Router server code so composition fetches participate in Next.js caching and revalidation; use new CanvasClient(...) everywhere else.

Fetching a single composition#

The client provides one method per lookup key. All of them accept the same options and return the same response shape:

Method	Looks up by
`getCompositionById`	Composition ID
`getCompositionBySlug`	Composition slug
`getCompositionByNodePath`	Project map node path (accepts optional `projectMapId`)
`getCompositionByNodeId`	Project map node ID (accepts optional `projectMapId`)

import { CANVAS_PUBLISHED_STATE } from "@uniformdev/canvas"; const { composition } = await canvasClient.getCompositionBySlug({ slug: "/company/about-us", state: CANVAS_PUBLISHED_STATE, }); console.log(composition._name, composition.parameters);

Common options#

Option	Type	Description
`state`	`number`	Publishing state to fetch: `CANVAS_DRAFT_STATE` (0) for draft, `CANVAS_PUBLISHED_STATE` (64) for published.
`locale`	`string`	Locale(s) to localize the response to. Accepts a single value (`en-US`), a comma-delimited list (`fr-CA,fr`), or `Accept-Language` header syntax. When omitted, all locales' data is returned.
`releaseId`	`string`	Fetch the composition as it would appear in the given release.
`withComponentIDs`	`boolean`	When `true`, includes the `_id` of each non-root component in the response.
`skipPatternResolution`	`boolean`	When `true`, pattern references are left unresolved. Useful when serializing compositions and patterns separately.
`versionId`	`string`	Fetch a historical version (retrieved from `getCompositionHistory`). Only valid with `getCompositionById`.
`skipDataResolution`	`boolean`	Skip edge-side data resolution (see below).
`resolutionDepth`	`number`	How many levels deep content references are resolved.
`dataSourceVariant`	`"unpublished"`	When set, data resources that support it fetch unpublished data from their data source.

Data resolution#

By default, single-composition fetches go through the Uniform Edge API, which resolves data resources, dynamic tokens, and referenced entries before returning the composition. Pass skipDataResolution: true to fetch the raw, unresolved composition from the origin API instead -- appropriate for serialization, migration scripts, or when you resolve data yourself:

const { composition } = await canvasClient.getCompositionById({ compositionId: "abc123", state: CANVAS_PUBLISHED_STATE, skipDataResolution: true, });

Listing compositions#

getCompositionList fetches multiple compositions, optionally filtered by root component type:

const { compositions } = await canvasClient.getCompositionList({ type: "landingPage", state: CANVAS_PUBLISHED_STATE, }); for (const { composition } of compositions) { console.log(composition._name, composition._slug); }

In addition to the common options, list queries accept:

Option	Type	Description
`type`	`string \| string[]`	Filter by root component type (public ID). Components in slots are not matched.
`keyword`	`string`	Matches compositions whose name, slug, or definition name contains the keyword. Not a full-text search.
`search`	`string`	Full-text search on textual fields, including resolved pattern content. Use for "where does this content appear" queries.
`pattern`	`boolean \| "any"`	`true` returns only patterns, `false` only regular compositions. Default: both.
`orderBy`	`string`	Sorting: `updated_at_DESC`, `updated_at_ASC`, `created_at_DESC`, `created_at_ASC`, `name_DESC`, `name_ASC`, `slug_DESC`, `slug_ASC`. Default: name ascending.
`limit` / `offset`	`number`	Pagination.
`withTotalCount`	`boolean`	Include the total result count in the response (impacts performance).
`resolveData`	`boolean`	When `true`, the list is fetched through the edge API with data resolution applied to each composition. Default: `false`.
`filters`	`CompositionFilters`	Structured field filters (see below).
`select`	`ProjectionSpec`	Data projection applied to each composition.

Filtering compositions#

The Canvas Client supports the same structured filter syntax as the Content Client, but compositions use parameters where entries use fields:

const response = await canvasClient.getCompositionList({ filters: { "type[eq]": "landingPage", "parameters.heroTitle[match]": "summer", }, });

See the Content Client filter reference for the full list of operators.

Selecting fields with data projection#

The select option fetches a subset of each composition instead of the whole thing, reducing payload size and skipping server-side resolution work for content you don't need. For compositions, the fields bucket selects parameters by name and the slots bucket controls how much of the component tree is returned:

const response = await canvasClient.getCompositionList({ filters: { "type[eq]": "landingPage" }, select: { fields: { only: ["pageTitle", "slug"] }, slots: { depth: 1 }, }, });

See data projection on the Content Client page for the full projection reference. The same option is available on RouteClient.getRoute.

Component definitions#

getComponentDefinitions fetches the component definitions of a project -- useful for tooling, validation, or generating typed component maps:

const { componentDefinitions } = await canvasClient.getComponentDefinitions(); const compositionTypes = componentDefinitions.filter( (definition) => definition.canBeComposition );

Management operations#

The client can also create, update, and delete compositions and component definitions. These operations require an API key with write permissions:

Method	Description
`updateComposition(body, options?)`	Creates or updates a composition. Pass `options.ifUnmodifiedSince` for optimistic concurrency control (the API returns HTTP 409 if the composition changed since that timestamp).
`removeComposition(body)`	Deletes a composition by ID.
`getCompositionHistory(options)`	Fetches historical versions of a composition or pattern.
`updateComponentDefinition(body)`	Creates or updates a component definition.
`removeComponentDefinition(body)`	Deletes a component definition.

await canvasClient.updateComposition({ state: CANVAS_DRAFT_STATE, composition: updatedComposition, });

warning

Most front ends only need the read methods. Management operations modify project content directly -- prefer running them in scripts or trusted server environments, never in browser code.

Import reference#

Export	Package	Description
`CanvasClient`	`@uniformdev/canvas`	Main composition client
`UncachedCanvasClient`	`@uniformdev/canvas`	Canvas Client with API caching bypassed
`CANVAS_DRAFT_STATE` / `CANVAS_PUBLISHED_STATE`	`@uniformdev/canvas`	Constants for the `state` option
`ProjectionSpec`	`@uniformdev/canvas`	Type for the `select` data projection option
`getCanvasClient`	`@uniformdev/next-app-router`	Pre-configured canvas client (server-only, App Router)