Name compiler macros consistently, and improve option definition cohesion

[glen-84]

Problems

1. It's non-obvious where functions like defineProps and defineEmits come from. They are compiler macros, but don't have a common prefix like the ref sugar functions have.
2. Defining some component properties (name, inheritAttrs, etc.) requires the use of an additional setup block, which doesn't seem ideal.
3. There is a lack of cohesion between compiler macros – some are magic functions, some are exported from an additional script block. When using define* functions, they may be mixed, with other code between them.

Potential solution

Give all compiler macros a $ prefix. If you see a $, it's usually soft-reserved for framework functionality.

defineProps might be replaced by something like $props, however this doesn't solve problem 3. Instead, consider a single compiler macro for component options:

<script lang="ts" setup>
  const { props } = $vue({
    name: 'VButton',
    props: {
      label: {
        type: String
      }
    }
  })
</script>

• The name $vue is unimportant in this example, it could be something else like $component or $options.
• If you don't need to specify any options, then there's no need to call this macro.
• Prop values are returned and accessible via destructuring. Same for emits.
• The macro could also return slots and attrs.

Benefits

• All compiler macros have a common prefix ($). You learn this once.
• All options are defined in one place, and together. No need for additional script blocks.
• The API surface is limited. As it stands, there is already: defineProps, defineEmits, defineExpose, and withDefaults – with the above solution, the API is reduced to a single macro.

Syntax

The exact syntax is less important than the goals – to make things more consistent and cohesive.

FAQ

• define* is stable API now, we can't change it.
  -> It can be deprecated later.

• I don't like $, it looks like jQuery.
  -> No, it looks like (new) Vue.js 🙃. This symbol is already being used for the ref sugar.

[leopiccionia]

Firstly, I disagree with the following:

Give all compiler macros a $ prefix. If you see a $, it's usually soft-reserved for framework functionality.

I think reserving the $ sugar for Ref Sugar macros only is a good idea. The distinction is not arbitrary, specially because Ref Sugar can be disabled inside <script setup>, but defineProps, etc. can't and probably shouldn't (except if deprecated for something better); otherwise, <script setup> would be much less useful.

However, I like the idea of a defineComponent-like macro that can return typed setup bindings like props, attrs, slots, emit and expose, if it's proved viable by tooling.

The main con I see is the ergonomics of TypeScript types-driven definitions, currently supported by defineProps, etc. Positional type variables are not so friendly.

[glen-84]

I don't see why anyone would want to disable ref sugar once it moves out of experimental status, or why that matters, even if they did. The point is that you have two sets of functions, those starting with $ ($, $ref, $computed, etc.), and another set without a common prefix (defineProps, defineEmits, defineExpose, and withDefaults). Knowing that withDefaults, for example, is a compiler macro provided by the framework that does not need to be imported, is not really obvious, especially for those new to Vue.js.

It's easier to teach (or for developers to remember), "Vue.js uses $ by convention, avoid using that yourself if possible", as opposed to "Vue.js uses $ for some compiler macros, while there are also others without that prefix, like define* and withDefaults". It's messy.

You can also say "all $-prefixed functions are available without import", vs "define* and withDefaults are available without import, but other functions must be imported from Vue", and having to remember which is which.

[leopiccionia]

withDefaults and $ref have very few in common, except that they are <script setup> macros exposed as globals.

Whether it's globally available or an explicit import is required seems to be an arbitrary criteria for naming a function. Moreover, tooling can help you alleviate the burden in many different levels (type-checking, linting, auto-importing, Vue compiler errors, etc.).

[glen-84]

It's the "macros exposed as globals" or even just "macros", that I'm referring to. A way to group all macros in some way, so that they stand out in your code. It's non-obvious where functions like withDefaults come from, and JS has enough globals already IMO.

Tooling doesn't help if you're looking at code in an article or on GitHub (for example).

[jods4]

On principle, I am all for consistency and good naming.
I'm also with you on the fact that it's a bit strange to have less common properties defined in a separate <script> block. It might be nice to find a more elegant solution to this.

It's often the fine details that are hard and I think your proposal needs some refining.

It's easier to teach (or for developers to remember), "Vue.js uses $ by convention, avoid using that yourself if possible"

I think it's generally (not specifically for Vue) understood that $ are compiler / framework / special members and that it's preferable avoid using that symbol in your code.

The distinction is not arbitrary, specially because Ref Sugar can be disabled inside <script setup>, but defineProps, etc. can't and probably shouldn't

I don't see why anyone would want to disable ref sugar once it moves out of experimental status, or why that matters, even if they did.

The opposite is true, though.
Ref-sugar $ will be usable outside script setup, whereas defineProps and co. will not.
So they aren't the same and aren't usable in exactly the same context.

defineProps might be replaced by something like $props

Maybe "something like" but please not $props because it's already used in Vue with a different meaning. Same for $emits.

consider a single compiler macro for component options: [$vue snippet...]

How does $vue work for TS users?
defineProps<{..}> and defineEmits<{..}> are such big improvements for TS, it's not conceivable to go back to the JS syntax.

All compiler macros have a common prefix ($). You learn this once.

Ok. You make a big deal out of this.
The trade-offs need to be positive, I agree it's good to have consistency naming patterns but I also think this is not making a huge difference either.

In fact, do you think devs need to know whether defineComponent is a macro or if it's a real runtime call? Does it really matter as long as it works as advertised?
What if Vue decides to change the implementation from one to the other in the future?

