vike-skills

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Vike Skills (Vue)

Vike技能（Vue版）

Core principle: Build fast, SEO-friendly Vue applications with server-side rendering using Vike's flexible architecture.

核心原则： 借助Vike灵活的架构，构建快速、对SEO友好的Vue服务端渲染应用。

When to Use This Skill

何时使用该技能

Always use when:

Creating new Vike + Vue pages
Setting up data fetching with
```
+data
```
hooks
Configuring layouts and nested layouts
Implementing route guards and authentication
Managing head tags and SEO
Working with client-only components

Don't use for:

Non-Vike Vue applications (use Nuxt or plain Vue)
React or Solid projects (use vike-react or vike-solid)

建议始终使用的场景：

创建新的Vike + Vue页面
通过
```
+data
```
钩子设置数据获取逻辑
配置布局与嵌套布局
实现路由守卫与身份验证
管理页面头部标签与SEO
开发仅客户端组件

不建议使用的场景：

非Vike架构的Vue应用（请使用Nuxt或原生Vue）
React或Solid项目（请使用vike-react或vike-solid）

Documentation Quick Links

文档快速链接

reference.md - Official API documentation links
examples.md - Vue + Vike patterns and code examples
Official Vike Docs - https://vike.dev

reference.md - 官方API文档链接
examples.md - Vue + Vike模式与代码示例
官方Vike文档 - https://vike.dev

Development Checklist

开发检查清单

When creating a new page, use TodoWrite to track:

Create
```
+Page.vue
```
component
Add
```
+data.js
```
if page needs data fetching
Use
```
useData()
```
to access data in component
Add
```
+guard.js
```
if page requires authentication
Configure head tags (
```
+title
```
,
```
+description
```
) for SEO
Handle errors with
```
throw render()
```
or
```
throw redirect()
```
Use
```
clientOnly()
```
for browser-only components

创建新页面时，可使用TodoWrite跟踪以下事项：

创建
```
+Page.vue
```
组件
若页面需要数据获取，添加
```
+data.js
```
在组件中使用
```
useData()
```
访问数据
若页面需身份验证，添加
```
+guard.js
```
配置页面头部标签（
```
+title
```
、
```
+description
```
）以优化SEO
通过
```
throw render()
```
或
```
throw redirect()
```
处理错误
对仅浏览器端组件使用
```
clientOnly()
```

Essential Requirements

基本要求

Every Page Must Have

每个页面必须包含

+Page.vue
component - The page's Vue component
Proper data access - Use
```
useData()
```
not direct pageContext
Error handling - Handle missing data gracefully
SEO consideration - Title and description for public pages

+Page.vue
组件 - 页面的Vue组件
正确的数据访问方式 - 使用
```
useData()
```
而非直接访问pageContext
错误处理 - 优雅处理数据缺失的情况
SEO考量 - 公开页面需设置标题与描述

Every Data Hook Must Have

每个数据钩子必须包含

Type exports -

export type Data = Awaited<ReturnType<typeof data>>

Error handling - Use
```
throw render(404)
```
for missing resources
Minimal data - Only return what the page needs (auto-serialized)

类型导出 -

export type Data = Awaited<ReturnType<typeof data>>

错误处理 - 对缺失的资源使用
```
throw render(404)
```
最小化数据返回 - 仅返回页面所需数据（会自动序列化）

Every Layout Must Have

每个布局必须包含

Children slot -
```
<slot />
```
to render nested content
Proper scoping - Place in correct directory for inheritance
No data fetching assumptions - Layouts share page's
```
+data
```

子元素插槽 - 使用
```
<slot />
```
渲染嵌套内容
正确的作用域 - 放置在正确的目录以实现继承
不预设数据获取逻辑 - 布局共享页面的
```
+data
```
数据

Every Guard Must Have

每个路由守卫必须包含

Clear conditions - Check auth state before render

Proper redirects - Use

throw redirect('/login')

throw render(401)

