# @vercel/remote

> An SDK for remote artifact caching on Vercel

Latest version **1.0.1** (published 2022-09-20) · MPL-2.0 license · 0 weekly downloads

## Install

```sh
npm install @vercel/remote
pnpm add @vercel/remote
yarn add @vercel/remote
bun add @vercel/remote
```

## Health

**Score 25/100 (F)** — status: abandoned.

Positive: has types; no vulnerabilities; high quality score.

Warnings: low downloads; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 1.0.1 |
| Published | 2022-09-20 |
| First published | 2022-08-30 |
| Weekly downloads | 0 |
| License | MPL-2.0 |
| TypeScript types | bundled |
| Module format | CommonJS |
| Dependencies | 4 |
| Unpacked size | 31.7 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 195 |
| Author | Jared Palmer |
| Maintainers | vercel-release-bot, zeit-bot |

## Links

- npm: https://www.npmjs.com/package/@vercel/remote
- Repository: https://github.com/vercel/remote-cache
- Homepage: https://github.com/vercel/remote-cache#readme
- Issues: https://github.com/vercel/remote-cache/issues
- npm.io page: https://npm.io/package/@vercel/remote

## Dependencies (4)

- [ci-info](https://npm.io/package/ci-info.md) ^3.4.0
- [raw-body](https://npm.io/package/raw-body.md) ^2.5.1
- [node-fetch](https://npm.io/package/node-fetch.md) ^2.6.7
- [concat-stream](https://npm.io/package/concat-stream.md) ^2.0.0

## Recent versions

- 1.0.1 (latest) — 2022-09-20
- 0.0.7-alpha.3 (alpha) — 2022-09-16
- 1.0.0 — 2022-09-19
- 0.0.9 — 2022-09-19
- 0.0.8 — 2022-09-17
- 0.0.7 — 2022-09-16
- 0.0.7-alpha.2 — 2022-09-16
- 0.0.7-alpha.0 — 2022-09-16
- 0.0.6 — 2022-09-15
- 0.0.5 — 2022-09-15
- 0.0.5-alpha.0 — 2022-09-15
- 0.0.4 — 2022-09-09
- 0.0.3 — 2022-09-08
- 0.0.2 — 2022-09-08
- 0.0.1 — 2022-09-06
- … 1 more at https://npm.io/package/@vercel/remote/versions

## README

# Vercel Remote Caching SDK

[![@vercel/remote](https://img.shields.io/npm/v/@vercel/remote)](https://npmjs.org/@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](https://vercel.com/docs/rest-api#endpoints/artifacts), 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.

## Table of Contents
<!-- START doctoc generated TOC please keep comment here to allow auto update -->
<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->

- [Installation](#installation)
- [Getting Started](#getting-started)
  - [Authentication](#authentication)
  - [Using buffers](#using-buffers)
  - [Using streams](#using-streams)
- [Creating a Remote Cache Client](#creating-a-remote-cache-client)
  - [Checking artifact exists](#checking-artifact-exists)
  - [Retrieve artifact](#retrieve-artifact)
  - [Store artifact](#store-artifact)
  - [Errors](#errors)

<!-- END doctoc generated TOC please keep comment here to allow auto update -->

## Installation

```sh
npm install @vercel/remote
```

## Getting Started

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](https://vercel.com/account/tokens). 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.
- The `hash` 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.

### Authentication

Use a [Vercel Access Token](https://vercel.com/docs/rest-api#introduction/api-basics/authentication) with access to the requested `teamId` in the `RemoteClient` to use this SDK.


### Using buffers

```js
import fs from 'fs-extra'
import { createClient } from '@vercel/remote'

const remote = createClient('<token>', {
  teamId: '<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)
}
```

### Using streams

```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('<token>', {
  teamId: '<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)
}
```

## Creating a Remote Cache Client

```js

const remote = createClient('<token>', {
  // 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: '<teamId>',
  // The build system you are using. For example turbo, nx, rush, etc.
  product: 'your-build-system'
});
```

### Checking artifact exists

Return `true` if an artifact exists in the remote cache. Otherwise return `false`.

```js
const exists = await remote.exists('6079a2819459d70b').send();
```

### Retrieve artifact

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();
```

### Store artifact

Uploads an artifact to the remote cache from a buffer

```js
await remote.put('6079a2819459d70b', {
    // `duration` 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

```js
await remote.put('6079a2819459d70b', {
    // `duration` is the compute time to create the artifact in milliseconds
    duration: 8030,
  }).stream(readStream);
```

### Errors

Throws errors in the format and for the reasons defined on the [Vercel Rest API](https://vercel.com/docs/rest-api#errors)

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