Go to prismic.ioDeveloper Docs

Set up Prismic

Learn how to set up a vanilla JavaScript project with Prismic.

Learn how to set up a vanilla JavaScript project with Prismic.

Building with JavaScript

To get started, you must set up an environment to render content from Prismic. We strongly recommend that you use a framework for your project.

If you want to create a project with vanilla JavaScript, there are two environments where you can do so:

  • The browser
  • Node.js

Next, we’ll explain each environment.

Node.js

Today, if you want to use JavaScript to build a website, you’ll probably use Node.js, a back-end JavaScript runtime.

Node.js alone doesn’t render content in the browser. For that, you would need a bundler or a server, like Express.js, Webpack (which powers React and Vue 2), or Vite (which powers Vue 3 and SvelteKit). For that reason, we strongly recommend that you build your Prismic project with a framework. At the time of writing, we have documentation for the following JavaScript frameworks:

  • Express.js
  • React
  • Next.js
  • Gatsby.js
  • Vue.js
  • Nuxt.js
  • Svelte.js

If you don’t use a framework, it won’t be straightforward to create a website with just Node.js, and this guide will not explain most of the steps.

This guide provides examples in Node.js, but those examples do not generate web pages; the only output will be in the console. To generate web pages, you’ll need to do additional development on your own.

The browser

JavaScript was initially developed to run in the browser. Today, it’s the only widely-used scripting language that runs natively in the browser.

It’s possible to write Vanilla JavaScript for a web app that will run in the browser, but this is strongly discouraged. Such a web app will likely have suboptimal performance, poor SEO, and prohibitive maintenance. For that reason, we recommend using a framework — which will bundle your app for you — such as React or Vue.

If you want to create a website in vanilla JavaScript with no framework, it is possible to write code by hand that will run in the browser.

This guide will provide examples for the browser, but we don’t recommend it for production websites.

The purpose of these examples

These examples provide a theoretical understanding of how Prismic works. They might be helpful for students learning web development or web developers building new frameworks or plugins.

Create a repository

If you don’t already have one, create a repository in Prismic, and then come back.

Create a new repository

Add some custom types and documents to your repository, so you have something to query and template in your project. You can learn more about creating custom types and documents in our Core Concepts documentation.

Setup for the browser

As stated above, we do not recommend creating a production website this way. This guide offers a theoretical introduction. To create a production website, we recommend using a framework.

Create an HTML file

To create a browser project, create a file called index.html, with the basic structure of an HTML page:

<!doctype html>
<html>
  <head>
    <title>Prismic Vanilla JavaScript App</title>
  </head>
  <body></body>
</html>

Import dependencies

Next, before the close of the head, add a script tag with the type='module'. Then, import Prismic’s client package from a CDN.

The package is @prismicio/client, which helps you query the Prismic API and provides a set of helpers to render retrieved data.

<!DOCTYPE html>
<html>
  <head>
    <title>Prismic Vanilla JavaScript App</title>
+   <script type='module'>
+     import * as prismic from 'https://cdn.skypack.dev/@prismicio/client'
+   </script>
  </head>
  <body></body>
</html>

Initialize your client

Then, initialize your client. Pass your repository name to prismic.createClient() to generate a client object.

The client object contains a collection of properties and methods to help you query the Prismic API.

<!DOCTYPE html>
<html>
  <head>
    <title>Prismic Vanilla JavaScript App</title>
    <script type='module'>
      import * as prismic from 'https://cdn.skypack.dev/@prismicio/client'
+
+     const repositoryName = 'your-repository-name'
+     const client = prismic.createClient(repositoryName)
    </script>
  </head>
  <body></body>
</html>

Query the Prismic API

Next, write an init function, which will run when the page loads. Inside this function, we’re going to query a document from the Prismic API using the client’s getFirst() method, which returns the first document on the API.

Then, we’ll extract the title and description from that document. (These properties are defined by the user in your Prismic repository, so they will likely be different in your code.)

<!DOCTYPE html>
<html>
  <head>
    <title>Prismic Vanilla JavaScript App</title>
    <script type='module'>
      import * as prismic from 'https://cdn.skypack.dev/@prismicio/client'

      const repositoryName = 'your-repository-name'
      const client = prismic.createClient(repositoryName)
+
+     const init = async () => {
+       const prismicDoc = await client.getFirst()
+       const { title, description } = prismicDoc.data
+     }
+
+     init()
    </script>
  </head>
  <body></body>
</html>

Template your content

Rich text and titles from the API are delivered as JSON, which must be converted to HTML for your website. We will use Prismic’s asHTML() method to convert the data to HTML.

