defineOptions

[sxzz]

• Start Date: 2022-02-13
• Target Major Version: 3.x and 2.x
• Reference Issues: use <script setup name="cpnName"> instead of two <script> core#5218
• Implementation PR: feat(compiler-sfc): add defineOptions marco core#5738

---

• Discussion
• Rendered

Summary

Introduce a macro in script setup, defineOptions, to use Options API in script setup, specifically to be able to set name, inheritAttrs and render in script setup.

Basic example

<script setup lang="ts">
import { useSlots } from 'vue'

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

// Setup code...
const slots = useSlots()
</script>

Compiled Output

const __default__ = {
  name: 'Foo',
  inheritAttrs: false
}
const setup = () => {
  const slots = useSlots()
  return { slots }
}
export default Object.assign(__default__, {
  setup
})

JSX in script-setup

<script setup lang="tsx">
defineOptions({
  render() {
    return <h1>Hello World</h1>
  }
})
</script>

Compiled Output

With Babel plugin.

const __default__ = {
  render() {
    return h('h1', {}, () => 'Hello World')
  }
}
const setup = () => {}
export default Object.assign(__default__, {
  setup
})

Motivation

This proposal is mainly to set the Options API using only script setup.

We already have <script setup>, but some options still need to be set in normal script tags (such as name and inheritAttrs). The goal of this proposal is to allow users to avoid script tag at all.

Detailed design

Overview

The behavior of defineOptions is basically the same as defineProps.

• defineOptions is only enabled in <script setup> and without normal script tag.
• defineOptions is compiler macros only usable inside <script setup>. They do not need to be imported, and are compiled away when <script setup> is processed.
• The options passed to defineOptions will be hoisted out of setup into module scope. Therefore, the options cannot reference local variables declared in setup scope. Doing so will result in a compile error. However, it can reference imported bindings since they are in the module scope as well.

Drawbacks

Alternatives

Adoption strategy

This feature is opt-in. Existing SFC usage is unaffected.

Unresolved questions

Appendix

Enabling the Macros

I made a very prototype plugin unplugin-vue-define-options.

It supports Vite, Rollup, webpack, Vue CLI and ESBuild powered by unplugin.

[posva]

It's nice you even made a plugin for it!

[sxzz]

Yes, I really needed this feature, so I had to make a plugin myself.

[chencheng365]

The plugin has a bug，vbenjs/vite-plugin-vue-setup-extend#9

[qianweihua123]

好像有点问题，我用了最新版本提示script未定义，是不是webpack版本不一致，降低版本使用后本地没有问题，打包后线上页面空白

[HerringtonDarkholme]

It is a really nice enhancement! Maybe the RFC can be written in a more formal format that looks like THE ONE rfc ?

---

Also some quick questions. Do we need to handle conflicts in defineOptions and a regular script block? Or conflicts with props?

e.g.

<script>
export default {
  name: 'Component1' // conflict in plain script
}
</script>

<script setup>
defineOptions({
  name: 'Component2',
  props: ['prop1']
})

const props = defineProps({
  prop2: String  // conflict in props
})
</script>

[sxzz]

