docs(Blob): Focus on vercel.com/docs rather than GH docs (#426)

- Remove API docs from GH - Remove useless content - Reorganize main storage README to link to vercel.com
vercel · Oct 18, 2023 · 8511407 · 8511407 · vercel · Oct 18, 2023
1 parent 8852c7a
commit 8511407
Show file tree

Hide file tree

Showing 2 changed files with 28 additions and 263 deletions.
diff --git a/README.md b/README.md
@@ -1,9 +1,7 @@
-# Vercel Storage
+# [Vercel Storage](https://vercel.com/docs/storage)
 
-- [`@vercel/postgres`](./packages/postgres) - Vercel Postgres database client
-- [`@vercel/kv`](./packages/kv) - Durable Redis-compatible Key Value store
-- [`@vercel/edge-config`](./packages/edge-config) - Ultra-low latency data at the edge
-- [`@vercel/blob`](./packages/blob) - Fast object storage
-- [`@vercel/postgres-kysely`](./packages/postgres-kysely) - A `@vercel/postgres` wrapper for the [kysely ORM](https://github.com/kysely-org/kysely)
-
-To get started, see the [documentation](https://vercel.com/docs/storage)
+- `@vercel/postgres` Vercel Postgres database client — [Documentation](https://vercel.com/docs/storage/vercel-postgres) | [Source](./packages/postgres)
+- `@vercel/kv` Durable Redis-compatible Key Value store — [Documentation](https://vercel.com/docs/storage/vercel-kv) | [Source](./packages/kv)
+- `@vercel/edge-config` Ultra-low latency data at the edge — [Documentation](https://vercel.com/docs/storage/edge-config) | [Source](./packages/edge-config)
+- `@vercel/blob` Fast object storage — [Documentation](https://vercel.com/docs/storage/vercel-blob) | [Source](./packages/blob)
+- `@vercel/postgres-kysely` A `@vercel/postgres` wrapper for the [kysely ORM](https://github.com/kysely-org/kysely) — [Documentation](./packages/postgres-kysely) | [Source](./packages/postgres-kysely)
diff --git a/packages/blob/README.md b/packages/blob/README.md
@@ -2,279 +2,47 @@
 
 The Vercel Blob JavaScript API client.
 
-## Install
+---
+
+<p align="center">
+  👉 
+  <a href="https://vercel.com/docs/storage/vercel-blob/quickstart">
+    <b>Quickstart</b>
+  </a> — 
+  <a href="https://vercel.com/docs/storage/vercel-blob/using-blob-sdk">
+    <b>SDK Reference</b>
+  </a>
+   👈
+  </b>
+</p>
+
+---
+
+## Installation
 
 ```sh
 npm install @vercel/blob
 ```
 
-## Examples
+## Quickstart
 
 We have examples on the vercel.com documentation, there are two ways to upload files to Vercel Blob:
 
 1. [Server uploads](https://vercel.com/docs/storage/vercel-blob/quickstart#server-uploads): This is the most common way to upload files. The file is first sent to your server and then to Vercel Blob. It's straightforward to implement, but you are limited to the request body your server can handle. Which in case of a Vercel-hosted website is 4.5 MB. **This means you can't upload files larger than 4.5 MB on Vercel when using this method.**
 2. [Client uploads](https://vercel.com/docs/storage/vercel-blob/quickstart#client-uploads): This is a more advanced solution for when you need to upload larger files. The file is securely sent directly from the client (a browser for example) to Vercel Blob. This requires a bit more work to implement, but it allows you to upload files up to 500 MB.
 
-## API
-
-### `put(pathname, body, options)`
-
-Upload a blob to the Vercel Blob API, and returns the URL of the blob along with some metadata.
-
-```ts
-async function put(
-  pathname: string,
-  body: ReadableStream | String | ArrayBuffer | Blob | File // All fetch body types are supported: https://developer.mozilla.org/en-US/docs/Web/API/fetch#body
-  options: {
-    access: 'public', // mandatory, as we will provide private blobs in the future
-    contentType?: string, // by default inferred from pathname
-    // `token` defaults to process.env.BLOB_READ_WRITE_TOKEN on Vercel
-    // and can be configured when you connect more stores to a project
-    // or using Vercel Blob outside of Vercel
-    token?: string,
-    addRandomSuffix?: boolean; // optional, allows to disable or enable random suffixes (defaults to `true`)
-    cacheControlMaxAge?: number, // optional, a duration in seconds to configure the edge and browser caches. Defaults to one year for browsers and 5 minutes for edge cache. Can only be configured server side (either on server side put or during client token generation). The Edge cache maximum value is 5 minutes.
-  }): Promise<{
-      pathname: string;
-      contentType: string;
-      contentDisposition: string;
-      url: string;
-    }> {}
-```
-
-### del(url, options)
-
-Delete one or multiple blobs by their full URL. This method doesn't return any value. If the blob url exists, it's deleted once del() returns.
-
-```ts
-async function del(
-  url: string | string[],
-  options?: {
-    token?: string;
-  }
-): Promise<void> {}
-```
-
-### head(url, options)
-
-Get the metadata of a blob by its full URL. Throws a `BlobNotFoundError` when the blob does not exist.
-
-```ts
-async function head(
-  url: string,
-  options?: {
-    token?: string;
-  }
-): Promise<{
-  size: number;
-  uploadedAt: Date;
-  pathname: string;
-  contentType: string;
-  contentDisposition: string;
-  url: string;
-  cacheControl: string;
-}> {}
-```
-
-### list(options)
-
-List blobs and get their metadata in the store. With an optional prefix and limit. Paginate through them.
-
-```ts
-async function list(options?: {
-  token?: string;
-  limit?: number; // defaults to 1,000
-  prefix?: string;
-  cursor?: string;
-}): Promise<{
-  blobs: {
-    size: number;
-    uploadedAt: Date;
-    pathname: string;
-    url: string;
-  }[];
-  cursor?: string;
-  hasMore: boolean;
-}> {}
-```
-
-### copy(fromUrl, toPathname, options)
-
-Copy an existing blob to a new location in the store.
-
-The `contentType` and `cacheControlMaxAge` will not be copied from the source blob. If the values should be carried over to the copy, they need to be defined again in the options object.
-
-Contrary to `put()`, `addRandomSuffix` is false by default. This means no automatic random id suffix is added to your blob url, unless you pass `addRandomSuffix: true`. This also means `copy()` overwrites files per default, if the operation targets a pathname that already exists.
-
-```ts
-async function copy(
-  fromUrl: string,
-  toPathname: string,
-  options: {
-    access: 'public'; // mandatory, as we will provide private blobs in the future
-    contentType?: string; // by default inferred from pathname
-    // `token` defaults to process.env.BLOB_READ_WRITE_TOKEN on Vercel
-    // and can be configured when you connect more stores to a project
-    // or using Vercel Blob outside of Vercel
-    token?: string;
-    addRandomSuffix?: boolean; // optional, allows to enable random suffixes (defaults to `false`)
-    cacheControlMaxAge?: number; // optional, a duration in seconds to configure the edge and browser caches. Defaults to one year for browsers and 5 minutes for edge cache. Can only be configured server side (either on server side put or during client token generation). The Edge cache maximum value is 5 minutes.
-  }
-): Promise<{
-  url: string;
-  pathname: string;
-  contentType?: string;
-  contentDisposition: string;
-}> {}
-```
-
-### client/`upload(pathname, body, options)`
-
-The `upload` method is dedicated to client uploads. It fetches a client token using the `handleUploadUrl` before uploading the blob.
-
-Read the [client uploads](https://vercel.com/docs/storage/vercel-blob/quickstart#client-uploads) documentation to know more.
-
-```ts
-async function upload(
-  pathname: string,
-  body: ReadableStream | String | ArrayBuffer | Blob | File // All fetch body types are supported: https://developer.mozilla.org/en-US/docs/Web/API/fetch#body
-  options: {
-    access: 'public', // mandatory, as we will provide private blobs in the future
-    contentType?: string, // by default inferred from pathname
-    // `token` defaults to process.env.BLOB_READ_WRITE_TOKEN on Vercel
-    // and can be configured when you connect more stores to a project
-    // or using Vercel Blob outside of Vercel
-    handleUploadUrl?: string, // A string specifying the route to call for generating client tokens for client uploads
-    clientPayload?: string, // A string that will be passed to the `onUploadCompleted` callback as `tokenPayload`. It can be used to attach data to the upload, like `JSON.stringify({ postId: 123 })`.
-  }): Promise<{
-      pathname: string;
-      contentType: string;
-      contentDisposition: string;
-      url: string;
-    }> {}
-```
-
-### client/`handleUpload(options)`
-
-This is a server-side route helper to manage client uploads, it has two responsibilities:
-
-1. Generate tokens for client uploads
-2. Listen for completed client uploads, so you can update your database with the URL of the uploaded file for example
-
-Read the [client uploads](https://vercel.com/docs/storage/vercel-blob/quickstart#client-uploads) documentation to know more.
-
-```ts
-async function handleUpload(options?: {
-  token?: string; // default to process.env.BLOB_READ_WRITE_TOKEN
-  request: IncomingMessage | Request;
-  onBeforeGenerateToken: (
-    pathname: string,
-    clientPayload?: string
-  ) => Promise<{
-    allowedContentTypes?: string[]; // optional, defaults to no restriction
-    maximumSizeInBytes?: number; // optional, defaults and maximum is 500MB (524,288,000 bytes)
-    validUntil?: number; // optional, timestamp in ms, by default now + 30s (30,000)
-    addRandomSuffix?: boolean; // see `put` options
-    cacheControlMaxAge?: number; // see `put` options
-    tokenPayload?: string; // optional, defaults to whatever the client sent as `clientPayload`
-  }>;
-  onUploadCompleted: (body: {
-    type: 'blob.upload-completed';
-    payload: {
-      blob: PutBlobResult;
-      tokenPayload?: string;
-    };
-  }) => Promise<void>;
-  body:
-    | {
-        type: 'blob.upload-completed';
-        payload: {
-          blob: PutBlobResult;
-          tokenPayload?: string;
-        };
-      }
-    | {
-        type: 'blob.generate-client-token';
-        payload: {
-          pathname: string;
-          callbackUrl: string;
-          clientPayload: string;
-        };
-      };
-}): Promise<
-  | { type: 'blob.generate-client-token'; clientToken: string }
-  | { type: 'blob.upload-completed'; response: 'ok' }
-> {}
-```
-
-## Examples
-
-- [Next.js App Router examples](../../test/next/src/app/vercel/blob/)
-- [https.get, axios, and got](../../test/next/src/app/vercel/blob/script.mts)
-
-## How to list all your blobs
-
-This will paginate through all your blobs in chunks of 1,000 blobs.
-You can control the number of blobs in each call with `limit`.
-
-```ts
-let hasMore = true;
-let cursor: string | undefined;
-while (hasMore) {
-  const listResult = await list({
-    cursor,
-  });
-  console.log(listResult);
-  hasMore = listResult.hasMore;
-  cursor = listResult.cursor;
-}
-```
-
-## Error handling
-
-All methods of this module will throw if the request fails for either:
-
-- missing parameters
-- bad token or token doesn't have access to the resource
-- suspended Blob store
-- Blob file or Blob store not found
-- or in the event of unknown errors
-
-You should acknowledge that in your code by wrapping our methods in a try/catch block:
-
-```ts
-try {
-  await put('foo', 'bar');
-} catch (error) {
-  if (error instanceof BlobAccessError) {
-    // handle error
-  } else {
-    // rethrow
-    throw error;
-  }
-}
-```
-
 ## Releasing
 
+Make sure to include a changeset in your PR. You can do this by running:
+
 ```sh
 pnpm changeset
-git commit -am "New version"
+git commit -am "changeset"
+git push
 ```
 
 Once such a commit gets merged in main, then GitHub will open a versioning PR you can merge. And the package will be automatically published to npm.
 
-## A note about Vercel file upload limitations
-
-When transferring a file to a Serverless or Edge Functions route on Vercel, then the request body is limited to 4.5 MB. If you need to send larger files then use the [client-upload](#client-upload) method.
-
-## Running examples locally
-
-- how to run examples locally (.env.local with token)
-- how to run examples on Vercel (vc deploy)
-- how to contribute (pnpm dev to rebuild, example uses local module)
-- for Vercel contributors, link on how to run the API locally (edge-functions readme link, wrangler dev, pnpm dev for module)
-
 ## A note for Vite users
 
 `@vercel/blob` reads the token from the environment variables on `process.env`. In general, `process.env` is automatically populated from your `.env` file during development, which is created when you run `vc env pull`. However, Vite does not expose the `.env` variables on `process.env.`
@@ -315,5 +83,4 @@ const blob = await head("filepath", {
 -  token: '<token>',
 +  token: BLOB_TOKEN,
 });
-
 ```