Skip to content
Files SDK
Esc
↑↓navigate↵open⌘Jpreview
On this page

Dropbox

Dropbox via the official SDK. Path-addressable, so virtual keys map directly to Dropbox paths - no cache, with OAuth refresh-token and access-token auth.

Installation

dropbox is an optional peer dependency of files-sdk - install alongside the SDK so the adapter’s imports resolve at runtime.

npm install files-sdk dropbox
pnpm add files-sdk dropbox
yarn add files-sdk dropbox
bun add files-sdk dropbox
nub add files-sdk dropbox
aube add files-sdk dropbox

Usage

Dropbox via the official dropbox SDK. Path-addressable like OneDrive (/folder/file.txt), so virtual keys map directly to Dropbox paths - no virtual-key cache, no bookkeeping. Four auth shapes (pre-built client, static or dynamic access token, OAuth refresh token + app key, or env-var fallback) cover personal Dropbox, Dropbox Business, and team-space deployments.

import { Files } from "files-sdk";
import { dropbox } from "files-sdk/dropbox";

// OAuth2 refresh-token flow (recommended for server-side apps).
// The adapter exchanges the refresh token at api.dropboxapi.com/oauth2/token
// and caches the access token until ~60s before expiry.
const files = new Files({
  adapter: dropbox({
    refreshToken: process.env.DROPBOX_REFRESH_TOKEN!,
    appKey: process.env.DROPBOX_APP_KEY!,
    appSecret: process.env.DROPBOX_APP_SECRET, // omit for PKCE public clients
    rootFolderPath: "/Uploads",
    // publicByDefault: true → upload() also creates a public shared link
    //                       and url() returns it (rewritten to ?dl=1 for
    //                       direct download).
  }),
});

Options

PropType
rootFolderPath?string

Logical "bucket root" — virtual keys live under this folder path on the Dropbox account. Must already exist; the adapter does not create folders. Path is normalized: leading slash is added, trailing slashes stripped. Defaults to the account root.

Typestring
publicByDefault?boolean

When `true`, `upload()` also creates a public shared link (anyone with the link can view) and `url()` returns that link's `url` (rewritten to `?dl=1` for direct download). When `false` (default), `url()` mints a 4-hour temporary link via `filesGetTemporaryLink` — as does `url(key, { expiresIn })` in either mode. **Plan policy note:** public shared links may be restricted on Dropbox Business teams; the adapter surfaces Dropbox's `access_denied` error unmodified in that case.

Typeboolean
publicBaseUrl?string

Origin used to build URLs from `url()`. When set, `url(key)` returns `${publicBaseUrl}/${key}` and skips both signing and shared-link creation. Useful when a CDN sits in front of pre-shared Dropbox links. `url(key, { expiresIn })` still mints a temporary link.

Typestring
defaultUrlExpiresIn?number

Default expiry, in seconds, for the temporary download links returned by `url()` when neither `publicByDefault` nor `publicBaseUrl` is set. **Validated only**: `filesGetTemporaryLink` takes no expiry parameter, so every link actually lives ~4 hours (14400s, the Dropbox fixed lifetime) regardless of what's requested — a default above 14400 is capped to it (a per-call `expiresIn` above 14400 throws), and values below are accepted but the link still outlives them. Don't rely on a short `expiresIn` as a security control with this adapter. Defaults to 3600.

Typenumber
client?Dropbox

Pre-built `Dropbox` client — escape hatch for callers that already wire auth themselves (e.g. with team-space `pathRoot`, custom headers, or shared `DropboxAuth`).

TypeDropbox
accessToken?string | (() => string | Promise<string>)

Static or dynamic access token. Pass a string for a one-shot token, or a function returning a fresh token on each call. The adapter does not cache the result of a callable — your callable is responsible for caching/refresh.

Typestring | (() => string | Promise<string>)
refreshToken?string

