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 = {
  name: 'example-plugin',
  // 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
  //  - the file/directory is already cached and its contents has not changed
  //    If this is a directory, this includes children's contents
  async onPostBuild({ utils }) {
    await utils.cache.save('./path/to/file')
  }
}

Multiple directories

// Restore/cache several files/directories
module.exports = {
  name: 'example-plugin',
  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 is already cached and its contents has not changed.

Returns true if the file/directory was cached, false otherwise.

options

move

Type: boolean
Default: false

Move files to the cache instead of copying them. This is much faster but this removes local files, so should only be done when those files won't be used anymore by the current build.

// Move files to the cache instead of copying them. This is much faster but this
// removes local files, so should only be done when those files won't be used
// anymore by the current build.
module.exports = {
  name: 'example-plugin',
  async onPreBuild({ utils }) {
    await utils.cache.restore('./path/to/file', { move: true })
  }
  async onPostBuild({ utils }) {
    await utils.cache.save('./path/to/file', { move: true })
  }
}

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 = {
  name: 'example-plugin',
  async onPreBuild({ utils }) {
    await utils.cache.restore('./path/to/file')
  }
  async onPostBuild({ utils }) {
    await utils.cache.save('./path/to/file', { ttl: 3600 })
  }
}

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.

// Computing whether a big directory of files has changed or not can be slow.
// If that directory has a lockfile or a manifest file that can be used to
// check if its contents has changed, you can pass it to the `digests` option.
// This will speed up cache saving.
// For example, `package-lock.json` and `yarn.lock` are digest files for the
// `node_modules` directory.
module.exports = {
  name: 'example-plugin',
  async onPreBuild({ utils }) {
    await utils.cache.restore('node_modules')
  }
  async onPostBuild({ utils }) {
    await utils.cache.save('node_modules', {
      digests: ['package-lock.json', 'yarn.lock']
    })
  }
}

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.

Returns true if the file/directory was restored, false otherwise.

options

move

Type: boolean
Default: false

remove(path)

path: string
Returns: Promise<Boolean>

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

Returns true if the file/directory cache was removed, false otherwise.

module.exports = {
  name: 'example-plugin',
  async onPostBuild({ utils }) {
    await utils.cache.remove('./path/to/file')
  },
}

has(path)

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 = {
  name: 'example-plugin',
  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}`)
    }
  },
}