cloud-storage-web

Standalone Install Note

If this environment only installed the current skill, start from the CloudBase main entry and use the published cloudbase/references/... paths for sibling skills.

• CloudBase main entry: https://cnb.cool/tencent/cloud/cloudbase/cloudbase-skills/-/git/raw/main/skills/cloudbase/SKILL.md
• Current skill raw source: https://cnb.cool/tencent/cloud/cloudbase/cloudbase-skills/-/git/raw/main/skills/cloudbase/references/cloud-storage-web/SKILL.md

Keep local references/... paths for files that ship with the current skill directory. When this file points to a sibling skill such as auth-tool or web-development, use the standalone fallback URL shown next to that reference.

Cloud Storage Web SDK

Activation Contract

Use this first when

• A browser or Web app must upload, download, or manage CloudBase storage objects through @cloudbase/js-sdk.
• The request mentions uploadFile, getTempFileURL, deleteFile, or downloadFile in frontend code.

Read before writing code if

• The task is browser-side storage work but you still need to separate it from Mini Program storage, backend storage management, or static hosting deployment.
• The request may be blocked by security domains or frontend auth.

Then also read

• Web login and identity -> ../auth-web/SKILL.md (standalone fallback: https://cnb.cool/tencent/cloud/cloudbase/cloudbase-skills/-/git/raw/main/skills/cloudbase/references/auth-web/SKILL.md)
• General Web app setup -> ../web-development/SKILL.md (standalone fallback: https://cnb.cool/tencent/cloud/cloudbase/cloudbase-skills/-/git/raw/main/skills/cloudbase/references/web-development/SKILL.md)
• Direct storage management through MCP tools -> ../cloudbase-platform/SKILL.md (standalone fallback: https://cnb.cool/tencent/cloud/cloudbase/cloudbase-skills/-/git/raw/main/skills/cloudbase/references/cloudbase-platform/SKILL.md)

Do NOT use for

• Mini Program file APIs.
• Backend or agent-side direct storage management through MCP.
• Static website hosting deployment via manageHosting(action="upload").
• Database operations.

Common mistakes / gotchas

• Uploading from browser code without configuring security domains.
• Using this skill for static hosting instead of storage objects.
• Mixing browser SDK upload flows with server-side file-management tasks.
• Assuming temporary download URLs are permanent links.
• On local Vite or dev-server tasks, forgetting to whitelist the exact current browser host:port before testing app.uploadFile().

Minimal checklist

• Confirm the caller is a browser/Web app.
• Initialize the Web SDK once.
• Check security-domain/CORS requirements.
• Pick the right storage method before coding.

Local dev recipe

When the app runs on a local browser origin and must upload files from the frontend:

1. Use envQuery with action="domains" to inspect the current security-domain whitelist.
2. Convert the browser origin into the CloudBase whitelist entry format:
3. Browser origin http://127.0.0.1:4173 -> whitelist entry 127.0.0.1:4173
4. Browser origin http://localhost:5173 -> whitelist entry localhost:5173
5. If the exact current host entry is missing, call envDomainManagement with action="create" and add that host entry before relying on app.uploadFile().
6. If the runtime port may change between runs, do not assume any fixed default port list is sufficient. Re-check the actual browser origin you are really using for testing or final validation, then add that exact host:port.
7. Tell the user that security-domain changes may take several minutes to propagate.
8. Only after that should you implement and test browser-side app.uploadFile() flows.

If the task uses browser-side file upload, treat this as a prerequisite rather than an optional cleanup.

Overview

Use this skill for browser-side cloud storage operations through the CloudBase Web SDK.

Typical tasks:

• upload files from a browser
• generate temporary download URLs
• delete files
• trigger browser downloads

SDK initialization

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

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

Initialization rules:

• Use synchronous initialization with a shared app instance.
• Do not re-initialize in every component.
• If the operation depends on user identity, handle auth before storage operations.

Method routing

• Upload from browser -> app.uploadFile()
• Temporary preview/download URL -> app.getTempFileURL()
• Delete existing files -> app.deleteFile()
• Trigger browser download -> app.downloadFile()

Upload

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

Upload rules

• cloudPath must include the filename.
• Use / to create folder structure.
• Validate file type and size before upload.
• Show upload progress for larger files when UX matters.
• On local dev origins, confirm the exact frontend origin already exists in environment security domains before assuming the upload path is usable.
• Match against the whitelist entry format returned by envQuery(action="domains"), which is typically host:port instead of a full http://... URL.
• After app.uploadFile() succeeds, do not fabricate a public-looking URL by concatenating envId, bucket domain, or cloudPath. Use the returned fileID with app.getTempFileURL() and store or display the SDK-resolved URL instead.

Progress example

await app.uploadFile({
  cloudPath: "uploads/avatar.jpg",
  filePath: selectedFile,
  onUploadProgress: ({ loaded, total }) => {
    const percent = Math.round((loaded * 100) / total);
    console.log(percent);
  }
});

Temporary URLs

const result = await app.getTempFileURL({
  fileList: [
    {
      fileID: "cloud://env-id/uploads/avatar.jpg",
      maxAge: 3600
    }
  ]
});

Use temp URLs when the browser needs to preview or download private files without exposing a permanent public link.

Typical upload + preview flow:

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

const tempUrlResult = await app.getTempFileURL({
  fileList: [{ fileID: uploadResult.fileID, maxAge: 3600 }]
});

const previewUrl = tempUrlResult.fileList?.[0]?.tempFileURL || tempUrlResult.fileList?.[0]?.download_url;
if (!previewUrl) {
  throw new Error("Failed to resolve temporary file URL after upload");
}

Delete files

await app.deleteFile({
  fileList: ["cloud://env-id/uploads/old-avatar.jpg"]
});

Always inspect per-file results before assuming deletion succeeded.

Download files

await app.downloadFile({
  fileID: "cloud://env-id/uploads/report.pdf"
});

Use this for browser-initiated downloads. For programmatic rendering or preview, prefer getTempFileURL().

Security-domain reminder

To avoid CORS problems, add your frontend domain in CloudBase security domains. In MCP-enabled workflows, prefer checking and updating this through tools before coding browser uploads.

{ "tool": "envQuery", "action": "domains" }

Use the actual browser origin when deciding what to add. If the page is running on a custom domain or a local dev port, add that exact host:port value instead of guessing from a hard-coded list.

{
  "tool": "envDomainManagement",
  "action": "create",
  "domains": ["<actual-browser-host>:<actual-browser-port>"]
}

Match the real browser origin to the whitelist entry format returned by envQuery(action="domains"). For local Vite and preview servers, the port can vary between runs, so avoid assuming any fixed default port is sufficient.

Typical examples:

• <your-local-host>:<actual-port>
• <your-custom-domain>

Best practices

1. Use a clear folder structure such as uploads/, avatars/, documents/.
2. Validate file size and t