OAuth2 refresh-token flow. Tokens are exchanged at `https://api.dropboxapi.com/oauth2/token` and cached until ~60s before expiry. `appSecret` is required for confidential clients (server-side apps); PKCE-only public clients should pass `appKey` alone.

Typestring
appKey?string

Dropbox app key (client_id). Required when `refreshToken` is set.

Typestring
appSecret?string

Dropbox app secret (client_secret). Required for confidential clients.

Typestring

Compatibility

Method Status Notes
upload ⚠️ Single-call filesUpload up to Dropbox’s 150 MB limit; bodies above that automatically switch to filesUploadSession* (chunked, up to 350 GB) buffered into memory. With dropbox 10.47 or later, those buffered sessions are concurrent: multipart.concurrency chunks (default 4) upload in parallel, and concurrency: 1 keeps them sequential. Stream bodies upload chunk-by-chunk through filesUploadSession* (8 MiB default, multipart.partSize), so memory stays bounded. User metadata and cacheControl throw - Dropbox has no native arbitrary-metadata field; use raw with property_groups (registered template required) if you need it.
download ⚠️ filesDownload buffers the full body - the SDK has no streaming download primitive. For as: 'stream' or a byte range, the adapter mints a temporary link and fetches it via standard HTTP, which exposes a ReadableStream body.
delete ✅ A folder key is a no-op, like a missing key. "", "/", and keys with a trailing slash throw Invalid (they name the root or a folder), here and on every other method.
list ⚠️ Recursive listing under rootFolderPath via filesListFolder({ recursive: true }); folder entries are filtered out. prefix is matched client-side within the returned page and can under-return when the prefix isn’t satisfied within a single page. Pagination uses Dropbox’s opaque cursor via filesListFolderContinue. limit is capped at 2000, the most Dropbox returns per page. With delimiter: '/', it lists one folder level (recursive: false) - the folder the prefix points into, up to its last / - keeps the children that match the full prefix, and returns subfolders as prefixes (photos/20 lists photos and returns photos/2024/).
search ⚠️ Built on listAll — inherits this adapter’s list behavior above. Client-side key match (glob, regex, substring, exact).
head ⚠️ Dropbox doesn’t store user-supplied content types - filesUpload accepts no Content-Type. head() returns a type inferred from the filename extension (or application/octet-stream when unknown). etag is Dropbox’s rev field.
exists ⚠️ Resolves via filesGetMetadata and returns false for folder or deleted entries at the path - matches Dropbox’s semantics where the same path can hold a folder or a tombstone. Only true file entries return true.
copy ✅ Overwrites an existing destination file like the other adapters: filesCopyV2 has no overwrite mode, so the adapter deletes the destination and copies again (the old file stays recoverable in Dropbox’s version history). A folder at the destination, or the same file under different casing, is Conflict; a folder as the source is NotFound. move behaves the same.
url ⚠️ Default mints a 4-hour temporary link via filesGetTemporaryLink - the API takes no expiry parameter, so expiresIn is validated only: values above Dropbox’s 14400s (4h) fixed lifetime throw, values below are accepted but the link still lives ~4h. The lifetime is provider-timed, so capabilities.signedUrl reports expiry: "provider" (with maxExpiresIn: 14400). Don’t rely on a short expiresIn as a security control here. With publicByDefault: true, upload() creates a public shared link and url() returns it (rewritten to ?dl=1 for direct download). With publicBaseUrl, returns <publicBaseUrl>/<key>. In both modes a plain url(key) returns the permanent link (no 4h cap); an explicit expiresIn still mints a temporary link, so signedUrl.supported stays true. responseContentDisposition always throws - Dropbox links have no Content-Disposition override.
signedUploadUrl ❌ Throws - Dropbox’s filesGetTemporaryUploadLink returns a URL that expects POST with a raw body, which fits neither the SDK’s PUT-with-headers nor POST-with-form-fields shape. Use upload() or drop to raw.filesGetTemporaryUploadLink(...) for client-side uploads.

Last updated on

Was this page helpful?