nuxt-best-practices

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Nuxt Best Practices

Nuxt最佳实践

Comprehensive performance optimization guide for Nuxt 3/4 applications. Contains 40+ rules across 8 categories, prioritized by impact to guide automated refactoring and code generation.

针对Nuxt 3/4应用的全面性能优化指南。包含8个分类下的40+条规则，按影响优先级排序，可指导自动化重构与代码生成。

When to Apply

适用场景

Reference these guidelines when:

Writing new Nuxt pages, components, or composables
Implementing data fetching (useFetch, useAsyncData)
Creating server routes and API endpoints
Organizing types, composables, and auto-imports
Working with Nuxt modules and plugins
Configuring rendering modes (SSR, SSG, SPA)

在以下场景中参考本指南：

编写新的Nuxt页面、组件或组合式函数（composables）
实现数据获取逻辑（useFetch、useAsyncData）
创建服务端路由与API端点
组织类型定义、组合式函数与自动导入内容
开发Nuxt模块与插件
配置渲染模式（SSR、SSG、SPA）

Rule Categories by Priority

按优先级划分的规则分类


data-
imports-
server-
rendering-
state-
types-
modules-
perf-

Priority	Category	Impact	Prefix
1	Data Fetching	CRITICAL	`data-`
2	Auto-Imports & Organization	CRITICAL	`imports-`
3	Server & API Routes	HIGH	`server-`
4	Rendering Modes	HIGH	`rendering-`
5	State Management	MEDIUM-HIGH	`state-`
6	Type Safety	MEDIUM	`types-`
7	Modules & Plugins	LOW-MEDIUM	`modules-`
8	Performance & Deployment	LOW	`perf-`


data-
imports-
server-
rendering-
state-
types-
modules-
perf-

优先级	分类	影响程度	前缀
1	数据获取	关键	`data-`
2	自动导入与代码组织	关键	`imports-`
3	服务端与API路由	高	`server-`
4	渲染模式	高	`rendering-`
5	状态管理	中高	`state-`
6	类型安全	中	`types-`
7	模块与插件	中低	`modules-`
8	性能与部署	低	`perf-`

Quick Reference

快速参考

1. Data Fetching (CRITICAL)

1. 数据获取（关键）

```
data-use-fetch
```
- Use useFetch/useAsyncData, never raw fetch in components
```
data-key-unique
```
- Always provide unique keys for data fetching
```
data-lazy-loading
```
- Use lazy option for non-critical data
```
data-transform
```
- Transform data at fetch time, not in template
```
data-error-handling
```
- Always handle error and pending states
```
data-refresh-patterns
```
- Use refresh() and clear() appropriately

```
data-use-fetch
```
- 使用useFetch/useAsyncData，切勿在组件中直接使用原生fetch
```
data-key-unique
```
- 始终为数据获取提供唯一的key
```
data-lazy-loading
```
- 对非关键数据使用lazy选项
```
data-transform
```
- 在获取数据时进行转换，而非在模板中处理
```
data-error-handling
```
- 始终处理错误与加载状态
```
data-refresh-patterns
```
- 合理使用refresh()与clear()方法

2. Auto-Imports & Organization (CRITICAL)

2. 自动导入与代码组织（关键）

```
imports-no-barrel-autoimport
```
- Never create barrel exports in auto-imported directories
```
imports-component-naming
```
- Don't duplicate folder prefix in component names
```
imports-type-locations
```
- Place types in dedicated directories (app/types, shared/types, server/types)
```
imports-composable-exports
```
- Composables export functions only, not types
```
imports-direct-composable-imports
```
- Use direct imports between composables

```
imports-no-barrel-autoimport
```
- 切勿在自动导入目录中创建桶式导出（barrel exports）
```
imports-component-naming
```
- 组件名称中不要重复文件夹前缀
```
imports-type-locations
```
- 将类型定义放在专用目录中（app/types、shared/types、server/types）
```
imports-composable-exports
```
- 组合式函数仅导出函数，不导出类型
```
imports-direct-composable-imports
```
- 组合式函数之间使用直接导入

3. Server & API Routes (HIGH)

3. 服务端与API路由（高）

