Web Development

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/web-development/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.

Cross-cutting protocols (required before code changes or static hosting publish):

• Change Safety Protocol: https://cnb.cool/tencent/cloud/cloudbase/cloudbase-skills/-/git/raw/main/skills/cloudbase/references/cloudbase-platform/references/protocols/change-safety-protocol.md
• Deployment Gate: https://cnb.cool/tencent/cloud/cloudbase/cloudbase-skills/-/git/raw/main/skills/cloudbase/references/cloudbase-platform/references/protocols/deployment-gate.md

Web Development

Activation Contract

Use this first when

• The request is to implement, integrate, debug, build, deploy, or validate a Web frontend or static site.
• The design direction is already decided, or the user is asking for engineering execution rather than visual exploration.
• The work involves React, Vue, Vite, routing, browser-based verification, or CloudBase Web integration.

Read before writing code if

• The task includes project structure, framework conventions, build config, deployment, routing, or frontend test and validation flows.
• The request includes UI implementation but the visual direction is already fixed; otherwise read ui-design first.

Then also read

• General React / Vue / Vite guidance -> frameworks.md
• Browser flow checks or page validation -> browser-testing.md
• Login flow -> ../auth-tool/SKILL.md (standalone fallback: https://cnb.cool/tencent/cloud/cloudbase/cloudbase-skills/-/git/raw/main/skills/cloudbase/references/auth-tool/SKILL.md), then ../auth-web/SKILL.md (standalone fallback: https://cnb.cool/tencent/cloud/cloudbase/cloudbase-skills/-/git/raw/main/skills/cloudbase/references/auth-web/SKILL.md)
• Official Account JSAPI Pay, Native QR-code Pay, or WeChat OAuth on CloudBase -> ../cloudbase-wechat-integration/SKILL.md (standalone fallback: https://cnb.cool/tencent/cloud/cloudbase/cloudbase-skills/-/git/raw/main/skills/cloudbase/references/cloudbase-wechat-integration/SKILL.md; official docs: https://docs.cloudbase.net/integration/introduce/index.md)
• CloudBase database work -> matching database skill

Do NOT use for

• Visual direction setting, prototype-first design work, or pure aesthetic exploration.
• Mini programs, native Apps, or backend-only services.
• WeChat payment or Official Account OAuth contract details; use cloudbase-wechat-integration after identifying the Web surface.

Common mistakes / gotchas

• Starting implementation before clarifying whether the task is design or engineering execution.
• Mixing framework setup, deployment, and CloudBase integration concerns into one vague change.
• Treating cloud functions as the default solution for Web authentication.
• Skipping browser-level validation after a UI or routing change.
• History mode SPA with CloudBase static hosting: deploying a single-page app using History mode (React Router / Vue Router) without configuring the static hosting "404 error document" to index.html. This causes NoSuchKey / 404 errors when users refresh or directly visit any sub-route.
• In an existing application, detouring into UI redesign or broad repo sweeps before patching the current handlers and services.

Engineering constitution (non-negotiable)

These rules override convenience. Treat them as a gate before saying "done".

1. TypeScript — do not silence the type system

• Do NOT use `any` to bypass type errors. Not : any, not as any, not @ts-ignore, not @ts-nocheck, not @ts-expect-error without a written justification. any propagates silently and defeats the only compile-time safety net this project has.
• When a type error appears, fix the root cause:
• Missing / wrong library types → install @types/..., or narrow the import, or write a precise interface / type for the shape you actually use.
• Shape is genuinely unknown at the boundary (JSON from an API, postMessage payload, window.* injection) → type it as unknown and narrow with a type guard (typeof, in, a discriminator field, or zod / equivalent).
• Third-party type is wrong → augment via declare module in a local .d.ts, not any.
• Truly dynamic case (e.g. generic event bus) → use a generic <T> with a constraint, not any.
• unknown + narrowing is the acceptable escape hatch. any is not.
• If you genuinely cannot avoid any for a specific line (extremely rare), leave a one-line comment with why and what would remove it, so reviewers can audit.
• The same spirit applies to ESLint: do not sprinkle // eslint-disable to mute the real signal. Fix the rule violation, or discuss before disabling.

2. Self-verify before claiming done

Before making any non-trivial code or configuration change, you must first follow the Change Safety Protocol in cloudbase-platform/references/protocols/change-safety-protocol.md (declare impact → user confirmation → post-edit verification). Before any static hosting publish or custom domain work, complete the checks in cloudbase-platform/references/protocols/deployment-gate.md.

Saying "I've implemented it" / "fixed it" / "it should work" without evidence is not acceptable. Before declaring completion, you must actually run the checks and report the result.

Static / build layer (always, when applicable):

• tsc --noEmit (or vue-tsc --noEmit) passes cleanly — zero errors, zero suppressed diagnostics you added.
• eslint / project linter passes on changed files.
• The project's build command (npm run build / pnpm build / vite build) completes without new warnings that you introduced.
• The project's unit tests pass if they exist and cover the touched area.

Runtime / browser layer (whenever the change affects rendering, routing, forms, auth, or async flows):

• Use the `agent-browser` tool to actually open the page and reproduce the user-visible flow. Follow browser-testing.md for the concrete workflow.
• Confirm: the target route loads, the interaction you claim to have fixed behaves the way you claim, no new console errors are introduced, and no regression in the adjacent routes you touched.
• Record what you checked (route, action, expected result, actual result).

Only after both layers pass may you say the task is done. If either layer cannot be executed locally (e.g. blocked by credentials, missing backend, paid API), say so explicitly and list exactly which step is still unverified — do not gloss over it.

3. Do not paper over failures

• Do not wrap broken logic in try { ... } catch {} to make the error go away.
• Do not delete or skip a failing test to make CI green — fix it, or explain why the test is actually wrong and change the test with justification.
• Do not mark a task complete because "the code compiles". Compilation is the bare minimum, not the goal.

When to use this skill

Use this skill for Web engineering work such as:

• Implementing React or Vue pages and components
• Setting up or maintaining Vite-based frontend projects
• Handling routing, data loading, forms, and build configuration
• Running browser-based validation and smoke checks
• Integrating CloudBase Web SDK and static hosting when the project needs CloudBase capabilities

Do NOT use for:

• UI direction or visual system design only; use ui-design
• Mini program development; use miniprogram-development
• Backend service implementation; use cloudrun-development or cloud-functions

How to use this skill (for a coding agent)

1. Clarify the execution surface

• Confirm whether the task is framework setup, page implementation, debugging, deployment, validation, or CloudBase integration.
• Keep the work scoped to the actual Web app surface instead of spreading into unrelated backend changes.
• If the workspace is an existing application with TODOs, treat it as a targeted repair task, not a greenfield build.

2. Follow framework and build conventions

• Prefer the existing project stack if one already exists.
• For new work, treat Vite as the default bundler unless the repo or user constraints say otherwise.
• Put reusable app code under src and build output under dist unless the repo already uses a different convention.
• In an existing application with fixed structure, inspect the files that already own the flow before reading broad docs: src/lib/backend.*, src/lib/auth.*, src/lib/*service.*, route guards, and the page handlers bound to submit buttons.

3. Validate through the browser, not only by reading code

• For interaction, routing, rendering, or regression checks, use agent-browser workflows from browser-testing.md.
• Prefer lightweight smoke validation for changed flows before claiming the frontend work is complete.

4. Treat CloudBase as an integration branch

• Use CloudBase Web SDK and static hosting guidance only when the project actually needs CloudBase platform features.
• Reuse auth-tool and auth-web for login or provider readiness instead of re-describing those flows here.

Core workflow

1. Choose the right engineering path

• React / Vue feature work: implement within the app's existing component, routing, and state conventions
• New Web app: prefer Vite unless the repo already standardizes on another toolchain
• Debugging and regressions: reproduce in browser, narrow to a specific page or interaction, then patch
• CloudBase integration: wire in Web SDK, auth, data, or static hosting only after the base frontend path is clear

2. Keep implementation grounded in project reality

• Follow the repo's package manager, scripts, and lint/test patterns
• Avoid framework rewrites unless the user explicitly asks for one
• Prefer the smallest viable page/component/config change that satisfies the task
• In TODO-based apps, complete the existing implementation directly instead of creating parallel helpers, sample pages, or detached prototypes

3. Validate changed flows explicitly

• Run the relevant local build / lint / typecheck / test command when available. A clean tsc --noEmit and a clean project build are the minimum bar — not proof of correctness.
• For anything user-visible (routing, forms, rendering, auth, async flows), open the affected page or flow in a browser with `agent-browser`. Code reading alone is not sufficient evidence — see the Engineering constitution above.
• Record what was checked: route, action, expected result, actual result, and any remaining gap.

CloudBase Web integration

Use this section only when the Web project needs CloudBase platform features.

Web SDK rules

• Prefer npm installation for React, Vue, Vite, and other bundler-based projects
• Use the CDN only for static HTML pages, quick demos, embedded snippets, or README examples
• Only use documented CloudBase Web SDK APIs; do not invent methods or options
• Keep a shared app or auth instance instead of re-initializing on every call
• If the user only provides an environment alias, nickname, or other shorthand, resolve it to the canonical full EnvId before writing SDK init code, console links, or config files. Do not pass alias-like short forms directly into cloudbase.init({ env }).

Authentication boundary

• Authentication must use CloudBase SDK built-in features
• Do not move Web login logic into cloud functions
• For provider readiness, login method setup, or publishable key issues, route to auth-tool and auth-web

Static hosting defaults

• Build before deployment
• Prefer relative asset paths for static hosting compatibility
• Use hash routing by default when the project lacks server-side route rewrites
• If the user does not specify a root path, avoid deploying directly to the site root by default
• SPA routing (History mode): when using React Router / Vue Router in History mode (not hash mode), configure the CloudBase static hosting "404 error document" to index.html. Otherwise refreshing or directly visiting any sub-route returns NoSuchKey / 404 error, because the static hosting looks for a file at that path instead of falling through to index.html for the SPA to handle routing.

Use the MCP tool to apply this:

  manageHosting({ action: "setWebsiteDocument", indexDocument: "index.html", errorDocument: "index.html" })

Then verify with:

  queryHosting({ action: "websiteConfig" })

CloudBase quick start

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

const app = cloudbase.init({
  env: "your-full-env-id", // Canonical full CloudBase environment ID resolved from envQuery or the console
});

const auth = app.auth();

Browser Validation (with agent-browser)

This file is the concrete playbook for the agent-browser tool. Use it whenever the Engineering constitution in SKILL.md says "verify in the browser before claiming done".

Code reading, static types, and a clean build are necessary but not sufficient. Any change that affects what the user sees, clicks, or navigates must be opened in a real browser and exercised.

When agent-browser is required (not optional)

Trigger browser validation for changes that touch any of:

• Routing / navigation — new routes, redirects, route guards, 404s, hash vs history mode, nested layouts
• Forms — submit handlers, controlled inputs, validation errors, disabled states, file uploads
• Auth flows — sign in, sign up, logout, session guards, token refresh, getSession
• Async UI — loading spinners, skeletons, error banners, retry buttons, streaming responses
• Conditional rendering — empty states, permission-gated sections, feature flags
• Third-party SDK calls from the browser — CloudBase Web SDK (auth, database, AI model, storage), analytics, payment

Skip browser validation only for pure build-config edits, README / documentation-only changes, backend-only work, or changes guarded by CI tests you verified pass.

When agent-browser is NOT the right tool

• Pure visual direction / aesthetic exploration → use the ui-design skill first.
• Backend-only logic that never renders in the browser → use unit tests or direct API calls.
• Smoke-testing a production URL against real user credentials → do not automate; ask the user.

Standard workflow

Follow these steps in order. Do not skip the "before the fix" reproduction — it is what proves the bug was real and that your change actually fixed it.

1. Start the app (or confirm it is already running).

• Typical: npm run dev / pnpm dev / vite. Record the local URL (often http://localhost:5173).
• If the project uses a build-and-serve flow instead of a dev server, document the exact commands you ran.

2. Open the target route with `agent-browser`, starting from the entry URL, not deep-linking into private pages unless you already have a valid session. 3. Reproduce the current (pre-fix or pre-feature) behavior. Capture: route, user action, observed outcome, console errors if any. This is the baseline. 4. Apply the code change. Rely on HMR where available; otherwise rebuild. 5. Re-run the exact same flow in the browser. Capture the new observed outcome. 6. Check adjacent routes you touched — if you edited a shared component or route guard, visit at least one other page that depends on it. 7. Inspect the browser console for new warnings / errors introduced by your change (React hydration mismatches, missing keys, uncaught promise rejections, CloudBase SDK init errors, etc.). New noise is a regression even if the happy path works.

What to record in the final summary

For each flow you exercised, report:

• Route — e.g. /login, /dashboard?tab=usage
• Action — e.g. "Submitted the phone+code form with a valid code"
• Expected — e.g. "Redirect to /dashboard and show user's nickname"
• Before — e.g. "Stayed on /login; console showed auth/invalid-session"
• After — e.g. "Redirected to /dashboard; nickname rendered; no new console errors"
• Gap (if any) — e.g. "Did not test WeChat login branch because no test account available"

A one-liner like "tested in browser, works" is not acceptable evidence.

Common CloudBase-specific flows worth validating

• Auth: sign-in page → success → protected route accessible; sign-out → same protected route redirects to /login.
• AI model: eligibility gate passes → generateText returns text → streamText incrementally updates UI → error path (invalid model name) surfaces a user-visible message, not a silent failure.
• Database queries: list page with pagination → empty state → after create, the new row appears without a hard refresh.
• Static hosting deploy: for a deployed build, confirm the root route, one sub-route (refresh directly on it — hash vs history matters), and one 404 route.

Common mistakes to avoid

• Claiming a frontend bug is fixed without actually opening the browser.
• Verifying only the happy path when the reported bug is about empty states, validation errors, or route refresh.
• Catching and swallowing console errors instead of understanding them.
• Using agent-browser for aesthetic / visual direction work that should have gone through ui-design.
• Skipping the adjacent-routes check after editing a shared component or route guard.
• Using an old cached dev-server instance after a config change — restart the dev server if you modified vite.config.*, env vars, or TS path aliases.

Escalation

If you cannot complete browser validation because of missing credentials, a missing backend, a paid external API, or a blocker in the local environment, do not paper over it. State exactly what you were unable to verify and what the user needs to supply. Partial verification with a named gap is acceptable; silent omission is not.

Framework Guidance

React

• Follow the existing router, data-fetching, and component patterns already used by the repo.
• Prefer focused page and component changes over broad refactors.
• Keep state close to where it is used unless the project already relies on shared state primitives.
• For form, navigation, and async UI bugs, verify the behavior in browser after code changes.

Vue

• Respect the existing composition style in the repo, such as Composition API or Options API.
• Keep template, script, and style responsibilities clear instead of mixing unrelated logic into one large SFC.
• When changing reactive state or watchers, verify the actual rendered behavior rather than assuming the code path is enough.

Vite

• Treat Vite as the default choice for new Web app setup unless the repo already standardizes on another bundler.
• Keep environment-specific values in .env or the project's existing config pattern instead of hardcoding them into UI files.
• Check route base paths, asset paths, and build output behavior before deployment.

Routing and build defaults

• Use the existing router if present; do not switch routing libraries without an explicit requirement.
• For purely static hosting environments, prefer hash routing when server rewrite support is absent or unknown.
• Make build and preview commands explicit before handing off deployment steps.