Required dependencies

npm install imgix-url-builder

No native modules, pod installs, or prebuild steps are required. The library is pure TypeScript and runs in both Node.js and browser environments.

Project setup

1. Copy the source/ directory into your project, e.g. src/prismic-client/.

2. Ensure tsconfig.json targets at least ES2017 and includes your source:

{
  "compilerOptions": {
    "target": "ES2020",
    "module": "ESNext",
    "moduleResolution": "bundler",
    "strict": true,
    "paths": {
      "@prismic/*": ["./src/prismic-client/*"]
    }
  },
  "include": ["src"]
}

3. If the source imports from ../package.json (used in WriteClient.ts for the client identifier), create a minimal package.json adjacent to source/ or patch that import to a constant:

// In WriteClient.ts, if needed, replace:
// import { name, version } from "../package.json"
// with:
const name = "@prismicio/client"
const version = "7.21.8"

4. Set the repository name. No env var is required by the library itself, but the pattern is:

const PRISMIC_REPO = process.env.PRISMIC_REPOSITORY_NAME ?? "my-repository"

5. For write/migration operations, provide an API write token via your environment:

const WRITE_TOKEN = process.env.PRISMIC_WRITE_TOKEN ?? ""

Public API

createClient

function createClient(
  repositoryNameOrEndpoint: string,
  options?: ClientConfig
): Client

The primary entry point for read queries. Pass a repository name ("my-repo") or a full endpoint URL. ClientConfig accepts accessToken, routes, fetch, and other options. Use this whenever you need to fetch published or draft content.

filter

const filter: {
  at(path: string, value: unknown): string
  not(path: string, value: unknown): string
  any(path: string, values: unknown[]): string
  fulltext(path: string, value: string): string
  // ...and more predicate builders
}

Composable filter builders for use with client.get, client.getAllByType, etc. Pass the result of filter.* calls into the filters query option. The deprecated alias predicate is also exported.

Migration

class Migration<TDocuments extends PrismicDocument = PrismicDocument> {
  _assets: Map<MigrationAssetConfig["file"], PrismicMigrationAsset>
  _documents: PrismicMigrationDocument<TDocuments>[]
  // methods added via createMigration factory
}

Accumulates assets and documents to be created or updated in a Prismic repository. Build a migration object, register content, then pass it to writeClient.migrate(). Use createMigration() rather than constructing directly.

asLink

function asLink(
  linkField: LinkField | PrismicDocument | null | undefined,
  options?: { resolver?: LinkResolverFunction }
): string | null

Resolves any Prismic link field (web link, document link, media link) to a URL string. Requires a resolver function for document links. Returns null for empty fields.

Working examples

Scenario - Fetch all documents of a type

Query every document of type blog_post from a Prismic repository, with strong TypeScript typing via a document union.

import { createClient } from "./prismic-client/createClient"
import type { PrismicDocument } from "./prismic-client/types/value/document"

interface BlogPostDocument extends PrismicDocument {
  type: "blog_post"
  data: { title: string; body: unknown[] }
}

type AppDocuments = BlogPostDocument

const client = createClient<AppDocuments>("my-repository", {
  accessToken: process.env.PRISMIC_ACCESS_TOKEN,
})

async function fetchBlogPosts(): Promise<BlogPostDocument[]> {
  return client.getAllByType("blog_post")
}

fetchBlogPosts().then((posts) => {
  posts.forEach((post) => console.log(post.data.title))
})

Scenario - Filter documents with predicates

Use filter to find documents matching specific field values.

import { createClient } from "./prismic-client/createClient"
import { filter } from "./prismic-client/filter"

const client = createClient("my-repository")

async function getFeaturedArticles() {
  const response = await client.get({
    filters: [
      filter.at("document.type", "article"),
      filter.at("my.article.is_featured", true),
    ],
    pageSize: 10,
    orderings: [{ field: "document.first_publication_date", direction: "desc" }],
  })
  return response.results
}

getFeaturedArticles().then(console.log)

Scenario - Resolve rich text and links

Convert Prismic rich text fields to plain text and resolve link fields to URLs.

import { asText } from "./prismic-client/helpers/asText"
import { asLink } from "./prismic-client/helpers/asLink"
import { asDate } from "./prismic-client/helpers/asDate"
import { isFilled } from "./prismic-client/helpers/isFilled"
import type { RichTextField } from "./prismic-client/types/value/richText"
import type { LinkField } from "./prismic-client/types/value/link"

function linkResolver(doc: { type: string; uid: string | null }) {
  if (doc.type === "blog_post") return `/blog/${doc.uid}`
  return "/"
}

function renderCard(doc: {
  data: { title: RichTextField; cta_link: LinkField; published_at: string }
}) {
  const title = asText(doc.data.title)
  const href = asLink(doc.data.cta_link, { resolver: linkResolver })
  const date = isFilled.date(doc.data.published_at)
    ? asDate(doc.data.published_at)
    : null

  return { title, href, date }
}