The API surface is limited. As it stands, there is already: defineProps, defineEmits, defineExpose, and withDefaults – with the above solution, the API is reduced to a single macro.

I'm afraid it can't. How do you put defineExpose in the same macro as the rest?
It's usage is generally at the end of the script block, when what you want to expose has been defined -- and those usually depend on props input.

Also your proposal need to consider that unlike others, defineExpose should be available outside script setup.

define* is stable API now, we can't change it. -> It can be deprecated later.

I'd appreciate if Vue didn't take the meaning of stable too lightly.
Deprecating something that just got declared stable is not good PR.

Some people waited for script-setup to become stable before using it in large, important projects, specifically to avoid having to refactor their code if the experimental API changed.
Changing the API now is like a slap in their face.

[glen-84]

The opposite is true, though.

The opposite of what? I was just saying that it seems unlikely that someone would disable ref sugar in the future. I would imagine that it will become the predominant method of working with references once it stabilises.

Ref-sugar $ will be usable outside script setup, whereas defineProps and co. will not.
So they aren't the same and aren't usable in exactly the same context.

Again, I'm not suggesting that they work the same way, or are available in the same places. What they have in common is that they are compiler macros, available globally. If you have a chunk of code using $, withDefaults, etc., how do you know which symbols are compiler macros? Looking for a lack of an import isn't very user friendly, and tooling doesn't exist in certain contexts (articles, GH, etc.).

Maybe "something like" but please not $props because it's already used in Vue with a different meaning. Same for $emits.

$props and $emits aren't necessary when using a single function like $vue to define most options.

How does $vue work for TS users?
defineProps<{..}> and defineEmits<{..}> are such big improvements for TS, it's not conceivable to go back to the JS syntax.

I am a TS user, although I haven't yet used type-only props/emits (wasn't really sure of the benefits).

I suppose top-level generics:

const { props } = $vue<Props, Emits>({
  name: 'VButton',
  props: {
    label: {
      default: 'example'
    }
  }
})

Or additional macros:

const { props } = $vue({
  name: 'VButton',
  props: $defineProps<Props>()
})

In fact, do you think devs need to know whether defineComponent is a macro or if it's a real runtime call? Does it really matter as long as it works as advertised?

Yes, I think it would be a cleaner, more understandable design. We learn two things as developers:

1. Magic is (generally) bad. In some cases, the benefits outweigh the cons, as in the case of improving the DX around reactive primitives, but when there's magic, make it obvious, and make it explainable.
2. Avoid polluting the global namespace. JS is bad enough in this regard as it is. As these functions are used frequently, there is definitely an argument for making them available without import, but you can provide a sort of "pseudo" namespace by at least giving them a common prefix, so that they are easy to identify.

Is there not the potential for naming conflicts as well? withDefaults isn't very specific, and I can imagine someone may have already been using a function with that name in their code.

What if Vue decides to change the implementation from one to the other in the future?

That would need to be considered a breaking change.

I'm afraid it can't. How do you put defineExpose in the same macro as the rest?

Good point. $expose is not currently used ...

const { props } = $vue({ name: 'VButton' })

// ...

$expose({ a, b })

Also your proposal need to consider that unlike others, defineExpose should be available outside script setup.

I don't think this changes anything?

I'd appreciate if Vue didn't take the meaning of stable too lightly.
Deprecating something that just got declared stable is not good PR.

Some people waited for script-setup to become stable before using it in large, important projects, specifically to avoid having to refactor their code if the experimental API changed.
Changing the API now is like a slap in their face.

I generally agree. It has to be weighed up in terms of pros and cons. I obviously see the benefits to a more consistent and cohesive structure, as it's easier to reason about, learn, and maintain, but I'm not suggesting just throwing this in there without proper care.

Since it'd likely be non-breaking, there is the option of deprecations, but even that has to carefully considered. You have to decide on the "do we want/need it" before the "how do we get there".

To reiterate, the syntax is less important than agreeing that:

1. Defining options across script blocks and throughout script blocks seems less than ideal (difficult to follow/disorganised).
2. It would be beneficial for all compiler macros to be identifiable in some way (for example with a common prefix), without the need for tooling.

[leopiccionia]

For what it's worth, I think that, if "something like $props" existed, the following

const { foo, bar } = $props({ ... })

should not compile to the equivalent to

const { foo, bar } = defineProps({ ... }) // ⚠️ reactivity lost

but instead compile to something like

import { toRefs as __toRefs } from 'vue'
const __props = defineProps({ ... })
const { foo, bar } = $(__toRefs(__props))

so it's consistent with Ref Sugar mental model i.e. $computed(() => foo * 2) and $$(bar) work as expected.

[yyx990803]

I've actually been thinking of compiling defineProps calls to retain reactivity on destructure:

const { foo, bar } = defineProps({ ... })

const baz = $computed(() => foo + 1)

to

const __props = defineProps({ ... })

const baz = $computed(() => __props.foo + 1)

Same for template references.

The only case we need to pay attention to is when users attempt to pass them into external functions:

• Beginners may not realize that they are passing values
• Users who are using ref sugar may expect these destructured bindings to be made into actual refs via $$ (which we can probably support by special handling prop bindings)

[darrylnoakes]

What about having defineProps keep it's current behavior and adding a $defineProps that does this?