Preview mode
Composable architectures need a layer where the systems come together and an experience is built. In Uniform, users can leverage data from integrated systems to create "compositions." These compositions can be created, edited, and published from our contextual editor, so that authors can see what the end user will see.
Configure the preview URL for the project
In Uniform, open your project.
Navigate to Settings > Canvas Settings.
Enter the following value for Preview URL:
- Next.js
- Nuxt 3
https://[!!! APP HOST NAME !!!]/api/preview?secret=[!!! PREVIEW SECRET !!!]
Token Value [!!! APP HOST NAME !!!]
The host name where the Next.js application is running. Any user who wants to use the preview feature must be able to access this host from their browser. [!!! PREVIEW SECRET !!!]
The value you specified for the preview secret in the .env
file.
This environment variable is usually calledUNIFORM_PREVIEW_SECRET
infoRead the Next.js documentation to learn more about how preview mode works in Next.js and why the preview URL needs this particular URL format.
The Uniform Canvas SDK provides a default implementation out of the box so you don't have to create any new "glue code" to get content previews working for your project.https://[!!! APP HOST NAME !!!]?preview=true
Token Value [!!! APP HOST NAME !!!]
The host name where the Nuxt application is running. Any user who wants to use the preview feature must be able to access this host from their browser. tipWhen in preview mode, the⚡️emoji is prepended to the title of the page.
- Click Save.
- Now when you open a composition in Canvas you should see your website inside of the Preview panel.
Preview mode only works if your front-end application is using "https://"" URLs due to standard browser security policies.
"http://"" will only work with localhost (e.g. http://localhost:3000), but this requires any user who wants to use the preview feature to have the front-end application running locally. This is only recommended for Uniform projects when the project is still under active development and the developer is the only person using the project.
Enable preview support in code
These instructions assume you already have Canvas activated in your front-end application. For instructions, see activation.
If you are the only person using your Uniform project, you can run the application locally. However, if other users need to use the preview feature, the front-end application must run somewhere that the other users can access it. This might be on a server on your network, or on an internet-accessible CDN like Netlify or Vercel.
How you enable preview mode in your application depends on the technology used to build the front end. In general, the process involves changing the code that reads the composition from Uniform so the most recent configuration (i.e. the draft version) from Uniform is used.
Next.js
Add preview route handler
After you have activated Canvas rendering in your front-end application, you need to add a preview route.
A number of new files are needed in order to support preview mode.
Start your front-end application.
Add the following values to your
.env
file:Environment variable Description UNIFORM_PREVIEW_SECRET
This can be any value you want. However, this value must be included in the preview URL that you will configure in a later step. About this stepTechnically you do not need to set the preview secret in an environment variable. You could hard-code the value into your app, but using environment variables is a "best practice."
Install dependencies
npm install @uniformdev/canvas-next
Add the following preview handler:
pages/api/preview.jsimport { createPreviewHandler } from '@uniformdev/canvas-next'
const handler = createPreviewHandler({
secret: () => process.env.UNIFORM_PREVIEW_SECRET,
})
export default handlerAbout this stepThis adds a handler to redirect preview requests to the right page. You can read more about Preview Mode in Nextjs docs.
Customize preview route handler
The previous code snippet works for simple projects that have basic routing and don't need enhancers. For more advanced projects you can customize the preview route handler to support enhancers and custom routing.
Enabling enhancers in preview mode
If your project uses enhancers, the following changes need to be added to the preview route handler to ensure that the enhancers are executed in preview mode when the composition is updated in Canvas.
import { createPreviewHandler } from '@uniformdev/canvas-next'
// import custom enhancer function - change this import to match to your project setup
import runEnhancers from "@/lib/enhancers";
// pass preview context to enhancers
const context = { preview: true };
const handler = createPreviewHandler({
secret: () => process.env.UNIFORM_PREVIEW_SECRET,
// run enhancers when content is updated in Canvas
enhance: (composition) => runEnhancers(composition, context)
})
export default handler
Custom routing in preview mode
In some cases you might want to have a different URL for your composition previews.
By specifiying a custom resolveFullPath
function you can construct your own URL
that will be used for the preview mode.
import { createPreviewHandler } from '@uniformdev/canvas-next'
// Example: render every composition in a localized "/preview/" route
const handler = createPreviewHandler({
secret: () => process.env.UNIFORM_PREVIEW_SECRET,
// add custom preview routing logic
resolveFullPath: ({ slug, path, id, locale }) => {
return `/preview/${locale}${path}`;
},
})
export default handler
Nuxt 3
The Uniform module for Nuxt integrates preview mode out of the box. No front-end application modifications are needed. But you still need to configure the Uniform project in order for the preview button to work.
Placeholders
When a composition has an empty slot, you'll see a placeholder as shown in the screenshot below:

To match the dimensions of a real components, the placeholder is based on one of the allowed components in that specific slot. But it might happen that the placeholder doesn't look exactly as expected. In this case you can:
Customize placeholders
- React/Next.js
- Vue/Nuxt
<UniformSlot
name="mySlotName"
emptyPlaceholder={<div style={{ width: "100px", height: "100px" }}></div>}
/>
<UniformSlot name="mySlotName">
<template #emptyPlaceholder>
<div :style="{width: '100px', height: '100px'}" />
</template>
</UniformSlot>
Disable placeholders
If you don't want to show placeholders for a specific slot of a component then you can disable them:
- React/Next.js
- Vue/Nuxt
<UniformSlot name="mySlotName" emptyPlaceholder={null} />
<UniformSlot name="mySlotName">
<template #emptyPlaceholder />
</UniformSlot>
Localization preview
Make sure that you have localization set up in your project first.
Contextual editing in Canvas allows previewing a localized version of your composition. This can be done by selecting a locale from the dropdown in the preview panel.

The value of this dropdown is also exposed to your app in preview mode, so you can use it to better localize your data during contextual editing (e.g. preview localized content from a CMS).
Example:
- Next.js
- Vue/Nuxt
import { createPreviewHandler } from "@uniformdev/canvas-next";
const handler = createPreviewHandler({
// You can also use `path` instead of `slug` if you're using Project Map.
resolveFullPath: ({ slug, locale }) => (locale ? `/${locale}${slug}` : slug),
});
<script lang="ts" setup>
const { locale } = useNuxtApp().$preview ?? {};
// Do something with the locale.
</script>
Troubleshooting preview Mode
Consult the troubleshooting guide you have any issues with enabling preview mode.