An SDK for remote artifact caching on Vercel
npm install @vercel/remote
When you build your project a set of build outputs are created. These build outputs are called artifacts and many times they can be reused and shared with your team running the same build. With Vercel's Remote Cache API, you can easily share these artifacts with your team or your CI environments.
The Vercel Remote Caching SDK is a thin layer over our existing API can be added to your build system to enable remote artifact caching.
- Installation
- Getting Started
- Authentication
- Using buffers
- Using streams
- Creating a Remote Cache Client
- Checking artifact exists
- Retrieve artifact
- Store artifact
- Errors
``sh`
npm install @vercel/remote
To get started you will need a Vercel Access Token and an optional team ID. You can create a vercel access token in your account settings. Your team ID can be found under your team settings page.
Every artifact on Vercel's Remote Cache is keyed by your Vercel teamId and the artifact hash.
- A valid teamId is necessary to share artifacts with your team. Otherwise, artifacts will only be accessible from the personal account of the Vercel Access token used to initialize the client.hash
- The is provided by your build system and is a unique indentifier for the task that generated artifacts. The hash is not a function of the artifact itself, but rather it's computed from the task graph your build system uses.
Use a Vercel Access Token with access to the requested teamId in the RemoteClient to use this SDK.
`js
import fs from 'fs-extra'
import { createClient } from '@vercel/remote'
const remote = createClient('
teamId: '
// e.g. turbo, nx, rush, etc.
product: 'your-build-system'
});
async function getArtifact(hash) {
const exists = await remote.exists(hash).send();
if (!exists) {
return false
}
// Process the incoming buffer to your local cache
const buf = await remote.get(hash).buffer()
await fs.writeFile(hash, buf)
return true
}
async function putArtifact(hash, buf) {
await remote.put(hash).buffer(buf)
}
`
`js
import fs from 'fs-extra'
import stream from 'stream'
import { promisify } from 'util';
import { createClient } from '@vercel/remote'
const pipeline = promisify(stream.pipeline);
const remote = createClient('
teamId: '
// e.g. turbo, nx, rush, etc.
product: 'your-build-system'
});
async function getArtifact(hash) {
const exists = await remote.exists(hash).send();
if (!exists) {
return false
}
const readStream = await remote.get(hash).stream()
// Process the incoming stream to your local cache
const writeStream = fs.createWriteStream(hash);
await pipeline(readStream, writeStream)
return true
}
async function putArtifact(hash) {
// Create the artifact stream from your local cache
const readStream = fs.createReadStream(hash);
// Push to Vercel remote cache
await remote.put(hash).stream(readStream)
}
`
`js
const remote = createClient('
// Vercel team ID. When this is not specified, the personal account
// associated with the provided token will be used. Specify a teamId
// to share artifacts with the team.
teamId: '
// The build system you are using. For example turbo, nx, rush, etc.
product: 'your-build-system'
});
Return true if an artifact exists in the remote cache. Otherwise return false.
`js`
const exists = await remote.exists('6079a2819459d70b').send();
Returns an artifact from the remote cache as a buffer
`js`
const buf = await remote.get('6079a2819459d70b').buffer();
Returns an artifact from the remote cache as a readable stream
`js`
const readStream = await remote.get('6079a2819459d70b').stream();
Uploads an artifact to the remote cache from a buffer
`jsduration
await remote.put('6079a2819459d70b', {
// is the compute time to create the artifact in milliseconds`
duration: 8030,
}).buffer(buf);
Uploads an artifact to the remote cache from a readable stream
`jsduration
await remote.put('6079a2819459d70b', {
// is the compute time to create the artifact in milliseconds``
duration: 8030,
}).stream(readStream);
Throws errors in the format and for the reasons defined on the Vercel Rest API