> ## Documentation Index
> Fetch the complete documentation index at: https://documentation.restash.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Client-side SDK

> Learn how to integrate Restash into any frontend framework.

## Installation

```bash npm theme={null}
npm i @restash/restash-js
```

```bash pnpm theme={null}
pnpm i @restash/restash-js
```

```bash yarn theme={null}
yarn add @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.

```typescript theme={null}
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](https://documentation.restash.io/uploads/client-uploads.md#uploading-your-first-file)
* [Signed uploads](https://documentation.restash.io/uploads/client-uploads.md#signed-uploads)

## Creating the uploader

The `createRestashUploader` function creates an uploader instance.

```typescript lib/restash.ts theme={null}
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](https://documentation.restash.io/uploads/client-uploads.md#signed-uploads).

## Using the uploader

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

```typescript theme={null}
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:

**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:

**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.

**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.

```typescript /api/restash/signature/route.ts theme={null}
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](https://www.npmjs.com/package/@restash/restash-js)**
>
> Download and install the Restash js client SDK from NPM

> **[Source code](https://github.com/restashio/restash-js)**
>
> View the complete source code for the Restash client SDK


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.