JSDoc Documentation for Script Setup Components

JSDoc Documentation for Script Setup Components

Impact: MEDIUM - enables proper documentation for composition API components

<script setup> doesn't have an obvious place to attach JSDoc comments for the component itself. Use a dual-script pattern.

Problem

Incorrect:

<script setup lang="ts">
/**
 * This comment doesn't appear in IDE hover or docs
 * @component
 */
import { ref } from 'vue'

const count = ref(0)
</script>

JSDoc comments inside <script setup> don't attach to the component export because there's no explicit export statement.

Solution

Use both <script> and <script setup> blocks:

Correct:

<script lang="ts">
/**
 * A counter component that displays and increments a value.
 *
 * @example
 * ```vue
 * <Counter :initial="5" @update="handleUpdate" />
 * ```
 *
 * @component
 */
export default {}
</script>

<script setup lang="ts">
import { ref } from 'vue'

const props = defineProps<{
  /** Starting value for the counter */
  initial?: number
}>()

const emit = defineEmits<{
  /** Emitted when counter value changes */
  update: [value: number]
}>()

const count = ref(props.initial ?? 0)
</script>

How It Works

• The regular <script> block's default export is merged with <script setup>
• JSDoc on export default {} attaches to the component
• Props and emits JSDoc in <script setup> still work normally

What Gets Documented

Reference

• Vue Language Tools Discussion #5932