/cloud-storage-web

name: cloud-storage-web
description: Complete guide for CloudBase cloud storage using Web SDK (@cloudbase/js-sdk) - upload, download, temporary URLs, file management, and best practices.
version: 2.26.0
alwaysApply: false

Sibling skills (local only)

Sibling CloudBase skills ship beside this skill. Use local relative paths such as `../auth-tool-cloudbase/SKILL.md`.

If a referenced sibling skill file is missing from this environment, ask the user to install the full CloudBase plugin (or the missing skill). Do **not** HTTP-fetch remote skill or protocol markdown into the agent context.

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-cloudbase/SKILL.md`
• General Web app setup -> `../web-development/SKILL.md`
• Direct storage management through MCP tools -> `../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.
• Ignoring `STORAGE_NOT_EXIST`; it means the target storage bucket/resource is not ready, not that the browser upload code should fabricate a URL.
• On local Vite or dev-server tasks, forgetting to whitelist the exact current browser `host:port` before testing `app.uploadFile()`.
• Treating CloudBase PG / `pgstore` like the legacy NoSQL CloudBase storage. PG environments use a separate `pgstore` backend whose buckets are NOT auto-created from your old NoSQL bucket. If `pgstore` has no bucket, every upload returns `STORAGE_BUCKET_NOT_FOUND` and the SDK then issues `PUT https://undefined/` (visible in DevTools as `net::ERR_NAME_NOT_RESOLVED`). Treat bucket existence as a hard prerequisite, just like Supabase: in Supabase Storage every upload must target an already-created bucket; CloudBase PG follows the same model.

Minimal checklist

• Confirm the caller is a browser/Web app.
• Initialize the Web SDK once.
• Confirm CloudBase storage exists in the current environment before testing upload. Use available MCP management/query tools to inspect or create/select the storage bucket when the environment has no default bucket. **In a PG / pgstore environment, the legacy NoSQL bucket from `DescribeEnvs` does NOT count as a usable pgstore bucket; create one explicitly before any browser upload. The legacy NoSQL bucket itself is still fine for legacy `app.uploadFile()` flows that already target it — PG and NoSQL storage coexist; this skill applies to BOTH.**
• 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:

• Browser origin `http://127.0.0.1:4173` -> whitelist entry `127.0.0.1:4173`
• Browser origin `http://localhost:5173` -> whitelist entry `localhost:5173`

3. If the exact current host entry is missing, call `envDomainManagement` with `action="create"` and add that host entry before relying on `app.uploadFile()`. 4. 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`. 5. Tell the user that security-domain changes may take a few minutes to propagate; poll `queryEnv(action="domains")` rather than blind-sleeping for a fixed long interval. 6. Only after that should you implement and test browser-side `app.uploadFile()` flows.

If `app.uploadFile()` returns `STORAGE_NOT_EXIST`, stop editing frontend code and fix the environment-side storage resource first. Re-check the environment storage list, create or select an available bucket if the task allows it, then retry the same SDK upload flow.

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

Bucket existence prerequisite (mandatory before any upload code)

Just like Supabase Storage, CloudBase Storage requires the target bucket to exist before any client-side upload. This is true for both legacy CloudBase NoSQL storage (`STORAGE_NOT_EXIST`) and the newer PG / `pgstore` backend (`STORAGE_BUCKET_NOT_FOUND`).

Mental model parity with Supabase:

| Step | Supabase | CloudBase | | ---- | -------- | --------- | | Create bucket | `supabase.storage.createBucket('covers', { public: true })` (admin-side, with service role) | In PG mode, create a `storage.buckets` bucket through PG storage HTTP API / CLI / console / SQL on `storage.buckets` when appropriate. The browser SDK cannot create one. | | Upload | `supabase.storage.from('covers').upload('a.png', file)` | **PG 模式**: `app.storage.from('covers').upload('a.png', file)` — `from(bucketName)` 指定 pgstore 存储桶。<br>**非 PG 模式**: `app.storage.from().upload('covers/a.png', file)` — bucket 名作为路径第一段。| | Bucket missing error | `Bucket not found` | Browser sees `STORAGE_BUCKET_NOT_FOUND` (PG) or `STORAGE_NOT_EXIST` (NoSQL), then a follow-