This add-on is operated by prismic.io

API-based CMS backend for your Heroku apps

Prismic

Last updated 13 April 2020

prismic.io is an add-on for providing a CMS backend.

Adding prismic.io to an application provides a full-featured writing room to write content in a user-friendly editor, based on the custom types that you define. The content can then be accessed via a REST API, and development kits are provided in the most popular languages: JavaScript, PHP, Java, Ruby, Python, C# and Scala.

Provisioning the add-on

Prismic.io can be attached to a Heroku application via the CLI:

$ heroku addons:create prismic
-----> Adding prismic to sharp-mountain-4005... done, v18 (free)

Once prismic has been added a PRISMIC_ENDPOINT config var will be available in the app configuration and will contain the URL used to request your API. This can be confirmed using the heroku config:get command.

$ heroku config:get PRISMIC_ENDPOINT
https://<repo-name>.prismic.io/api

After installing prismic, the application should be configured to fully integrate with the add-on.

Local setup

After provisioning the add-on it’s necessary to locally replicate the config vars so your development environment can operate against the service.

Use the Heroku Local command-line tool to configure, run and manage process types specified in your app’s Procfile. Heroku Local reads configuration variables from a .env file. To view all of your app’s config vars, type heroku config. Use the following command for each value that you want to add to your .env file.

$ heroku config:get PRISMIC_ENDPOINT -s  >> .env

For more information, see the Heroku Local article.

Full blog sample in NodeJS

If you’re starting from scratch in JavaScript, you can use the prismic.io command line tool to bootstrap your project. Here is how you can create a blog from a template in just a few minutes. To start from an existing project or a different technology, skip to the next section.

Start by installing the prismic.io CLI:

$ npm install -g prismic-cli

Source code

In the directory of your project, after adding the addon, initialize the source code:

$ prismic heroku --template NodeJS-blog
Initialize local project...
Running npm install...
Your project in ready! Go to the undefined folder and follow the instructions in the README.

The heroku command will ensure the environment variable set by Heroku will be used as the endpoint, and the template option specify that you want the blog template.

Custom types

Open the writing room, from the Heroku console or via the CLI:

$ heroku addons:open prismic
Opening prismic for sharp-mountain-4005

In the writing room, create the bloghome custom type:

{
  "Main" : {
    "headline" : {
      "type" : "StructuredText",
      "config" : {
        "placeholder" : "Main title...",
        "single" : "heading1"
      }
    },
    "description" : {
      "type" : "StructuredText",
      "config" : {
        "placeholder" : "Sub-title",
        "single" : "heading2"
      }
    },
    "image" : {
      "type" : "Image"
    }
  }
}

Then create the post custom type:

{
  "Blog Post" : {
    "uid" : {
      "type" : "UID",
      "config" : {
        "placeholder" : "unique-identifier-for-blog-post-url"
      }
    },
    "title": {
      "type": "Text",
      "config": {
        "label": "Title"
      }
    },
    "date" : {
      "fieldset" : "Post properties",
      "type" : "Date",
      "config" : {
        "label" : "Post date"
      }
    },
    "body" : {
      "fieldset" : "Post content",
      "type" : "Slices",
      "config" : {
        "labels" : {
          "image-with-caption" : [ {
            "name" : "emphasized",
            "display" : "Emphasized"
          }, {
            "name" : "image-full-width",
            "display" : "Full"
          } ]
        },
        "choices" : {
          "text" : {
            "type" : "StructuredText",
            "fieldset" : "Text",
            "config" : {
              "multi" : "paragraph, heading2, heading3, strong, em, hyperlink, ulist, list-item",
              "placeholder" : "Post text..."
            }
          },
          "quote" : {
            "type" : "StructuredText",
            "fieldset" : "Quote",
            "config" : {
              "placeholder" : "Post quote...",
              "single" : "paragraph"
            }
          },
          "image-with-caption" : {
            "type" : "Group",
            "fieldset" : "Post image and caption",
            "config" : {
              "fields" : {
                "illustration" : {
                  "type" : "Image",
                  "config" : {
                    "constraint" : {
                      "width" : 640
                    }
                  }
                },
                "caption" : {
                  "type" : "StructuredText",
                  "config" : {
                    "single" : "heading3",
                    "placeholder" : "Image caption..."
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}

Write some content

Start by filling in your photo, your name and a headline for your blog’s homepage.

Go to “Content” and hit “New”, choose the Blog’s home type and fill it with your own content. Save and publish!

Now, write a few blog posts. Make sure to fill in the mandatory UID field that is used for your post’s URL. Save and publish!

Start your blog!

You can run it locally like any other application on Heroku:

$ heroku local

And you can of course deploy it!

Using in an existing project

Prismic.io can be used the same way from your local machine or from Heroku servers. While the data is available from a REST API, it is recommended to use the kit provided for your language.

Node.js

Just install the npm package:

$ npm install prismic.io

The API object can then be queried:

var prismic = require('prismic.io');

app.route('/:uid').get(function(req, res) {
  var uid = req.params.uid;
  prismic.api(process.env.PRISMIC_ENDPOINT, {req:req}).then(function(api) {
    return api.getByUID('basic-page', uid));
  }).then(function(doc) {
    res.render('index', {
      pageContent: doc
    });
  });
});

Client-side JavaScript

If you’re building client-side JavaScript from npm packages, you can install it like indicated above in the Node.js section.

Otherwise you can use the version from the CDN:

https://npmcdn.com/prismic.io@2.0.0/dist/prismic.io.min.js

You can then query your repository in a similar way to the Node.js example above.

Ruby/Rails

To install the gem on your computer, run in shell:

$ gem install prismic.io --pre

then add in your code:

require 'prismic'
endpoint = ENV['PRISMIC_ENDPOINT']

api = Prismic.api(endpoint)
doc = api.getByUID('basic-page', params[:uid])

PHP

Install the kit from Composer:

$ composer require prismic/php-sdk

Then use prismic in your code:

$uid = $_GET('uid');
$doc = $api->getByUID("basic-page", $uid);

Writing room

The writing room allows you to define custom types, write content, and publish documents that will be available through your API.

The writing room can be accessed via the CLI:

$ heroku addons:open prismic
Opening prismic for sharp-mountain-4005

or by visiting the Heroku Dashboard, going to the application you want to access, and selecting prismic.io from the Add-ons menu.

Configuring previews and edit button.

With prismic.io, you can preview draft content or future releases directly on your live website. You can also have an edit button display on your website for writers who are logged in.

More information on configuring previews can be found in our online documentation.

Removing the add-on

Prismic.io can be removed via the CLI.

$ heroku addons:destroy prismic
-----> Removing prismic from sharp-mountain-4005... done, v20 (free)

Support

All prismic.io support and runtime issues should be submitted via one of the Heroku Support channels. Any non-support related issues or product feedback is welcome at contact@prismic.io.