@pack/client: Client Library Documentation

The @pack/client package provides a client for interacting with the Pack GraphQL API.

Quick Start

Install the client with a package manager:

npm install @pack/client

Import and create a new client instance, and use its methods to interact with your project's Content Lake. Below is a simple example in a React Router 7 (Hydrogen) route. In a Hydrogen storefront you will usually query through context.pack from @pack/hydrogen instead, which wraps this client with caching, preview mode, and A/B testing.

Example

import {useEffect} from 'react'
import {useLoaderData} from 'react-router'
import {PackClient} from '@pack/client'

import type {Route} from './+types/site-settings'

// Loader function for this specific route
export async function loader({context}: Route.LoaderArgs) {
  return {
    token: context.env.PACK_SECRET_TOKEN,
  }
}

const SITE_SETTINGS_QUERY = `
  query SiteSettings($version: Version) {
    siteSettings(version: $version) {
      id
      status
      settings
      seo {
        title
        description
        keywords
      }
      favicon
      publishedAt
      createdAt
      updatedAt
    }
  }
`

export default function SiteSettingsRoute() {
  const {token} = useLoaderData<typeof loader>()

  useEffect(() => {
    // Initialize the client with the fetched token
    const packClient = new PackClient({
      token,
      apiUrl: 'https://app.packdigital.com/graphql', // defaults to our CDN API https://apicdn.packdigital.com/graphql
      contentEnvironment: 'content_environment_handle', // defaults to the primary content environment
    })

    // Make a query to fetch the site settings
    packClient
      .fetch(SITE_SETTINGS_QUERY, {variables: {version: 'CURRENT'}})
      .then(({data, error}) => {
        if (error) console.error(error)
        console.log(data?.siteSettings)
      })
  }, [token])

  return (
    <div>
      <h1>Site Settings</h1>
    </div>
  )
}

This example sends your secret token to the browser for illustration only. In production, query Pack on the server (for example, in a loader) and keep PACK_SECRET_TOKEN server-side.

`PackClientOptions`

interface PackClientOptions {
  /** Pack API token. Required: the constructor throws ERR_CL_MISSING_TOKEN without it */
  token?: string
  /** Pack Store ID, sent as X-Pack-Storefront-Id */
  storeId?: string
  /** The content environment handle, sent as X-Environment */
  contentEnvironment?: string
  /** The session ID, sent as X-Pack-Session-Id */
  sessionId?: string
  /** The URL of the Pack GraphQL API. Defaults to https://apicdn.packdigital.com/graphql */
  apiUrl?: string
  /** The client name, sent as x-graphql-client-name. Defaults to 'PackClient' */
  clientName?: string
  /** Locale code for content, e.g. 'es-ES', sent as X-Locale */
  locale?: string
  /** Content release ID to preview, sent as X-Pack-Release-Id */
  releaseId?: string
  /** Page draft ID to preview, sent as X-Page-Draft */
  pageDraft?: string
  /** Site settings draft ID to preview, sent as X-Site-Settings-Draft */
  siteSettingsDraft?: string
  /** A/B test handle, sent as X-Pack-Test-Handle */
  testHandle?: string
  /** A/B test variant handle, sent as X-Pack-Test-Variant-Handle */
  testVariantHandle?: string
  /** Resolve tests regardless of status (draft/ended), sent as X-Pack-Test-Ignore-Test-Status */
  ignoreTestStatus?: boolean
}

Headers are only sent for options you set, except X-Environment, X-Pack-Storefront-Id, and X-Pack-Session-Id, which are always sent (empty when unset).

Methods

Name
fetch
Type
(query: string, options?: { variables?: Record<string, any>; headers?: Record<string, string> }) => Promise<{ data, error }>
Description
Sends a GraphQL request. headers are merged over the default headers. GraphQL errors are returned as error ({ message, param, code, type }) from the first error; a non-2xx response throws ERR_CL_API_ERROR.
Name
isValidEditToken
Type
(token: string | null) => Promise<any>
Description
Validates a Customizer edit token. Used by @pack/hydrogen preview mode.

Resources

GraphQL CMS API

Learn more about our GraphQL content APIs