1---
2title: defineEmits Must Be Used at Top Level of script setup
3impact: HIGH
4impactDescription: Using defineEmits inside functions causes compilation errors - macros must be at module scope
5type: gotcha
6tags: [vue3, defineEmits, script-setup, macros, composition-api]
7---
8 
9# defineEmits Must Be Used at Top Level of script setup
10 
11**Impact: HIGH** - The `defineEmits()` macro can only be used directly within `<script setup>` at the top level. It cannot be placed inside functions, conditionals, or any other nested scope. Vue's compiler hoists these macros to module scope during compilation.
12 
13This applies to all Vue macros: `defineProps`, `defineEmits`, `defineExpose`, `defineOptions`, and `defineSlots`.
14 
15## Task Checklist
16 
17- [ ] Place `defineEmits()` directly in `<script setup>`, not inside functions
18- [ ] Do not wrap macro calls in conditionals or loops
19- [ ] Do not reference local variables in macro arguments
20- [ ] Store the emit function and reuse it throughout the component
21 
22## The Problem
23 
24**Incorrect - Inside a function:**
25```vue
26<script setup>
27function useEvents() {
28  // ERROR: defineEmits cannot be used inside a function
29  const emit = defineEmits(['submit', 'cancel'])
30  return emit
31}
32 
33const emit = useEvents() // This fails at compile time
34</script>
35```
36 
37**Incorrect - Inside a conditional:**
38```vue
39<script setup>
40if (someCondition) {
41  // ERROR: Cannot use defineEmits in conditional
42  const emit = defineEmits(['eventA'])
43} else {
44  const emit = defineEmits(['eventB'])
45}
46</script>
47```
48 
49**Incorrect - Referencing local variables:**
50```vue
51<script setup>
52const eventNames = ['submit', 'cancel']
53 
54// ERROR: Cannot reference local variables
55const emit = defineEmits(eventNames)
56</script>
57```
58 
59## Correct Usage
60 
61**Correct - Top level declaration:**
62```vue
63<script setup>
64// CORRECT: defineEmits at top level of script setup
65const emit = defineEmits(['submit', 'cancel', 'update'])
66 
67function handleSubmit() {
68  emit('submit', data)
69}
70 
71function handleCancel() {
72  emit('cancel')
73}
74</script>
75```
76 
77**Correct - With TypeScript types:**
78```vue
79<script setup lang="ts">
80// CORRECT: Type-based declaration at top level
81const emit = defineEmits<{
82  submit: [data: FormData]
83  cancel: []
84  'update:modelValue': [value: string]
85}>()
86 
87function handleSubmit(data: FormData) {
88  emit('submit', data)
89}
90</script>
91```
92 
93**Correct - Using constant arrays (compile-time constant):**
94```vue
95<script setup>
96// CORRECT: Literal array is fine
97const emit = defineEmits(['submit', 'cancel'])
98</script>
99```
100 
101## Why This Restriction Exists
102 
103Vue's compiler processes `<script setup>` macros at compile time, not runtime. The arguments must be statically analyzable so Vue can:
104 
1051. Generate the correct component options
1062. Provide TypeScript type inference
1073. Enable IDE support for event autocompletion
1084. Validate emitted events
109 
110Since the macro is hoisted out of `<script setup>` during compilation, it cannot access anything that only exists at runtime.
111 
112## Using emit in Composables
113 
114If you want to share emit logic in a composable, pass the emit function as an argument:
115 
116**Correct - Pass emit to composable:**
117```vue
118<script setup>
119const emit = defineEmits(['submit', 'cancel', 'validate'])
120 
121// Pass emit to composable
122const { handleSubmit, handleCancel } = useFormEvents(emit)
123</script>
124```
125 
126```js
127// composables/useFormEvents.js
128export function useFormEvents(emit) {
129  function handleSubmit(data) {
130    emit('submit', data)
131  }
132 
133  function handleCancel() {
134    emit('cancel')
135  }
136 
137  return { handleSubmit, handleCancel }
138}
139```
140 
141## ESLint Rule
142 
143The `eslint-plugin-vue` provides the `vue/valid-define-emits` rule that catches these errors:
144 
145```js
146// eslint.config.js
147export default [
148  {
149    rules: {
150      'vue/valid-define-emits': 'error'
151    }
152  }
153]
154```
155 
156This rule reports:
157- `defineEmits` used inside functions
158- `defineEmits` referencing local variables
159- Multiple `defineEmits` calls in the same component
160- `defineEmits` used outside `<script setup>`
161 
162## Reference
163- [Vue.js SFC script setup](https://vuejs.org/api/sfc-script-setup.html#defineprops-defineemits)
164- [ESLint vue/valid-define-emits](https://eslint.vuejs.org/rules/valid-define-emits)
165