Vue SFC Structure Specification

This specification applies to all

.vue

files in this project, focusing on constraining the organization order and responsibility layering of

script setup

Scope

File matching:
```
**/*.vue
```
.
Applicable objects: Vue single-file components using
```
<script setup>
```
.
Non-applicable objects: Pure template components without
```
<script setup>
```
or non-SFC writing methods.

Objectives

Make component script structures stable, predictable, and easy to scan.
Layer type definitions, reactive states, context providers, watchers, and lifecycle hooks to reduce back-and-forth reading.

script setup Order

Recommended order is as follows:

import statements
```
defineOptions
```
props type definitions or
```
import type
```
```
defineProps
```
emits type definitions or
```
import type
```
```
defineEmits
```
slots type definitions or
```
import type
```
```
defineSlots
```
hooks / composables initialization
Component business logic, grouped by semantics
Necessary
```
init
```
functions
Context provider
```
watch
```
/
```
watchEffect
```
Lifecycle hooks
```
defineExpose
```

Detailed Explanations

defineOptions

Place
```
defineOptions
```
as early as possible, usually right after imports.
Component
```
name
```
follows the project's existing naming conventions.

props / emits / slots Type Definitions

When the project has a
```
types.ts
```
convention, prioritize importing types from the sibling
```
types.ts
```
.
If the type is very simple, you can directly declare a small interface or tuple-style type in the current file.

defineProps / defineEmits / defineSlots

Do not pass variables when not in use, just use
```
defineXxx<Type>()
```
.
When access is needed in the script, use
```
const xxx = defineXxx<Type>()
```
.
Even if the
```
props
```
object is retained in the script, directly use the prop name in the template instead of writing
```
props.xxx
```
.

hooks / composables Initialization

Place initialization logic like
```
useRoute
```
and
```
useRouter
```
here.
This section only focuses on "acquiring capabilities" and "obtaining basic context", do not mix in a lot of business calculations.

Component Business Logic

Group by business semantics instead of mixing by API type.
Place related
```
ref
```
,
```
computed
```
, and functions as close to each other as possible.
For data that does not require deep reactivity such as objects, arrays, instance handles, etc., prioritize using
```
shallowRef
```
instead of
```
ref
```
.

Reactive Reference Selection

Use
```
ref
```
when you need to track primitive values or truly rely on reactive updates of deep properties.
If you only care about the overall replacement of
```
.value
```
and do not need automatic tracking of internal deep properties, prioritize using
```
shallowRef
```
.
Especially for values like objects, arrays, third-party instances, DOM handles, context state containers, etc., consider
```
shallowRef
```
by default.
Only continue to use
```
ref
```
when you need to rely on changes in object internal fields to trigger updates.

init Function

Only define
```
init
```
when there is indeed an initialization process.
Concentrate initialization logic into one function to avoid scattering it across multiple lifecycle hooks.

Context Provider

Place providers like
```
provideXxx
```
after business logic and before watchers and lifecycle hooks.
Prepare the data to be provided first, then inject uniformly, avoid interleaving state definitions before and after providers.

watch / watchEffect

Place
```
watch
```
and
```
watchEffect
```
after providers.
Do not introduce watchers unnecessarily; prioritize
```
computed
```
or direct event flows.

Lifecycle hooks

Place lifecycle hooks at the end of the script.
If
```
init()
```
exists, it is usually called here or in an equivalent creation phase to keep the initialization entry centralized.

defineExpose

Place
```
defineExpose
```
at the very end of the script.
Only use it when the component really needs to expose instance APIs.

Template Binding Functions

The implementation of functions bound to events, slot parameter callbacks, or attributes in the template must be written in
```
script setup
```
, or explicitly imported from outside before being referenced in the template.
Do not directly write inline arrow functions, anonymous functions, or function implementations carrying business logic in the template; the template only binds functions already defined in the script.
Allowed to pass parameters to functions defined in the script in the template, such as
```
@click="handleSelect(item.id)"
```
; not allowed to write inline implementations like
```
@click="() => handleSelect(item.id)"
```
.

attrs Inheritance

