Skip to main content

@uniformdev/uniform-nuxt

Getting started

Install the peer dependencies of the module (if you haven't already):

npm i @uniformdev/canvas @uniformdev/canvas-vue @uniformdev/context @uniformdev/context-vue

Install the module

npm i @uniformdev/uniform-nuxt

Add the module to your Nuxt config:

import { defineNuxtConfig } from 'nuxt';

export default defineNuxtConfig({
modules: ['@uniformdev/uniform-nuxt'],
uniform: {
projectId: process.env.UNIFORM_PROJECT_ID,
readOnlyApiKey: process.env.UNIFORM_API_KEY,
}
});

Features

  • Auto-registers the needed Uniform components.
  • Creates a Canvas client automatically.
  • Creates a Uniform Context instance and provides it through the whole app, without the need of a wrapping component.
  • Provides a handy useUniformComposition composable, built on top of Nuxt's useAsyncData.
  • Handles Live Preview.
  • Watches query string change, which Nuxt doesn't do by default.

API reference

Options

These are the option you pass to the module in nuxt.config.ts.

OptionTypeDescription
projectId*stringThe ID of the Uniform project you want to use in your app.
readOnlyApiKey*stringAn API key that has read permissions to your Uniform project. ⚠️ Make sure the API key has only read access, because it's used in Nuxt's public runtime config
manifestManifestV2The Uniform Context manifest. This one is usually fetched right before the app is started using Uniform's CLI. Uniform Context won't be enabled if a manifest is missing.
outputType'standard' | 'edge'Set it to 'edge' when building the app for the edge using NESI technology. Defaults to 'standard'
apiHoststringThe host to be used when calling the API. Defaults to https://uniform.app
defaultConsentbooleanSets the default value of the user consent. Defaults to false
enableContextDevToolsbooleanEnables the Context DevTools plugin. Defaults to true
uniformContextPathstringThe path to a file that exports a Unifrom Context instance as default. This will override the values of manifest, defaultConsent and enableContextDevTools. Useful for advanced use cases (such us using plugins other than the Context DevTools one).

* Required

Auto-imported composables

These are the composables that the module auto registers for you, so you can use them without import.

useUniformComposition

A Vue composable which takes care of fetching a composition and optionally enhancing it. The composable also takes care of enabling Contextual editing capability. It takes the following named arguments:

Named argumentTypeDescription
enhancefunctionA function to enhance the composition after fetching it. It passes the fetched composition as an argument and should return the enhanced composition.
Parameters to get a composition-The compasable allows passing any of the parameters allowed by CanvasClient's getCompositionBy... methods (e.g. getCompositionById, getCompositionBySlug, etc.)

Example:

const { composition } = useUniformComposition({
slug: '/my-slug',
enhance: (c) => doSomething(c),
});

Components

These are the components that the module auto registers for you, so you can use them without import.

<UniformComposition />

This component wraps the whole composition, it accepts the following props:

PropTypeDescription
data*stringThe data of the composition to be rendered, this is usually the composition object returned by useUniformComposition
resolveRendererfunctionThis function is responsible for mapping Canvas components to Vue components. It takes a ComponentInstance object and should return a Vue component (usually based on the component type). If no resolver is provided, it will try to resolve the component on the global context of the app, so if you have globally defined components, it will try to map them based on the name of the Vue component and the type of the Canvas component.
behaviorTracking'onLoad' | 'onView'Determines when to track behavior from enrichment tags on the current composition.
onView: adds enrichment score when the visitor views the tagged component in the browser viewport.
onLoad: adds enrichment score as soon as the component mounts, regardless of viewport.
contextualEditingEnhancerfunctionA function to enhance the composition inside Canvas editor.
This function runs on the client side.
If no value is provided, the enhancer will be inherited from useUniformComposition

* Required

<UniformSlot />

This component is used to render the slots of a composition, and it can be only used inside a <UniformComposition />. You can nest <UniformSlot /> inside each other if you have nested slots.

PropTypeDescription
namestringThe name of the Canvas slot to render. If no value is provided, all the slots will be rendered (this is not recommended as the order of the rendered slots is not guaranteed).

Injected in the Nuxt instance

These are the properties that the module injects in the Nuxt app instance, so you can use them anywhere in your app via useNuxtApp().

PropertyTypeDescription
$useUniformContextfunctionA Vue composable that returns the current Uniform Context instance which allows you to interact with the context such updating the scores and so on. It also returns other provided properties such as outputType
$previewobject | undefinedThis object is only defined in preview mode, so you can use it to adjust your app if it's in preview mode. It contains the slug of the current composition.
$uniformCanvasClientCanvasClientReturns the Canvas client which you can use to fetch or update compositions. For composition fetching, it's recommended to use $useComposition instead.

Examples

Here are some examples using the module: