Files reference - DeepSpace

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
Upload (base64)
List
Delete
Read / download

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
}

There is no mimeType / contentType field on R2FileInfo. Capture the MIME type at upload time and store it in a sidecar collection if you need it later. See storing metadata.

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

R2 uploads require an APP_IDENTITY_TOKEN minted by the deploy worker. The CLI does not provision this token locally, so upload() round-trips return 401 from the platform file gateway. In local dev, assert that uploads are dispatched; the full flow works only against deployed apps.

​useR2Files(options?)

​R2FileInfo

​Scoping - R2Scope

​Display helpers

​Local dev limitation

​See also

`useR2Files(options?)`

`R2FileInfo`

Scoping - `R2Scope`

Display helpers

Local dev limitation

See also