ts-prismic

A light-weight interface to Prismic's REST API.

This package provides:

• URL builders for the REST API V2
• Predicate builders for repository queries
• TypeScript types for API responses

This is not a batteries-included API client. Instead, this library provides you the minimal set of tools to fetch and manage data yourself.

This means your codebase can be lean and purpose-built.

Status

Installation

npm install --save ts-prismic

Example Usage

Note: The following examples use Got to make API requests, but any method can be used, including fetch.

Get the default API endpoint for a repository:

import * as prismic from 'ts-prismic'

const endpoint = prismic.defaultEndpoint('qwerty')

Request a repository's metadata, such as refs and custom types.

import * as prismic from 'ts-prismic'
import got from 'got'

const endpoint = prismic.defaultEndpoint('qwerty')
const url = prismic.buildRepositoryURL(endpoint)
const repository = (await got(url).json()) as prismic.Response.Repository

Get the master ref from the metadata:

const masterRef = repository.refs.find((ref) => ref.isMasterRef)

Query all documents:

import * as prismic from 'ts-prismic'
import got from 'got'

const url = prismic.buildQueryURL(
  endpoint, // Defined in previous example
  masterRef.ref, // Defined in previous example
)
const allDocs = (await got(url).json()) as prismic.Response.Query

Query with predicates:

import * as prismic from 'ts-prismic'
import got from 'got'

const url = prismic.buildQueryURL(
  endpoint, // Defined in previous example
  masterRef.ref, // Defined in previous example
  [
    prismic.predicate.at('document.type', 'blog-post'),
    prismic.predicate.has('my.blog-post.title'),
  ],
)
const blogPosts = (await got(url).json()) as prismic.Response.Query

Query with parameters:

import * as prismic from 'ts-prismic'
import got from 'got'

const url = prismic.buildQueryURL(
  endpoint, // Defined in previous example
  masterRef.ref, // Defined in previous example
  prismic.predicate.at('document.type', 'blog-post'),
  { orderings: 'my.blog-post.date', orderingsDirection: 'desc' },
)
const blogPosts = (await got(url).json()) as prismic.Response.Query

API

All functions and types are documented in the source files using TSDoc to provide documentation directly in your editor.

If you editor does not have TSDoc integration, you can read all documentation by viewing the source files.

URL Builders

The following functions can be used to build an API request URL.

• buildQueryURL
• buildRepositoryURL
• defaultEndpoint

Predicate Builders

The following functions can be used to build predicates for use with buildQueryURL.

• at
• not
• any
• in
• fulltext
• has
• missing
• similar
• geopointNear
• numberLessThan
• numberGreaterThan
• numberInRange
• dateAfter
• dateBefore
• dateBetween
• dateDayOfMonth
• dateDayOfMonthAfter
• dateDayOfMonthBefore
• dateDayOfWeek
• dateDayOfWeekAfter
• dateDayOfWeekBefore
• dateMonth
• dateMonthAfter
• dateMonthBefore
• dateYear
• dateHour
• dateHourAfter
• dateHourBefore

Types

The following types can be used to type API responses:

• Response.Repository
• Response.Query

The following types may be useful throughout your project:

• Document
• Ref