I think a better idea is to report an error (https://github.com/sxzz/unplugin-vue-define-options/blob/main/src/core/transform.ts#L22-L25). Because if both tags are supported, the order of script and script-setup needs to be considered. Does script override script-setup or vice versa? This is a tricky question.

[sxzz]

Yes, but I think we should also provide a pure way of just using script-setup.

[sxzz]

conflict in props

defineOptions provides only a subset of Options API options, which means options other than props and emits. Props and emits can be set in script-setup(with defineProps and defineEmits), so there is no need to support them.

[sxzz]

conflict in props

I tried it on Vue SFC

I think the behavior of defineOptions is based on two script tags. If you set props in script and use defineProps in script-setup, script-setup will override script.

[Tofandel]

Well first I would say that defineOptions should only be for things that are not available (eg no props or emits or whatever) and it should report an error or warning if there is both defineOptions and <script>export default {}</script>

[leopiccionia]

I think it's doable, but would require some lexical considerations.

For example, this is obviously invalid:

import { ref } from 'vue'

const source = ref(null)

defineOptions({
  beforeRouteEnter (to, from) {
    source.value = from
    return true
  }
})

But it's more debatable if the following should be valid:

import { ref } from 'vue'

const message = "Hello, world!"

defineOptions({
  beforeRouteEnter (to, from) {
    console.log(message)
    return true
  }
})

const isOpen = ref(false)

Perhaps it should have different meaning if message appears in template (or expose, etc.) or not.

[posva]

This is a good point but I think it makes sense to disallow component in guards in defineOptions() because they don't align with script setup (except for onBeforeRouteUpdate/Leave()) or in a more general sense, to only allow base options because libraries that expose option-based API can also expose a setup based API

[Akryum]

I agree that allowing only official options would be beneficial for this proposal as we would be in control of what you can put in defineOptions and guaranty it works with script setup.

[leopiccionia]

My initial thought was disallowing any variable declaration that wasn't an import statement.

If we limit it to core Vue options, I think only the following would make sense: inheritAttrs and name (and perhaps extends and mixins for easier migration).

[sxzz]

I think both of two examples are invalid. Just like defineProps Example

[sxzz]

In general, I think defineOptions and defineProps should behave the same.

1. defineOptions is only enabled when there is only script-setup, otherwise an error will be reported. The biggest advantage of defineOptions is to avoid two script tags. If two tags are already used, then there is no need to use defineOptions.

2. defineOptions cannot use script-setup variables, just like defineProps. Demo

3. If the options of defineOptions conflict with script-setup, then an error should be reported.

defineOptions({ props: { foo: string }})
defineProps({ foo: Number })

[posva]

const { props, emit } = defineOptions<Props, Emits>() could even accept two generics to define props and emits. It will still be missing a way to define default values for props though

[sxzz]

With reactivity transform:
const { props: { foo = 'hello', bar }, emit } = defineOptions<Props, Emits>()

[sxzz]

I updated to a more formal RFC.

[Aaron-Pool]

I like this, but I think it should be limited to common options that can't be done any other way -- inheritAttrs, name being the most important ones. I actually think it shouldn't return anything either, since defineEmits and defineProps can allow you to access props and emit already. It could already be argued that Vue suffers from having too many ways to do things. So introducing an additional way to define emit or prop options seems unnecessary.

[Imaydo]

This is a good idea, defineOptions should be used more as a patch to the <script setup> than to provide an escape hatch.

Mixing composition API and options API is not encouraged

[sxzz]

Another usage scenario: with this feature, you can use JSX in script-setup.

<script setup lang="tsx">
defineOptions({
  render() {
    return <h1>Hello World</h1>
  }
})
</script>

[leopiccionia]

What's the advantage in comparison to a non-setup <script> tag?

Just consistency?

[sxzz]

Yeah, I can avoid using two script tags. Combined to one script setup tag.

[lovetingyuan]

https://vuejs.org/guide/extras/composition-api-faq.html#does-composition-api-cover-all-use-cases

When using Composition API, there are only a few options that may still be needed: props, emits, name, and inheritAttrs. If using <script setup>, then inheritAttrs is typically the only option that may require a separate normal <script> block.

I don't quite understand this passage.

[yyx990803]

I like how well-thought-out this proposal is. Some of my concerns are:

• The case of needing to declare name, inhertiAttrs or render is very rare in application components. I understand that you need this more when working on a component library, but it's really a different set of trade-offs for 90% of application components.

• Many components only need props/emits. defineOptions makes it quite a bit more verbose:

  const { foo } = defineProps(['foo'])

  vs.

  const { props: { foo }} = defineOptions({ props: ['foo'] })

  It's slightly better when using type declarations.

• The proposal currently prohibits co-usage of defineOptions and defineProps etc. This creates another "yet another way of doing things" problem. Users will have to decide whether to use defineProps/defineEmits vs. defineOptions - this creates a style fragmentation.

• Combined with the added implementation complexity, I'm not sure if this is really worth it.

Maybe we can make this additive instead - i.e. restrict defineOptions to only non-props/emits/expose options. This still achieves the goal of "avoid a separate <script> tag" but without introducing conflicting styles.

[HerringtonDarkholme]

For extensibility, defineOption is more versatile since library users can extend the option it takes via TypeScript's interface merging. It is almost a free food.

restrict defineOptions to only non-props/emits/expose options

This restriction is also easy to do by TS's Omit utility type.

Script attribute can do the same but volar needs extra support for it.

[Tofandel]

Yes, I believe the second one is the way to go

[jods4]

@HerringtonDarkholme just being curious, are there libraries that extend a component definition with extra properties? What kind of use-case do they use it for?

[leopiccionia]

@HerringtonDarkholme just being curious, are there libraries that extend a component definition with extra properties? What kind of use-case do they use it for?

In Vue 2, there were many examples. Most of them were used to setup local or global mixins, a use case that Composition API can replace. Some examples from the top of my head:

• vuelidate (defining validations)
• vue-apollo (defining queries, mutations, subscriptions)
• vue-rx (defining subscriptions)
• vue-meta (defining page meta tags, etc.)
• vue-async-computed (defining async computed properties and sync fallbacks)

But there are other usecases that would be harder to migrate, because they are used before the component instance is created:

• Vue Router has a beforeRouteEnter lifecycle hook that can abort instance creation, so it's too late to call it during setup or other lifecycle hook
• Some full-stack frameworks, like Nuxt and Gridsome, uses some route-related options (like layout or fetch) to configure their page components.

[jods4]

@leopiccionia thanks, that's instructive.

Like you mentioned I think the first set of "instance-related" properties should use Composition API in <script setup> instead. Polluting the global Component object is probably best avoided when possible.

I've seen the router discussion about how to use beforeRouteEnter inside <script setup> and it's an interesting point.
Clearly it does not belong inside setup and maybe "defineOptions" is the way to "escape" the setup function for those cases.

[Tofandel]

The more I think about it, the more I think it can be confusing to expose options within the setup because there is not direct relationship between the scope of setup and the scope of options so that would result in some weird things when people try to use variables in defineOptions, unless we make it very explicit that no reference is ever allowed within and checking it on compilation

[gastrodia]

Expect this feature, Thanks to the Vue team

[tflins]

Perhaps we could be a little more granular and introduce single responsibility functions like defindeName, defindeRender, etc.

[gastrodia]

I agree ！！

[DevilTea]

Perhaps the "name" or "inheritAttrs" could be used as attributes like this

<script 
  setup 
  name="ComponentName"
  inheritAttrs="false"
>
.
.
.
</script>

[jods4]

It was discussed here ☝

[mesqueeb]

@DevilTea can you make a RFCS PR with this simplified proposal?

I think this is the cleanest solution that doesn't have any trade-backs.

[DevilTea]

@DevilTea can you make a RFCS PR with this simplified proposal?

I think this is the cleanest solution that doesn't have any trade-backs.

Ok, but it would take some time for me to realize how to make an RFC PR.
And also I'm writing a rough vite plugin to reach the feature for experimental.

[DevilTea]

@mesqueeb You could try the vite plugin I've made, but I cannot be responsible for the result if you use it in a production lol.

[yyx990803]

Relevant: vuejs/core#4997 is merged and component using <script setup> now automatically infers name option from filename. This should eliminate the need for manual name declarations as long as you have a descriptive filename.

[sxzz]

Hmmm that's great, but I still need to specify the name manually. in element-plus, the name of button.vue needs to start with el- (ElButton).

In addition, this API is still needed to easily set the inheritAttrs.

[Tofandel]

Yep, while it solves another problem and part of the problem, there is still another one if you use eslint multi word component name (which is a default in the vue config) if your file is only single word and you want to prefix or suffix the name

inheritAttrs is also very much useful in normal vue apps

[sxzz]

Summary

Based on the above discussion and the implemented plugins, there seem to be two ways to implement this feature.

• This RFC, using the defineOptions function
• <script setup name="App"> using script tag attribute

defineOptions

i.e. this RFC

Advantages

• Following JavaScript semantics without much parsing and conversion.
• TypeScript friendly.
• Ability to set properties of any type (e.g function, object), such as the render function.
  • Example
• Ability to receive literal constants if this PR merged.
• Ability to integrate with third-party plugins or apps (e.g vue-router、Inertia.js).
  • Integration with Inertia.js

Restrictions

This RFC is intended to avoid two <script> tags, so this feature is only enabled if there is only one <script> tag and it is <script setup>.

Existing implementations

• https://github.com/sxzz/unplugin-vue-define-options
• feat(compiler-sfc): add defineOptions marco core#5738

<script setup name="App"> using script tag attribute

TBH, I don't personally agree with this solution, so I won't comment on it.

Existing implementations

• https://github.com/DevilTea/vite-plugin-vue-3-script-setup-options
• https://github.com/vbenjs/vite-plugin-vue-setup-extend
• https://github.com/chenxch/unplugin-vue-setup-extend-plus

Questions

I would like to know if there are any other questions or situations that the Vue team needs to consider? Any concerns are welcome.

Is the Vue team considering implementing this feature in Vue 3.3 if this RFC passes? I have already submitted a PR of this feature.

[christhofer]

If it's only used for name and inheritAttrs, why not make them as a separate function?

defineInheritAttrs(true | false), or just disableInheritAttrs() as the default is true already.

defineComponentName('MyComponent') or defineName('MyComponent')

[darrylnoakes]

Plugins (such as Vue Router) can add their own options to the normal Options API object. I assume this would support that?

[sxzz]

example
Integration with Inertia.js

for more details, please refer to #430 (comment)

[christhofer]

@sxzz Is this layout option Inertia exclusive?
I can't find this in Vue documentation.

I don't understand your use case for calling render() inside script setup

[zhenzhenChange]

I don't recommend.

1. The script-setup itself is designed to isolate the options api, you can't open another port, or the composition api would be meaningless.
2. If you really need to define name or inheritAttrs, the name might as well be defineMeta, what other props, render, watch options should not be mixed in again, or use the plugin to implement.
3. Different systems I think it is important to draw the line, otherwise it will only become more confusing.

[cdwmhcc]

error:

At least one <template> or <script> is required in a single file component.

[dev-93]

i have question
'unplugin-vue-define-options' cant' use in Vue CLI ?

const DefineOptions = require('unplugin-vue-define-options/webpack');
...
defineConfig({
  parallel: false,
  configureWebpack: (config) => {
    config.push(DefineOptions());
  }
})

i write in vue.config.js and defineOptions use in Header Component
but defineOptions is not defined

defineOptions({
  name: 'Header',
});

[sxzz]

Please report it to repo https://github.com/sxzz/unplugin-vue-macros instead of this thread.

[sxzz]

@yyx990803 So this PR #432 can be merged now?

[seahindeniz]

Is there a reason or a technical impossibility to not returning an object to define options?

<script setup lang="tsx">
//...
return {
  render() {
    return <h1>Hello World</h1>
  }
};
</script>

[darrylnoakes]

A little late, but anyway...

1. The return would have to be at the end of the script. You have no freedom of placement.
   I, for one, like being able to have my options defined alongside props definitions and such; all the "config" in one place.
2. <script setup> doesn't really "feel" like a function, so it would be unintuitive to use a return to define anything.
3. Following on from the previous point, I'm not sure how TypeScript support would be handled.
   It would likely require some intermediate changes before passing code to the language server (I'm not sure of the internals of Volar and such, so I can't really speak as to implementations).