Package Exports

@netlify/cache-utils

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (@netlify/cache-utils) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

Utility for caching files in Netlify Build.

Examples

Simple

module.exports = {
  // 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
  async onPreBuild({ 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
  async onPostBuild({ utils }) {
    await utils.cache.save('./path/to/file')
  },
}

Multiple directories

// Restore/cache several files/directories
module.exports = {
  async onPreBuild({ utils }) {
    await utils.cache.restore(['./path/to/file', './path/to/other'])
  },
  async onPostBuild({ 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.

// Only cache the following file/directory for 1 hour
module.exports = {
  async onPreBuild({ utils }) {
    await utils.cache.restore('./path/to/file')
  },
  async onPostBuild({ 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.

// 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.
module.exports = {
  async onPreBuild({ utils }) {
    await utils.cache.restore('node_modules')
  },
  async onPostBuild({ 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 the file/directory already exists locally or if it has not been cached yet.

Please be careful: this overwrites the local file/directory if any exists.

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.

module.exports = {
  async onPostBuild({ 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.

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

module.exports = {
  async onPreBuild({ 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}`)
    }
  },
  async onPostBuild({ 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.

module.exports = {
  async onPreBuild({ 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.