Integrating with an existing 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.

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.

npm install @prismicio/client 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.

const Prismic = require('@prismicio/client');
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.

var apiEndpoint = '';

5. Add a Link Resolver

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.

// 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.

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;

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.

const Prismic = require('@prismicio/client');

// Initialize the 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.

const Prismic = require('@prismicio/client');

// Initialize the 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, Prismic uses a cookie that it assigns to the `req` object.

Simply providing `req` to the API enables unlimited previews 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.

const Prismic = require('@prismicio/client');

// Homepage Route
app.get('/', function (req, res) {	
  initApi(req).then(function(api) {
    api.query('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
// In your index.ejs view
<div class="content">
  <h1><%= PrismicDOM.RichText.asText( %></h1>
  <img src="<%= %>" />
  <%- PrismicDOM.RichText.asHtml(, ctx.linkResolver) %>
// In your index.pug view
  h1 !{ PrismicDOM.RichText.asText( }
  != PrismicDOM.RichText.asHtml(, ctx.linkResolver)

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

10. Take advantage of Previews and the Prismic Toolbar

In order to take full advantage of Prismic's features, check out the Previews and the Prismic Toolbar page. 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.

Was this article helpful?
Not really
Yes, Thanks

Can't find what you're looking for? Get in touch with us on our Community Forum.