Classic Cloud Storage

In classic mode, CloudBase JS SDK v3 provides cloud storage file operations through app.storage.from(). Classic mode works with the built-in cloud storage of an environment. Upload APIs take storage-relative paths and return full fileIDs. For download, deletion, signed URLs, and file metadata queries, use the full fileID returned by upload.

Note

In classic mode, storage APIs use the open capabilities of the Cloud Storage HTTP API. Before using them, check whether the StoragesHttpApiAllow policy is configured as expected. See Policy Management for details.

Quick Start

import cloudbase from "@cloudbase/js-sdk";

const app = cloudbase.init({ env: "your-env-id" });
const storage = app.storage.from();

const { data, error } = await storage.upload("images/photo.jpg", file);
if (error) throw error;

const fileID = data.id;
const { data: blob } = await storage.download(fileID);
const { data: signed } = await storage.createSignedUrl(fileID, 3600);
await storage.remove([fileID]);

API Methods

Client Entry

from() - Get the classic cloud storage file operation client
throwOnError() - Throw on error

File Operations

upload() - Upload files
update() - Update files
download() - Download files
remove() - Delete files
move() - Move files
copy() - Copy files

URL Management

createSignedUrl() - Create a signed URL
createSignedUrls() - Create signed URLs in batch
getPublicUrl() - Get a public URL
createSignedUploadUrl() - Create a signed upload URL

File Information

info() - Get file information
exists() - Check whether a file exists

from

from(): ClassicStorageFileApi

Parameters

No parameters

Response

ClassicStorageFileApi

Object

Classic-compatible object operation client.

Example

const storage = app.storage.from();

throwOnError

throwOnError(): this

Parameters

No parameters

Response

this

ClassicStorageFileApi

Current client instance for chaining.

Example

const storage = app.storage.from().throwOnError();
await storage.upload("file.txt", file);

upload

Upload a file to storage.

upload(path: string, fileBody: FileBody, fileOptions?: FileOptions): Promise<
  | { data: { id: string; path: string; fullPath: string }; error: null }
  | { data: null; error: StorageError }
>

type FileBody = Blob | ArrayBuffer | ArrayBufferView | Uint8Array | string | { size?: number; byteLength?: number; [key: string]: any };

interface FileOptions {
  cacheControl?: string;
  contentType?: string;
  metadata?: Record<string, any>;
  upsert?: boolean; // default true
}

Parameters

path

string

Storage-relative path, for example `images/photo.jpg`.

fileBody

FileBody

File content.

fileOptions

FileOptions

Upload options. Classic mode defaults to `upsert: true`.

Response

data

Object

Return data

error

StorageError | null

Error.

Example

Basic upload
Upload with options

// Upload documents.
const { data, error } = await app.storage
  .from()
  .upload("images/photo.jpg", file);

if (error) {
  console.error("Failed to upload:", error);
} else {
  console.log("upload succeeded:", data);
  console.log("file ID:", data.id);
  console.log("file path:", data.path);
}

// Upload files and configure settings
const { data, error } = await app.storage
  .from()
  .upload("images/photo.jpg", file, {
    cacheControl: "max-age=3600",
    contentType: "image/jpeg",
    metadata: {
      author: "John Doe",
      uploadedAt: new Date().toISOString(),
    },
  });

if (error) {
  console.error("Failed to upload:", error);
} else {
  console.log("upload succeeded:", data);
}

update

Update an existing file.

update(path: string, fileBody: FileBody, fileOptions?: FileOptions): Promise<{ data, error }>

Parameters

path

string

Storage-relative path.

fileBody

FileBody

New file content.

fileOptions

FileOptions

Upload options.

Response

data

{ id; path; fullPath } | null

Update result.

error

StorageError | null

Error.

Example

Update file
Update and modify metadata

// Update file contents
const { data, error } = await app.storage
  .from()
  .update("images/photo.jpg", newFile);

if (error) {
  console.error("update failed:", error);
} else {
  console.log("Update successful:", data);
}

Update file and modify metadata
const { data, error } = await app.storage
  .from()
  .update("images/photo.jpg", newFile, {
    cacheControl: "max-age=7200",
    metadata: {
      updatedAt: new Date().toISOString(),
      version: "2.0",
    },
  });

if (error) {
console.error("update failed:", error);
} else {
console.log("file updated:", data.path);
}

download

Download a file.

download(fileId: string, options?: TransformOptions): Promise<{ data: Blob; error: null } | { data: null; error: StorageError }>

interface TransformOptions {
  width?: number;
  height?: number;
  quality?: number;
  format?: "jpg" | "png" | "webp";
}

Parameters

fileId

string

Full CloudBase fileID.

options

