defineMeta to define props, events, options at one place

[jd-solanki]

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

Summary

Make SFC code structural just like defineComponent by separating component meta (props, events, options) & business logic.

Problem

With the increase of new macros in Vue 3, we are breaking the SFC's script block in much smaller chunks and it makes code less structural.

ATM, we have to write multiple macros to define props, events, options, slots, etc. This is make code less structural and hard to read & navigate when component have all three of them.

<script lang="ts" setup>
const props = defineProps({
  foo: String
})

const emit = defineEmits(['change', 'delete'])

defineOptions({
  name: 'MyComponent',
  inheritAttrs: false,
})

const slots = defineSlots<{
  default(props: { msg: string }): any
}>()

// When you want slots and attrs, you have to write more macros/functions
const slots = useSlots()
const attrs = useAttrs()
</script>

Above is just minimal example using all three macros. In real world, we may have more props, emits, options & slots. It will be hard to read, navigate and maintain. Taking it further, due to multiple macros written independently there's possibility of writing business logic between them.

Naming

Following @johnsoncodehk convention from volar ("show component meta"), I named it defineMeta.

Alternatively, We can also name it defineComponent (like without setup attribute in script block) to align with existing API but it might make more confusion or might not be possible.

Example/Design

Basic Usage

Basically, this is like writing defineComponent but without setup function. and returning props & context like setup function.

Component meta at one place. No more, multiple macros for props, emits, options, attrs, slots, etc.

<script lang="ts" setup>
const { props, context } = defineMeta({
  props: {
    foo: String
  },
  emits: ['change', 'delete'],
  options: {
    name: 'MyComponent',
    inheritAttrs: false,
  }
})

// Business logic which clearly separated from component meta
const state = reactive({
  bar: 1
})
</script>

Alternative API

Alternatively, We can make context flat for better DX.

  <script lang="ts" setup>
- const { props, context } = defineMeta({
+ const { props, attrs, slots, emit, expose } = defineMeta({
    props: {
      foo: String
    },
    emits: ['change', 'delete'],
    options: {
      name: 'MyComponent',
      inheritAttrs: false,
    }
  })
  
  // Business logic which clearly separated from component meta
  const state = reactive({
    bar: 1
  })
  
  const isUsed = computed(() => slots.default)
  </script>

TypeScript

We can also use defineMeta with TypeScript.

<script lang="ts" setup>
const { props } = defineMeta<{
  props: {
    foo: string
  },
  emits: {
    (e: 'change', id: number): void
    (e: 'update', value: string): void
  }
}>({
  options: {
    name: 'MyComponent',
    inheritAttrs: false,
  }
})
</script>

Drawbacks

• just another way of defining things
• When using with TypeScript, we might have to define props & emits in generic placeholder (IDK what <> is called) and options as defineMeta's argument.
• In TypeScript, Using defineMeta with withDefaults is arguable. (I don't know how it will work with defineMeta).

  • One possible solution is we can allow default in defineMeta's argument props.

    View Example

    <script lang="ts" setup>
    const { props } = defineMeta<{
        props: {
            foo: string
        },
        emits: {
            (e: 'change', id: number): void
            (e: 'update', value: string): void
        }
    }>({
        props: {
            foo: {
                default: 'bar' // set default from here 😔
            }
        },
        options: {
            name: 'MyComponent',
            inheritAttrs: false,
        }
    })
    </script>

Benefits

• Code will be more structural and easy to read & navigate.
• Clear Separation between component meta/definition & business logic.
• Less macros & less code to write.
• Single macro to define & use props, emits, options, attrs, slots & expose. (In next major version if we remove other macros in case if this RFC is accepted then Vue SFC setup API will be simple at it's best and easy to learn)
• Enforces avoid writing business logic between multiple macros. ESLint rule can do this

Alternatives

Using existing API with multiple macros

Adoption Strategy

• This is a new API so it will be opt-in and no breaking changes.

[jacekkarczmarczyk]

Drawbacks

• just another way of defining things added to RFC

Also provided examples don't really appear to me as "easy to read & navigate" and the proposal still doesn't provide full separation between component meta/definition & business logic, you can still mix them:

const foo = 'foo';

function bar () {}

defineMeta(...);

// more business logic

I do however agree with the idea in general. Maybe a separate tag (<component> or <meta>) would be a better solution?

[jd-solanki]

just another way of defining things

True 💯 , Let me add it

you can still mix them

It's order problem, Not mixing in between. For your example, there's already rule: https://eslint.vuejs.org/rules/define-macros-order.html

Maybe a separate tag

Separate tag/block is pretty nice, I liked that 👍🏻

[jacekkarczmarczyk]

It's order problem

Isn't that the same problem with current macros? If I understand correctly the rule you could use it to move all macros at the beginning. So for me it's either the same/similar problem with multiple macros as with the single macro, or it's not a problem at all (because there's that eslint rule) with both approaches

[jd-solanki]

Actually, I was referring to this:

<script lang="ts" setup>

const props = defineProps({
  msg: String
})

// Someone can write watcher here ❌
watch(() => props.msg, (newVal, oldVal) => {
  console.log(newVal, oldVal)
}

// New macro
const emit = defineEmits([...])

// Business logic starts here 👇🏻
</script>

It's not an order but someone can write business logic between macros.

But I guess, eslint rule might solve this.

[posva]

I think just having the defineOptions() allowing these things would make more sense than "defineMeta" which doesn't mean much in the context of components.

That being said, I don't think the problem here is well-defined or valid:

• What is less structural
• Why is it harder to read? (Subjective)
• Having one big object can actually be harder to navigate and to maintain than having smaller pieces

[jd-solanki]

What is less structural

There's no restriction in mixin the business logic with component definition or meta: example

Why is it harder to read?

after writing multiple macros, I have to identify where my component's business logic starts carefully. In simple terms, it's not grouped at one place that's the whole point.

Having one big object can actually be harder to navigate and to maintain than having smaller pieces

With new approach, It just takes single editor fold to hide whole component definition and just focus on what component is doing.

Thanks for your comments, It allowed me to express the issue more clearly.

[posva]

There's no restriction in mixin the business logic with component definition or meta: #514 (reply in thread)

That is actually an advantage: it allows to group or split things by domain (like the composition api) rather than enforcing all options being together.

With new approach, It just takes single editor fold to hide whole component definition

Exactly, one single fold means no flexibility and harder to navigate.

From an organization point of view, not all options are meant to be changed together, they do not relate to the same things, so it's better to have them separated. e.g. inheritAttrs, name are rarely changed after they are set once. However, props and emit are often updated. Having to navigate through a big object to search for emit rather than seeing const emit at the beginning of the line is objectively harder for the brain. One would end up always using the search to find stuff around.