When to use this skill

Use this skill for Web frontend project development when you need to:

• Develop web frontend pages and interfaces
• Deploy static websites to CloudBase static hosting
• Integrate CloudBase Web SDK for database, cloud functions, and authentication
• Set up modern frontend build systems (Vite, Webpack, etc.)
• Handle routing and build configurations for static hosting

Do NOT use for:

• Mini-program development (use miniprogram-development skill)
• Backend service development (use cloudrun-development skill)
• UI design only (use ui-design skill, but may combine with this skill)

---

How to use this skill (for a coding agent)

1. Follow project structure conventions

   • Frontend source code in

     src

     directory
   • Build output in

     dist

     directory
   • Cloud functions in

     cloudfunctions

     directory
   • Use modern frontend build systems (Vite, etc.)

2. Use CloudBase Web SDK correctly

   • Always use SDK built-in authentication features
   • Never implement login logic in cloud functions
   • Use

     envQuery

     tool to get environment ID

3. Deploy and preview properly

   • Build project first (ensure

     npm install

     is executed)
   • Use relative paths for

     publicPath

     configuration
   • Use hash routing for better static hosting compatibility
   • Deploy to subdirectory if user doesn't specify root directory

---

Web Frontend Development Rules

Project Structure

1. Directory Organization:

   • Frontend source code should be stored in

     src

     directory
   • Build output should be placed in

     dist

     directory
   • Cloud functions should be in

     cloudfunctions

     directory

2. Build System:

   • Projects should use modern frontend build systems like Vite
   • Install dependencies via npm

3. Routing:

   • If the frontend project involves routing, use hash routing by default
   • Hash routing solves the 404 refresh issue and is more suitable for static website hosting deployment

Deployment and Preview

1. Static Hosting Deployment:

   • For frontend projects, after building, you can use CloudBase static hosting
   • First start local preview, then confirm with user if deployment to CloudBase static hosting is needed
   • When deploying, if user has no special requirements, generally do not deploy directly to root directory
   • Return deployed address in markdown link format

2. Local Preview:

   • To preview static web pages locally, navigate to the specified output directory and use

     npx live-server

3. Public Path Configuration:

   • When web projects are deployed to static hosting CDN, since paths cannot be known in advance,

     publicPath

     and similar configurations should use relative paths instead of absolute paths
   • This solves resource loading issues

CloudBase Web SDK Usage

1. SDK Integration:
   • If user's project needs database, cloud functions, and other features, need to introduce

     @cloudbase/js-sdk@latest

     in the web application

Important: Authentication must use SDK built-in features. It is strictly forbidden to implement login authentication logic using cloud functions!

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

const app = cloudbase.init({
  env: "xxxx-yyy", // Can query environment ID via envQuery tool
});
const auth = app.auth();

// Check current login state
let loginState = await auth.getLoginState();

if (loginState && loginState.user) {
  // Logged in
  const user = await auth.getCurrentUser();
  console.log("Current user:", user);
} else {
  // Not logged in - use SDK built-in authentication features
  // Method 1: Redirect to default login page (recommended)
  await auth.toDefaultLoginPage({});

  // Method 2: Anonymous login
  // await auth.signInAnonymously();
}

Initialization rules (Web, @cloudbase/js-sdk):

• Always use synchronous initialization with the pattern above
• Do not lazy-load the SDK with

  import("@cloudbase/js-sdk")

• Do not wrap SDK initialization in async helpers such as

  initCloudBase()

  with internal

  initPromise

  caches
• Keep a single shared

  app

  /

  auth

  instance in your frontend app; reuse it instead of re-initializing

Web SDK API usage rules

• Only use documented CloudBase Web SDK methods
• Before calling any method on

  app

  ,

  auth

  ,

  db

  , or other SDK objects, confirm it exists in the official CloudBase Web SDK documentation
• If a method or option is not mentioned in the official docs (for example some guessed method name), do NOT invent or use it

Local development proxy for default login page

When using

auth.toDefaultLoginPage()

in local development, you must proxy the

/__auth

path to your CloudBase Web hosting domain. For example, in a Vite + React project:

// vite.config.ts
import { defineConfig } from "vite";
import react from "@vitejs/plugin-react";

export default defineConfig({
  plugins: [react()],
  base: "./", // Use relative paths to avoid asset issues on static hosting
  server: {
    host: "127.0.0.1",
    proxy: {
      "/__auth": {
        target: "https://envId-appid.tcloudbaseapp.com/", // Replace with your CloudBase Web app domain
        changeOrigin: true,
      },
    },
    allowedHosts: true,
  },
});

The CloudBase Web hosting domain can be obtained via the CloudBase MCP

envQuery

tool (Static hosting config); in the response, use the value from the

StaticDomain

field.

In other dev servers/build tools (Webpack dev server, Next.js custom dev server, etc.), implement an equivalent proxy rule so that all

/__auth

requests are forwarded to the CloudBase domain during local development.

Authentication Best Practices

1. Must use SDK built-in authentication: CloudBase Web SDK provides complete authentication features, including default login page, anonymous login, custom login, etc.

2. Forbidden to implement login using cloud functions: Do not create cloud functions to handle login logic, this is the wrong approach

3. User data management: After login, user information can be obtained via

   auth.getCurrentUser()

   , then stored to database

4. Error handling: All authentication operations should include complete error handling logic

Build Process

Web project build process: Ensure

npm install

command has been executed first, then refer to project documentation for building