@uniformdev/uniform-nuxt

Uniform Nuxt module

• Uniform Nuxt module
  • Getting started
  • Features
  • API reference
    • Options
    • Auto-imported composables
      • useUniformComposition
    • Components
      • <UniformComposition />
      • <UniformSlot />
    • Injected in the Nuxt instance
  • Examples

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.

Option	Type	Description
projectId*	string	The ID of the Uniform project you want to use in your app.
readOnlyApiKey*	string	An 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
manifest	ManifestV2	The 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'
apiHost	string	The host to be used when calling the API. Defaults to https://uniform.app
edgeApiHost	string	The host to be used when calling the Edge API. Defaults to https://uniform.global
defaultConsent	boolean	Sets the default value of the user consent. Defaults to false
enableContextDevTools	boolean	Enables the Context DevTools plugin. Defaults to true
uniformContextPath	string	The 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 argument	Type	Description
enhance	function	A 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:

Prop	Type	Description
data*	string	The data of the composition to be rendered, this is usually the composition object that you get from useUniformComposition
resolveRenderer	function	This 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.
contextualEditingEnhancer	function	A 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.

Prop	Type	Description
name	string	The 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().

Property	Type	Description
$useUniformContext	function	A 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
$preview	object | undefined	This 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.
$uniformCanvasClient	CanvasClient	Returns 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:

• https://github.com/uniformdev/uniformconf-nuxt
• https://github.com/uniformdev/nuxt-canvas-context-helloworld

part of the Uniform Platform. See our documentation for more details.