@prismicio/vue Technical Reference

Overview

@prismicio/vue is the Prismic package for creating web apps with Prismic and Vue.

The package formerly known as 'prismic-vue'

@prismicio/vue used to be called prismic-vue. The latter is now deprecated, and you can replace it with @prismicio/vue.

Dependencies & Requirements

This package can only be used in a Vue.js project. It relies on @prismicio/client and prismic-dom as peer dependencies.

Installation

Install packages

Add @prismicio/vue and its peer dependencies to your Vue project via the command line:

  • NPM
  • Yarn
Copy
npm install @prismicio/vue @prismicio/client prismic-dom
Copy
yarn add @prismicio/vue @prismicio/client prismic-dom

Add a Link Resolver

Create a Link Resolver function. This will tell Vue how to handle internal links in Prismic documents. A Link Resolver function takes a document from Prismic as an argument and returns the URL path for that document.

Here's a basic example of a linkResolver.js file:

Copy
export default function (document) {
  if (document.type === 'post') {
    return '/blog/' + document.uid;
  }
  return '/';
};

Register plugin

Add the Prismic plugin to ~/src/main.js in your Vue project. Only include the access token if your repo is private.

Copy
import Vue from 'vue';
import PrismicVue from '@prismicio/vue'
import linkResolver from './path-to-link-resolver'; // Update this path

const accessToken = '' // Add if necessary

// register plugin
Vue.use(PrismicVue, {
  endpoint: "https://your-repo-name.cdn.prismic.io/api/v2",
  linkResolver,
	// access token for private repos
	apiOptions: { accessToken } 
});

// create vue instance
new Vue({
  render: (h) => h(App)
}).$mount('#app')

Usage

@prismicio/vue provides four main functionalities:

  • API Client: It sets up an API client to fetch your Prismic content to use in your project.
  • Query Predicates: It provides a set of "Predicate" functions, which help to format your search queries.
  • Helper Functions: It provides a collection of helper functions to render data from the Prismic API.
  • Components: It provides a collection of components to render data from the Prismic content.

Client

@prismicio/vue initializes an instance of the Prismic API Client class from @prismicio/client and then makes the instance globally available as $prismic.client.

The client has all of the query helpers described in the @prismicio/client Technical Reference, under the "Query Helpers" section. To learn more about these helpers, see that documentation.

All of these methods can optionally accept an options object and a callback function as arguments.

Here is an overview of the $prismic.client methods:

Copy
$prismic.client.query(query, options, callback)
// queries the api with the given query predicates and returns a promise containing the api response

$prismic.client.getByID(id, options, callback)
// queries the api for the document with a given id and returns a promise containing the response

$prismic.client.getByIDs(arrayOfIDs, options, callback)
// queries the api for documents with given ids and returns a promise containing the response

$prismic.client.getByUID(uid, type, options, callback)
// queries the api for the document of a given type with a given uid and returns a promise containing the response

$prismic.client.getSingle(type, options, callback)
// queries the api for the document of a given singleton type and returns a promise containing the response

Predicates

Simply put, a predicate is a query parameter. There are dozens of predicates available with Prismic, allowing for powerful, flexible querying. @prismicio/vue imports a collection of Predicate methods from the @prismicio/client package to help you format your predicates for the $prismic.client.query() method.

Here's an example of a query using predicates. This query gets all documents of type "blog-post" published in the year 2019.

Copy
$prismic.client.query([
  $prismic.Predicates.year('document.last_publication_date', 2019),
  $prismic.Predicates.at('document.type', 'blog-post')
])

This is a list of some of the most commonly-used predicates. For a full list, and to learn more how they work, please see the Predicate documentation.

Copy
$prismic.Predicates.at( path, value )
// checks for documents where the path matches a given value

$prismic.Predicates.not( path, value )
// checks for documents where the path does not match a given value

$prismic.Predicates.any( path, values )
// Checks for documents where the path matches one item in a given array

$prismic.Predicates.in( path, values )
// Checks for document whose id or uid is in a given array

$prismic.Predicates.lt( path, value )
// Checks for documents where the path (a number field) is less than a given value

$prismic.Predicates.gt( path, value )
// Checks for documents where the path (a number field) is greater than a given value

Helpers

@prismicio/vue creates a globally-accessible object named $prismic. The $prismic objects includes all of the methods exported from the @prismicio/client package (see the @prismicio/client Technical Reference for more detail) and more.

The properties available on the $prismic object are:

Copy
$prismic.asText(richText)
$prismic.richTextAsPlain(richText)
// Takes a rich text array from the Prismic API and returns a plain text string.

$prismic.asHtml(richText, linkResolver, htmlSerialzier)
// Takes a Rich Text or Title field from the Prismic API, Link Resolver function and, an HTML Serializer function, and returns HTML.

$prismic.asLink(link, linkResolver)
// Takes a link from the API and a Link Resolver function and returns a URL. Works for Document Links, Media Links, and Web Links.

$prismic.asDate(date)
// Converts a date string from the Prismic API to a JavaScript Date object.

$prismic.linkResolver
// Your application's Link Resolver

$prismic.htmlSerializer
// Your application's HTML Serializer

$prismic.endpoint
// Your Prismic repo API endpoint

Components

@prismicio/vue provides four components for rendering data from the Prismic API. These components are not available in the runtime-only build of Vue. In order to use them, you will ensure the runtimeCompiler is on in vue.config.js:

Copy
module.exports = {
  runtimeCompiler: true
}

Here are the four components:

  • prismic-image: accepts an Image field, and generates an img element with src, alt, and copyright.
  • prismic-rich-text: accepts a Title or Rich Text field and an (optional) HTML Serializer, and generates content formatted in HTML.
  • prismic-link: accepts a Link or Content Relationship field and an (optional) Link Resolver function and generates a vueRouter (default) or Nuxt link, depending on the plugin configuration.
  • prismic-embed: accepts an embed field and generates embed HTML.

When not provided with an HTML Serializer or Link Resolver, the components will use the ones defined in the plugin config.

Here is an example of the components in use:

Copy
<template>
  <div>
    <prismic-image :field="document.data.image" />
    <prismic-rich-text
      :htmlSerializer="htmlSerialzier"
      :field="document.data.description"
    />
    <prismic-link :field="document.data.link" :linkResolver="linkResolver">
      Link to another post
    </prismic-link>
    <prismic-embed :field="document.data.embed" />
  </div>
</template>

<script>
import htmlSerializer from './path-to-html-serializer'
import linkResolver from './path-to-link-resolver'

export default {
  name: 'MyComponent',
  data() {
        return {
        document: null,
        htmlSerializer
      }
    }
  },
  methods: {
    getContent: async () => {
      const document = await this.$prismic.client.getSingle('home')
      this.document = document
    }
  },
  created () {
    this.getContent();
  }
}
</script>