# @netlify/cache-utils

> Utility for caching files in Netlify Build

Latest version **7.1.2** (published 2026-08-25) · MIT license · 0 weekly downloads

## Install

```sh
npm install @netlify/cache-utils
pnpm add @netlify/cache-utils
yarn add @netlify/cache-utils
bun add @netlify/cache-utils
```

## Health

**Score 75/100 (B)** — status: active.

Positive: has types; esm support; no vulnerabilities; has provenance; recently updated; high maintenance score; high quality score.

Warnings: low downloads.

## Facts

| | |
|---|---|
| Version | 7.1.2 |
| Published | 2026-08-25 |
| First published | 2019-12-19 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Node | >=22.12.0 |
| Dependencies | 2 |
| Unpacked size | 26.2 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Provenance | attested (GitHub Actions) |
| GitHub stars | 258 |
| Author | Netlify Inc. |
| Maintainers | netlify-bot, mikewen, youvalv, serhalp-netlify, mlgualtieri-gatsby |
| Keywords | nodejs, javascript, windows, macos, linux, shell, bash, build, terminal, deployment, es6, serverless, continuous-integration, continuous-delivery, ci, continuous-deployment, plugins, continuous-testing, netlify-plugin, netlify |

## Links

- npm: https://www.npmjs.com/package/@netlify/cache-utils
- Repository: https://github.com/netlify/build
- Issues: https://github.com/netlify/build/issues
- npm.io page: https://npm.io/package/@netlify/cache-utils

## Dependencies (2)

