Set up Prismic
This technology has no Slice Machine integration
This framework has no integration with Prismic's developer tool, Slice Machine. You can still build a Prismic website with this technology by using Prismic's Legacy Builder. However, if you're starting a new project with Prismic, we strongly recommend using a technology that integrates with Slice Machine: Next.js or Nuxt.
Learn how to set up a vanilla JavaScript project with Prismic.
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.
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.
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.
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.
ℹ️ Proceed with caution
As explained above, it is not practical to build a Prismic website with Vanilla JavaScript. The examples in this guide are purely theoretical. We strongly recommend that you develop your Prismic project with a framework.
See the docs homepage for a complete list of supported frameworks.
If you don't already have one, create a repository in Prismic, and then come back.
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.
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.
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></div>
</html>
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></div>
</html>
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>
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>
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>
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.
If you want to see a complete working example of this setup, with comments, see the following JSFiddle.
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.
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.
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:
- Install Node.js and NPM on Mac - William Vincent
- Install Node.js and NPM on Windows - William Vincent
The following steps also assume that you're comfortable using the terminal.
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 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 * as prismic from '@prismicio/client'
import fetch from 'node-fetch'
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 })
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()
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.
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.
Can't find what you're looking for?
Need technical Support? Spot an error in the documentation? Get in touch with us on our Community Forum.