Svelte / SvelteKit SDK

The Uniform SDK for Svelte and SvelteKit provides a full integration between Uniform DXP and Svelte applications. It spans three complementary packages:

• @uniformdev/canvas-svelte -- Svelte components for rendering Canvas compositions (UniformComposition, UniformSlot, UniformText, UniformRichText) and contextual editing support.
• @uniformdev/canvas-sveltekit -- SvelteKit-specific integrations: route loading (createUniformLoad), server hooks (createUniformHandle), preview handlers, and ISR configuration.
• @uniformdev/context-svelte -- Svelte bindings for Uniform Context, enabling personalization, A/B testing, visitor scoring, and behavior tracking via the UniformContext provider and reactive helpers.

How it works#

Understanding the request lifecycle helps you reason about configuration choices and debug issues:

1. A visitor requests a page -- SvelteKit's catch-all route [...path]/+page.server.ts receives the request.

2. The composition is fetched server-side -- createUniformLoad from @uniformdev/canvas-sveltekit uses RouteClient to resolve the URL against the Project Map and fetch the full composition data.

3. Components render via the composition tree -- UniformComposition walks the tree and uses your componentMap (or a custom resolveRenderer) to map each Uniform component type to a Svelte component. Parameters are flattened and passed directly as props.

4. Personalization and testing are evaluated -- The UniformContext provider evaluates personalization rules and A/B tests either client-side (standard) or outputs NESI placeholders for edge evaluation (edge).

5. Visual editing works out of the box -- When previewing in the Uniform dashboard, the SDK automatically enables contextual editing, inline text editing, and live preview via the playground route.

Getting started#

Prerequisites#

• SvelteKit 2+ (Svelte 5)
• Node.js 18+
• A Uniform project with compositions set up

Install packages#

Install the Uniform CLI as a dev dependency for syncing content and downloading manifests:

Environment variables#

Create a .env file in your project root:

Project setup#

The Uniform SDK requires a specific set of files to wire up routing, rendering, and preview. Here is the minimal file structure:

The following sections walk through each file.

Step 1: TypeScript declarations#

Update src/app.d.ts to include Uniform preview data types:

Step 2: Root layout with UniformContext#

Create src/routes/+layout.svelte to initialize the Uniform Context provider:

UniformContext props#

Step 3: Server hooks#

Create src/hooks.server.ts to handle Uniform preview mode detection:

The createUniformHandle hook:

• Parses preview cookies set by the Canvas editor
• Makes preview data available via event.locals.uniformPreview
• Optionally calls a callback when preview mode is active

Step 4: Catch-all route#

Create the route structure to serve Uniform compositions.

src/routes/[...path]/+page.server.ts -- Server-side data loading:

src/routes/[...path]/+page.svelte -- Composition rendering:

createUniformLoad options#

Step 5: Component mapping#

Create src/lib/uniform/componentMap.ts to map Uniform component types to Svelte components:

The componentMap is a simple object where keys are Uniform component type strings and values are Svelte components. For variant-specific mappings, use the type__variant format (double underscore).

Step 6: Preview handler#

Create src/routes/preview/+server.ts to enable Canvas contextual editing:

Step 7: Playground page#

Create src/routes/playground/+page.svelte for previewing individual components and patterns:

The playground page renders an empty composition shell that the Canvas editor populates during contextual editing sessions.

Building components#

Uniform components in Svelte receive flattened props -- parameter values are extracted from their ComponentParameter wrappers and spread directly onto the component via Svelte 5's $props(). For example, if a Uniform component has a title parameter of type text, your Svelte component receives a title prop with the string value directly.

Every component also receives a component prop containing the full ComponentInstance, which provides access to raw parameter data, component metadata, variant info, and slots.

Component props#

Every component rendered via the componentMap receives these props:

Basic component with parameters#

Use the ComponentProps<T> type to define your component's props:

Component with slots#

Use UniformSlot to render child components placed in named slots:

Component with variants#

Access variant information via the component prop to conditionally style components:

Register variants in the component map using the type__variant format:

UniformText#

UniformText renders text parameters with built-in support for inline editing in the Uniform visual editor:

UniformText props#

Custom rendering with snippets#

UniformText supports a default snippet slot for custom value rendering:

UniformRichText#

UniformRichText renders rich text parameters with full formatting support:

UniformRichText props#

Custom rich text node rendering#

Override how specific rich text node types are rendered:

UniformSlot#

UniformSlot renders child components placed in a named slot:

When name is omitted, UniformSlot renders all slots combined.

UniformSlot props#

Empty slot placeholder#

UniformSlot supports an emptyPlaceholder snippet for when the slot has no items:

UniformComposition#

UniformComposition is the entry point for rendering a composition tree:

UniformComposition props#

Asset parameters#

Use flattenValues from @uniformdev/canvas to work with asset parameters:

Personalization and testing#

Personalization and A/B testing are configured in the Uniform dashboard and evaluated automatically by the SDK. When UniformSlot encounters a personalization or test container in the composition tree, it renders the appropriate Personalize or Test component from @uniformdev/context-svelte.

How personalization works#

1. The personalization manifest is downloaded locally (see Manifest management) and passed to the Context in the root layout.
2. The UniformContext provider creates a Context instance and makes it available to the entire component tree.
3. When UniformSlot encounters a personalization container, it evaluates the visitor's scores against the variant criteria and renders the winning variant(s).
4. Score updates happen through enrichment tracking (Track component) and route-based signals.

Output types#

The outputType prop on UniformContext controls how variants are rendered:

• standard (default) -- Evaluates personalization during SSR or on the client. Only the winning variant HTML is included. Best for development and most deployments.

• edge -- Outputs all variants as NESI placeholders. An edge middleware selects the winning variant before the response reaches the browser. Best for production with edge personalization (see Edge personalization).

Client-side context#

getUniformContext#

Access the Uniform Context instance directly. Must be called within a UniformContext provider:

The context object is the @uniformdev/context Context instance:

getScores#

Provides reactive access to the current visitor's score values. Uses Svelte 5's $state rune internally:

Returns an object with a reactive .current property containing the ScoreVector.

getQuirks#

Provides reactive access to the current visitor's quirk values:

Returns an object with a reactive .current property containing the Quirks object.

Updating quirks#

Update visitor quirks to trigger personalization changes:

Contextual editing#

The SDK provides built-in support for Uniform's visual/contextual editing. When a composition is opened in the Uniform Canvas editor, the SDK automatically:

1. Listens for composition update messages from the editor
2. Re-renders the component tree with the updated data
3. Enables inline editing for UniformText and UniformRichText components
4. Annotates components with editing attributes for the Canvas UI

getUniformContextualEditing#

For custom contextual editing setups, use getUniformContextualEditing directly:

Manifest management#

Add these scripts to your package.json:

Create a placeholder manifest file at src/lib/uniform/contextManifest.json:

Add contextManifest.json to src/lib/uniform/.gitignore since it is auto-generated.

Uniform CLI configuration#

Create uniform.config.ts at your project root:

Edge personalization#

For production deployments on Vercel, you can enable edge-side personalization using NESI (Nested Edge-Side Includes). This moves personalization evaluation from the client to the edge, delivering fully personalized HTML with zero client-side JavaScript overhead.

How edge personalization works#

Setup#

Edge personalization requires two additional packages:

1. Set output type to edge in production#

This is already configured if you followed the setup guide:

2. Create edge middleware#

Create middleware.ts in the project root (for Vercel deployments):

ISR (Incremental Static Regeneration)#

For Vercel deployments, enable ISR to cache and revalidate pages:

And configure the Vercel adapter in svelte.config.js:

Import reference#

@uniformdev/canvas-svelte#

@uniformdev/canvas-sveltekit#

@uniformdev/context-svelte#

@uniformdev/canvas#

@uniformdev/context#

Type definitions#

ComponentProps#

ComponentMap#

Keys can be:

• "hero" -- matches type "hero" with no variant
• "hero__featured" -- matches type "hero" with variant "featured" (double underscore)

RenderComponentResolver#

