Upload file

Upload a generic file (document, video, or other) without server-side processing

Overview

Uploads a file to Sublay storage without any server-side processing. The raw file is stored and a proxy URL is returned. Use this for PDFs, videos, Office documents, or any file type where you don’t need variant generation.

For images that need resizing or format conversion, use useUploadImage instead.

Requires an authenticated user. The hook uses the private axios instance and will throw if no session is active.

Usage Example

import { useUploadFile } from "@sublay/react-js";

function DocumentUploader({ entityId }: { entityId: string }) {
  const uploadFile = useUploadFile();

  const handleFile = async (file: File) => {
    const result = await uploadFile(file, ["documents", entityId], {
      entityId,
      metadata: { label: "Attachment" },
    });

    console.log(result.publicPath); // Use this URL to reference the file
  };

  return <input type="file" onChange={e => e.target.files && handleFile(e.target.files[0])} />;
}

Parameters

uploadFile(file, pathParts, options?) accepts three arguments:

file · BrowserFile | RNFile · required

The file to upload. In the browser, pass a standard File object. In React Native, pass { uri, name, type? }.

pathParts · string[] · required

Storage path segments. The file is stored under the joined path, with a UUID sub-folder appended automatically for uniqueness. For example, ["documents", "user-123"] stores the file at documents/user-123/<uuid>/<filename>.

options · UploadFileOptions

Optional associations and metadata.

Options

entityId · string

Associates the file with an entity. The file is deleted when the entity is deleted.

commentId · string

Associates the file with a comment. The file is deleted when the comment is deleted.

spaceId · string

Associates the file with a space.

position · number

Display order when a record has multiple attachments. Defaults to 0.

metadata · Record<string, any>

Custom key-value data stored alongside the file record.

Returns

The hook returns the uploadFile function directly (no state wrappers). The function returns a Promise<UploadResponse>:

{
  fileId: string;
  type: "image" | "video" | "document" | "other"; // Inferred from MIME type
  relativePath: string;    // Internal storage path
  publicPath: string;      // Proxy URL for client access
  size: number;            // Bytes
  mimeType: string;
  createdAt: string;       // ISO 8601
}

The type field is inferred automatically from the file’s MIME type. PDFs and Office documents become "document", video files become "video", images become "image", and everything else becomes "other".