Installation

Glacier installs as a single package and works with any JavaScript runtime. This guide covers adding it to a project and creating your first client.

Requirements

Glacier supports Node.js 18 and newer, as well as modern edge runtimes (Cloudflare Workers, Vercel Edge, Deno). It has no native dependencies, so it installs cleanly anywhere npm runs.

Install the package

Add the core package with your package manager of choice:

npm install @glacier/core

If you're working in React, install the bindings too. They provide a provider component and hooks like useGlacier:

npm install @glacier/react

Create a client

Create one client and export it so the rest of your app can import it. This is the only required setup.

// glacier.config.js
import { Glacier } from '@glacier/core'

export const glacier = new Glacier({
  strategy: 'predictive',
  edge: true,
  ttl: '5m',
})

Configuration options

• strategy — 'predictive' (default) learns access patterns and prefetches; 'lazy' only caches what's explicitly requested.
• edge — when true, predictions and warming run at the nearest edge location.
• ttl — default time-to-live for cached entries. Accepts a duration string like '30s' or '5m'.

Verify it's working

Wrap a data fetch and read it twice. The second read should resolve from cache:

import { glacier } from './glacier.config'

const getPosts = glacier.predict('posts', () => api.fetchPosts())

await getPosts() // fetches and warms
await getPosts() // served from cache

You're set. Next, read Understanding predictive caching to learn how Glacier decides what to warm.