<!DOCTYPE html>
<html>
  <head>
    <title>Prismic Vanilla JavaScript App</title>
    <script type='module'>
      import * as prismic from 'https://cdn.skypack.dev/@prismicio/client'

      const repositoryName = 'your-repository-name'
      const client = prismic.createClient(repositoryName)

      const init = async () => {
       const prismicDoc = await client.getFirst()
       const { title, description } = prismicDoc.data
+      const titleHTML = prismic.asHTML(title)
+      const descriptionHTML = prismic.asHTML(description)
      }

      init()
    </script>
  </head>
  <body></body>
</html>

Add content to the page

Finally, we will add a new div to our page, to use as a container for our HTML. We will then select that div on the DOM and set the inner HTML using our content from Prismic.

<!DOCTYPE html>
<html>
  <head>
    <title>Prismic Vanilla JavaScript App</title>
    <script type='module'>
      import * as prismic from 'https://cdn.skypack.dev/@prismicio/client'

      const repositoryName = 'your-repository-name'
      const client = prismic.createClient(repositoryName)

      const init = async () => {
        const prismicDoc = await client.getFirst()
        const { title, description } = prismicDoc.data
        const titleHTML = prismic.asHTML(title)
        const descriptionHTML = prismic.asHTML(description)
+       const container = document.getElementById('container')
+       container.innerHTML = titleHTML + descriptionHTML
      }

      init()
    </script>
  </head>
  <body>
+    <div id='container'></div>
  </body>
</html>

Now, if you open the index.html file with your browser, you should see content from Prismic displayed on the page.

Next steps

On the following pages, we will go into more depth about two of the above steps:

  • Fetching, which we did in this example with client.getFirst()
  • Templating, which we did in this example with prismic.asHTML()

Prismic has lots of helpers for fetching and templating, which we will explain in more detail.

Setup for Node.js

As stated above, this guide won’t explain how to create web pages. It offers a theoretical introduction to using Prismic in Node.js. To create a website, we recommend using a framework.

Prerequisites

Before you proceed, you’ll need a package manager like npm or Yarn installed globally on your machine. If you don’t have those, here are some guides we recommend:

The following steps also assume that you’re comfortable using the terminal.

Init your project

Create a directory for your project and open that directory to get started. If you don’t already have an npm project, create one:

npm init

In this project, we’ll use ESModules, so you’ll need to add 'type': 'module' to your package.json.

Then, create a file called index.js (or whatever filename is specified as the main entry point in your package.json).

Install dependencies

Install these dependencies at the root level of your project:

npm install @prismicio/client

@prismicio/client helps you query the Prismic API, and provides a set of helpers to render the retrieved data.

You will also need to install a package that provides a fetch function to make HTTP requests, such as node-fetch:

npm install node-fetch

Import dependencies

In your index.js, import the dependencies you just installed:

+ import * as prismic from '@prismicio/client'
+ import fetch from 'node-fetch'

Initialize your client

Next, initialize your client. Pass your repository name to prismic.createClient() along with an options object that includes the fetch function. This is the function that the client will use to query the API. prismic.createClient() will return a client object that contains a collection of properties and methods to help you query the Prismic API.

  import * as prismic from '@prismicio/client'
  import fetch from 'node-fetch'
+
+ const repositoryName = 'your-repository-name'
+ const client = prismic.createClient(repositoryName, { fetch })

Query the Prismic API

Next, write an init function. Inside this function, we will query a document from the Prismic API using the client’s getFirst() method, which returns the first document on the API.

Then, we’ll extract the title and description from that document. (You define these properties in your Prismic repository, so they will likely be different in your code.)

  import * as prismic from '@prismicio/client'
  import fetch from 'node-fetch'

  const repositoryName = 'your-repository-name'
  const client = prismic.createClient(repositoryName, { fetch })
+
+ const init = async () => {
+   const prismicDoc = await client.getFirst()
+   const { title, description } = prismicDoc.data
+ }
+
+ init()

Template your content

Rich text and titles from the API are delivered as JSON, so you must convert them to HTML for your website. We will use Prismic’s asHTML() method to convert the data to HTML.

Finally, we’ll console.log() the HTML we have created so that we can see the result.

  import * as prismic from '@prismicio/client'
  import fetch from 'node-fetch'

  const repositoryName = 'your-repository-name'
  const client = prismic.createClient(repositoryName, { fetch })

  const init = async () => {
  const prismicDoc = await client.getFirst()
  const { title, description } = prismicDoc.data
+   const titleHTML = prismic.asHTML(title)
+   const descriptionHTML = prismic.asHTML(description)
+   console.log(titleHTML, descriptionHTML)
  }

  init()

Now, run the script in the terminal:

node index.js

You should see the HTML appear as a log in the terminal.

As stated above, this will not generate a web page.

Next steps

If you want to see a complete working example of this setup, with comments, see the following StackBlitz.

On the following pages, we will go into more depth about two of the above steps:

  • Fetching, which we did in this example with client.getFirst()
  • Templating, which we did in this example with prismic.asHTML()

Prismic has lots of helpers for fetching and templating, which we will explain in more detail.