web-development

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

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)

当你需要进行以下操作时，在Web前端项目开发中使用此技能：

开发Web前端页面与界面
将静态网站部署到CloudBase静态托管
集成CloudBase Web SDK以实现数据库、云函数和认证功能
搭建现代化前端构建系统（Vite、Webpack等）
处理静态托管的路由与构建配置

请勿用于：

小程序开发（使用miniprogram-development技能）
后端服务开发（使用cloudrun-development技能）
仅UI设计（使用ui-design技能，可与此技能结合使用）

How to use this skill (for a coding agent)

如何使用此技能（针对编码Agent）

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.)
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
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

遵循项目结构约定
- 前端源代码放在
```
src
```
  目录
- 构建输出放在
```
dist
```
  目录
- 云函数放在
```
cloudfunctions
```
  目录
- 使用现代化前端构建系统（如Vite）
正确使用CloudBase Web SDK
- 始终使用SDK内置的认证功能
- 切勿在云函数中实现登录逻辑
- 使用
```
envQuery
```
  工具获取环境ID
正确部署与预览
- 先构建项目（确保已执行
```
npm install
```
  ）
- ```
publicPath
```
  配置使用相对路径
- 使用哈希路由以获得更好的静态托管兼容性
- 如果用户未指定根目录，部署到子目录

Web Frontend Development Rules

Web前端开发规范

Project Structure

项目结构

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
Build System:
- Projects should use modern frontend build systems like Vite
- Install dependencies via npm
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

目录组织:
- 前端源代码应存储在
```
src
```
  目录
- 构建输出应放在
```
dist
```
  目录
- 云函数应放在
```
cloudfunctions
```
  目录
构建系统:
- 项目应使用Vite等现代化前端构建系统
- 通过npm安装依赖
路由:
- 如果前端项目涉及路由，默认使用哈希路由
- 哈希路由可解决刷新404问题，更适合静态网站托管部署

Deployment and Preview

部署与预览

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
Local Preview:
- To preview static web pages locally, navigate to the specified output directory and use
```
npx live-server
```
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静态托管
- 先启动本地预览，再确认用户是否需要部署到CloudBase静态托管
- 部署时，若用户无特殊要求，一般不直接部署到根目录
- 以Markdown链接格式返回部署地址
本地预览:
- 要在本地预览静态网页，导航到指定输出目录并使用
```
npx live-server
```
公共路径配置:
- 当Web项目部署到静态托管CDN时，由于路径无法提前知晓，
```
publicPath
```
  及类似配置应使用相对路径而非绝对路径
- 这可解决资源加载问题

CloudBase Web SDK Usage

CloudBase Web SDK 使用规范

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
    
  // Collect user's phone number into variable `phoneNum` by providing a input UI

  // Send SMS code
  const verificationInfo = await auth.getVerification({
    phone_number: `+86 ${phoneNum}`,
  });
  
  // Collect user's phone number into variable `verificationCode` by providing a input UI 
  
  // Sign in
  await auth.signInWithSms({
    verificationInfo,
    verificationCode,
    phoneNum,
  });
}

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

SDK集成:
- 如果用户项目需要数据库、云函数等功能，需在Web应用中引入
```
@cloudbase/js-sdk@latest
```

重要提示：认证必须使用SDK内置功能。严禁使用云函数实现登录认证逻辑！

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

const app = cloudbase.init({
  env: "xxxx-yyy", // 可通过envQuery工具查询环境ID
});
const auth = app.auth();

// 检查当前登录状态
let loginState = await auth.getLoginState();

if (loginState && loginState.user) {
  // 已登录
  const user = await auth.getCurrentUser();
  console.log("Current user:", user);
} else {
  // 未登录 - 使用SDK内置认证功能
    
  // 通过提供输入UI将用户手机号收集到变量`phoneNum`中

  // 发送短信验证码
  const verificationInfo = await auth.getVerification({
    phone_number: `+86 ${phoneNum}`,
  });
  
  // 通过提供输入UI将用户验证码收集到变量`verificationCode`中
  
  // 登录
  await auth.signInWithSms({
    verificationInfo,
    verificationCode,
    phoneNum,
  });
}

初始化规则（Web端，@cloudbase/js-sdk）：

始终使用上述模式进行同步初始化
请勿使用
```
import("@cloudbase/js-sdk")
```
懒加载SDK
请勿将SDK初始化包装在
```
initCloudBase()
```
等带有内部
```
initPromise
```
缓存的异步工具中
在前端应用中保持单个共享的
```
app
```
/
```
auth
```
实例；复用该实例而非重新初始化

Web SDK API usage rules

Web SDK API 使用规则

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

仅使用官方文档中记录的CloudBase Web SDK方法
在调用
```
app
```
、
```
auth
```
、
```
db
```
或其他SDK对象的任何方法前，确认该方法存在于CloudBase Web SDK官方文档中
如果某方法或选项未在官方文档中提及（例如某些猜测的方法名），请勿自创或使用

Authentication Best Practices

认证最佳实践

Must use SDK built-in authentication: CloudBase Web SDK provides complete authentication features, including login by SMS, anonymous login, custom login, etc.
Forbidden to implement login using cloud functions: Do not create cloud functions to handle login logic, this is the wrong approach
User data management: After login, user information can be obtained via
```
auth.getCurrentUser()
```
, then stored to database
Error handling: All authentication operations should include complete error handling logic

必须使用SDK内置认证：CloudBase Web SDK提供完整的认证功能，包括短信登录、匿名登录、自定义登录等。
禁止使用云函数实现登录：请勿创建云函数处理登录逻辑，这是错误的做法
用户数据管理：登录后，可通过
```
auth.getCurrentUser()
```
获取用户信息，再存储到数据库
错误处理：所有认证操作都应包含完整的错误处理逻辑

Build Process

构建流程

Web project build process: Ensure

npm install

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

Web项目构建流程：确保已先执行

npm install

命令，再参考项目文档进行构建