If the template has only one non-slot root tag and attrs should naturally fall on this root tag as a whole, do not set
```
inheritAttrs: false
```
, and do not write extra
```
useAttrs()
```
+
```
v-bind="attrs"
```
to pass through root attrs.
Prioritize using Vue's default attrs inheritance, allowing ordinary attrs passed by the caller to be automatically bound to the root tag, reducing boilerplate code and meaningless forwarding layers.
Only use
```
inheritAttrs: false
```
or manually consume
```
useAttrs()
```
in the following scenarios: need to split attrs into multiple nodes; need to filter or rewrite attrs; need to pass attrs to non-root nodes; need to explicitly read attrs in script logic; or the component itself is not a single root tag structure that can directly承接 attrs.

Others

If the component is very simple, do not force empty sections just to follow the order; the order is to enhance readability, not to create boilerplate code.

Inspection Checklist

Is
```
defineOptions
```
placed early enough?
Are props / emits / slots types paired with
```
defineProps
```
/
```
defineEmits
```
/
```
defineSlots
```
and in a stable order?
Are hooks initialization, business logic, providers, watchers, and lifecycle hooks clearly layered?
If the template is a single non-slot root tag that can承接 attrs, have unnecessary
```
inheritAttrs: false
```
and manual
```
useAttrs()
```
passing been avoided?
Are all functions bound in the template defined or imported in
```
script setup
```
instead of written as inline implementations?
Have
```
shallowRef
```
been prioritized for states that do not require deep reactivity?
Have unnecessary
```
init
```
, watchers, and
```
defineExpose
```
been retained just for formality?

Complete Example

The following example demonstrates the implementation of the above order and best practices in a typical component:

vue

<script setup lang="ts">
import { computed, onMounted, ref, shallowRef, watch } from 'vue';
import { useRoute, useRouter } from 'vue-router';
import type { OptionItem } from './types';
import { provideFilterContext } from './context';

// 1. defineOptions
defineOptions({ name: 'FilterPanel' });

// 2-3. props 类型定义 + defineProps
interface Props {
  modelValue: string;
  options: OptionItem[];
}
const props = defineProps<Props>();

// 4-5. emits 类型定义 + defineEmits
interface Emits {
  (e: 'update:modelValue', value: string): void;
  (e: 'change', value: OptionItem): void;
}
const emit = defineEmits<Emits>();

// 6. hooks / composables 初始化
const route = useRoute();
const router = useRouter();

// 7. 组件业务逻辑(按语义分块,shallowRef 用于不需要深层响应式的数据)
const listRef = shallowRef<OptionItem[]>(props.options);
const keyword = ref('');

const filtered = computed(() => {
  const kw = keyword.value.trim().toLowerCase();
  return kw ? listRef.value.filter(item => item.label.toLowerCase().includes(kw)) : listRef.value;
});

// 8. template 绑定的函数:在脚本中定义,模板只负责引用
function handleSelect(item: OptionItem) {
  emit('update:modelValue', item.value);
  emit('change', item);
}

// 9. init 函数(仅在确实存在初始化流程时)
function init() {
  const initial = route.query.keyword;
  if (typeof initial === 'string') {
    keyword.value = initial;
  }
}

// 10. context provider
provideFilterContext({ keyword, filtered });

// 11. watch / watchEffect(仅在必要时引入)
watch(keyword, value => {
  router.replace({ query: { ...route.query, keyword: value || undefined } });
});

// 12. 生命周期 hooks
onMounted(() => {
  init();
});

// 13. defineExpose(仅在需要暴露实例 API 时)
defineExpose({ reset: () => (keyword.value = '') });
</script>

<template>
  <div class="filter-panel">
    <input v-model="keyword" placeholder="搜索" />
    <ul>
      <li
        v-for="item in filtered"
        :key="item.value"
        @click="handleSelect(item)"
      >
        {{ item.label }}
      </li>
    </ul>
  </div>
</template>

Key Recap:

```
defineOptions
```
follows immediately after imports, followed by a stable order of props → emits → hooks → business logic → provider → watch → lifecycle.
```
listRef
```
, which does not require deep reactivity, uses
```
shallowRef
```
;
```
keyword
```
, which needs to track input values, uses
```
ref
```
.
The
```
@click="handleSelect(item)"
```
in the template references a function already defined in the script, no inline arrow functions are used.
With a single-root tag structure where attrs should fall on the root tag as a whole,
```
inheritAttrs: false
```
is not set.

vue-sfc-structure

NPX Install

Tags

SKILL.md Content (Chinese)