Installation

Install dependencies

Install the required dependencies with a package manager of your choice:

pnpm install vs3

npm install vs3

yarn add vs3

bun add vs3

Create a storage adapter

vs3 requires an adapter to interact with the storage. See Adapters for a full list of supported adapters.

import { aws } from "vs3/adapters";

const adapter = aws({
    region: process.env.AWS_REGION!,
    credentials: {
        accessKeyId: process.env.AWS_ACCESS_KEY_ID!,
        secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY!,
    },
});

Create a storage instance

Create a storage instance and pass in the adapter you created:

export const storage = createStorage({
    bucket: process.env.AWS_BUCKET!,
    adapter,
});

// Required for the client to infer the metadata schema
export type StorageMetadata = storage.$Infer.metadata;

While this will work without any other options you might want to pass in some additional options. Check out the Configuration section for more information.

Mount handlers

Mount the handlers to your framework of choice at /api/storage/[...all]. If you prefer to use a different path, you can pass the apiPath option when creating the storage instance. See the Configuration section for more information.

export const { GET, POST, OPTIONS, PUT } = toNextJsRouteHandler({ handler: storage.handler });

Create a client instance

To access the storage API from the client you need to create a client instance. Create a client instance by importing createStorageClient for the framework of your choice and passing in the same options you passed to the storage instance.

"use client";

import { createStorageClient } from "vs3/react";
import type { StorageMetadata } from "./server";

export const storageClient = createStorageClient<StorageMetadata>({
    // Optional configuration
});

If you passed the StorageMetadata type to the client instance, you do not need to pass the metadata schema again. The schema will be inferred automatically.

All done

That's it! You can now use vs3 to upload and download files. Check out the usage section for more information on how to use the client and server APIs.

"use client";

const { upload } = storageClient.useUpload();
upload(file, { userId: "123" });