TransformOptions

Image transformation options.

Response

data

Blob | null

File content.

error

StorageError | null

Error.

Example

Download file
Download thumbnail
Conversion format

// Downloading original file
const { data, error } = await app.storage
  .from()
  .download("cloud://envId.xxx/images/photo.jpg");

if (data) {
  // Create a download link
  const url = URL.createObjectURL(data);
  const a = document.createElement("a");
  a.href = url;
  a.download = "photo.jpg";
  a.click();
}

Download and convert the image to a thumbnail
const { data: thumbnail, error } = await app.storage
  .from()
  .download("cloud://envId.xxx/images/photo.jpg", {
    width: 300,
    height: 200,
    quality: 80,
  });

if (thumbnail) {
Display thumbnails
  const url = URL.createObjectURL(thumbnail);
  document.getElementById("thumbnail").src = url;
}

Download and convert the image format
const { data: webpImage, error } = await app.storage
  .from()
  .download("cloud://envId.xxx/images/photo.jpg", {
    format: "webp",
    quality: 90,
  });

if (webpImage) {
console.log("converted to WebP format");
}

remove

Delete one or more files.

remove(paths: string[]): Promise<{ data: FileObject[]; error: null } | { data: null; error: StorageError }>

Parameters

paths

string[]

Full fileID array.

Response

data

FileObject[] | null

Deletion result.

error

StorageError | null

Error.

Example

Delete a single file
Delete in batches

// Delete a single file
const { data, error } = await app.storage
  .from()
  .remove(["cloud://envId.xxx/images/photo.jpg"]);

if (error) {
  console.error("delete failed:", error);
} else {
  console.log("deleted successfully:", data);
}

// Batch delete multiple files
const { data, error } = await app.storage
  .from()
  .remove([
    "cloud://envId.xxx/images/photo1.jpg",
    "cloud://envId.xxx/images/photo2.jpg",
    "cloud://envId.xxx/documents/file.pdf",
  ]);

if (error) {
  console.error("delete failed:", error);
} else {
  console.log(`delete successfully ${data.length} files`);
}

move

Move a file to a new path.

move(fromPath: string, toPath: string): Promise<{ data: { message: string }; error: null } | { data: null; error: StorageError }>

Parameters

fromPath

string

Source path.

toPath

string

Destination path.

Response

data

Object

Return data

error

StorageError | null

Error.

Example

Move files
Rename file

Move files to the new location
const { data, error } = await app.storage
  .from()
  .move("images/old-photo.jpg", "images/archive/photo.jpg");

if (error) {
console.error("move failure:", error);
} else {
console.log("move succeeded:", data.message);
}

// Rename the file (move to the same directory with a new name)
const { data, error } = await app.storage
  .from()
  .move("images/photo.jpg", "images/new-photo.jpg");

if (error) {
  console.error("rename failed:", error);
} else {
  console.log("Rename successfully");
}

copy

Copy a file to a new path.

copy(fromPath: string, toPath: string): Promise<{ data: { path: string }; error: null } | { data: null; error: StorageError }>

Parameters

fromPath

string

Source path.

toPath

string

Destination path.

Response

data

Object

Return data

error

StorageError | null

Error.

Example

Copy file
Create a copy

Copy the file to the new location
const { data, error } = await app.storage
  .from()
  .copy("images/photo.jpg", "images/backup/photo.jpg");

if (error) {
console.error("copy failed:", error);
} else {
console.log("copied successfully, file path:", data.path);
}

// Create a copy under the same directory
const { data, error } = await app.storage
  .from()
  .copy("images/photo.jpg", "images/photo-copy.jpg");

if (error) {
  console.error("create copy failed:", error);
} else {
  console.log("copy created:", data.path);
}

createSignedUrl

Create a temporary access URL.

createSignedUrl(path: string, expiresIn: number, options?: { download?: string | boolean; transform?: TransformOptions }): Promise<{ data: { signedUrl: string }; error: null } | { data: null; error: StorageError }>

Parameters

path

string

Full fileID.

expiresIn

number

Expiration in seconds.

options

Object

Download and image transform options.

Response

data

Object

Return data

error

StorageError | null

Error.

Example

Create temporary link
Create thumbnail link
Short-term share link

// Create a temporary link valid for 1 hr
const { data, error } = await app.storage
  .from()
  .createSignedUrl("cloud://envId.xxx/images/photo.jpg", 3600);

if (error) {
console.error("create failed:", error);
} else {
console.log("temporary link:", data.signedUrl);
This link can be accessed directly to open the file.
}

Create a temporary link for the thumbnail
const { data, error } = await app.storage
  .from()
  .createSignedUrl("cloud://envId.xxx/images/photo.jpg", 3600, {
    width: 300,
    height: 200,
    quality: 80,
  });

