Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.mirage.strukto.ai/llms.txt

Use this file to discover all available pages before exploring further.

Mirage ships DropboxResource in two runtimes:
  • @struktoai/mirage-node, uses client_id + client_secret + long-lived refresh token to fetch short-lived access tokens server-side.
  • @struktoai/mirage-browser, supports the same refresh token via PKCE (no client secret in the bundle).
Both runtimes hit the same Dropbox v2 HTTP API: /2/files/list_folder for directories, /2/files/download for content, and /2/files/search_v2 for search. Credentials are obtained the same way in both runtimes, see Dropbox Credentials.

​
Node (server-side)

pnpm add @struktoai/mirage-node

import { DropboxResource, MountMode, Workspace } from '@struktoai/mirage-node'

const dropbox = new DropboxResource({
  clientId: process.env.DROPBOX_APP_KEY!,
  clientSecret: process.env.DROPBOX_APP_SECRET!,
  refreshToken: process.env.DROPBOX_REFRESH_TOKEN!,
})

const ws = new Workspace({ '/dropbox': dropbox }, { mode: MountMode.READ })
const res = await ws.execute('ls /dropbox/')
console.log(res.stdoutText)
The DropboxTokenManager caches the access token in memory and refreshes it ~5 minutes before expiry, so cold-start API calls don’t pay the refresh round-trip.

​
Browser (PKCE, no client secret)

pnpm add @struktoai/mirage-browser

import { DropboxResource, MountMode, Workspace } from '@struktoai/mirage-browser'

// Refresh token obtained via the PKCE flow, see examples/typescript/browser/src/dropbox_pkce.ts.
const dropbox = new DropboxResource({
  clientId: import.meta.env.VITE_DROPBOX_APP_KEY,
  refreshToken: refreshTokenFromLocalStorage,
})

const ws = new Workspace({ '/dropbox': dropbox }, { mode: MountMode.READ })
await ws.execute('ls /dropbox/')
Set the redirect URI on your Dropbox app’s Settings tab to your dev/prod origin (e.g. http://localhost:5173/dropbox_pkce.html). The bundled examples/typescript/browser/src/dropbox_pkce.ts runs the full PKCE dance end-to-end and persists the refresh token to localStorage.

​
VFS mode (patchNodeFs)

Mirage exposes a patchNodeFs(workspace) shim that routes fs.promises.* calls under a mount through the workspace, so any library that uses Node’s fs API can read directly from Dropbox without code changes. 
import { createRequire } from 'node:module'
import { DropboxResource, MountMode, patchNodeFs, Workspace } from '@struktoai/mirage-node'

const require = createRequire(import.meta.url)
const fs = require('fs') as typeof import('fs')

const ws = new Workspace({ '/dropbox': dropbox }, { mode: MountMode.READ })
const restore = patchNodeFs(ws)

const entries = await fs.promises.readdir('/dropbox/')
const stat = await fs.promises.stat('/dropbox/data')
const bytes = await fs.promises.readFile('/dropbox/data/example.parquet')

restore()
Only fs.promises.* (the async API) is patched. Sync forms like fs.statSync and fs.readFileSync aren’t supported because remote reads can’t block the event loop.

​
FUSE mode

For tools that need a real filesystem path (CLI tools, editors, system utilities), mount the workspace under FUSE: 
import { DropboxResource, FuseManager, MountMode, Workspace } from '@struktoai/mirage-node'

const ws = new Workspace({ '/dropbox': dropbox }, { mode: MountMode.READ })
const fm = new FuseManager()
const mp = await fm.setup(ws)

// Now `${mp}/dropbox/` is a real filesystem path:
//   ls ${mp}/dropbox/
//   find ${mp}/dropbox -name '*.parquet'
//   cat ${mp}/dropbox/data/example.json | jq .

await fm.close(ws)
Requires macFUSE on macOS or libfuse on Linux. See FUSE setup.

​
Available commands

DropboxResource ships the same shell command set as the GDrive resource:
  • Filesystem: ls, cat, head, tail, nl, wc, stat, find, tree, du, file, realpath, basename, dirname
  • Search/text: grep, rg, awk, sed, sort, uniq, cut, diff, cmp, jq
  • Encoding: base64
  • Format-aware: cat_parquet, cat_feather, cat_hdf5, head_parquet, head_feather, head_hdf5, cut_*, grep_*, ls_*, stat_*, tail_*, wc_*, file_* for .parquet, .feather, .hdf5/.h5, .orc files
The format-aware commands transparently decode binary tabular files, so cat /dropbox/data/example.parquet returns a column preview instead of binary garbage.

​
Examples

End-to-end runnable scripts are in examples/typescript/dropbox/: