defineProp macro for single prop definition

[johnsoncodehk]

• Start Date: 2023-07-28
• Target Major Version: 3.x
• Reference Issues:
• Implementation PR:

Summary

Provides a DX excellent props definition method for script setup.

Basic example

// the prop name will be inferred from variable name
const propName = defineProp<T>()
const propName = defineProp<T>(defaultValue)
const propName = defineProp<T>(defaultValue, required)
const propName = defineProp<T>(defaultValue, options)
const variableName = defineProp<T>(defaultValue, options, propName)

Motivation

We align the usage of prop with ref() / computed(), which can effectively improve the fluency of thinking when writing SFC.

On the other hand, the situation where people used to dislike .value is reversed, and now most people like .value based code. For me .value is a clear hint that the value is responsive, which actually reduces the mental load.

Detailed design

Basic Usage

<script setup>
// declare prop `count` with default value `0`
const count = defineProp(0)

// declare required prop `disabled`
const disabled = defineProp(undefined, true)

// access prop value
console.log(count.value, disabled.value)
</script>

With Options

<script setup>
// Declare prop with options
const count = defineProp(0, {
  type: Number,
  validator: (value) => value < 20,
})
</script>

TypeScript

<script setup lang="ts">
const count = defineProp<number>()
count.value
//    ^? type: number | undefined

// Declare prop of TS type boolean with default value
const disabled = defineProp<boolean>(true)
disabled.value
//        ^? type: boolean
</script>

Reusing Props definitions

We don't prevent defineProps from being used together with defineProp, so for reuse props definitions can still use defineProps.

<script setup>
import { sharedPropsOption } from '../shared'

const props = defineProps(sharedPropsOption)
const count = defineProp(0)
</script>

For consistency, users can use toRefs to destructure defineProps to refs.

<script setup>
import { sharedPropsOption } from '../shared'
import { toRefs } from 'vue'

const { propA, propB } = toRefs(defineProps(sharedPropsOption))
const count = defineProp(0)

propA.value //...
</script>

Props Inheritance

Since props are not collected into a single object, you need to use $props in the template instead of the variable define by defineProps.

<template>
    <MyComp v-bind="$props" />
</template>

Drawbacks

defineProp is a new API that does the same thing with defineProps and might cause some confusion for users in the short term.

Alternatives

• Stay with defineProps
• [Core Team RFC] Reactive Props Destructure #502
• Another API design: https://vue-macros.sxzz.moe/macros/define-prop.html#kevin-s-edition-default

Adoption strategy

This is a new feature for backward compatibility.

[antfu]

Look really promising to me, I love it!

A few ideas about the design of the argument:

1. Does it have an expected behavior when not passing props? I feel the syntax to declare require props a bit verbose. Should we consider making required enabled by default? For example:

const foo = defineProp('foo') // type: String, required: false
const foo = defineProp() // type: null, required: true
const foo = defineProp<string>() // type: String, required true
const foo = defineProp<string | undefined>() // type: String, required false
const foo = defineProp(undefined, {
  required: false,
  type: String
}) // type String, required: false

Then maybe we could save one argument:

const propName = defineProp<T>(): Ref<T>
const propName = defineProp<T>(defaultValue): Ref<T>
const propName = defineProp<T>(defaultValue, restOptions)
const propName = defineProp<T>(defaultValue, restOptions, bindingName)

[sxzz]

required is false by default in Vue actually. How about putting required into restOptions?

const foo = defineProp('foo') // type: String, required: false
const foo = defineProp() // type: null, required: false
const foo = defineProp<string>() // type: String, required false
const foo = defineProp(undefined, {
  required: true,
  type: String
}) // type String, required: true

[johnsoncodehk]

I think it would be nice for required to keep default false. In reality, optional prop has more use cases than required option, and default optional also makes component type-check more inclusive.

The RFC has been updated, and now it's:

