nuxtjs-vue-typescript

NuxtJS Vue TypeScript 开发

使用 TypeScript、Shadcn Vue、Radix Vue、VueUse 和 Tailwind 构建 Nuxt 3 与 Vue 3 应用的指南。

代码风格与结构

• 编写简洁、专业的 TypeScript，并提供准确的示例
• 使用组合式 API 和声明式模式；避免使用选项式 API
• 优先采用迭代和模块化，而不是重复代码
• 使用描述性变量名，并搭配辅助动词（isLoading、hasError）
• 组织文件：导出的组件、组合式函数、辅助函数、静态内容、类型
• 明确组件边界——一个组件应负责一块 UI 或一种行为；当逻辑超出简单的模板辅助功能时，提取组合式函数

命名约定

• 目录：小写并使用连字符分隔（components/auth-wizard）
• 组件：PascalCase（AuthWizard.vue）
• 组合式函数：camelCase（useAuthState.ts）

TypeScript 用法

• 全程使用 TypeScript；优先使用类型而不是接口，但如果预期某种结构会被扩展或实现（例如组件属性约定），则使用接口
• 共享类型应放在所属功能附近；只有当第二个功能也需要某个类型时，才将其移至共享的 types/ 目录
• 避免使用枚举；改用 const 对象
• 使用 Vue 3 与 TypeScript、defineComponent 和 PropType

语法与格式

• 方法和计算属性使用箭头函数
• 条件语句尽量减少花括号
• 使用模板语法进行声明式渲染

UI 与样式

• 使用 Shadcn Vue、Radix Vue 和 Tailwind
• 采用移动端优先的 Tailwind 方法进行响应式设计
• Tailwind 的使用应兼顾可访问性，并与项目的设计系统保持一致，避免堆砌零散的工具类

性能

• 利用 Nuxt 内置的优化功能
• 使用 Suspense 处理异步组件
• 为路由和组件实现懒加载
• 优化图片：使用 WebP 格式、调整图片大小、启用懒加载
• 定期检查打包体积（nuxi analyze），并对体积较大且很少使用的组件采用动态 import()

主要约定

• 使用 VueUse 提供的常见组合式函数——在它们能简化响应式逻辑时优先考虑，但避免使用会隐藏你需要明确理解的状态转换的函数
• 使用 Pinia 进行状态管理
• 优化 Web Vitals（LCP、CLS、FID）
• 使用 Nuxt 的自动导入功能

Nuxt 专属指南

• 遵循 Nuxt 3 目录结构（pages/、components/、composables/、layouts/、plugins/、server/）
• 使用自动导入、基于文件的路由、服务端路由和插件
• 使用布局（layouts/default.vue、<NuxtLayout>）共享页面框架，而不是在每个页面中重复编写
• 使用 server/api/ 路由（Nitro）处理服务端端点，并使用 useRuntimeConfig() 管理特定于环境的配置，而不是硬编码值
• 使用 useFetch 和 useAsyncData 获取数据
• 使用 useHead 和 useSeoMeta 实现 SEO

Vue 3 组合式 API 最佳实践

• 使用 <script setup> 语法
• 使用 ref、reactive 和 computed
• 使用 provide/inject 实现依赖注入
• 为可复用逻辑创建自定义组合式函数