Async support - Guards can be async for API checks

清晰的条件判断 - 渲染前检查认证状态

正确的重定向 - 使用

throw redirect('/login')

或

throw render(401)

异步支持 - 守卫可支持异步操作以调用API检查

Core Patterns

核心模式

Basic Page with Data

带数据的基础页面

vue

<!-- /pages/movies/+Page.vue -->
<script setup lang="ts">
import { useData } from 'vike-vue/useData'
import type { Data } from './+data'

const { movies } = useData<Data>()
</script>

<template>
  <h1>Movies</h1>
  <ul>
    <li v-for="movie in movies" :key="movie.id">
      {{ movie.title }}
    </li>
  </ul>
</template>

typescript

// /pages/movies/+data.ts
export type Data = Awaited<ReturnType<typeof data>>

export async function data() {
  const movies = await fetchMovies()
  return { movies }
}

vue

<!-- /pages/movies/+Page.vue -->
<script setup lang="ts">
import { useData } from 'vike-vue/useData'
import type { Data } from './+data'

const { movies } = useData<Data>()
</script>

<template>
  <h1>Movies</h1>
  <ul>
    <li v-for="movie in movies" :key="movie.id">
      {{ movie.title }}
    </li>
  </ul>
</template>

typescript

// /pages/movies/+data.ts
export type Data = Awaited<ReturnType<typeof data>>

export async function data() {
  const movies = await fetchMovies()
  return { movies }
}

Layout

布局示例

vue

<!-- /pages/+Layout.vue -->
<script setup>
import Navigation from '../components/Navigation.vue'
</script>

<template>
  <Navigation />
  <main>
    <slot />
  </main>
</template>

vue

<!-- /pages/+Layout.vue -->
<script setup>
import Navigation from '../components/Navigation.vue'
</script>

<template>
  <Navigation />
  <main>
    <slot />
  </main>
</template>

Route Guard

路由守卫示例

typescript

// /pages/admin/+guard.ts
import { redirect } from 'vike/abort'

export async function guard(pageContext) {
  if (!pageContext.user) {
    throw redirect('/login')
  }
  if (!pageContext.user.isAdmin) {
    throw render(403, 'Admin access required')
  }
}

typescript

// /pages/admin/+guard.ts
import { redirect } from 'vike/abort'

export async function guard(pageContext) {
  if (!pageContext.user) {
    throw redirect('/login')
  }
  if (!pageContext.user.isAdmin) {
    throw render(403, 'Admin access required')
  }
}

File Naming Conventions

文件命名规范

File	Purpose
`+Page.vue`	Page component
`+Layout.vue`	Layout wrapper
`+data.ts`	Server-side data fetching
`+guard.ts`	Route protection
`+config.ts`	Page/directory configuration
`+title.ts`	Page title
`+Head.vue`	Custom head tags

文件	用途
`+Page.vue`	页面组件
`+Layout.vue`	布局容器
`+data.ts`	服务端数据获取
`+guard.ts`	路由保护
`+config.ts`	页面/目录配置
`+title.ts`	页面标题设置
`+Head.vue`	自定义页面头部标签

File Suffixes

文件后缀说明

Suffix	Runs On
`.server.ts`	Server only (default for +data)
`.client.ts`	Client only
`.shared.ts`	Both server and client

后缀	运行环境
`.server.ts`	仅服务端（+data默认使用）
`.client.ts`	仅客户端
`.shared.ts`	服务端与客户端均可运行

Red Flags - Stop If You See

警示信号——遇到以下情况请停止操作

Accessing
```
window
```
or
```
document
```
in SSR code without
```
clientOnly()
```
Missing
```
passToClient
```
for server data needed on client
Data fetching inside Vue components (use
```
+data
```
instead)
Hardcoded URLs instead of using routing
Missing error handling in
```
+data
```
hooks
Guards that don't
```
throw
```
(they must throw, not return)
Layouts without
```
<slot />
```
for children

在SSR代码中未使用
```
clientOnly()
```
就访问
```
window
```
或
```
document
```
客户端所需的服务端数据未添加到
```
passToClient
```
在Vue组件内部进行数据获取（请使用
```
+data
```
替代）
使用硬编码URL而非路由机制
```
+data
```
钩子中缺少错误处理
路由守卫未抛出异常（必须抛出
```
redirect()
```
或
```
render()
```
，而非返回值）
布局中未包含
```
<slot />
```
以渲染子内容

Common Rationalizations

常见误区纠正

Excuse	Reality
"I'll add SEO later"	Missing titles hurt from day one
"Guards can return false"	Guards must `throw redirect()` or `throw render()`
"I can access window in +data"	`+data` runs on server by default
"pageContext has everything"	Use `useData()` for type-safe data access

借口	实际情况
"我之后再添加SEO内容"	缺失页面标题从上线第一天就会影响效果
"路由守卫可以返回false"	路由守卫必须抛出 `throw redirect()` 或 `throw render()`
"我可以在+data中访问window"	`+data` 默认在服务端运行
"pageContext包含所有内容"	请使用 `useData()` 进行类型安全的数据访问

Configuration Inheritance

配置继承机制

Vike configs cascade down the directory tree:

pages/
  +config.ts          # Applies to ALL pages
  +Layout.vue         # Global layout
  (marketing)/
    +Layout.vue       # Nested inside global layout
    about/+Page.vue   # Has both layouts
  admin/
    +guard.ts         # Applies to all admin pages
    +config.ts        # Admin-specific config
    users/+Page.vue   # Protected by guard

Vike配置会沿目录树向下级联：

pages/
  +config.ts          # 应用于所有页面
  +Layout.vue         # 全局布局
  (marketing)/
    +Layout.vue       # 嵌套在全局布局内
    about/+Page.vue   # 同时应用两种布局
  admin/
    +guard.ts         # 应用于所有admin页面
    +config.ts        # 管理员专属配置
    users/+Page.vue   # 受路由守卫保护

passToClient Defaults

passToClient默认配置

With client routing, these are automatically available client-side:

```
pageContext.Page
```
```
pageContext.data
```
```
pageContext.config
```
```
pageContext.routeParams
```
```
pageContext.urlOriginal
```
```
pageContext.urlPathname
```
```
pageContext.urlParsed
```

For custom properties (like

user

), add to

+config.ts

typescript

export default {
  passToClient: ['user']
}

启用客户端路由时，以下内容会自动在客户端可用：

```
pageContext.Page
```
```
pageContext.data
```
```
pageContext.config
```
```
pageContext.routeParams
```
```
pageContext.urlOriginal
```
```
pageContext.urlPathname
```
```
pageContext.urlParsed
```

若需自定义属性（如

user

），请在

+config.ts

中添加：

typescript

export default {
  passToClient: ['user']
}

Quick Workflow

快速工作流

Need API details? → Check reference.md
Need examples? → Check examples.md
Building something? → Follow checklist above, use TodoWrite
Stuck? → Check official docs at https://vike.dev

需要API细节？ → 查看reference.md
需要示例？ → 查看examples.md
开发新功能？ → 遵循上述检查清单，使用TodoWrite跟踪
遇到问题？ → 查看官方文档https://vike.dev

Final Rule

最终规则

Every Vike + Vue page must have:
1. +Page.vue component
2. +data.ts for server data (if needed)
3. useData() for type-safe data access
4. Error handling for edge cases
5. SEO tags for public pages

Follow these principles for fast, SEO-friendly Vue applications.

每个Vike + Vue页面必须包含：
1. +Page.vue组件
2. 如需服务端数据，添加+data.ts
3. 使用useData()进行类型安全的数据访问
4. 针对边缘情况添加错误处理
5. 公开页面需配置SEO标签

遵循这些原则，构建快速、对SEO友好的Vue应用。