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