```
server-validated-input
```
- Use getValidatedQuery/readValidatedBody with Zod
```
server-route-meta
```
- Always add defineRouteMeta for OpenAPI docs
```
server-runtime-config
```
- Use useRuntimeConfig, never process.env
```
server-error-handling
```
- Use createError for consistent error responses
```
server-middleware-order
```
- Understand middleware execution order

```
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. Rendering Modes (HIGH)

4. 渲染模式（高）

```
rendering-route-rules
```
- Configure rendering per-route with routeRules
```
rendering-hybrid
```
- Use hybrid rendering for optimal performance
```
rendering-prerender
```
- Prerender static pages at build time
```
rendering-client-only
```
- Use ClientOnly for browser-specific components

```
rendering-route-rules
```
- 通过routeRules为单个路由配置渲染模式
```
rendering-hybrid
```
- 使用混合渲染以获得最优性能
```
rendering-prerender
```
- 在构建时预渲染静态页面
```
rendering-client-only
```
- 对浏览器专属组件使用ClientOnly

5. State Management (MEDIUM-HIGH)

5. 状态管理（中高）

```
state-use-state
```
- Use useState for SSR-safe shared state
```
state-pinia-setup
```
- Set up Pinia correctly with Nuxt
```
state-hydration
```
- Handle hydration mismatches properly
```
state-computed-over-watch
```
- Prefer computed over watch for derived state

```
state-use-state
```
- 使用useState实现支持SSR的共享状态
```
state-pinia-setup
```
- 正确在Nuxt中配置Pinia
```
state-hydration
```
- 妥善处理水合不匹配问题
```
state-computed-over-watch
```
- 优先使用computed而非watch处理派生状态

6. Type Safety (MEDIUM)

6. 类型安全（中）

```
types-no-inline
```
- Never define types inline in components/composables
```
types-import-paths
```
- Use correct import paths (#shared, ~/, ~~/)
```
types-no-any
```
- Never use
```
any
```
type
```
types-zod-schemas
```
- Use Zod for runtime validation with type inference
```
types-strict-emits
```
- Use kebab-case emits with full type definitions

```
types-no-inline
```
- 切勿在组件/组合式函数中内联定义类型
```
types-import-paths
```
- 使用正确的导入路径（#shared、~/、~~/）
```
types-no-any
```
- 切勿使用
```
any
```
类型
```
types-zod-schemas
```
- 使用Zod进行运行时验证并实现类型推断
```
types-strict-emits
```
- 使用短横线命名法（kebab-case）的emits并提供完整类型定义

7. Modules & Plugins (LOW-MEDIUM)

7. 模块与插件（中低）

```
modules-order
```
- Module order matters in nuxt.config
```
modules-runtime-vs-build
```
- Understand runtime vs build-time modules
```
plugins-client-server
```
- Use .client.ts and .server.ts suffixes correctly
```
plugins-provide-inject
```
- Use provide/inject for cross-cutting concerns

```
modules-order
```
- nuxt.config中的模块顺序至关重要
```
modules-runtime-vs-build
```
- 区分运行时模块与构建时模块
```
plugins-client-server
```
- 正确使用.client.ts与.server.ts后缀
```
plugins-provide-inject
```
- 使用provide/inject处理横切关注点

8. Performance & Deployment (LOW)

8. 性能与部署（低）

```
perf-bundle-analysis
```
- Analyze and optimize bundle size
```
perf-image-optimization
```
- Use nuxt/image for optimized images
```
perf-font-loading
```
- Configure font loading strategy
```
perf-caching-headers
```
- Set appropriate cache headers

```
perf-bundle-analysis
```
- 分析并优化包体积
```
perf-image-optimization
```
- 使用nuxt/image优化图片
```
perf-font-loading
```
- 配置字体加载策略
```
perf-caching-headers
```
- 设置合适的缓存头

How to Use

使用方法

Read individual rule files for detailed explanations and code examples:

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

Each rule file contains:

Brief explanation of why it matters
Incorrect code example with explanation
Correct code example with explanation
Additional context and Nuxt-specific notes

阅读单个规则文件以获取详细说明与代码示例：

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

每个规则文件包含：

规则重要性的简要说明
错误代码示例及解释
正确代码示例及解释
额外说明与Nuxt专属注意事项

Full Compiled Document

完整编译文档

For the complete guide with all rules expanded:

AGENTS.md

如需查看包含所有规则详情的完整指南，请参考：

AGENTS.md