Activation Contract
Use this first when
- The request is for a CloudBase Web app, static hosting site, frontend page, or Web SDK integration.
Read before writing code if
- The task includes frontend structure, build config, deployment, routing, or Web SDK usage.
Then also read
- Login flow ->
../auth-tool/SKILL.md, then ../auth-web/SKILL.md
- UI work ->
../ui-design/SKILL.md first
- NoSQL / MySQL data work -> matching database skill
Do NOT use for
- Mini programs, native Apps, or container backend services.
Common mistakes / gotchas
- Treating cloud functions as the default solution for Web authentication.
- Starting UI implementation before reading
ui-design.
- Routing native App requests into Web SDK code paths.
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)
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
- Mention the official CDN early when the user needs a static HTML or no-build integration
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
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
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 Web SDK Usage
- SDK Integration:
- If user's project needs database, cloud functions, and other features, need to introduce
@cloudbase/js-sdk@latest in the web application
- Official CDN:
https://static.cloudbase.net/cloudbase-js-sdk/latest/cloudbase.full.js
- Prefer npm for React, Vue, Vite, Webpack, and other bundler-based projects
- Prefer the CDN only for static HTML pages, quick demos, embedded snippets, or README examples where a build step is unnecessary
CDN quick start (static HTML / no-build):
<script src="https://static.cloudbase.net/cloudbase-js-sdk/latest/cloudbase.full.js"></script>
<script>
const app = cloudbase.init({
env: "xxxx-yyy",
});
</script>
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
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
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
Build Process
Web project build process: Ensure npm install command has been executed first, then refer to project documentation for building
1---2name: web-development3description: Web frontend project development rules. Use this skill when developing web frontend pages, deploying static hosting, and integrating CloudBase Web SDK.4---5
6## Activation Contract
7
8### Use this first when
9
10- The request is for a CloudBase Web app, static hosting site, frontend page, or Web SDK integration.
11
12### Read before writing code if
13
14- The task includes frontend structure, build config, deployment, routing, or Web SDK usage.
15
16### Then also read
17
18- Login flow -> `../auth-tool/SKILL.md`, then `../auth-web/SKILL.md`
19- UI work -> `../ui-design/SKILL.md` first
20- NoSQL / MySQL data work -> matching database skill
21
22### Do NOT use for
23
24- Mini programs, native Apps, or container backend services.
25
26### Common mistakes / gotchas
27
28- Treating cloud functions as the default solution for Web authentication.
29- Starting UI implementation before reading `ui-design`.
30- Routing native App requests into Web SDK code paths.
31
32## When to use this skill
33
34Use this skill for **Web frontend project development** when you need to:
35
36- Develop web frontend pages and interfaces
37- Deploy static websites to CloudBase static hosting
38- Integrate CloudBase Web SDK for database, cloud functions, and authentication
39- Set up modern frontend build systems (Vite, Webpack, etc.)
40- Handle routing and build configurations for static hosting
41
42**Do NOT use for:**
43- Mini-program development (use miniprogram-development skill)
44- Backend service development (use cloudrun-development skill)
45- UI design only (use ui-design skill, but may combine with this skill)
46
47---
48
49## How to use this skill (for a coding agent)
50
511. **Follow project structure conventions**
52 - Frontend source code in `src` directory
53 - Build output in `dist` directory
54 - Cloud functions in `cloudfunctions` directory
55 - Use modern frontend build systems (Vite, etc.)
56
572. **Use CloudBase Web SDK correctly**
58 - Always use SDK built-in authentication features
59 - Never implement login logic in cloud functions
60 - Use `envQuery` tool to get environment ID
61 - Mention the official CDN early when the user needs a static HTML or no-build integration
62
633. **Deploy and preview properly**
64 - Build project first (ensure `npm install` is executed)
65 - Use relative paths for `publicPath` configuration
66 - Use hash routing for better static hosting compatibility
67 - Deploy to subdirectory if user doesn't specify root directory
68
69---
70
71# Web Frontend Development Rules
72
73## Project Structure
74
751. **Directory Organization**:
76 - Frontend source code should be stored in `src` directory
77 - Build output should be placed in `dist` directory
78 - Cloud functions should be in `cloudfunctions` directory
79
802. **Build System**:
81 - Projects should use modern frontend build systems like Vite
82 - Install dependencies via npm
83
843. **Routing**:
85 - If the frontend project involves routing, use hash routing by default
86 - Hash routing solves the 404 refresh issue and is more suitable for static website hosting deployment
87
88## Deployment and Preview
89
901. **Static Hosting Deployment**:
91 - For frontend projects, after building, you can use CloudBase static hosting
92 - First start local preview, then confirm with user if deployment to CloudBase static hosting is needed
93 - When deploying, if user has no special requirements, generally do not deploy directly to root directory
94 - Return deployed address in markdown link format
95
962. **Local Preview**:
97 - To preview static web pages locally, navigate to the specified output directory and use `npx live-server`
98
993. **Public Path Configuration**:
100 - 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
101 - This solves resource loading issues
102
103## CloudBase Web SDK Usage
104
1051. **SDK Integration**:
106 - If user's project needs database, cloud functions, and other features, need to introduce `@cloudbase/js-sdk@latest` in the web application
107 - Official CDN: `https://static.cloudbase.net/cloudbase-js-sdk/latest/cloudbase.full.js`
108 - Prefer npm for React, Vue, Vite, Webpack, and other bundler-based projects
109 - Prefer the CDN only for static HTML pages, quick demos, embedded snippets, or README examples where a build step is unnecessary
110
111**CDN quick start (static HTML / no-build)**:
112```html
113<script src="https://static.cloudbase.net/cloudbase-js-sdk/latest/cloudbase.full.js"></script>
114<script>
115const app = cloudbase.init({
116 env: "xxxx-yyy",
117});
118</script>
119```
120
121**Important: Authentication must use SDK built-in features. It is strictly forbidden to implement login authentication logic using cloud functions!**
122
123```js
124import cloudbase from "@cloudbase/js-sdk";
125
126const app = cloudbase.init({
127 env: "xxxx-yyy", // Can query environment ID via envQuery tool
128});
129const auth = app.auth();
130
131// Check current login state
132let loginState = await auth.getLoginState();
133
134if (loginState && loginState.user) {
135 // Logged in
136 const user = await auth.getCurrentUser();
137 console.log("Current user:", user);
138} else {
139 // Not logged in - use SDK built-in authentication features
140
141 // Collect user's phone number into variable `phoneNum` by providing a input UI
142
143 // Send SMS code
144 const verificationInfo = await auth.getVerification({
145 phone_number: `+86 ${phoneNum}`,
146 });
147
148 // Collect user's phone number into variable `verificationCode` by providing a input UI
149
150 // Sign in
151 await auth.signInWithSms({
152 verificationInfo,
153 verificationCode,
154 phoneNum,
155 });
156}
157```
158
159**Initialization rules (Web, @cloudbase/js-sdk):**
160
161- Always use **synchronous initialization** with the pattern above
162- Do **not** lazy-load the SDK with `import("@cloudbase/js-sdk")`
163- Do **not** wrap SDK initialization in async helpers such as `initCloudBase()` with internal `initPromise` caches
164- Keep a single shared `app`/`auth` instance in your frontend app; reuse it instead of re-initializing
165
166### Web SDK API usage rules
167
168- Only use **documented** CloudBase Web SDK methods
169- Before calling any method on `app`, `auth`, `db`, or other SDK objects, **confirm it exists in the official CloudBase Web SDK documentation**
170- If a method or option is **not** mentioned in the official docs (for example some guessed method name), **do NOT invent or use it**
171
172## Authentication Best Practices
173
1741. **Must use SDK built-in authentication**: CloudBase Web SDK provides complete authentication features, including login by SMS, anonymous login, custom login, etc.
175
1762. **Forbidden to implement login using cloud functions**: Do not create cloud functions to handle login logic, this is the wrong approach
177
1783. **User data management**: After login, user information can be obtained via `auth.getCurrentUser()`, then stored to database
179
1804. **Error handling**: All authentication operations should include complete error handling logic
181
182## Build Process
183
184**Web project build process**: Ensure `npm install` command has been executed first, then refer to project documentation for building