Dropbox JavaScript SDK

The official Dropbox API v2 SDK for JavaScript.

Runtime support

The SDK supports Node.js 22 and newer, modern web browsers, and Web Workers. Continuous integration currently tests Node.js 22 and 24, and Node.js uses its built-in fetch implementation. Browser and Worker environments must provide Promise, fetch, and TextEncoder; PKCE authentication also requires the Web Crypto API. Add polyfills when targeting older environments that do not provide the required APIs.

Installation

Create an app in the Developer Console, then install the SDK from npm. Published npm packages already contain CommonJS, ES module, browser, and TypeScript builds; applications do not need to build the SDK from source. Published versions and release history are available on the npm versions page.

npm install dropbox

Node.js

const { Dropbox } = require('dropbox');

const dbx = new Dropbox({
  accessToken: process.env.DROPBOX_ACCESS_TOKEN,
});

dbx.filesListFolder({ path: '' })
  .then(({ result }) => console.log(result.entries))
  .catch(console.error);

Browser application with a bundler

Webpack, Rollup, Vite, and similar tools can use the package's ES module build.

import { Dropbox } from 'dropbox';

const dbx = new Dropbox({ accessToken: 'YOUR_ACCESS_TOKEN' });

Browser application from a CDN

The browser bundle exposes the SDK through the global Dropbox object. Pin an exact SDK version so a future breaking release cannot change your application unexpectedly.

<script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/Dropbox-sdk.min.js"></script>
<script>
  const dbx = new Dropbox.Dropbox({ accessToken: 'YOUR_ACCESS_TOKEN' });
</script>

Do not hard-code production access tokens in public source code.

For debugging, use the unminified bundle:

<script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/Dropbox-sdk.js"></script>

Web Worker

The same browser bundle can be loaded in a Worker:

importScripts('https://cdn.jsdelivr.net/npm/[email protected]/dist/Dropbox-sdk.min.js');

const dbx = new Dropbox.Dropbox({ accessToken: 'YOUR_ACCESS_TOKEN' });

Install from source

Building is required only when developing the SDK itself or running examples directly from this repository.

git clone https://github.com/dropbox/dropbox-sdk-js.git
cd dropbox-sdk-js
npm install
npm run build

Browser authentication and PKCE

Client-side applications cannot keep an app secret confidential. Never embed a Dropbox app secret in browser or Worker code. Use the OAuth authorization-code flow with PKCE and your app key instead. See the browser PKCE example and the Dropbox OAuth guide. PKCE requires a secure context and the Web Crypto API.

Server applications can keep an app secret confidential and may use the regular authorization-code flow.

API reference

• Dropbox class — Dropbox API routes for files, sharing, users, teams, and other namespaces.
• DropboxAuth class — OAuth URLs, PKCE, access tokens, and token refresh.
• DropboxResponseError class — errors returned by API requests.
• Global API — generated methods and route type definitions.

The complete generated API reference is published on GitHub Pages.

Examples

The examples demonstrate common SDK operations. Most are available in both JavaScript and TypeScript, with additional Node.js OAuth examples.

• OAuth

  • Auth - [ JS ] - A simple auth example to get an access token and list the files in the root of your Dropbox account.
  • Simple Backend [ JS ] - A simple example of a node backend doing a multi-step auth flow for Short Lived Tokens.
  • PKCE Backend [ JS ] - A simple example of a node backend doing a multi-step auth flow using PKCE and Short Lived Tokens.
  • PKCE Browser [ JS ] - A simple example of a frontend doing a multi-step auth flow using PKCE and Short Lived Tokens.

• Other Examples

  • Basic - [ TS, JS ] - A simple example that takes in a token and fetches files from your Dropbox account.
  • Backend Download - [ JS ] - An example showing resumable backend downloads to local storage.
  • Download - [ TS, JS ] - An example showing how to download a shared file.
  • Team As User - [ TS, JS ] - An example showing how to act as a user.
  • Team - [ TS, JS ] - An example showing how to use the team functionality and list team devices.
  • Upload [ TS, JS ] - An example showing how to upload a file to Dropbox.

Reliable file transfers

For Node.js applications that need resumable local downloads or retrying uploads, the SDK exports file transfer helpers alongside the generated API methods.

const {
  Dropbox,
  DropboxFileUploader,
  bytesUpload,
  downloadFile,
  fileUpload,
  readerUpload,
  sizedReaderUpload,
} = require('dropbox');

const dbx = new Dropbox({ accessToken: process.env.DROPBOX_ACCESS_TOKEN });

await downloadFile(dbx, '/large-file.bin', './large-file.bin', {
  parallelDownloads: 4,
  progress: ({ bytesWritten, totalBytes }) => {
    console.log(`${bytesWritten}/${totalBytes}`);
  },
});

const uploader = new DropboxFileUploader(dbx, {
  progress: ({ bytesCommitted, totalBytes }) => {
    console.log(`${bytesCommitted}/${totalBytes}`);
  },
});

await uploader.upload(
  await fileUpload('./large-file.bin'),
  { path: '/large-file.bin', mode: { '.tag': 'overwrite' } },
);

await uploader.upload(
  bytesUpload('hello from the Dropbox SDK\n'),
  { path: '/hello.txt' },
);

Downloads write to localPath + ".part" and rename the file after validating the final size and Dropbox content_hash metadata when present. Uploads retry transient failures at the individual session request, reconcile committed offsets after lost responses, and use upload sessions for every source. Pass parallelUploads for repeatable byte or file sources, or use readerUpload() and sizedReaderUpload() for one-shot Node readable streams.

Getting Help

If you find a bug, please see CONTRIBUTING.md for information on how to report it.

If you need help that is not specific to this SDK, please reach out to Dropbox Support.

License

This SDK is distributed under the MIT license, please see LICENSE for more information.