Integrating Prismic with an existing project

If you are already working on a project that uses ES Modules, that's the case if your project is based on the Vue.js template for Webpack, then you can simply use our Vue.js plugin: @prismicio/vue. Let's walk through all the steps to get Prismic integrated into your project.

1. Create a Prismic repository

A Prismic repository is where you define, edit and publish content.

Create a new repository

Next, you'll need to model your content, create some Custom Types, and publish some documents in your repository. To learn more about this, check out our user guide about Content modeling and custom types.

Now, let's take a look at how to query content from Prismic and integrate it into a Vue component.

2. Add the @prismicio/vue plugin

Let's add the @prismicio/vue plugin as a dependency, as well as prismic-javascript and prismic-dom as peer dependencies to your project. Launch the terminal (command prompt or similar on Windows), point it to your project location, and run the following command:

Copy
npm install @prismicio/vue prismic-javascript prismic-dom

3. Include the Prismic Toolbar

In the index.html file, just before the closing </head>, make sure to add the Prismic Toolbar script. You can find it inside your repository Settings > Previews. There you'll find a script similar to the following code with your repository's name:

Copy
<script async defer src="https://static.cdn.prismic.io/prismic.js?new=true&repo=your-repo-name”></script>

Correct repo name

Note: This example script has your-repo-name at the end of the URL, this value needs to be replaced with your repository name.

Your content may contain links that need to point to a Prismic document. To make the links work properly within your website, you need to set up a Link Resolver function that returns the appropriate URL. This function takes a Prismic document object as an input and returns the corresponding route path of your website.

To learn more about this, check out the Link Resolving documentation page.

In the src folder of your project, create a file named link-resolver.js:

Copy
export default function (doc) {
  // Return the path depending on Prismic Document's type

  // If it's a Single Custom Type with the API ID of "home"
  if (doc.type === 'home') {
    return '/';
  }

  // If it is a Repeatable Custom Type with the API ID of "page" (must contain a UID field)
  if (doc.type === 'page') {
    return '/page/' + doc.uid;
  }

  // Default to the root
  return '/';
};

5. Use the @prismic/vue plugin

Then you have to use the @prismic/vue plugin in your Vue app. Two values are required in its options object argument:

  • The API endpoint
  • The Link Resolver function

Add these in the src/main.js file:

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

// Add this before the new Vue instance
Vue.use(PrismicVue, {
  endpoint: "https://your-repo-name.cdn.prismic.io/api/v2",
  linkResolver
});

If you are using a private repository, then you'll need to include your access token like this:

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

const accessToken = 'MC5XMDNQUFNFQUFDUUFjZm9L...v73vv73vv70f77-977-9Vi0';

Vue.use(PrismicVue, {
  endpoint: "https://your-repo-name.cdn.prismic.io",
  linkResolver,
  apiOptions: { accessToken }
});

6. Query and integrate your content in a component

Here's an example of a Vue component, defined as a single-file component, that pulls content from Prismic. In this example we assume that you have a Single Custom Type with the API ID of home which contains 3 fields:

  • A Key Text field with an API ID of title
  • An Image field with an API ID of logo
  • A Rich Text field with an API ID of rich_content
Copy
<template>
  <div>
    <h1>{{ fields.title }}</h1>
    <prismic-image :field="fields.logo"/>
    <prismic-rich-text :field="fields.richContent"/>
  </div>
</template>

<script>
export default {
  data () {
    return {
      fields: {
        title: null,
        logo: null,
        richContent: null
      }
    };
  },
  methods: {
    getContent () {
      this.$prismic.client.getSingle('home')
        .then((document) => {
          this.fields.title = document.data.title;
          this.fields.logo = document.data.logo;
          this.fields.richContent = document.data.rich_content;
        })
    }
  },
  created () {
    this.getContent();
  }
}
</script>

Quick explanations

As you can see in this Vue component, the data object returns an object named fields containing the different Prismic fields we want to get. All of these fields are initialized at null. When the component is created the getContent method is run. It makes a query to get the "home" document from the Prismic repository.

Finally, we fill the fields object with the corresponding values from the Prismic document object we've just retrieved.

  • title is a Key Text field, meaning it's a plain string so it can be output using the "Mustache" syntax (double curly braces).
  • logo is an Image field, we have to pass its content object to the :field prop of the <prismic-image/> component.
  • rich_content is a Rich Text field. We have to pass its content object into the :field prop of the <prismic-rich-text/> component. These two Vue components are already defined and automatically imported by the @prismic/vue plugin.

The Prismic components

If you're using the runtime-only build of Vue, you won't be able to take advantage of the @prismic/vue components, which are:

<prismic-image>, <prismic-rich-text>, <prismic-link> and <prismic-embed>.

In order to use these, you need to turn on the runtimeCompiler option.

To do this, just add or modify the vue.config.js file at the root of your project and add the following:

module.exports = {
runtimeCompiler: true
}

Learn more about @prismicio/vue components

And your Prismic journey begins!

You should have all the tools now to really dig into your project. We invite you to further explore the documentation to learn about How to Query the API and about Templating.

Take advantage of Prismic features

In order to take advantage of all that Prismic has to offer, check out the HTML Serializer and
Previews and the Prismic Toolbar pages to learn how to add these great features into your Vue.js project.