Integrating Prismic with an existing Node.js project

If you already have a Node.js project that you want to integrate with Prismic, then you can simply add the Prismic javascript library as a dependency to your project. Let's walk through all the steps to get Prismic 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. To learn more, check out our documentation for Creating Custom Types.

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

2. Add the Prismic development kits as dependencies

Now let’s add the Prismic development kits as a 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 prismic-javascript prismic-dom --save

3. Include an instance of each kit in your file

To use the Prismic javascript libraries, you’ll need to include an instance of each. For example in your app.js file you can include them by adding the following code.

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

4. Add a variable for your API Endpoint

Now we will add a variable for your API Endpoint. Make sure to update the following code with your repository's name.

Copy
var apiEndpoint = 'http://your-repo-name.prismic.io/api/v2';

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 '/';
}

6. Create a middleware to add the prismic context

Here we add a middleware function that is run on every route. It will add the prismic context along with the PrismicDOM library to the locals so that we can access these in our templates.

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

// Middleware to inject prismic context
app.use(function(req, res, next) {
  res.locals.ctx = {
    endpoint: apiEndpoint,
    linkResolver: linkResolver,
  };
  // add PrismicDOM in locals to access them in templates.
  res.locals.PrismicDOM = PrismicDOM;
  next();
});

7. Connect to the API

Next we need to add a simple function that initializes the Prismic API.

Without an access token

If your API is public, then you don't need an access token for the API.

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

// Initialize the prismic.io api
function initApi(req) {
  return Prismic.getApi(apiEndpoint, {
    req: req
  });
}

With an access token

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

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

// Initialize the prismic.io api
function initApi(req) {
  return Prismic.getApi(apiEndpoint, {
    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 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 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.

8. Add queries to your routes

Now we can query your Prismic repository and retrieve the content. Add a query like the one below to your routes.

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

// Homepage Route
app.get('/', function (req, res) {	
  initApi(req).then(function(api) {
    api.query(
      Prismic.Predicates.at('document.type', 'homepage')
    ).then(function(response) {
      // response is the response object. Render your views here.
      res.render('index', { document: response.results[0] });
    });
  });
});

To learn more about querying the API, check out the How to Query the API page.

Pagination of API Results

When querying a Prismic repository, your results will be paginated. By default, there are 20 documents per page in the results. You can read more about how to manipulate the pagination in the Pagination for Results page.

9. Add the queried content to your templates

Once you’ve retrieved your content and passed it to your view, you can include the content in your template using the helper functions in the PrismicDOM development kit. Here’s a simple example.

  • ejs
  • pug
Copy
// In your index.ejs view
<div class="content">
  <h1><%= PrismicDOM.RichText.asText(document.data.title) %></h1>
  <img src="<%= document.data.image.url %>" />
  <%- PrismicDOM.RichText.asHtml(document.data.description, ctx.linkResolver) %>
</div>
Copy
// In your index.pug view
div.content
  h1 !{ PrismicDOM.RichText.asText(document.data.title) }
  img(src=document.data.image.url)
  != PrismicDOM.RichText.asHtml(document.data.description, ctx.linkResolver)

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

10. Take advantage of previews and edit buttons

In order to take full advantage of Prismic'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 Node.js app.

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 docs to learn how to define your Custom Types, query the API, and add your content to your templates.