Installation & Quickstart

See how to quickly get up and running with the file upload service

Create an account, API key and provider

  1. Visit our dashboard and create an account by pressing login

  2. Navigate to the upload service dashboard and create a new upload service

  3. Inside your upload service dashboard, create an API key and a provider

For more info, see our detailed guide on setting up your account. For information on how to get your access keys for different storage services, see this page.

Install the JS upload client library

Our JavaScript client library is extremely lightweight. It's only 1.8kB gzipped and has zero external dependencies. It is supported by all modern browsers. There are only 2 browser dependencies required for it to work correctly:

  • Promises

  • Fetch API

If you need to support browsers missing either of these, you can use to polyfill both of those.

There are 2 ways you can install the client library. Our recommend method is to use the NPM package. The package also ships with TypeScript definitions. It can be installed with the following command:

npm install --save @betterstack/upload-client

Alternatively, you can include the library via script tag in your HTML. You can include it in either the head or body of a page as long as it's included before it's used.

<script src="[email protected]/dist/umd/index.min.js"></script>

Upload a file

To upload a file, you must extract it from a HTML file input <input type="file">.

import UploadClient from "@betterstack/upload-client"; // NPM only
// Init upload client
const UC = new UploadClient({
apiKey: "<YOUR_API_KEY>",
// In your HTML: <input id="file-input" type="file"/>
const file = document.getElementById("file-input").files[0];
// Create upload task
const task = UC.upload({
providerId: "<YOUR_PROVIDER_ID>",
files: [{ file: file }]
// Track upload progress
task.onProgress((e) => console.log(e.loadedPercent));
// Start upload with promise
.then((uploaded) => {
const uploadedFile = uploaded[0];
console.log(uploadedFile.key); // Uploaded path
console.log(uploadedFile.file); // Uploaded file
.catch((e) => {
console.log(e.code); // Error code
console.log(e.message); // Error message
// See all errors on 'Error Handling' page

Where to go from here

We recommend reading through the other sections of the documentation that are relevant for you. In particular, the Code Examples page will show you a variety of ways to upload files such as using it in React, form posts, uploading multiple files, etc.