mcpField
N
nuxt-best-practices

nuxt-best-practices

github.com/vinayakkulkarni开发43305 次安装14 周前更新
代码仓库

关于 nuxt-best-practices

面向 Nuxt 应用开发者的性能与代码实践指南，包含 23 条按影响排序的规则，覆盖数据获取、渲染、服务端路由、状态管理和项目组织，并注明 Nuxt 3 与 4.5 相关事项。

主要功能

  1. 01九类共 23 条优先级规则
  2. 02数据获取与错误状态指导
  3. 03服务端路由和输入验证
  4. 04渲染与状态管理实践
  5. 05类型安全与项目组织
  6. 06性能和部署指导

适用场景

  1. 01审查新建的 Nuxt 页面与组件
  2. 02选择数据获取和渲染模式
  3. 03组织组合式函数、类型与自动导入
  4. 04检查服务端路由和部署设置

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/vinayakkulkarni/vue-nuxt-best-practices --skill nuxt-best-practices

安装后在 Claude Code 中输入/nuxt-best-practices确认已加载。

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

AGENTS.md
metadata.json
package.json
rules/
_sections.md
_template.md
data-conditional-enabled.md
data-error-handling.md
data-key-unique.md
data-transform.md
data-use-fetch.md
imports-component-naming.md
imports-composable-exports.md
imports-direct-composable-imports.md
imports-no-barrel-autoimport.md
imports-type-locations.md
pages-named-views.md
pages-nuxtlink-custom-prefetch.md
pages-use-layout.md
rendering-client-only.md
rendering-ssr-streaming.md
server-error-handling.md
server-route-meta.md
server-runtime-config.md
server-validated-input.md
state-use-state.md
types-import-paths.md
types-no-any.md
types-strict-emits.md
scripts/
build.ts
validate.ts

详细介绍

Nuxt 最佳实践

Nuxt 4 应用的全面性能优化指南（当前版本：Nuxt 4.5，附有针对即将结束生命周期的 3.x 应用的说明）。包含 9 个类别中的 23 条规则，按影响优先级排列，用于指导自动重构和代码生成。

适用场景

在以下情况下，请参考这些指南：

  • 编写新的 Nuxt 页面、组件或组合式函数
  • 实现数据获取（useFetch、useAsyncData、4.5 的 enabled 选项）
  • 创建服务端路由和 API 端点
  • 组织类型、组合式函数和自动导入
  • 使用 Nuxt 模块和插件
  • 配置渲染模式（SSR、SSG、SPA、4.5 实验性的 SSR 流式传输）
  • 使用布局、命名视图和 NuxtLink 预取（Nuxt 4.5 约定）

按优先级划分的规则类别

优先级类别影响前缀
1数据获取CRITICALdata-
2自动导入与组织CRITICALimports-
3服务端与 API 路由HIGHserver-
4渲染模式HIGHrendering-
5状态管理MEDIUM-HIGHstate-
6页面、布局与导航MEDIUMpages-
7类型安全MEDIUMtypes-
8模块与插件LOW-MEDIUMmodules-
9性能与部署LOWperf-

快速参考

1. 数据获取（CRITICAL）
  • data-use-fetch - 使用 useFetch/useAsyncData，切勿在组件中直接使用 fetch
  • data-key-unique - 始终为数据获取提供唯一键
  • data-lazy-loading - 对非关键数据使用 lazy 选项
  • data-transform - 在获取数据时转换数据，而不是在模板中转换
  • data-error-handling - 始终处理错误和待处理状态
  • data-refresh-patterns - 适当使用 refresh() 和 clear()
  • data-conditional-enabled - 使用 enabled 选项进行条件数据获取（4.5+）
2. 自动导入与组织（CRITICAL）
  • imports-no-barrel-autoimport - 切勿在自动导入目录中创建聚合导出
  • imports-component-naming - 组件名称中不要重复文件夹前缀
  • imports-type-locations - 将类型放在专用目录中（app/types、shared/types、server/types）
  • imports-composable-exports - 组合式函数只导出函数，不导出类型
  • imports-direct-composable-imports - 组合式函数之间使用直接导入
3. 服务端与 API 路由（HIGH）
  • server-validated-input - 使用带 Zod 的 getValidatedQuery/readValidatedBody
  • server-route-meta - 始终添加 defineRouteMeta，以生成 OpenAPI 文档
  • server-runtime-config - 使用 useRuntimeConfig，切勿使用 process.env
  • server-error-handling - 使用 createError，确保错误响应一致
  • server-middleware-order - 了解中间件的执行顺序
4. 渲染模式（HIGH）
  • rendering-route-rules - 使用 routeRules 按路由配置渲染方式
  • rendering-hybrid - 使用混合渲染，以获得最佳性能
  • rendering-prerender - 在构建时预渲染静态页面
  • rendering-client-only - 对浏览器专用组件使用 ClientOnly
  • rendering-ssr-streaming - 启用 SSR 流式传输前先了解其机制（4.5+，实验性）
5. 状态管理（MEDIUM-HIGH）
  • state-use-state - 使用 useState 管理 SSR 安全的共享状态
  • state-pinia-setup - 在 Nuxt 中正确配置 Pinia
  • state-hydration - 妥善处理水合不匹配
  • state-computed-over-watch - 派生状态优先使用 computed，而不是 watch
6. 页面、布局与导航（MEDIUM）
  • pages-use-layout - 使用 useLayout 读取解析后的布局（4.5+）
  • pages-named-views - 为命名视图使用 [email protected] 约定（4.5+）
  • pages-nuxtlink-custom-prefetch - 在 NuxtLink 自定义插槽中手动接入预取（4.5+）
7. 类型安全（中）
  • types-no-inline - 切勿在组件或组合式函数中内联定义类型
  • types-import-paths - 使用正确的导入路径（#shared、~/、~~/）
  • types-no-any - 切勿使用 any 类型
  • types-zod-schemas - 使用 Zod 进行运行时验证，并推断类型
  • types-strict-emits - 为 emits 完整定义类型；声明时使用 camelCase，监听时使用 kebab-case
8. 模块与插件（低-中）
  • modules-order - 模块在 nuxt.config 中的顺序很重要
  • modules-runtime-vs-build - 了解运行时模块与构建时模块的区别
  • plugins-client-server - 正确使用 .client.ts 和 .server.ts 后缀
  • plugins-provide-inject - 使用 provide/inject 处理横切关注点
9. 性能与部署（低）
  • perf-bundle-analysis - 分析并优化打包体积
  • perf-image-optimization - 使用 nuxt/image 优化图像
  • perf-font-loading - 配置字体加载策略
  • perf-caching-headers - 设置适当的缓存标头

使用方法

阅读各条规则文件，了解详细说明和代码示例：

rules/data-use-fetch.md
rules/imports-no-barrel-autoimport.md
rules/_sections.md

每个规则文件都包含：

  • 简要说明规则的重要性
  • 错误代码示例及说明
  • 正确代码示例及说明
  • 补充背景信息和 Nuxt 特定说明

完整汇编文档

如需查看包含所有规则完整内容的指南，请参阅：AGENTS.md

评论

支持 Markdown