Skip to main content
Docs
SDK reference

Files reference

`useR2Files` and file display helpers.

The useR2Files hook handles uploads, listings, deletions, and signed URLs against the app's R2 bucket. All operations route through the platform's file gateway, so end users never touch raw R2 credentials. For patterns and worked examples, see the file uploads guide.

import { useR2Files, isImageFile, formatFileSize } from 'deepspace'
import type { R2FileInfo, R2Scope } from 'deepspace'

useR2Files(options?)#

type R2UploadResult = {
  success: boolean
  key?: string
  url?: string
  name?: string
  error?: string
}

function useR2Files(options?: R2Scope): {
  upload:       (file: File | Blob, name?: string) => Promise<R2UploadResult>
  uploadBase64: (base64Data: string, name: string, mimeType?: string) => Promise<R2UploadResult>
  deleteFile:   (fileOrKey: R2FileInfo | string) => Promise<{ success: boolean; error?: string }>
  downloadFile: (fileOrKey: R2FileInfo | string, fileName?: string) => Promise<{ success: boolean; error?: string }>
  readFile:     (fileOrKey: R2FileInfo | string) => Promise<Response>
  list:         (prefix?: string) => Promise<R2FileInfo[]>
  getUrl:       (fileOrKey: R2FileInfo | string) => string
  isUploading:  boolean
}
options is the R2Scope itself - pass { scope: 'self' } (or omit entirely; 'self' is the only valid scope). Every method that takes a file accepts either an R2FileInfo object from list() or a raw key string.

upload accepts a File (from <input type="file"> or a drag-drop event) or a Blob and an optional display name. Returns R2UploadResult - check success and read the key field.

const { upload, isUploading } = useR2Files()

async function onFileChange(e: React.ChangeEvent<HTMLInputElement>) {
  const file = e.target.files?.[0]
  if (!file) return
  const result = await upload(file, file.name)
  if (!result.success) return console.error(result.error)
  console.log('uploaded:', result.key)
}

Use when you have data as a Base64 string - for example, from <canvas> toDataURL(). name is required; mimeType is optional.

const { uploadBase64 } = useR2Files()

const canvas = canvasRef.current!
const dataUrl = canvas.toDataURL('image/png')
const base64 = dataUrl.split(',')[1]

const result = await uploadBase64(base64, 'drawing.png', 'image/png')
list() is an async function - call it and store the result in component state rather than expecting a reactive array. Pass a sub-prefix to filter.

import { useState, useEffect } from 'react'

const { list } = useR2Files()
const [files, setFiles] = useState<R2FileInfo[]>([])

async function refresh() {
  setFiles(await list())
}

useEffect(() => { refresh() }, [])

Removes the file from R2 and broadcasts the change. Accepts either the full R2FileInfo from list() or a raw key string. There is no recycle bin - deletes are immediate and irreversible.

const { deleteFile } = useR2Files()

await deleteFile(file)        // R2FileInfo from list()
await deleteFile('reports/q1.pdf') // or a raw key
getUrl() returns a plain URL (no auth attached - only usable for unauthenticated reads). downloadFile() triggers a browser-side blob download and returns { success, error? }. readFile() returns the raw Response so you can call .text(), .blob(), .arrayBuffer(), .json(), etc.

const { getUrl, downloadFile, readFile } = useR2Files()

<img src={getUrl(file)} alt="" />

await downloadFile(file)                       // triggers Save As…
await downloadFile('reports/q1.pdf', 'q1.pdf') // explicit filename

const response = await readFile(file)
const text = await response.text()
list() is an async function - call it and store the result in component state rather than reading a reactive array.

R2FileInfo#

type R2FileInfo = {
  key: string
  size: number
  uploaded: string
  url: string
  originalName?: string
  uploadedBy?: string
}

Scoping - R2Scope#

type R2Scope = { scope?: 'self' }

The hook is always scoped to the current app (scope: 'self') - the platform derives the bucket prefix from the request's hostname. There is no per-user, per-room, or cross-app scope option exposed by useR2Files.

const { upload, list } = useR2Files()             // implicit { scope: 'self' }
const { upload, list } = useR2Files({ scope: 'self' }) // equivalent

Display helpers#

Helper Signature
isImageFile(mimeType: string) Returns true for image/* MIMEs
formatFileSize(bytes: number) Returns '1.2 MB', '456 KB', etc.

Local dev limitation#

See also#