UniformContextComponentProps#

PersonalizeComponentProps#

TestComponentProps#

Recipes#

Recipe: Adding Uniform to an existing SvelteKit project#

1. Install packages:

2. Add environment variables to .env:

3. Update src/app.d.ts:

4. Download the personalization manifest:

5. Create the component map (src/lib/uniform/componentMap.ts):

6. Create the root layout (src/routes/+layout.svelte) with UniformContext (see Step 2).

7. Create the catch-all route (src/routes/[...path]/+page.server.ts and +page.svelte) (see Step 4).

8. Create the preview handler (src/routes/preview/+server.ts) (see Step 6).

9. Create the playground page (src/routes/playground/+page.svelte) (see Step 7).

10. Create server hooks (src/hooks.server.ts) (see Step 3).

11. Add scripts to package.json:

Recipe: Building a component with text, rich text, and slots#

Recipe: Component with quirk-based personalization#

Recipe: Forget visitor data (reset personalization)#

Recipe: DevTools integration#

Enable the Uniform Context DevTools browser extension for debugging:

The DevTools extension lets you inspect and modify visitor scores and quirks in real time during development.

Svelte vs SvelteKit#

The Uniform Svelte SDK is split between framework-agnostic Svelte packages and SvelteKit-specific packages:

If you are using SvelteKit (recommended), install all packages. The Svelte-only packages (canvas-svelte, context-svelte) can also be used in non-SvelteKit Svelte setups, but you will need to handle routing and data fetching yourself.

Best practices#

1. Use TypeScript -- The SDK is TypeScript-first. Define Props interfaces using ComponentProps<T> for all components with proper types for each parameter.

2. Use componentMap over resolveRenderer -- The declarative component map is simpler, more readable, and easier to maintain than a resolver function. Reserve resolveRenderer for cases where you need dynamic resolution logic.

3. Download manifest before build -- Use npm run pull:manifest && vite build to ensure the manifest is always up-to-date. Never commit a stale manifest.

4. Run publish:manifest after changes -- Always run uniform context manifest publish after modifying signals, enrichments, or quirks. The manifest must be re-downloaded after publishing.

5. Use flattenValues for assets -- Always use flattenValues from @uniformdev/canvas for asset parameters rather than manually traversing the parameter structure.

6. Access component prop for metadata -- When you need raw parameter data, component IDs, variant info, or slot information, use the component prop.

7. Use getScores() and getQuirks() for reactive data -- Accessing context.scores directly does not trigger re-renders. Always use the reactive helpers for values that affect the UI.

8. Keep the preview handler in place -- The preview API endpoint and server hooks are required for visual editing in the Uniform Canvas editor. Do not remove them.

9. Prefer standard output for development -- Use outputType: 'standard' during development for easier debugging. Switch to 'edge' only in production with a configured edge middleware.

10. Use the type__variant naming convention -- For variant-specific component mappings, use double underscore (hero__dark) in the component map rather than creating separate resolver logic.

Troubleshooting#

Common issues#

1. "Cannot find module contextManifest.json"

   • Run npm run pull:manifest to download the manifest.
   • Ensure UNIFORM_API_KEY and UNIFORM_PROJECT_ID are set correctly.

2. Preview not working

   • Verify the preview URL is configured in Uniform Canvas settings.
   • Check UNIFORM_PREVIEW_SECRET matches in both the .env file and Uniform dashboard.
   • See the troubleshoot preview guide for more help.

3. Components not rendering

   • Verify component type names in componentMap match the types defined in Uniform Canvas.
   • Check browser console for mapping errors.
   • Make sure the component is exported and imported correctly.

4. TypeScript errors with $props()

   • Ensure you are using Svelte 5. The SDK uses Svelte 5's $props() rune for component props.
   • Use interface Props extends ComponentProps<T> {} pattern for type-safe props.

5. Edge personalization not working

   • Ensure outputType is set to 'edge' in production.
   • Verify the edge middleware is deployed and running.
   • Check that the NESI packages (@uniformdev/context-edge, @uniformdev/context-edge-sveltekit) are installed.