纯 JavaScript + JSDoc 开发 Vue 3…

在不用 TypeScript 的 Vue 3 项目中，用 JavaScript、Composition API 和 JSDoc 实现组件、composables、路由与状态管理。

适用场景

解决思路

1. 设计架构：规划组件结构和 composables，并为它们添加 JSDoc 类型注解。
2. 实现：使用 `<script setup>`（不要 `lang="ts"`），必要时使用 `.mjs` 模块。
3. 注解：添加完整 JSDoc 注释（`@typedef`、`@param`、`@returns`、`@type`）以实现完整类型覆盖；然后运行 ESLint 并启用 JSDoc 插件（`eslint-plugin-jsdoc`）验证覆盖率；在继续前修复任何缺失或格式错误的注解。
4. 测试：使用 JavaScript 文件通过 Vitest 验证；确认所有公共 API 的 JSDoc 覆盖率；如果测试失败，回到相关 composable 或组件，修正逻辑或注解，并重新运行直到测试套件通过。
5. 当处理 JSDoc 类型、`@typedef`、`@param`、类型提示时，加载 `references/jsdoc-typing.md`。
6. 当处理自定义 composables、`ref`、`reactive`、生命周期钩子时，加载 `references/composables-patterns.md`。
7. 当处理 props、emits、slots、provide/inject 时，加载 `references/component-architecture.md`。
8. 当处理 Pinia、stores、响应式状态时，加载 `references/state-management.md`。
9. 当处理 Vitest、组件测试、mocking 时，加载 `references/testing-patterns.md`。
10. 对于共享的 Vue 概念，改用 vue-expert 的 `../vue-expert/references/composition-api.md` 了解核心响应式模式。
11. 对于共享的 Vue 概念，改用 vue-expert 的 `../vue-expert/references/components.md` 了解 Props、emits、slots。
12. 对于共享的 Vue 概念，改用 vue-expert 的 `../vue-expert/references/state-management.md` 了解 Pinia stores。
13. 组件模式：在 `<script setup>` 中用 `@typedef` 定义 `UserCardProps`，用 `@property` 描述每个 prop 类型和可选默认值。
14. 组件模式：使用 `/** @type {UserCardProps} */` 标注 `defineProps` 结果。
15. 组件模式：用 `defineProps({...})` 声明运行时 props 类型、必填和默认值。
16. 组件模式：用 `@typedef` 定义 `UserCardEmits`，用函数类型描述事件签名。
17. 组件模式：用 `defineEmits(['select'])` 声明 emits。
18. 组件模式：给事件处理函数加 `/** @param {string} id */` 并调用 `emit('select', id)`。
19. 组件模式：在 template 中绑定 `@click="handleSelect(props.name)"` 并渲染 props。
20. Composable 模式：在 `composables/useCounter.mjs` 中从 `vue` 导入 `ref`、`computed`。
21. Composable 模式：用 `@typedef` 定义 `CounterState`，包含 `Ref<number>`、`ComputedRef<boolean>` 和方法。
22. Composable 模式：用 `@param` 标注 `initial` 和 `step` 默认值，用 `@returns {CounterState}` 标注返回。
23. Composable 模式：用 `/** @type {import('vue').Ref<number>} */` 标注 `count = ref(initial)`。
24. Composable 模式：用 `computed(() => count.value > 0)` 创建 `isPositive`。
25. Composable 模式：实现 `increment` 将 `count.value += step`，`reset` 将 `count.value = initial`。
26. Composable 模式：返回 `{ count, isPositive, increment, reset }`。
27. 跨文件复杂对象：在 `types/user.mjs` 中用 `@typedef` 定义 `User`，包含 `id`、`name`、`email`、`role`（`'admin'|'viewer'`）。
28. 跨文件复杂对象：在其他文件中通过 `/** @type {import('./types/user.mjs').User} */` 引用该类型。
29. MUST DO：使用 Composition API 搭配 `<script setup>`。
30. MUST DO：用 JSDoc 注释做类型文档。
31. MUST DO：需要时对 ES 模块使用 `.mjs` 扩展名。
32. MUST DO：为每个公共函数标注 `@param` 和 `@returns`。
33. MUST DO：跨文件共享的复杂对象结构使用 `@typedef`。
34. MUST DO：为响应式变量使用 `@type` 注解。
35. MUST DO：遵循 vue-expert 模式，并针对 JavaScript 调整。
36. MUST NOT DO：使用 TypeScript 语法（不要 `<script setup lang="ts">`）。
37. MUST NOT DO：使用 `.ts` 文件扩展名。
38. MUST NOT DO：省略公共 API 的 JSDoc 类型。
39. MUST NOT DO：在 Vue 文件中使用 CommonJS `require()`。
40. MUST NOT DO：完全忽略类型安全。
41. MUST NOT DO：在同一组件中混用 TypeScript 文件和 JavaScript。
42. 输出模板：组件文件使用 `<script setup>`（无 lang 属性），并带有 JSDoc 类型的 props/emits。
43. 输出模板：为复杂 prop 或 state 形状提供 `@typedef` 定义。
44. 输出模板：composable 带有 `@param` 和 `@returns` 注解。
45. 输出模板：附上一份简短的类型覆盖说明。
46. 知识栈：使用 Vue 3 Composition API、JSDoc、ESM modules、Pinia、Vue Router 4、Vite、VueUse、Vitest、Vue Test Utils、JavaScript ES2022+。

适用边界 · 注意事项

• 项目已使用或要求 TypeScript、`.ts` 文件、TS 编译器或强类型检查时。
• 技术栈不是 Vue 3（如 Vue 2 Options API 且不迁移、React、Svelte 等）时。
• 团队不接受 JSDoc 注解、不希望维护类型注释，或需要仅靠 TypeScript 提供的复杂类型能力时。