Skip to main content

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.

info

These instructions assume you already have Canvas activated in your front-end application. For instructions, see activation.

Activate front-end​

The activation process depends on the technology used to build the front-end. In general, however, 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​

In order to make these instructions easier to follow, a specific example is used. The example activates preview mode for the following page:

Sample page used in this example
import Head from 'next/head'
import {
  CanvasClient,
} from '@uniformdev/canvas'
import {
  UniformComposition,
  UniformSlot,
} from '@uniformdev/canvas-react'

export async function getStaticProps() {
  const client = new CanvasClient({
    apiKey: process.env.UNIFORM_API_KEY,
    projectId: process.env.UNIFORM_PROJECT_ID,
  })
  const { composition } = await client.getCompositionBySlug({
    slug: "/",
  })
  return {
    props: {
      title: 'Sample app',
      composition,
    }
  }
}

function UnknownComponent({ component }) {
  return <div>[unknown component: {component.type}]</div>
}
function resolveRenderer({ type }) {
  //TODO: Add your components.
  return UnknownComponent
}

export default function Home({ title, composition }) {
  return (
    <UniformComposition data={composition} resolveRenderer={resolveRenderer}>
      <div>
        <Head>
          <title>{title}</title>
        </Head>

        <main>
          <UniformSlot name='body' />
        </main>
      </div>
    </UniformComposition>
  )
}

Add preview route handler​

A number of new files are needed in order to support preview mode.

  1. Add the following values to your .env file:

    Environment variableDescription
    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 step

    Technically 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."

  2. Add the secret to the serverRuntimeConfig in your app's next.config.js:

    next.config.js
    const nextConfig = {
      [...]
      serverRuntimeConfig: {
        [...]
        previewSecret: process.env.UNIFORM_PREVIEW_SECRET,
      },
    };

  3. Install dependencies

    npm install @uniformdev/canvas-next

  4. Add the following preview handler:

    pages/api/preview.js
    import getConfig from 'next/config'
    import { createPreviewHandler } from '@uniformdev/canvas-next'

    const handler = createPreviewHandler({
      secret: () => getConfig().serverRuntimeConfig.previewSecret,
    })

    export default handler
    About this step

    This adds a handler to redirect preview requests to the right page. You can read more about Preview Mode in Nextjs docs.

Edit page files​

Next you need to make changes to the pages that read compositions from Uniform.

tip

This section guides you through the process of activating preview mode by explaining each step. It takes longer to go through, but it will help you understand why each line of code is needed.

  1. In the page file, import the composition state constants:

    import Head from 'next/head'
    import {
      CanvasClient,
      CANVAS_DRAFT_STATE,
      CANVAS_PUBLISHED_STATE,
    } from '@uniformdev/canvas'
    import {
      UniformComposition,
      UniformSlot,
    } from '@uniformdev/canvas-react'
    ...

  2. Conditionally set the right state code if we are in preview mode or not:

    export async function getStaticProps({ preview }) {
      const client = new CanvasClient({
        apiKey: process.env.UNIFORM_API_KEY,
        projectId: process.env.UNIFORM_PROJECT_ID,
      })
      const { composition } = await client.getCompositionBySlug({
        slug: '/',
        state: preview ? CANVAS_DRAFT_STATE : CANVAS_PUBLISHED_STATE,
      })
      return {
        props: {
          title: 'Sample app',
          composition,
        }
      }
    }

  3. Continue with the section Configure Uniform project.

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.

Configure Uniform project​

  1. Start your front-end application.

    can users access the application?

    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.

    https and http

    You will only get the automatic update on save when your front-end application is accessed using https:// due to standard browser security.

    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 where the developer is the only person using the project.

  2. In Uniform, open your project.

  3. Navigate to Settings > Canvas Settings.

  4. Enter the following value for Preview URL:

    https://[!!! APP HOST NAME !!!]/api/preview?secret=[!!! PREVIEW SECRET !!!]
    TokenValue
    [!!! 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.

  5. Click Save.

  6. Now when you open a composition in Canvas, a button Preview is available.