- [junk](https://npm.io/package/junk.md) ^4.0.0
- [get-stream](https://npm.io/package/get-stream.md) ^9.0.0

## Alternatives

- [random-seedable](https://npm.io/package/random-seedable.md) — 27.9K weekly downloads
- [n2words](https://npm.io/package/n2words.md) — 22.2K weekly downloads
- [@stdlib/math-base-special-factorialln](https://npm.io/package/@stdlib/math-base-special-factorialln.md) — 5.7K weekly downloads
- [@stdlib/math-base-special-abs2](https://npm.io/package/@stdlib/math-base-special-abs2.md) — 1.7K weekly downloads
- [commons-math-interpolation](https://npm.io/package/commons-math-interpolation.md) — 1.4K weekly downloads

## Recent versions

- 7.1.2 (latest) — 2026-08-25
- 4.1.6-rc (rc) — 2022-09-23
- 1.0.8-0 (beta) — 2021-03-08
- 1.0.2-0 (debug) — 2020-08-26
- 7.1.1 — 2026-08-03
- 7.1.0 — 2026-07-17
- 7.0.0 — 2026-06-16
- 6.0.5 — 2026-02-25
- 6.0.4 — 2025-08-08
- 6.0.3 — 2025-05-29
- 6.0.2 — 2025-05-22
- 6.0.1 — 2025-05-20
- 6.0.0 — 2025-05-14
- 5.2.0 — 2024-12-11
- 5.1.6 — 2024-08-05
- … 50 more at https://npm.io/package/@netlify/cache-utils/versions

## README

[![Coverage Status](https://codecov.io/gh/netlify/build/branch/main/graph/badge.svg)](https://codecov.io/gh/netlify/build)
[![Build](https://github.com/netlify/build/workflows/Build/badge.svg)](https://github.com/netlify/build/actions)

Utility for caching files in Netlify Build

# Examples

## Simple

```js
// Restore file/directory cached in previous builds.
// Does not do anything if:
//  - the file/directory already exists locally
//  - the file/directory has not been cached yet
export const onPreBuild = async function ({ utils }) {
  await utils.cache.restore('./path/to/file')
}

// Cache file/directory for future builds.
// Does not do anything if:
//  - the file/directory does not exist locally
export const onPostBuild = async function ({ utils }) {
  await utils.cache.save('./path/to/file')
}
```

## Multiple directories

```js
// Restore/cache several files/directories
export const onPreBuild = async function ({ utils }) {
  await utils.cache.restore(['./path/to/file', './path/to/other'])
}

export const onPostBuild = async function ({ utils }) {
  await utils.cache.save(['./path/to/file', './path/to/other'])
}
```

# API

## save(path, options?)

`path`: `string`\
`options`: `object`\
_Returns_: `Promise<Boolean>`

Cache a file/directory.

Skipped if the file/directory does not exist locally.

Returns `false` if the file/directory does not exist. Returns `true` otherwise.

### options

#### ttl

_Type_: `number` (in seconds)\
_Default_: `undefined`

Only cache the file/directory for a specific amount of time.

```js
// Only cache the following file/directory for 1 hour
export const onPreBuild = async function ({ utils }) {
  await utils.cache.restore('./path/to/file')
}

export const onPostBuild = async function ({ utils }) {
  const ttl = 3600
  await utils.cache.save('./path/to/file', { ttl })
}
```

#### digests

_Type_: `string[]`\
_Default_: `[]`

Paths to lock files or manifest files that can be used to check if the directory to cache has changed. Using this option
speeds up caching.

```js
// If that directory has a lockfile or a manifest file, use it to check if its
// contents has changed. This will speed up cache saving.
// For example, `package-lock.json` and `yarn.lock` are digest files for the
// `node_modules` directory.
export const onPreBuild = async function ({ utils }) {
  await utils.cache.restore('node_modules')
}

export const onPostBuild = async function ({ utils }) {
  await utils.cache.save('node_modules', {
    digests: ['package-lock.json', 'yarn.lock'],
  })
}
```

#### cwd

_Type_: `string` \
_Default_: `process.cwd()`

Current directory used to resolve relative paths.

## restore(path, options?)

`path`: `string`\
`options`: `object`\
_Returns_: `Promise<Boolean>`

Restore a file/directory previously cached. Skipped if it has not been cached yet.

Please be careful: if the file/directory was cached, this will delete local file/directory and replace it with cached
content.

Returns `false` if the file/directory was not cached yet. Returns `true` otherwise.

### options

#### cwd

_Type_: `string` \
_Default_: `process.cwd()`

Current directory used to resolve relative paths.

## remove(path, options?)

`path`: `string`\
_Returns_: `Promise<Boolean>`

Remove a file/directory from the cache. Useful for cache invalidation.

Returns `false` if the file/directory was not cached yet. Returns `true` otherwise.

```js
export const onPostBuild = async function ({ utils }) {
  await utils.cache.remove('./path/to/file')
}
```

### options

#### cwd

_Type_: `string` \
_Default_: `process.cwd()`

Current directory used to resolve relative paths.

## has(path, options?)

`path`: `string`\
_Returns_: `Promise<Boolean>`

Returns whether a file/directory is currently cached.

```js
// Conditional logic can be applied depending on whether the file has been
// previously cached or not
const path = './path/to/file'

export const onPreBuild = async function ({ utils }) {
  if (!(await utils.cache.has(path))) {
    console.log(`File ${path} not cached`)
    return
  }

  console.log(`About to restore cached file ${path}...`)
  if (await utils.cache.restore('./path/to/file')) {
    console.log(`Restored cached file ${path}`)
  }
}

export const onPostBuild = async function ({ utils }) {
  if (await utils.cache.save('./path/to/file')) {
    console.log(`Saved cached file ${path}`)
  }
}
```

### options

#### cwd

_Type_: `string` \
_Default_: `process.cwd()`

Current directory used to resolve relative paths.

## list(options?)

_Returns_: `Promise<string[]>`

Returns the absolute paths of the files currently cached. Those are the paths of the files before being saved (or after
being restored), not while being cached.

```js
export const onPreBuild = async function ({ utils }) {
  const files = await utils.cache.list()
  console.log('Cached files', files)
}
```

### options

#### cwd

_Type_: `string` \
_Default_: `process.cwd()`

Current directory used to resolve relative paths.

#### depth

_Type_: `number` \
_Default_: `1`

Number of subdirectories to include. `0` means only top-level directories will be included.

---
_Source: https://npm.io/package/@netlify/cache-utils · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._