Scenario - Run a content migration

Create a migration, register documents, and execute via WriteClient.

import { createMigration } from "./prismic-client/createMigration"
import { createWriteClient } from "./prismic-client/createWriteClient"

const writeClient = createWriteClient("my-repository", {
  writeToken: process.env.PRISMIC_WRITE_TOKEN!,
})

async function runMigration() {
  const migration = createMigration()

  migration.createDocument(
    {
      type: "blog_post",
      uid: "hello-world",
      lang: "en-us",
      data: { title: [{ type: "heading1", text: "Hello World", spans: [] }] },
    },
    "Hello World Post",
  )

  await writeClient.migrate(migration, {
    reporter: (event) => console.log(event.type),
  })
}

runMigration()

File walkthrough

• index.ts - Barrel that re-exports the entire public surface; import from here in consuming code.
• Client.ts - Implements all read query methods (get, getByUID, getAllByType, preview resolution, etc.) with automatic retries and ref management.
• WriteClient.ts - Extends Client with migrate(), asset upload, and document write methods; uses pLimit for concurrency control.
• Migration.ts - Stateful accumulator for migration assets and documents; used as input to WriteClient.migrate().
• createClient.ts / createWriteClient.ts / createMigration.ts - Thin factory wrappers for the three main classes.
• buildQueryURL.ts - Pure function converting query options into a Prismic REST API URL string.
• filter.ts - Predicate/filter builder functions for composing query constraints.
• errors.ts - Typed error hierarchy (PrismicError → NotFoundError, ForbiddenError, RefExpiredError, etc.).
• cookie.ts - Constants for Prismic cookie names used in preview resolution.
• getRepositoryEndpoint.ts / getRepositoryName.ts / getGraphQLEndpoint.ts / getToolbarSrc.ts - URL utility functions.
• isRepositoryEndpoint.ts / isRepositoryName.ts - Boolean guards for validating input strings.
• helpers/ - Field-level utilities covering dates, HTML serialization, image src/srcset, links, rich text, and slice zones.
• richtext/ - Core rich text engine: tree builder, serializer, map-serializer wrapper, and type definitions.
• lib/ - Private internals: HTTP request wrapper, pLimit concurrency limiter, migration data resolvers, HTML escaping, dev-mode warnings.
• types/ - TypeScript-only type declarations for API responses, content model shapes, migration payloads, and field value shapes.

Common pitfalls and fixes

• ../package.json import fails at build time - WriteClient.ts imports name and version from the package root; if your bundler cannot resolve it, replace with hardcoded constants or an alias.
• fetch not available in Node.js < 18 - Pass a fetch implementation (e.g. node-fetch) in ClientConfig.fetch; Node 18+ has global fetch built in.
• ESM/CJS interop errors with imgix-url-builder - Ensure your bundler or tsconfig module resolution is set to bundler or node16; avoid mixing require() and import for this dep.
• Preview cookies not resolving - The Client reads preview tokens from request cookies; pass your HTTP request object (Express req or Web API Request) to client.resolvePreviewURL({ request }).
• writeToken vs accessToken confusion - accessToken is for read API; writeToken (passed in WriteClientConfig) is the separate migration/write API token. Both may be required simultaneously.
• Type errors on getAllByType return - Register your document union as the generic parameter to createClient<AppDocuments>(...) so return types narrow correctly; without it you get PrismicDocument<Record<string, never>>.

Vibe-coding prompt template

I have the Prismic client library source at `src/prismic-client/` in my project.
The integration guide is in `USAGE.md` next to this source.
The upstream package is `@prismicio/client@7.21.8`.

Please help me integrate it into my project step by step:

1. Read `USAGE.md` for the full API surface, real import paths, and setup steps.
2. Use only the exports documented in `USAGE.md` and visible in `src/prismic-client/index.ts`.
3. Create a Prismic client instance using `createClient` from `src/prismic-client/createClient.ts`.
4. Wire up the client in [describe your framework, e.g. "an Express middleware" / "Next.js route handlers"].
5. Add helper usage (asText, asLink, isFilled) where I display Prismic field data.
6. If I need write/migration support, use `createWriteClient` and `createMigration` as shown in USAGE.md.
7. Do not import from `@prismicio/client` (the npm package); always import from `src/prismic-client/`.
8. Show me the TypeScript types I need to define for my custom document types.

License and credit

The source is licensed under the Apache License, Version 2.0. See source/LICENSE if present, or refer to the upstream repository for the full license text. Upstream package: @prismicio/client by Prismic.

This product’s unique contribution is clean room implementation of valuable code block into AVCP compatible standard.

The full install guide and integration prompts unlock after purchase.