[Core Team RFC] New SFC macro: defineRender

[sxzz]

• Start Date: 2023-10-14
• Target Major Version: 3.x (2.x is also supported in Vue Macros)
• Reference Issues: N/A
• Implementation PR: feat(compiler-sfc): introduce defineRender macro core#9400

Summary

This proposal introduces a new SFC macro called defineRender that allows for declaring the render function in <script setup> without <template>.

Basic example

JSX Element

<script setup lang="jsx">
defineRender(
  <div>
    <span>Hello</span>
  </div>
)
</script>

JSX Render Function

<script setup lang="jsx">
defineRender(() => {
  return (
    <div>
      <h1>Hello World</h1>
    </div>
  )

})
</script>

h Function

<script setup>
import { h } from 'vue'
defineRender(() => {
  return h('h1', 'Hello')

})
</script>

Motivation

<template> can be limiting in some cases where the render structure of a component needs to be dynamically composed with complex, and sometimes imperative logic.

Currently, developers can only use JSX/TSX or raw render functions via defineComponent in non-script-setup context. While we have tried to improve the type inference and generic support of defineComponent, it still lacks many other features we have covered in SFCs: HMR, typed emits, typed slots, and higher-level frameworks features like auto imports in Nuxt.

You can technically use render functions in <script setup> via the render option with defineOptions - but due to the scope restrictions of defineOptions, code inside render() won't have access to setup scope variables.

defineRender fills this gap: it allows developers to use JSX/TSX render functions in <script setup> when needed, while keeping the same consistent access to all the SFC features.

Detailed design

• The macro is a <script setup> only feature.
• The macro can only be called once and the order of the statement is irrelevant.
• The macro is experimental. Introduced a new compiler script option defineRender, and it's disabled by default.
• The macro cannot be used with <template>. If it does, an error will be thrown.
• If the first argument is a JSX element, it will be wrapped by an arrow function. (e.g <div /> => () => <div />)
• If the argument contains JSX expressions, they will be output as is and won't be transformed into h functions.

Macro Signature

function defineRender(renderFn: VNode | RenderFunction): void

Drawbacks

Alternatives

Return Statement

Allows a return statement in <script setup>

<script setup>
return <div />
return () => <div />
return () => h('div')
</script>

Compared to defineRender macro:

• Macro is more explicit for defining render. The return statement has unclear semantics.
• return can be written more than once can could cause losing reactivity, but in defineRender it can only called once.
• For macros, the order of calling is not concerned, but the return statement is not.
• Like the above one, all macros can only called in the top level of <script setup> but the return statement is not.

See more at #585 (comment)

Export Default Statement

Also implemented in Vue Macros.

Compared to the defineRender and return statement:

• Export default also has unclear semantics.
• Resolve problems of order & top-level in the return statement.
• Two export default statements in both <script> & <script setup> could make developers confused.

See more at #585 (comment)

Adoption strategy

It's an opt-in feature and is disabled by default now.

Unresolved questions

N/A

Appendix

Existing Implementation

defineRender is already available in Vue Macros.

[ricardov03]

This proposal presents a significant opportunity to target React users who are currently migrating to other frameworks. By offering a simple alternative with a lower learning curve, we can provide an attractive option that will help to retain these users.

[matthew-dean]

I'm trying to understand how this is simpler than a <template> block? What's simpler about it?

[crutchcorn]

While I'm already very familiar with Vue, the React part of my brain that this appeals to find the usage of defineRender appealing finds this confusing, as it acts more like a "hook" through a quick glance.

As such, I would rather see the "alternative" as outlined (which allows a return type) implemented. However, I might propose that we introduce a new script flag to enable this in order to sidestep some of the shortcomings. Maybe:

<script setup render lang="tsx">

[yyx990803]

The problem with return is that to many tools (including Volar, if without dedicated support), it looks like a top-level return which is a syntax error. For example, @babel/parser will throw an error when encountering top-level return unless it's explicitly allowed via options. This could lead to potential compatibility issues with tools that need to parse the content of <script setup>.

