Client-side SDK

Learn how to integrate Restash into any frontend framework.

Installation

npm

npm i @restash/restash-js

Basic usage

Here’s a simple example of how to use the Restash client SDK to upload files directly from the browser.

import { createRestashUploader } from "@restash/restash-js";

// create the uploader with your public API key
const upload = createRestashUploader({
  publicKey: "pk_123456789",
});

// can be a file or a blob
const file = new File(["test"], "test.txt", {
  type: "text/plain",
});

const result = await upload(file);

console.log(result.url); // https://cdn.restash.io/{result.key}

For more usage examples, check out:

• Uploading your first file
• Signed uploads

Creating the uploader

The createRestashUploader function creates an uploader instance.

lib/restash.ts

import { createRestashUploader } from "@restash/restash-js";

export const upload = createRestashUploader({
  publicKey: "pk_123456789",
});

It accepts an options object with the following properties:

publicKey · string · required

Your Restash public API key. This is required to authenticate the upload request.

handleSignature · string

The URL of your server route that returns a signature and payload. Only required if your team has signature enforcement enabled. Learn more.

Using the uploader

You can import your uploader instance and use it to upload files.

import { upload } from "@/lib/restash";

const result = await upload(file, {
  path: "uploads/",
  onProgress: ({ percent }) => {
    console.log(`uploading...${percent}%`);
  },
});

It accepts the following parameters:

file · File | Blob · required

The file or blob to upload.

options · UploadOptions object

An object with the following optional properties:

Show properties

name · string

A custom name for the file. This will override the original file name. If a blob is passed and no name is provided, we will generate a random name.

path · string

Prefix the file name with a custom path. This is useful for organizing files in your Restash account. You can think of this as a folder structure.

metadata · object

Key-value pairs of metadata associated with the file. This can be used to store additional information about the file.

onProgress · function

A callback function that will be called with the progress of the upload. It receives an object with the following properties:

Show properties

percent · number

The progress of the upload as a percentage.

loaded · number

The number of bytes uploaded so far.

total · number

The total number of bytes to be uploaded.

A successful upload will respond with the following:

data · UploadResult object

The information about the uploaded file.

Show properties

id · string

The unique identifier of the uploaded file.

name · string

The name of the uploaded file.

url · string

The URL of the uploaded file.

size · number

The size of the uploaded file in bytes.

contentType · string

The content type of the uploaded file.

key · string

The unique key of the uploaded file.

metadata · object | null

Key-value pairs of metadata associated with the file.

Generating signatures

If your team has signature enforcement enabled, you need to generate a signature for each upload request. You can do this by creating a server route that returns a signature and payload using the generateSig function from the Restash client SDK. Generating signatures needs to be done on the server. You can then pass this route to the createRestashUploader so that it can be called when needed.

/api/restash/signature/route.ts

import { NextResponse } from "next/server";
import { generateSig } from "@restash/restash-js";

export const GET = () => {
 const secret = process.env.RESTASH_SECRET_KEY!;
 const { signature, payload } = generateSig(secret);

 return NextResponse.json({ signature, payload });
}

It accepts the following parameters:

secret · string · required

Your Restash secret API key. This is required to generate the signature.

Additional resources

NPM package

Download and install the Restash js client SDK from NPM

Source code

View the complete source code for the Restash client SDK