Installation

Install dependencies

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

pnpm install vs3 @aws-sdk/client-s3 @aws-sdk/s3-request-presigner

vs3 requires the @aws-sdk/client-s3 and @aws-sdk/s3-request-presigner packages to be installed.

Create a storage adapter

To interact with the storage provider you need to create an adapter. 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,
});

While this will work without any other options you might want to pass in some additional options. Check out Storage Options 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 Storage Options 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 { storage } from "./server";

export const storageClient = createStorageClient<typeof storage.$Infer>({
    // Optional configuration
});

Pass typeof storage.$Infer to share all server-inferred types with the client from a single generic. Use a type-only import (import type) so no server code is pulled into the client bundle.

All done

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

"use client";

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