Drag components here
` |
| `"onLoad"` | Tracks immediately when the component mounts, regardless of viewport. No wrapping element |
---
## Client-side context
The Nuxt module automatically sets up the `UniformContextProvider` for your app. Several composables are available for client-side interactivity.
### useUniformContext
Access the Uniform Context instance directly. Available through the Nuxt app instance:
```vue
```
The `context` object is the `@uniformdev/context` `Context` instance, providing access to:
| Method / Property | Description |
| --- | --- |
| `context.scores` | Current visitor score values |
| `context.quirks` | Current visitor quirk values |
| `context.update(options)` | Update visitor data (quirks, enrichments, URL) |
| `context.forget(purge)` | Clear all visitor data. Pass `true` to also clear cookies |
| `context.personalize(options)` | Manually evaluate personalization |
### useQuirks
Provides reactive access to the current visitor's quirk values. The component re-renders whenever quirks change:
```vue
```
---
## Project Map integration
The Uniform Project Map defines the site's URL structure and maps paths to compositions. You can query project map nodes to build navigation or resolve routes programmatically.
### Fetching navigation from Project Map
Create a composable to fetch project map nodes for navigation:
```ts
// composables/useUniformProjectMapNodes.ts
import { ProjectMapClient } from "@uniformdev/project-map";
import {
CANVAS_DRAFT_STATE,
CANVAS_PUBLISHED_STATE,
} from "@uniformdev/canvas";
export function useUniformProjectMapNodes() {
const nuxtApp = useNuxtApp();
const isPreview = nuxtApp.$preview as boolean;
const uniformConfig = useRuntimeConfig().public.$uniform;
return useAsyncData(
`project-map-nodes-${isPreview}`,
async () => {
const projectMapClient = new ProjectMapClient({
apiKey: uniformConfig.readOnlyApiKey,
apiHost: uniformConfig.apiHost,
projectId: uniformConfig.projectId,
bypassCache: true,
});
const state =
process.env.NODE_ENV === "development" || isPreview
? CANVAS_DRAFT_STATE
: CANVAS_PUBLISHED_STATE;
const response = await projectMapClient.getNodes({
state,
depth: 1,
});
return (response.nodes ?? [])
.filter(
(node) =>
node.path &&
node.type === "composition" &&
node.compositionId
)
.map((node) => ({
title: node.name,
url: node.path,
}));
}
);
}
```
Use it in a navigation component:
```vue
```
---
## Manifest management
> **Warning:**
>
> **Nuxt requires downloading the manifest locally.** Unlike the Next.js App Router SDK which fetches the manifest at runtime, the Nuxt SDK expects the manifest to be imported as a JSON file and passed to the module configuration.
Add these scripts to your `package.json`:
```json
{
"scripts": {
"dev": "run-s download:manifest nuxt:dev",
"nuxt:dev": "nuxt dev",
"build": "run-s download:manifest nuxt:build",
"nuxt:build": "nuxt build",
"download:manifest": "uniform context manifest download --output ./lib/uniform/contextManifest.json",
"uniform:push": "uniform sync push",
"uniform:pull": "uniform sync pull",
"uniform:publish": "uniform context manifest publish"
}
}
```
| Script | Description |
| --- | --- |
| `download:manifest` | Downloads the personalization manifest to a local JSON file |
| `uniform:push` | Pushes local content definitions to your Uniform project |
| `uniform:pull` | Pulls content definitions from your Uniform project |
| `uniform:publish` | Publishes the personalization manifest (required after changing signals, enrichments, or quirks) |
> **Note:**
>
> The `dev` and `build` scripts use `npm-run-all` (`run-s`) to download the manifest before starting the dev server or building. Install it as a dev dependency: `npm install -D npm-run-all`.
The manifest file is imported in `nuxt.config.ts`:
```ts
import manifest from "./lib/uniform/contextManifest.json";
import type { ManifestV2 } from "@uniformdev/context";
export default defineNuxtConfig({
uniform: {
manifest: manifest as ManifestV2,
// ...
},
});
```
---
## Uniform CLI configuration
Create `uniform.config.ts` at your project root to configure the Uniform CLI for content sync:
```ts
// uniform.config.ts
import { uniformConfig } from "@uniformdev/cli/config";
module.exports = uniformConfig({
preset: "all",
overrides: {
serializationConfig: { directory: "./content" },
},
disableEntities: ["webhook"],
});
```
This configuration:
- Uses the `all` preset to sync all entity types
- Serializes content definitions to the `./content` directory
- Disables webhook syncing (optional)
---
## 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
### useUniformContextualEditing
This composable is integrated into `UniformComposition` automatically. For custom setups, you can use it directly:
```vue
```
| Return Value | Type | Description |
| --- | --- | --- |
| `composition` | `ComputedRef` | The current composition (updates during editing) |
| `isContextualEditing` | `ComputedRef` | Whether the app is currently in contextual editing mode |
### Custom contextual editing enhancer
If you need to enhance the composition data during contextual editing (e.g., to run data enhancers), pass a custom `contextualEditingEnhancer` to `UniformComposition`:
```vue
;
```
### ComponentProps
```ts
type ComponentProps = TProps & {
component: ComponentInstance;
};
```
### UniformCompositionProps
```ts
type UniformCompositionProps = {
/** The composition data */
data?: RootComponentInstance;
/** Function to resolve Vue components for Canvas component types */
resolveRenderer?: ResolveRenderer;
/** When to track enrichment behavior: "onView" | "onLoad" */
behaviorTracking?: "onLoad" | "onView";
/** Custom enhancer for contextual editing updates */
contextualEditingEnhancer?: (
message: Pick
) => RootComponentInstance | Promise;
};
```
### UniformContextProps
```ts
type UniformContextProps = {
/** The configured Uniform Context instance */
context: Context;
/** Output type: "standard" (SSR/CSR evaluated) or "edge" (all variants output) */
outputType?: "standard" | "edge";
/** Whether to track route changes automatically */
trackRouteOnRender?: boolean;
};
```
### UniformSlotProps
```ts
type UniformSlotProps = {
/** Name of the slot to render */
name?: string;
/** Override the resolve renderer for this slot's children */
resolveRenderer?: ResolveRenderer;
};
```
### UniformTextProps
```ts
type UniformTextProps = {
/** The ID of the parameter */
parameterId: string;
/** HTML element to render (default: "span") */
as?: string;
/** Enable multi-line mode with white-space: pre-wrap */
isMultiline?: boolean;
/** Placeholder text in the Canvas editor */
placeholder?: string | ((parameter: { id: string }) => string | undefined);
};
```
### UniformRichTextProps
```ts
type UniformRichTextProps = {
/** The ID of the rich text parameter */
parameterId: string;
/** Custom resolver for rich text node renderers */
resolveRichTextRenderer?: RenderRichTextComponentResolver;
/** Wrapper HTML element */
as?: keyof HTMLElementTagNameMap;
/** Placeholder text in the Canvas editor */
placeholder?: string | ((parameter: { id: string }) => string | undefined);
};
```
---
## Recipes
### Recipe: Adding Uniform to an existing Nuxt project
1. Install packages:
```bash
npm install @uniformdev/uniform-nuxt@latest @uniformdev/canvas@latest @uniformdev/canvas-vue@latest @uniformdev/context@latest @uniformdev/context-vue@latest @uniformdev/project-map@latest
npm install -D @uniformdev/cli@latest npm-run-all
```
2. Add environment variables to `.env`:
```bash
UNIFORM_API_KEY=your-api-key
UNIFORM_PROJECT_ID=your-project-id
```
3. Download the personalization manifest:
```bash
npx uniform context manifest download --output ./lib/uniform/contextManifest.json
```
4. Configure `nuxt.config.ts`:
```ts
import manifest from "./lib/uniform/contextManifest.json";
import type { ManifestV2 } from "@uniformdev/context";
export default defineNuxtConfig({
modules: ["@uniformdev/uniform-nuxt"],
uniform: {
projectId: process.env.UNIFORM_PROJECT_ID,
readOnlyApiKey: process.env.UNIFORM_API_KEY,
manifest: manifest as ManifestV2,
defaultConsent: true,
outputType: "standard",
playgroundPath: "/playground",
},
});
```
5. Create the component resolver (`components/canvasComponents.ts`):
```ts
import type { ComponentInstance } from "@uniformdev/canvas";
import {
DefaultNotImplementedComponent,
type ResolveRenderer,
} from "@uniformdev/canvas-vue";
const componentMap: Record = {};
export const resolveRenderer: ResolveRenderer = (component) => {
return (
componentMap[component.type] ?? DefaultNotImplementedComponent
);
};
```
6. Create the catch-all route (`pages/[...path].vue`):
```vue
```
Register it in your component resolver:
```ts
import Article from "./Article.vue";
const componentMap = {
article: Article,
// ...other components
};
```
### Recipe: Component with quirk-based personalization
```vue
```
### Recipe: Forget visitor data (reset personalization)
```vue
```
### Recipe: Accessing composition data for metadata
```vue
Current country: {{ quirks?.country ?? "Unknown" }}
```
### useScores
Provides reactive access to the current visitor's score values:
```vue
Tech interest score: {{ scores?.tech ?? 0 }}
```
### Updating quirks
Update visitor quirks to trigger personalization changes:
```vue
Welcome from {{ quirks.country }}!
We see you're interested in {{ topInterest }}.