fec-nuxt-project-standard · diff

git:20260525.fbc4b04 to git:20260611.9d7f5e4

57 added, 57 removed. Audit A to A.

---
name: fec-nuxt-project-standard
description: Use when creating or reviewing Nuxt 3 projects, file routes, pages, layouts, SSR/SSG/SPA behavior, Nuxt data fetching, route middleware, plugins, modules, server routes, or Nuxt-specific Vue 3 conventions. For generic Vue component architecture, apply the project's Vue conventions separately; Chinese triggers include Nuxt, Nuxt 3.
---
- # Nuxt 3 项目规范
+ # Nuxt 3 Project Specifications
- 适用于使用 Nuxt 3 + Vue 3 + TypeScript 的仓库。
+ For repositories using Nuxt 3 + Vue 3 + TypeScript.
## Purpose
- 规范 Nuxt 3 项目中 SSR/SSG 渲染模式、组合式 API、自动导入、数据获取、路由中间件和模块插件的工程实践，确保约定式开发和类型安全。
+ Standardize the engineering practices of SSR/SSG rendering mode, combined API, automatic import, data acquisition, routing middleware and module plug-ins in the Nuxt 3 project to ensure conventional development and type safety.
## Procedure
- 1. 先识别目标属于 Nuxt pages/layouts、渲染模式、数据获取、route middleware、plugin/module 还是 server route。
- 2. 明确 SSR / SSG / SPA 选择，避免服务端可执行代码依赖 `window` 或 `document`。
- 3. 数据获取优先使用 Nuxt 的 `useFetch` / `useAsyncData`，并检查水合一致性。
- 4. 路由鉴权、redirect 和权限问题与路由保护 workflow 对齐。
- 5. 通用 Vue 组件架构问题分流到 Vue 项目 workflow。
+ 1. First identify whether the target belongs to Nuxt pages/layouts, rendering mode, data acquisition, route middleware, plugin/module or server route.
+ 2. Clarify SSR / SSG / SPA selection to avoid server-side executable code relying on `window` or `document`.
+ 3. For data acquisition, Nuxt’s `useFetch` / `useAsyncData` is used first, and the hydration consistency is checked.
+ 4. Route authentication, redirection and permission issues are aligned with the route protection workflow.
+ 5. Common Vue component architecture issues are offloaded to the Vue project workflow.
- ## 项目结构
+ ## Project structure
```
- ├── app.vue # 根组件
- ├── nuxt.config.ts # Nuxt 配置
+ ├── app.vue # Root component
+ ├── nuxt.config.ts # Nuxt configuration
│
- ├── pages/ # 基于文件的路由
+ ├── pages/ # File-based routing
│ ├── index.vue # /
│ ├── login.vue # /login
│ ├── dashboard/
│ │ ├── index.vue # /dashboard
│ │ └── users/
│ │ ├── index.vue # /dashboard/users
│ │ └── [id].vue # /dashboard/users/:id
- │ └── [...slug].vue # 捕获所有
+ │ └── [...slug].vue # Capture all
│
- ├── layouts/ # 布局
+ ├── layouts/ # layout
│ ├── default.vue
│ └── auth.vue
│
- ├── components/ # 自动导入组件
+ ├── components/ # Automatically import components
│ ├── Button/
│ │ └── Button.vue
│ └── AppHeader.vue
│
- ├── composables/ # 组合式函数（自动导入）
+ ├── composables/ # Combined functions (automatically imported)
│ ├── useAuth.ts
│ └── useFetch.ts
│
- ├── server/ # 服务端 API
- │ ├── api/ # API 路由
+ ├── server/ # Server API
+ │ ├── api/ # API routing
│ │ └── users/
│ │ └── index.get.ts
- │ ├── middleware/ # 服务端中间件
- │ └── utils/ # 服务端工具
+ │ ├── middleware/ # Server-side middleware
+ │ └── utils/ # Server-side tools
│
- ├── plugins/ # 插件
+ ├── plugins/ # Plug-in
│ └── i18n.client.ts
│
- ├── middleware/ # 路由中间件
+ ├── middleware/ # Routing middleware
│ └── auth.ts
│
- ├── public/ # 静态资源
- ├── assets/ # 需构建的资源
- └── types/ # 类型定义
+ ├── public/ # Static resources
+ ├── assets/ # Resources to be built
+ └── types/ # Type definition
```
- ## 渲染模式
+ ## Rendering mode
- | 模式 | 配置 | 说明 |
+ | Mode | Configuration | Description |
| ------- | --------------- | -------------- |
- | **SSR** | 默认 | `ssr: true` |
- | **SSG** | `nuxt generate` | 预渲染所有页面 |
- | **SPA** | `ssr: false` | 纯客户端渲染 |
+ | **SSR** | Default | `ssr: true` |
+ | **SSG** | `nuxt generate` | Pre-render all pages |
+ | **SPA** | `ssr: false` | Pure client-side rendering |
```ts
// nuxt.config.ts
export default defineNuxtConfig({
- ssr: true, // 或 false
+ ssr: true, // or false
});
```
- ## 数据获取
+ ## Data acquisition
- - `useFetch` / `useAsyncData`：服务端 + 客户端，自动去重
- - `$fetch`：直接请求，适合服务端或一次性调用
- - `useLazyAsyncData`：不阻塞导航，适合非首屏
- - 避免在 `setup` 顶层混用同步/异步逻辑导致水合不匹配
+ - `useFetch` / `useAsyncData`: server + client, automatic deduplication
+ - `$fetch`: direct request, suitable for server or one-time call
+ - `useLazyAsyncData`: does not block navigation, suitable for non-first screen
+ - Avoid mixing synchronous/asynchronous logic at the top level of `setup` causing hydration mismatch
- ## 路由与布局
+ ## Routing and layout
- - `pages/` 下文件自动生成路由
- - 动态路由：`[id].vue`、`[...slug].vue`
- - 布局：`layout` 选项或 `layouts/default.vue` 默认
- - 嵌套路由：`pages/parent/child.vue` 需配合 `NuxtPage`
+ - Automatically generate routes for files under `pages/`
+ - Dynamic routing: `[id].vue`, `[...slug].vue`
+ - Layout: `layout` option or `layouts/default.vue` default
+ - Nested routing: `pages/parent/child.vue` needs to be combined with `NuxtPage`
- ## 中间件
+ ## Middleware
- - `middleware/` 下文件自动注册
- - 页面级：`definePageMeta({ middleware: ['auth'] })`
- - 全局：`nuxt.config.ts` 的 `router.middleware`
- - 服务端中间件：`server/middleware/`
+ - Automatically register files under `middleware/`
+ - Page level: `definePageMeta({ middleware: ['auth'] })`
+ - Global: `router.middleware` of `nuxt.config.ts`
+ - Server-side middleware: `server/middleware/`
- ## 插件与模块
+ ## Plug-ins and modules
- - 插件：`plugins/*.ts`，支持 `.client`、`.server` 后缀
- - 模块：`modules/` 或 `node_modules`，在 `nuxt.config` 中 `modules: []`
+ - Plug-in: `plugins/*.ts`, supports `.client`, `.server` suffixes
+ - Modules: `modules/` or `node_modules`, in `nuxt.config` `modules: []`
## Constraints
- - 服务端可访问的代码不要依赖 `window`、`document`
- - 使用 `useState` 共享状态时注意 SSR 序列化
- - 图片使用 `NuxtImg`，链接使用 `NuxtLink`
- - 避免在 `setup` 顶层使用 `await` 导致阻塞，优先用 `useAsyncData` / `useFetch`
+ - Server-accessible code should not rely on `window` or `document`
+ - Be careful about SSR serialization when using `useState` to share state
+ - Use `NuxtImg` for images and `NuxtLink` for links
+ - Avoid using `await` at the top level of `setup` which will cause blocking. Use `useAsyncData` / `useFetch` first
## Expected Output
- - 页面按 `pages/` 约定式路由组织，动态路由正确配置
- - 渲染模式（SSR/SSG/SPA）选择正确，`nuxt.config.ts` 配置清晰
- - 数据获取使用 `useFetch` / `useAsyncData`，自动去重和水合
- - Composables 和组件自动导入正确，服务端/客户端边界清晰
+ - Pages are organized according to `pages/` conventional routing, and dynamic routing is correctly configured
+ - The rendering mode (SSR/SSG/SPA) is correctly selected and the `nuxt.config.ts` configuration is clear
+ - Data acquisition uses `useFetch` / `useAsyncData`, automatic deduplication and hydration
+ - Composables and components are automatically imported correctly, and the server/client boundary is clear