if (error) {
console.error("create failed:", error);
} else {
Use the thumbnail URL
  document.getElementById("thumbnail").src = data.signedUrl;
}

Create a short-term share link valid for 5 minutes
const { data, error } = await app.storage
  .from()
  .createSignedUrl("cloud://envId.xxx/images/photo.jpg", 300);

if (error) {
console.error("create failed:", error);
} else {
// Share this link, it will automatically expire in 5 minutes
  navigator.clipboard.writeText(data.signedUrl);
alert("Share link copied to clipboard");
}

createSignedUrls

Create temporary access URLs in batch.

createSignedUrls(paths: string[], expiresIn: number): Promise<{ data, error }>

Parameters

paths

string[]

Full fileID array.

expiresIn

number

Expiration in seconds.

Response

data

Array | null

Signed URL results.

error

StorageError | null

Error.

Example

Batch create links
Batch create thumbnail links

// Create temporary links for multiple files in batches
const { data, error } = await app.storage
  .from()
  .createSignedUrls(
    [
      "cloud://envId.xxx/images/photo1.jpg",
      "cloud://envId.xxx/images/photo2.jpg",
      "cloud://envId.xxx/images/photo3.jpg",
    ],
    3600
  );

if (error) {
  console.error("create failed:", error);
} else {
  data.forEach((item) => {
    console.log(`${item.path}: ${item.signedUrl}`);
  });
}

// Batch create thumbnail links
const { data, error } = await app.storage
  .from()
  .createSignedUrls(
    [
      "cloud://envId.xxx/images/photo1.jpg",
      "cloud://envId.xxx/images/photo2.jpg",
      "cloud://envId.xxx/images/photo3.jpg",
    ],
    3600
  );

if (error) {
console.error("create failed:", error);
} else {
Display all thumbnails
  const gallery = document.getElementById("gallery");
  data.forEach((item) => {
    const img = document.createElement("img");
    img.src = item.signedUrl;
    gallery.appendChild(img);
  });
}

getPublicUrl

Get a public access URL.

getPublicUrl(path: string, options?: { download?: string | boolean; transform?: TransformOptions }): Promise<{ data: { publicUrl: string }; error: null } | { data: null; error: StorageError }>

Parameters

path

string

Full fileID.

Response

data

Object

Return data

Example

Get public link
Get thumbnail link

Get the public access URL of the file
const { data } = await app.storage
  .from()
  .getPublicUrl("cloud://envId.xxx/images/photo.jpg");

console.log("public link:", data.publicUrl);
This link can be used directly (if the file is set to public access).

Get the public URL of the thumbnail
const { data } = await app.storage
  .from()
  .getPublicUrl("cloud://envId.xxx/images/photo.jpg", {
    width: 300,
    height: 200,
    quality: 80,
  });

// for use in img tag
document.getElementById("thumbnail").src = data.publicUrl;

info

Get file information.

info(pathOrFileId: string): Promise<{ data: FileInfo; error: null } | { data: null; error: StorageError }>

Parameters

pathOrFileId

string

Full fileID or relative path.

Response

data

FileInfo | null

File information.

error

StorageError | null

Error.

Example

Get file information
Display file details

// Get file details
const { data, error } = await app.storage
  .from()
  .info("cloud://envId.xxx/images/photo.jpg");

if (error) {
  console.error("get failed:", error);
} else {
  console.log("filename:", data.name);
  console.log("file size:", data.size, "bytes");
  console.log("creation time:", data.created_at);
  console.log("update time:", data.updated_at);
  console.log("metadata:", data.metadata);
}

// Display file details on the interface
const { data, error } = await app.storage
  .from()
  .info("cloud://envId.xxx/documents/report.pdf");

if (data) {
  const sizeInMB = (data.size / 1024 / 1024).toFixed(2);
  document.getElementById("fileName").textContent = data.name;
  document.getElementById("fileSize").textContent = `${sizeInMB} MB`;
  document.getElementById("createdAt").textContent = new Date(
    data.created_at
  ).toLocaleString();
}

exists

Check whether a file exists.

exists(pathOrFileId: string): Promise<{ data: boolean; error: null } | { data: null; error: StorageError }>

Parameters

pathOrFileId

string

Full fileID or relative path.

Response

data

boolean | null

Whether it exists.

error

StorageError | null

Error.

Example

Check file exists
Check before upload

Check whether the file exists
const { data: exists, error } = await app.storage
  .from()
  .exists("cloud://envId.xxx/images/photo.jpg");

if (error) {
console.error("check failed:", error);
} else if (exists) {
console.log("file exists");
} else {
console.log("file not found");
}

