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.
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:
The following types may be useful throughout your project: