@netlify/cache-utils
Version:
Utility for caching files in Netlify Build
221 lines (152 loc) • 5.13 kB
Markdown
[](https://codecov.io/gh/netlify/build)
[](https://github.com/netlify/build/actions)
Utility for caching files in Netlify Build.
```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')
}
```
```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'])
}
```
`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.
_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 })
}
```
_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'],
})
}
```
_Type_: `string` \
_Default_: `process.cwd()`
Current directory used to resolve relative paths.
`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.
_Type_: `string` \
_Default_: `process.cwd()`
Current directory used to resolve relative paths.
`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')
}
```
_Type_: `string` \
_Default_: `process.cwd()`
Current directory used to resolve relative paths.
`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}`)
}
}
```
_Type_: `string` \
_Default_: `process.cwd()`
Current directory used to resolve relative paths.
_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)
}
```
_Type_: `string` \
_Default_: `process.cwd()`
Current directory used to resolve relative paths.
_Type_: `number` \
_Default_: `1`
Number of subdirectories to include. `0` means only top-level directories will be included.