Cloud Storage Web SDK

Use this skill when building web applications that need to upload, download, or manage files using CloudBase cloud storage via the @cloudbase/js-sdk (Web SDK).

When to use this skill

Use this skill for file storage operations in web applications when you need to:

• •Upload files from web browsers to CloudBase cloud storage
• •Generate temporary download URLs for stored files
• •Delete files from cloud storage
• •Download files from cloud storage to local browser

Do NOT use for:

• •Mini-program file operations (use mini-program specific skills)
• •Backend file operations (use Node SDK skills)
• •Database operations (use database skills)

How to use this skill (for a coding agent)

1. •

   Initialize CloudBase SDK

   • •Ask the user for their CloudBase environment ID
   • •Always use the standard initialization pattern shown below
2. •

   Choose the right storage method

   • •uploadFile - For uploading files from browser to cloud storage
   • •getTempFileURL - For generating temporary download links
   • •deleteFile - For deleting files from storage
   • •downloadFile - For downloading files to browser
3. •

   Handle CORS requirements

   • •Remind users to add their domain to CloudBase console security domains
   • •This prevents CORS errors during file operations
4. •

   Follow file path rules

   • •Use valid characters: [0-9a-zA-Z], /, !, -, _, ., , *, Chinese characters
   • •Use / for folder structure (e.g., folder/file.jpg)

SDK Initialization

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

const app = cloudbase.init({
  env: "your-env-id", // Replace with your CloudBase environment ID
});

Initialization rules:

• •Always use synchronous initialization with the pattern above
• •Do not lazy-load the SDK with dynamic imports
• •Keep a single shared app instance across your application

File Upload (uploadFile)

Basic Usage

const result = await app.uploadFile({
  cloudPath: "folder/filename.jpg", // File path in cloud storage
  filePath: fileInput.files[0],     // HTML file input element
});

// Result contains:
{
  fileID: "cloud://env-id/folder/filename.jpg", // Unique file identifier
  // ... other metadata
}

Advanced Upload with Progress

const result = await app.uploadFile({
  cloudPath: "uploads/avatar.jpg",
  filePath: selectedFile,
  method: "put", // "post" or "put" (default: "put")
  onUploadProgress: (progressEvent) => {
    const percent = Math.round(
      (progressEvent.loaded * 100) / progressEvent.total
    );
    console.log(`Upload progress: ${percent}%`);
    // Update UI progress bar here
  }
});

Parameters

Cloud Path Rules

• •Valid characters: [0-9a-zA-Z], /, !, -, _, ., , *, Chinese characters
• •Invalid characters: Other special characters
• •Structure: Use / to create folder hierarchy
• •Examples:
  • •"avatar.jpg"
  • •"uploads/avatar.jpg"
  • •"user/123/avatar.jpg"

CORS Configuration

⚠️ IMPORTANT: To prevent CORS errors, add your domain to CloudBase console:

1. •Go to CloudBase Console → Environment → Security Sources → Security Domains
2. •Add your frontend domain (e.g., https://your-app.com, http://localhost:3000)
3. •If CORS errors occur, remove and re-add the domain

Temporary Download URLs (getTempFileURL)

Basic Usage

const result = await app.getTempFileURL({
  fileList: [
    {
      fileID: "cloud://env-id/folder/filename.jpg",
      maxAge: 3600 // URL valid for 1 hour (seconds)
    }
  ]
});

// Access the download URL
result.fileList.forEach(file => {
  if (file.code === "SUCCESS") {
    console.log("Download URL:", file.tempFileURL);
    // Use this URL to download or display the file
  }
});

Multiple Files

const result = await app.getTempFileURL({
  fileList: [
    {
      fileID: "cloud://env-id/image1.jpg",
      maxAge: 7200 // 2 hours
    },
    {
      fileID: "cloud://env-id/document.pdf",
      maxAge: 86400 // 24 hours
    }
  ]
});

Parameters

fileList Item Structure

Response Structure

{
  code: "SUCCESS",
  fileList: [
    {
      code: "SUCCESS",
      fileID: "cloud://env-id/folder/filename.jpg",
      tempFileURL: "https://temporary-download-url"
    }
  ]
}

Best Practices

• •Set appropriate maxAge based on use case (1 hour to 24 hours)
• •Handle SUCCESS/ERROR codes in response
• •Use temporary URLs for private file access
• •Cache URLs if needed, but respect expiration time

File Deletion (deleteFile)

Basic Usage

const result = await app.deleteFile({
  fileList: [
    "cloud://env-id/folder/filename.jpg"
  ]
});

// Check deletion results
result.fileList.forEach(file => {
  if (file.code === "SUCCESS") {
    console.log("File deleted:", file.fileID);
  } else {
    console.error("Failed to delete:", file.fileID);
  }
});

Multiple Files

const result = await app.deleteFile({
  fileList: [
    "cloud://env-id/old-avatar.jpg",
    "cloud://env-id/temp-upload.jpg",
    "cloud://env-id/cache-file.dat"
  ]
});

Parameters

Response Structure

{
  fileList: [
    {
      code: "SUCCESS",
      fileID: "cloud://env-id/folder/filename.jpg"
    }
  ]
}

Best Practices

• •Always check response codes before assuming deletion success
• •Use this for cleanup operations (old avatars, temp files, etc.)
• •Consider batching multiple deletions for efficiency

File Download (downloadFile)

Basic Usage

const result = await app.downloadFile({
  fileID: "cloud://env-id/folder/filename.jpg"
});

// File is downloaded to browser default download location

Parameters

Response Structure

{
  // Success response (no specific data returned)
  // File is downloaded to browser
}

Best Practices

• •Use for user-initiated downloads (save file dialogs)
• •For programmatic file access, use getTempFileURL instead
• •Handle download errors appropriately

Error Handling

All storage operations should include proper error handling:

try {
  const result = await app.uploadFile({
    cloudPath: "uploads/file.jpg",
    filePath: selectedFile
  });

  if (result.code) {
    // Handle error
    console.error("Upload failed:", result.message);
  } else {
    // Success
    console.log("File uploaded:", result.fileID);
  }
} catch (error) {
  console.error("Storage operation failed:", error);
}

Common Error Codes

• •INVALID_PARAM - Invalid parameters
• •PERMISSION_DENIED - Insufficient permissions
• •RESOURCE_NOT_FOUND - File not found
• •SYS_ERR - System error

Best Practices

1. •File Organization: Use consistent folder structures (uploads/, avatars/, documents/)
2. •Naming Conventions: Use descriptive filenames with timestamps if needed
3. •Progress Feedback: Show upload progress for better UX
4. •Cleanup: Delete temporary/unused files to save storage costs
5. •Security: Validate file types and sizes before upload
6. •Caching: Cache download URLs appropriately but respect expiration
7. •Batch Operations: Use arrays for multiple file operations when possible

Performance Considerations

1. •File Size Limits: Be aware of CloudBase file size limits
2. •Concurrent Uploads: Limit concurrent uploads to prevent browser overload
3. •Progress Monitoring: Use progress callbacks for large file uploads
4. •Temporary URLs: Generate URLs only when needed, with appropriate expiration

Security Considerations

1. •Domain Whitelisting: Always configure security domains to prevent CORS issues
2. •Access Control: Use appropriate file permissions (public vs private)
3. •URL Expiration: Set reasonable expiration times for temporary URLs
4. •User Permissions: Ensure users can only access their own files when appropriate