Check whether the file already exists before uploading
const { data: exists } = await app.storage
  .from()
  .exists("cloud://envId.xxx/images/photo.jpg");

if (exists) {
File already exists. Overwrite?
const shouldOverwrite = confirm("File already exists, whether to overwrite?");
  if (shouldOverwrite) {
    await app.storage.from().update("images/photo.jpg", file);
  }
} else {
// File does not exist, direct upload
  await app.storage.from().upload("images/photo.jpg", file);
}

createSignedUploadUrl

Create a signed upload URL.

createSignedUploadUrl(path: string): Promise<{ data, error }>

Parameters

path

string

Upload target path.

Response

data

Object | null

Signed upload URL and CloudBase upload metadata.

error

StorageError | null

Error.

Example

Create upload link
Client direct upload

// Create a pre-signed URL for uploading
const { data, error } = await app.storage
  .from()
  .createSignedUploadUrl("cloud://envId.xxx/images/photo.jpg");

if (error) {
console.error("creation failed:", error);
} else {
console.log("upload URL:", data.signedUrl);
console.log("upload token:", data.token);

Use this URL to directly upload
  const formData = new FormData();
  formData.append("file", file);

  await fetch(data.signedUrl, {
    method: "PUT",
    body: file,
    headers: {
      "Content-Type": file.type,
    },
  });
}

// Implement direct upload on the client
async function uploadFileDirectly(file) {
  // Get a signature upload URL
  const { data, error } = await app.storage
    .from()
    .createSignedUploadUrl(`cloud://envId.xxx/uploads/${file.name}`);

  if (error) {
    console.error("Failed to get upload URL:", error);
    return;
  }

  // 2. Direct upload to cloud storage
  const uploadResponse = await fetch(data.signedUrl, {
    method: "PUT",
    body: file,
    headers: {
      "Content-Type": file.type,
    },
  });

  if (uploadResponse.ok) {
    console.log("upload succeeded");
  } else {
    console.error("Failed to upload");
  }
}

Type Definitions

type Result<T> =
  | { data: T; error: null }
  | { data: null; error: StorageError };

type FileBody = Blob | ArrayBuffer | ArrayBufferView | Uint8Array | string | { size?: number; byteLength?: number; [key: string]: any };

interface UploadResult {
  id: string;
  path: string;
  fullPath: string;
}

interface FileOptions {
  cacheControl?: string;
  contentType?: string;
  metadata?: Record<string, any>;
  upsert?: boolean;
}

interface TransformOptions {
  width?: number;
  height?: number;
  quality?: number;
  format?: "jpg" | "png" | "webp";
}

Migration Guide

If you are migrating from JS SDK v2 or older file APIs to the JS SDK v3 classic cloud storage API, use the following replacements:

Legacy API	JS SDK v3 Classic Mode API
`app.uploadFile()`	`app.storage.from().upload()`
`app.downloadFile()`	`app.storage.from().download()`
`app.getTempFileURL()`	`app.storage.from().createSignedUrl()`
`app.deleteFile()`	`app.storage.from().remove()`

When migrating, store the full fileID returned by upload() and use it for download, deletion, signed URLs, and file metadata queries.

Best Practices

1. Error handling

const { data, error } = await app.storage.from().upload("images/photo.jpg", file);

if (error) {
  console.error("Operation failed:", error.message);
  return;
}

2. Path rules

Pass storage-relative paths when uploading, for example images/photo.jpg.
For download, deletion, signed URLs, and file metadata queries, use the full fileID returned by upload.
Do not start paths with / or include consecutive /.

Quick Start​

API Methods​

Client Entry​

File Operations​

URL Management​

File Information​

from​

Parameters

Response

Example

throwOnError​

Parameters

Response

Example

upload​

Parameters

Response

Example

update​

Parameters

Response

Example

download​

Parameters

Response

Example

remove​

Parameters

Response

Example

move​

Parameters

Response

Example

copy​

Parameters

Response

Example

createSignedUrl​

Parameters

Response

Example

createSignedUrls​

Parameters

Response

Example

getPublicUrl​

Parameters

Response

Example

info​

Parameters

Response

Example

exists​

Parameters

Response

Example

createSignedUploadUrl​

Parameters

Response

Example

Type Definitions​

Migration Guide​

Best Practices

1. Error handling​

2. Path rules​

Related Resources

Quick Start

API Methods

Client Entry

File Operations

URL Management

File Information

from

throwOnError

upload

update

download

remove

move

copy

createSignedUrl

createSignedUrls

getPublicUrl

info

exists

createSignedUploadUrl

Type Definitions

Migration Guide

1. Error handling

2. Path rules