Also, the point of defineRender being in the same scope with <script setup> is that the JSX inside can have access to everything else declared in the same scope. I'm not sure how declaring it in a separate script block improves things.

[blake-newman]

I think this is a great proposal, we came from using Vue 2 with TSX (finally migrated to Vue 3). However everything is in TSX (using defineComponent) in SFC.

This change would allow us to progressively migrate our components to setup syntax and convert to templates over time and in stages.

[zhiyuanzmj]

Or other alternative:

We can use import in setup, so we should also allow the existence of export.
export default to define render.

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

const foo = ref('')

export default () => (
  <div>{foo.value}</div>
)
</script>

[sxzz]

Export statements and return statements have the same problem: unclear semantics.

Three kinds of export defaults are implemented in Vue Macros, all with different uses.

[yyx990803]

There could already be export default in the normal <script> - allowing export default in two difference contexts with different semantics can be confusing.

Also, some users may expect the type when importing an SFC to be that of the exported render function.

[Aaron-Pool]

As someone who wrote a pattern library in vue2 jsx, this would make modernizing and eventually upgrading that library to vue 3 much more straightforward.

On that note, I want to request that this be backported to vue 2 (or maybe vue macros already supports this?), as it would allow for incremental migration to a modern syntax. Once the whole library reaches modern syntax in vue 2, the final vue 3 migration is much less daunting.

[zhiyuanzmj]

Yes. https://vue-macros.dev/macros/define-render.html.

[Super-Chama]

Pardon my ignorance, but won't this make two different behaviours between script setup and setup hook? In setup hook one can return a render function directly. The alternative solution mentioned here matches the behaviour of setup hook.

[Aaron-Pool]

Yeah, but script setup is not (unless you're aware of the underlying implementation) a function, unlike the traditional setup hook. So having a return statement could definitely be confusing. Additionally, most tooling (eslint, prettier, etc...) will choke on it, in its current state.

[leopiccionia]

Yes, a return statement outside a function body is considered a SyntaxError; Chrome throws with "Illegal return statement" error message, Firefox throws with "return not in function", etc.

[g-plane]

There're compatibility issues between "typescript-eslint" and using JSX in SFC:

• Bug: [recommended-requiring-type-checking] Parsing error: '>' expected typescript-eslint/typescript-eslint#6532
• Bug: Parsing error: Cannot set property index of Error which has only a getter typescript-eslint/typescript-eslint#7597

Though they aren't caused by this RFC, such issues can block people to use this macro.

[matthew-dean]

How does this handle multiple slots? There's this Vue guide, but the syntax seems rather verbose for multiple slots, and I'm hoping that a better macro could simplify the syntax? Note that currently, the Vue Macros defineRender does not type the slots properly.

[matthew-dean]

I would love if the defineRender macro still supported this:

<MyComponent>
 default slot
  <template #foo>
    <div>foo</div>
  </template>
  <template #bar>
    <span>one</span>
    <span>two</span>
  </template>
</MyComponent>

Or something that was still valid JSX, e.g.

<MyComponent>
  {(defaultSlotProps) => (
    <Button onClick={defaultSlotProps.show} />
  )}
  <template foo>
    { /* optional */ }
    {(fooSlotProps) => (
      <div>foo</div>
    )}
  </template>
  <template bar>
    <span>one</span>
    <span>two</span>
  </template>
</MyComponent>

[zhiyuanzmj]

https://github.com/vue-macros/vue-macros/blob/main/playground/vue3/src/examples/jsx-directive/v-slot/index.vue

You can try @vue-macros/jsx-directive.

[septatrix]

How would this interact with vapor mode?

[ShGKme]

It won't, in vapor render function is different.

But Vapor mode is not global. It allows to have some components in a classic VDOM and some with new Vapor

[septatrix]

So in vapor mode the macro would just be disabled? Sounds good

[zhiyuanzmj]

defineRender of the vue-macros add a vapor option to support vapor mode.

defineRender: {
  vapor: true
}