Integrating prismic.io with an existing Javascript project

If you already have a javascript project that you want to integrate with prismic.io, then you can simply add the javascript prismic.io development kit libraries as dependencies. Let's walk through all the steps to get prismic.io integrated into your project!

1. Create a content repository

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

Create a new repository

Next you'll need to model your content, create your custom types, and publish some documents to your repository.

Now, let's take a look at how to connect this new content with your project.

2. Add the development kit as a dependency

Now let's add the prismic.io javascript kit as a dependency 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 prismic-javascript prismic-dom --save

3. Connect to the API and query your content

Next we need to connect to your prismic.io API to retrieve content.  

Copy
var Prismic = require('prismic-javascript');

var apiEndpoint = "https://your-repository-name.prismic.io/api/v2";
 
Prismic.getApi(apiEndpoint, { req: req }).then(function(api) {
  return api.query(""); // An empty query will return all the documents
}).then(function(response) {
  console.log("Documents: ", response.results);
}, function(err) {
  console.log("Something went wrong: ", err);
});

You can omit the `req` parameter if you're doing your queries on the client side (React.js, Angular.js, etc)

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

Copy
var Prismic = require('prismic-javascript');

var apiEndpoint = "https://your-repository-name.prismic.io/api/v2";
var apiToken = "MC5XVHFod1NrQUFDWUE0RVFw...e-_vX5dYu-_vQnvv70";
 
Prismic.getApi(apiEndpoint, {accessToken: apiToken}).then(function(api) {
  return api.query(""); // An empty query will return all the documents
}).then(function(response) {
  console.log("Documents: ", response.results);
}, function(err) {
  console.log("Something went wrong: ", err);
});

Using the API server-side

It comes handy to create a helper function if you're doing your query from the server side (like in Node.js) :

Copy
// Initialize the prismic.io api
function initApi(req){
  return Prismic.getApi('http://your-repo-name.prismic.io/api', {
    accessToken: 'your-access-token',
    req: req
  });
}

Should I call `initApi` on every query?

The `initAPI` call returns the API object and is required to get the latest version of your content. You should call `initApi` to retrieve the API object on every request, page, or screen. It is recommended to assign the API object to a variable, and use it for all queries of the same screen.

Why does `initApi` call require a `req` parameter?

prismic.io has the capacity to do unlimited different preview sessions for different drafts or releases. To offer this and other powerful functionalities, like A/B testing, prismic.io uses a cookie that it assigns to the `req` object.

Simply providing `req` to the API enables unlimited previews, A/B testing and other upcoming powerful features.

You can omit the `req` parameter if you're performing your queries for the client-side (ex: React.js, Angular.js). The API will be able to retrieve the required token on its own.

To learn more about how to query your content, check out the How to Query the API page.

Next we will define a link resolver which will determine what a page's url will look like. This will be used for the preview functionality as well as when we add our content to the templates.

You can read more about this on our Link Resolving page.

You will need to modify the link resolver to fit your needs.

Copy
// Link Resolver
function linkResolver(doc) {
  
  // Define the url depending on the document type
  if (doc.type === 'page') {
    return '/page/' + doc.uid;
  } else if (doc.type === 'blog_post') {
    return '/blog/' + doc.uid;
  }
  
  // Default to homepage
  return '/';
}

5. Add the queried content to your templates

Once you’ve retrieved your content, you can include it in your template. In order to display certain fields such as Rich Text, you will need to use the helper functions included in the prismic-dom library. Be sure to include this library in your files.

Copy
var PrismicDOM = require('prismic-dom');

Then you can load your content in your templates. Here's a simple example using the EJS templating language.

Copy
<div class="content">
  <h1><%= PrismicDOM.RichText.asText(document.data.title) %></h1>
  <img src=<%= document.data.image.url %> />
  <%- PrismicDOM.RichText.asHtml(document.data.body) %>
</div>

You can read more about templating your content in the Templating section of the documentation.

6. Take advantage of previews and edit buttons

In order to take full advantage of prismic.io's features, check out the the in-website preview and edit-button pages. There you will find the steps needed to add these features to your own javascript project.

And your prismic.io journey begins!

You should have all the tools now to really dig into your project. We invite you to further explore the docs to learn how to define your Custom Types, create advanced queries, and add your content to your templates.