const propName = defineProp<T>(): ComputedRef<T | undefined>
const propName = defineProp<T>(defaultValue): ComputedRef<T>
const propName = defineProp<T>(defaultValue, required)
const propName = defineProp<T>(defaultValue, restOptions)
const variableName = defineProp<T>(defaultValue, restOptions, propName)

[jd-solanki]

using .value is nice idea but I prefer writing all my props at one place (defineProps). Basically, This makes code more structural.

<script lang="ts" setup>
// component meta => props, emits, defineOptions, etc.

// Business logic
</script>

[johnsoncodehk]

Vue 3.3 also added defineModel, which has separated from a single props, but when you use defineModel together with defineProp, you will find that it is more consistent.

[posva]

After reading the proposal, it doesn't seem to be worth adding yet another syntax for props, it will just divide more the ecosystem. Adding a new API has a long term impact as well, not short term. As code samples might be written in different syntaxes online and become harder to understand. Especially given that one could totally use Vue without this feature but also use it everywhere instead of defineProps().

I also think it has way too many overloads and that having 2:

• defineProp(defaultValue)
• defineProp(defaultValue, { other optionss }) is more than enough

But even then, I feel like it just add yet another syntax to remember compared to the existing object: defineProp({ default: defaultValue })

[johnsoncodehk]

Another motivation is to propose this proposal as a replacement for #502, which for solve the DX problem of prop default.

Your suggestion is good, the updated RFC will simplify the API. But I still keep defineProp<T>(defaultValue, required), because this is enough for most use cases.

[posva]

In that case, the version proposed by @antfu with required by default, and letting the user add the generic with undefined seems to be closer to existing APIs.

That being said, I still think this is not a good idea. It also doesn't really replace #502. It does address the verbosity of a default value but I feel like there have been other ideas that could be closer to the existing syntax, especially in TypeScript like defineProps<{ size?: number }>({ size: 2 }) to give a default value.

When writinng props I don't see much benefit in writing one defineProps() vs multiple defineProp(). In fact, I will likely switch from defineProp() to defineProps() as a component grows. This means that I rather just use defineProps() from the beginning since git diffs will be lighter.

[jods4]

@johnsoncodehk I hate the discrepancy with defineModel:

const m = defineModel<string>("value") // value is model name
const p = defineProp<string>("value") // value is default value :(

[edikdeisling]

I really like that proposal. It is too verbose setting the default value for props right now

<script lang="ts" setup>
  // current approach #1
  import { PropType } from 'vue';
  const props = defineProps({
    variant: {
      type: String as PropType<'primary' | 'secondary'>,
      default: 'primary',
    },
    size: {
      type: String as PropType<'xs' | 'sm' | 'md'>,
      default: 'xs',
    },
  });
  console.log(props.variant);
  console.log(props.size);

  // current approach #2 
  const props = withDefaults(
    defineProps<{
      variant: 'primary' | 'secondary';
      size: 'xs' | 'sm' | 'md';
    }>(),
    {
      variant: 'primary',
      size: 'xs',
    }
  );
  console.log(props.variant);
  console.log(props.size);

  // proposal
  const variant = defineProp<'primary' | 'secondary'>('primary');
  const size = defineProp<'xs' | 'sm' | 'md'>('xs');
  console.log(variant.value);
  console.log(size.value);
</script>

I assume that defining props is a piece of code that is written almost in every component and it introduces a lot of noise in the current shape of API.
Maybe need to think more about required/defaultValue positions inside defineProp, but general direction is awesome

[callumacrae]

I like the problem this RFC is addressing - when teaching people the composition API it's come up multiple times that while it's possible to group most things by business domain, not by Vue's functionality (like with the options API), that doesn't apply to prop definitions.

I'm not sure this is the best solution, though. defineProps isn't the only functionality that has to happen across multiple domains, and I don't think it makes sense to think about it completely in isolation. There's also defineEmits, useRouter, useI18n, and a bunch of other stuff that I usually see either defined at the top of a component, or eventually moved up there when code above where it's currently defined starts needing it. I don't think it makes sense to introduce a new API that only solves the problem for one of these cases.

