Nuxt Project Standard

Nuxt 3 项目规范，涵盖目录结构、SSR/SSG、组合式 API、数据获取、路由、中间件、插件与模块。当用户在 Nuxt 3 项目中创建、修改页面或模块时自动激活。

Security Scan

This skill is an instruction-only Nuxt 3 styleguide and its requested resources and runtime instructions are consistent with that purpose.

Purpose & Capability

Name/description state a Nuxt 3 project standard; the skill is instruction-only and contains only guidelines about project structure, SSR/SSG, routing, middleware, plugins, and best practices. There are no unrelated requirements (no env vars, binaries, or config paths).

Instruction Scope

SKILL.md contains static coding guidelines and examples only — it does not instruct the agent to run shell commands, read files, access environment variables, or transmit data to external endpoints. Scope stays within the stated purpose of giving Nuxt 3 conventions.

Install Mechanism

No install spec and no code files are present; the skill is instruction-only so nothing is written to disk or installed during enablement.

Credentials

No environment variables, credentials, or config paths are requested. The lack of secrets is proportionate to a documentation/styleguide skill.

Persistence & Privilege

always is false and there is no request to modify other skills or agent-wide configuration. The skill can be invoked by the agent (platform default), which is appropriate for a helper that activates when editing Nuxt files.

Assessment

This skill is a static Nuxt 3 styleguide (no code or installers) and appears low-risk and coherent with its description. If you plan to enable it, confirm you actually work on Nuxt 3 + TypeScript projects so its automatic activation will be useful. As with any skill, watch for future versions that might add install steps or request credentials — those changes would require a fresh review.

Nuxt 3 项目规范

适用于使用 Nuxt 3 + Vue 3 + TypeScript 的仓库。

适用场景

• 新建或修改页面
• 配置 SSR / SSG（静态生成）
• 使用组合式 API、数据获取
• 路由、中间件、插件与模块

项目结构

├── app.vue                    # 根组件
├── nuxt.config.ts              # Nuxt 配置
│
├── pages/                     # 基于文件的路由
│   ├── index.vue               # /
│   ├── login.vue               # /login
│   ├── dashboard/
│   │   ├── index.vue           # /dashboard
│   │   └── users/
│   │       ├── index.vue       # /dashboard/users
│   │       └── [id].vue       # /dashboard/users/:id
│   └── [...slug].vue          # 捕获所有
│
├── layouts/                   # 布局
│   ├── default.vue
│   └── auth.vue
│
├── components/                # 自动导入组件
│   ├── Button/
│   │   └── Button.vue
│   └── AppHeader.vue
│
├── composables/               # 组合式函数（自动导入）
│   ├── useAuth.ts
│   └── useFetch.ts
│
├── server/                    # 服务端 API
│   ├── api/                   # API 路由
│   │   └── users/
│   │       └── index.get.ts
│   ├── middleware/            # 服务端中间件
│   └── utils/                 # 服务端工具
│
├── plugins/                   # 插件
│   └── i18n.client.ts
│
├── middleware/                # 路由中间件
│   └── auth.ts
│
├── public/                    # 静态资源
├── assets/                    # 需构建的资源
└── types/                     # 类型定义

渲染模式

模式	配置	说明
SSR	默认	ssr: true
SSG	nuxt generate	预渲染所有页面
SPA	ssr: false	纯客户端渲染

// nuxt.config.ts
export default defineNuxtConfig({
  ssr: true,  // 或 false
})

数据获取

• useFetch / useAsyncData：服务端 + 客户端，自动去重
• $fetch：直接请求，适合服务端或一次性调用
• useLazyAsyncData：不阻塞导航，适合非首屏
• 避免在 setup 顶层混用同步/异步逻辑导致水合不匹配

路由与布局

• pages/ 下文件自动生成路由
• 动态路由：[id].vue、[...slug].vue
• 布局：layout 选项或 layouts/default.vue 默认
• 嵌套路由：pages/parent/child.vue 需配合 NuxtPage

中间件

• middleware/ 下文件自动注册
• 页面级：definePageMeta({ middleware: ['auth'] })
• 全局：nuxt.config.ts 的 router.middleware
• 服务端中间件：server/middleware/

插件与模块

• 插件：plugins/*.ts，支持 .client、.server 后缀
• 模块：modules/ 或 node_modules，在 nuxt.config 中 modules: []

强约束

• 服务端可访问的代码不要依赖 window、document
• 使用 useState 共享状态时注意 SSR 序列化
• 图片使用 NuxtImg，链接使用 NuxtLink
• 避免在 setup 顶层使用 await 导致阻塞，优先用 useAsyncData / useFetch