inkreach-official-website/apps/website/.agents/skills/vue-debug-guides/reference/sfc-named-exports-forbidden.md

title, impact, impactDescription, type, tags

title	impact	impactDescription	type	tags
SFC Script Block Must Use Default Export Only	HIGH	Named exports in SFC script blocks will fail silently or cause build errors - Vue expects exactly one default export	gotcha	vue3 sfc export script-block composition-api

SFC Script Block Must Use Default Export Only

Impact: HIGH - Vue Single-File Components expect exactly one default export from the <script> block. Using named exports for your component will cause build failures or runtime errors because Vue's tooling is designed to process a single default-exported component definition per .vue file.

Task Checklist

• Always use export default in <script> blocks (Options API)
• Use <script setup> which handles exports automatically (Composition API)
• Move shared utilities to separate .js/.ts files, not the component's script block
• If you need to export types, use a separate <script> block alongside <script setup>

Problematic Code:

<!-- MyComponent.vue -->
<script>
// BAD: Named exports don't work for the component itself
export const MyComponent = {
  data() {
    return { count: 0 }
  }
}

// BAD: Exporting multiple things from component script
export const CONSTANT = 42
export function helper() { }
</script>

<template>
  <div>{{ count }}</div>
</template>

Correct Code:

<!-- MyComponent.vue - Options API -->
<script>
// GOOD: Single default export
export default {
  data() {
    return { count: 0 }
  }
}
</script>

<template>
  <div>{{ count }}</div>
</template>

<!-- MyComponent.vue - Composition API with script setup -->
<script setup>
// GOOD: No export needed, component is auto-exported
import { ref } from 'vue'

const count = ref(0)
</script>

<template>
  <div>{{ count }}</div>
</template>

Exporting Types Alongside Script Setup

For TypeScript, use a separate regular script block for type exports:

<script lang="ts">
// Regular script block for exports
export interface User {
  id: number
  name: string
}

export type Status = 'pending' | 'active' | 'inactive'
</script>

<script setup lang="ts">
// Setup script for component logic
import { ref } from 'vue'

const users = ref<User[]>([])
</script>

<template>
  <ul>
    <li v-for="user in users" :key="user.id">{{ user.name }}</li>
  </ul>
</template>

Sharing Utilities Across Components

Don't put shared code in component script blocks. Create separate files:

// utils/constants.ts
export const ITEMS_PER_PAGE = 20
export const API_BASE_URL = '/api/v1'

// utils/helpers.ts
export function formatDate(date: Date): string {
  return date.toLocaleDateString()
}

export function formatCurrency(amount: number): string {
  return `$${amount.toFixed(2)}`
}

<!-- ProductList.vue -->
<script setup>
// GOOD: Import shared utilities from external files
import { ITEMS_PER_PAGE } from '@/utils/constants'
import { formatCurrency } from '@/utils/helpers'
import { ref } from 'vue'

const products = ref([])
</script>

Why This Restriction Exists

Vue's SFC compiler and build tools expect:

1. One component per file: The .vue file format is designed for single-component definitions
2. Predictable structure: Tools like Volar, vue-tsc, and bundler plugins assume default export
3. Hot Module Replacement: HMR relies on the single-component-per-file convention

// How Vue tooling processes SFCs internally
import MyComponent from './MyComponent.vue'
// ^ Always expects the default export to be the component

Common Mistake: Reusing Code via SFC Exports

<!-- BAD PATTERN: Trying to reuse code from components -->
<script>
// This won't work as expected
export const sharedLogic = () => { ... }

export default {
  // component definition
}
</script>

Instead, use composables:

// composables/useSharedLogic.ts
export function useSharedLogic() {
  // Shared reactive logic
  const state = ref(0)
  const increment = () => state.value++

  return { state, increment }
}

<!-- ComponentA.vue -->
<script setup>
import { useSharedLogic } from '@/composables/useSharedLogic'

const { state, increment } = useSharedLogic()
</script>

Reference

• Vue.js SFC Specification
• Vue.js Composition API - Composables