I also think the current API, especially with reactive props destructuring, can be made to solve this problem with only a small change—making it possible to use defineProps more than once in the same component:

const { foo } = defineProps<{ foo?: boolean }>();
// Logic dealing with foo here

const { bar = 'default' } = defineProps<{ bar?: string }>();
// Logic dealing with bar here

That does feel pretty dependent on the reactive props destructure RFC (which I'm not too sure of the status of), but potentially solves the same problem without requiring any new APIs.

[edikdeisling]

Good catch. reactive props destructuring solves the problem I mentioned above

[zzhenryquezz]

Hi, I have used this macro via vue-macros package for some time and It is very nice and useful to organize well the code in components in separated parts

Also, while using the macro I get some more ideas of other possible implementations

A similar approach as defineModel()

// get prop name from variable
const myProp = defineProp()

// or explicit tell prop name via argument
const myProp = defineProp('propName', {
    type: String,
    required: false
})

const myProp = defineProp<T>(): Ref<T>
const myProp = defineProp<T>(propOptions): Ref<T>
const myProp = defineProp<T>(propName, restOptions)

Github copilot suggestion

This is a code that Github copilot suggest for me quite frequently when I was using the macro, and it looks nice too

// get prop name from variable
const myProp = defineProp()
// or set propName on options
const myProp = defineProp({
    prop: "propName",
    type: String,
    required: false
})

const myProp = defineProp<T>(): Ref<T>
const myProp = defineProp<T>(propOptions): Ref<T>

Some sample code:

Button
ListItem

[jods4]

I think I like it.

Early defineProps (plural) was clearly influenced by the non-script setup approach to Vue components.
The generic TS variant turned out to be a little awkward to use with default values or other additional parameters (e.g. value validation).
Over the years it was refined in a direction that would be much aligned with defineProp (singular):

• (Experimental) reactive destructuring gives us "ref-like props", and adds nice syntax for default props value. (Could be superseded by this? It's less magical and achieves similar goals.)
• defineModel was added separately from defineProps, also with a ref-like single variable per model and clean options.

I kind of think that with hindsight this might have been the preferred approach.

So I feel like defineProp (singular) would be a nice addition. I appreciate:

• Ease of single props variable usage;
• Cleanly add any option to a prop;
• Consistency with defineModel and ref.

Feedback on API design:
Not a fan of having many overloads with parameters of various types (any, string, bool, object... meh). This being a macro, there's no runtime cost to using a clean options object.
Also I strongly feel like defineProp must be consistent with defineModel.
That would mean:

const propName = defineProp() // : Ref<any>
const propName = defineProp<string>() // : Ref<string | undefined>
// Not all options depicted: also type (for JS), validator, etc.
const propName = defineProp<string>({ required: true, default: "world" }) // Ref<string>
const prop = defineProp<string>("propName")
const prop = defineProp<string>("propName", { default: "world" })
// ^ Ref<string>, under strictNullCheck if undefined can be manually assigned I'd expect:
//  defineProp<string | undefined>({ default: "world" })

[johnsoncodehk]

@jods4 I completely agree with your proposal. My proposal was made before defineModel was stable so consistency was not considered. I personally think the API design of defineModel is a bit bloated, but in any case defineModel has been stable, we should submit a new RFC compatible with defineModel, and I will close this RFC.

Since I haven't been able to follow work on this recently, if you want to submit an RFC for your proposal please feel free to do so. 🙏

[jods4]

@johnsoncodehk I'll see if I find time to do it, I'm quite busy right now 😕
If anyone wants to jump in, please do.

It's worth moving this forward quickly because there is overlap with the reactive props destructuring proposal, which Evan just announced he's planning on making stable.

If Vue had const name = defineProp<string>() I am not sure it also needs props destructuring?

[yogeshgalav]

@johnsoncodehk
Can the drawback be overcame with using
prop instead of defineProp
Like ref it's much easier to read and write.

Idea here is all properties of vue2 object like computed, mounted, watch are without define prefix,
so should be the same case for prop and emit.