defineProps() JSDoc support

[shamrin]

Problem

defineProps() macro is mostly limited to types like String and Number in <script setup> blocks. It is limiting when the project avoids TypeScript syntax, but uses JSDoc for type annotations and type checks:

vue-tsc --noEmit --allowJs --checkJs

<!-- SomeComponent.vue -->
<script setup>
/** @type {import('vue').Ref<'simple' | 'advanced'>} */
const mode = ref('simple')

const props = defineProps({
  flag: { type: Boolean }
})

// mode.value and props.flag are type-safe
if (mode.value === 'simple' || props.flag) { /* ... */ }
</script>

The above works great, except for more non-basic types in defineProps() macro.

For example, I haven't found a good way to turn mode into a prop but keep the type safety. I have to relax mode type to a string:

<!-- SomeComponent.vue -->
<script setup>
const props = defineProps({
  flag: { type: Boolean }
  mode: { type: String, required: true },
})
</script>

Proposal

It would nice if Vue would allow the following:

<!-- SomeComponent.vue -->
<script setup>
/** @type {{ flag: boolean, mode: 'simple' | 'advanced' }} */
const props = defineProps()
</script>

Work-around

This is a work-around I found:

<!-- SomeComponent.vue -->
<script setup>
/** @type {{ flag: boolean, mode: 'simple' | 'advanced' }} */
// @ts-ignore
const props = defineProps(['flag', 'mode'])
</script>

It even seems to check types at the usage: <SomeComponent mode="simple">.

Related

• Manually annotating prop with JSDoc doesn't produce right type core#6854
• Allow component prop validation of 'Array of type' in javascript core#8804
• `defineProp` macro for single prop definition #513
• Allow to explicitly pass type parameters via JSDoc microsoft/TypeScript#27387 (comment)

[shamrin]

I've found an improvement to JSDoc / defineProps() work-around.

<!-- SomeComponent.vue -->

<script setup>
/** @type {{ flag: boolean, mode: 'simple' | 'advanced' }} */
const props = defineProps(['flag', 'mode']);
</script>

// vue.d.ts

// Augment vue types to work around Vue TypeScript JSDoc limitation, see https://github.com/vuejs/rfcs/discussions/584
import 'vue';

declare module 'vue' {
  // This makes TypeScript check that runtime prop names match JSDoc @type
  export function defineProps<PropNames extends string>(props: PropNames[]): { [key in PropNames]: any };
}

What works:

• ✅ types at the usage <SomeComponent :flag="true" mode="simple">
• ✅ prop names match between @type and defineProps() argument

What does not work:

• ❌ missing props are not caught by TS: <SomeComponent>
• ❌ extra props are not caught by TS: <SomeComponent :flag="true" mode="simple" extra="something">

Full example: https://stackblitz.com/edit/vitejs-vite-cc31fd?file=src%2Fcomponents%2FSomeComponent.vue (use npm run check-types to try type checking).

[Drumstix42]

This workaround is useful knowledge for sure. Is there any kind of markup/workaround for documenting the Component itself, and not just it's props?, (e.g. <SomeComponent> tag itself) This would allow adding a description, and possible listing/documenting the props, emits, example code, etc.

[KeroZhai]

How to provide default value and custom validator?

[phil294]

I think things work as intended here, except having the TS macros based on generic args would be great.

In the meantime this is all that's necessary:

<script setup>
defineProps({
  mode: {
    type: /** @type {Vue.PropType<'simple' | 'advanced'>} */ (String)
  },
  myObject: {
    /** @type {Vue.PropType<MyInterface>} */
    type: Object
  }
})
</script>