@nuxtjs/prismic - v4

Overview

@nuxtjs/prismic is the official Prismic package for creating Nuxt websites.

With this package, you can:

Query Prismic content with a dedicated client.
Display Prismic content with components and helpers.
Set up Prismic previews.
Benefit from Prismic’s integration in Nuxt DevTools.

This page documents all APIs provided by @nuxtjs/prismic.

Install

@nuxtjs/prismic is automatically installed when bootstrapping a Nuxt project with @slicemachine/init.

npx @slicemachine/init@latest

It can also be manually installed in any Nuxt project:

npx nuxi@latest module add prismic

API

`PrismicModule`

A Nuxt module that sets up Prismic in your project.

nuxt.config.ts

export default defineNuxtConfig({
  modules: ["@nuxtjs/prismic"],
  prismic: {
    endpoint: "example-prismic-repo",
  },
});

property

Description

Default

endpoint

string

A Prismic repository name (recommended) or full endpoint.

clientConfig

optional

object

Options for @prismicio/client used to create a client. Only one of clientConfig or client can be used.

client

optional

string

A path to a file exporting a @prismicio/client instance to be used by the plugin. Only one of clientConfig or client can be used.

linkResolver

optional

string

A path to a file exporting a link resolver function used to determine a URL from a link field or document. If it returns a value, it takes priority over a route resolver. Prefer using only a route resolver with the plugin’s clientConfig.routes option.

injectComponents

optional

boolean

Whether to auto-import @prismicio/vue components within the Nuxt app.

true

preview

optional

string | false

The preview endpoint used to route content writers to a previewed document. Set to false to disable previews.

"/preview"

toolbar

optional

boolean

Whether to inject the Prismic toolbar. The toolbar is required for content previews to work.

true

devtools

optional

boolean

Whether to enable Prismic’s Nuxt DevTools integration.

true

components

optional

object

Options for @prismicio/vue components.

property

Description

Default

linkRel

optional

string

A path to a file exporting a rel attribute’s value to apply on links rendered by PrismicLink. A function can be exported to use the link’s metadata to determine the rel value.

"~/prismic/linkRel"

imageWidthSrcSetDefaults

optional

number[]

Default widths to use when rendering an image with PrismicImage’s widths="defaults" option.

[640, 828, 1200, 2048, 3840]

imagePixelDensitySrcSetDefaults

optional

number[]

Default pixel densities to use when rendering an image with PrismicImage’s pixel-densities="defaults" option.

[1, 2, 3]

richTextComponents

optional

string

A path to a file exporting a map of rich text block types to Vue components to use with PrismicRichText.

"~/prismic/richTextComponents"

sliceZoneDefaultComponent

optional

string

A path to a file exporting a component rendered if a component mapping from the SliceZone’s components prop cannot be found.

"~/prismic/sliceZoneDefaultComponent"

Use a custom client, link resolver, etc.
Nuxt configuration has to be serializable. This means that you can’t configure the Prismic module with functions and other non-serializable values directly in the nuxt.config.ts file.
Instead, you can provide those values through files that export the values you want to use. By default, the module will try to look for the following files in your project’s app directory:
- ~/prismic/client for a custom client.
- ~/prismic/linkResolver for a custom link resolver.
- ~/prismic/linkRel for a custom link rel attribute value.
- ~/prismic/richTextComponents for a custom rich text components map.
- ~/prismic/sliceZoneDefaultComponent for a custom slice zone default component.
You can configure which files the module should use by configuring the paths to them in the module’s options.
nuxt.config.ts
```
export default defineNuxtConfig({
  modules: ["@nuxtjs/prismic"],
  prismic: {
    client: "~/path-to/client",
    linkResolver: "~/path-to/linkResolver",
    components: {
      linkRel: "~/path-to/linkRel",
      richTextComponents: "~/path-to/richTextComponents",
      sliceZoneDefaultComponent: "~/path-to/sliceZoneDefaultComponent",
    },
  },
});
```

`usePrismicPreview`

Resolves a content preview on the preview entry page.

nuxt.config.ts

usePrismicPreview("/");

parameter

Description

Default

defaultURL

optional

string

The default redirect URL if a URL cannot be determined for the previewed document.

"/"

Define a custom preview page
You can customize the page used to open content previews by creating your own at the route defined by the preview module option (~/pages/preview.vue by default). The route must call usePrismicPreview() to resolve previews.
~/pages/preview.vue
```
<script setup lang="ts">
usePrismicPreview();
</script>

<template>
  <p>Loading Prismic preview...</p>
</template>
```

Upgrading from v3

Follow these steps to upgrade an existing project to @nuxtjs/prismic v4.

Install `@nuxtjs/prismic` v4

npm install --save-dev @nuxtjs/prismic@^4

Handle @prismicio/vue v5 breaking changes
@nuxtjs/prismic now uses @prismicio/vue v5. This version introduces breaking changes, such as the removal of default wrappers for the <PrismicText> and <PrismicRichText> components.
Follow the @prismicio/vue v5 upgrade guide.
Update Nuxt plugins to depend on @nuxtjs/prismic
This step is only necessary for websites using a Nuxt plugin depending on @nuxtjs/prismic’s own plugin.
@nuxtjs/prismic’s Nuxt plugin is now parallel for better performance. If a Nuxt plugin depends on @nuxtjs/prismic’s plugin, include it as a dependency.
```
export default defineNuxtPlugin({
  name: "depends-on-prismic-nuxt-plugin",
  dependsOn: ["prismic:setup"], 
  async setup(nuxtApp) {},
});
```

@nuxtjs/prismic - v4

Overview

Install

API

`PrismicModule`

Use a custom client, link resolver, etc.

`usePrismicPreview`

Define a custom preview page

Upgrading from v3

Install `@nuxtjs/prismic` v4

Handle `@prismicio/vue` v5 breaking changes

Update Nuxt plugins to depend on `@nuxtjs/prismic`