Class style `props` definition

[ktsn]

Summary

To be able to define component props with class properties. You can use prop helper to specify detailed prop options:

import { Vue, prop } from 'vue-class-component'

// Define props in a class
class Props {
  count = prop({
    // Same as Vue core's prop option
    type: Number,
    required: true,
    validator: (value) => value >= 0
  })
}

// Pass the Props class to `Vue.with` so that the props are defined in the component
export default class MyComp extends Vue.with(Props) {}

In TypeScript, you can omit prop helper when you only need to define its type (runtime validation does not happen in that case):

import { Vue, prop } from 'vue-class-component'

class Props {
  // optional prop
  foo?: string

  // required prop
  bar!: string

  // optional prop with default
  baz = prop<string>({ default: 'default value' })
}

export default class MyComp extends Vue.with(Props) {}

You need to specify "useDefineForClassFields": true for TypeScript compiler option to let Vue Class Component aware of the properties without initializer (in the above example foo and bar):

{
  "compilerOptions": {
    "useDefineForClassFields": true
  }
}

Motivation

One motivation is to properly type Props type parameter of a component for props type checking in TSX and Vetur. TSX can validate props type on compile type thanks to TypeScript:

import { defineComponent } from 'vue'

// The type Props = { count: number } in component type
const Counter = defineComponent({
  props: {
    count: {
      type: Number,
      required: true
    }
  }
})

<Counter count={'Hello'} /> // Error because `count` is of type `number`

Vetur also offers similar prop type validation on <template> block. To utilize these features, we need to properly type Props type parameter of a component.

The other motivation is less verbosity. Vue's basic props option requires us to define props with values then infers the prop type from the value. For example, we have to annotate complex type with PropType utility:

interface Person {
  firstName: string
  lastName: string
}

const App = defineComponent({
  props: {
    // Specify value `Object` then annotate it with `PropType<Person>`
    person: Object as PropType<Person>
  }
})

This is relatively verbose compared to the existing @Prop decorator approach from vue-property-decorator.

interface Person {
  firstName: string
  lastName: string
}

@Component
class App extends Vue {
  // Just specify `Person` type (and `@Prop` decorator)
  @Prop person: Person
}

Ideally, the new approach should as short as the decorator approach.

Details

We will introduce two API: Vue.with static method and prop helper function.

Vue.with(...) method receives a class constructor that describes the component props. It collects all class properties and generates props option for the component under the hood. It also respects the property types for the props types:

import { Vue } from 'vue-class-component'

class Props {
  optional?: string
  required!: number
}

class App extends Vue.with(Props) {
  // Vue.with generates the following props option under the hood
  // props: { optional: null, required: null }

  mounted() {
    // It retains the property types for props
    this.optional // string | undefined
    this.required // number
  }
}

Note that we have to specify useDefineForClassFields: true component option in TypeScript to make the above code works.

We can also specify detailed prop options by using prop helper (e.g. default, validator). The prop helper receives exact same as Vue core's props option object:

class Props {
  // with validator
  count: number = prop({
    validator: (count: number) => count >= 0
  })
  
  // with default
  // You can specify the type via `prop` type parameter
  amount = prop<number>({ default: 1 })
}

Note that we have to specify the type of prop via prop helper type parameter when we use default value. This is to differentiate required prop and with-default prop on the type level. That is, required should be always of type string but withDefault should be of type string in the component while being of type string | undefined when it is used on a parent component since it does not have to receive a value. If the type is able to be inferred from the default value, you don't have to specify it.

class Props {
  // type is `string`
  required!: string

  // type is `WithDefault<string>`
  withDefault = prop({ default: 'default' })
}

class App extends Vue.with(Props) {
  mounted() {
    this.required // string
    this.withDefault // string
  }
}

// In the usage of TSX/template
// required: string
// withDefault: string | undefined
<App required="Hello" />

Alternative approaches

Decorator approach

There has been an approach with @Prop decorator but there are issues which already described in #447

TL;DR

• Cannot type the Props type parameter, then there is no way to check props type.
• There are concerns regarding uncertainties of the spec.

Mixin approach

This is an approach proposed in #447. But it turned out too verbose compared to the decorator approach. There is also a feedback that defining it as a mixin is not intuitive.

[Mikilll94]

@ktsn
I have few questions:

1. Is this line not going to conflict with Vue global object.

import { Vue, prop } from 'vue-class-component'

What if someone has in the same file this line?

import Vue from 'vue'

2. These three lines are equivalent, right?

baz = prop<string>({ default: 'default value' })
baz: string = prop({ default: 'default value' })
baz = prop({ default: 'default value' })

3. What if someone wants to extends also from another base class or from mixin? How the syntax will look like?

[TiBianMod]

@Mikilll94

I don't think you can use type annotations when you using the prop function (at least not the normal way)...
I think this is invalid (at least for now)...

baz: string = prop({ default: 'default value' })

The signature from the prop function is..

declare function prop<T>(options: PropOptionsWithDefault<T>): WithDefault<T>;

so you need to write the above example like this to be valid..

import { WithDefault } from 'vue-class-component';

baz: WithDefault<string> = prop({ default: 'default value' })
// you need to use the WithDefault interface :(
// or shorter like this..
baz = prop<string>({ default: 'default value' })

my thoughts on this two examples...They are both the same, but...

baz = prop<string>({ default: 'default value' }) // valid only on typescript of course
baz = prop({ default: 'default value' }) // valid on typescript and javascript

@ktsn

Can you consider renaming the Vue.props to something more generic.
Because doesn't make sense for a component to extends props, sorry :(

Something like this for example...

import { Vue } from 'vue-class-component';

class MyComponent extends Vue.component {

}

or

import { Component } from 'vue-class-component';

class MyComponent extends Component {

}

or both :)

and you can pass the props or whatever like an argument on the component..

import { Component } from 'vue-class-component';

class MyComponent extends Component(Props, [Mixins], Whatever) {

}

[ktsn]

@Mikilll94

1. Is this line not going to conflict with Vue global object.

There is no Vue constructor Vue 3. So the conflict never happens.

3. What if someone wants to extends also from another base class or from mixin? How the syntax will look like?

Mixin is also a Vue constructor, hence it will looks like:

class App extends mixins(Foo, Bar).props(Props) {}

@TiBianMod

Let's discuss Vue and Vue.props individually. As for Vue, I don't think there is much benefit to rename it with Component or something because Vue is already common in Vue v2 as a base class of a component, and most of the users should be familiar with it. I guess renaming it would just increase the migration cost from v7 and involve confusion as there was @Component in v7. If you want to discuss it further, please post to #406

As for Vue.props, I agree with reconsidering the naming as I thought that there is too much prop appeared in the code and there should be a better API interface. However, I'm not sure if we can do Vue(Props) because Vue is a class constructor which is prohibited to be called as a function by ECMAScript spec.

I'm not good at wording but maybe we should use abstract words for that like Vue.add(Props), Vue.use(Props) etc.

[TiBianMod]

I guess renaming it would just increase the migration cost from v7 and involve confusion as there was @Component

I understand, you are right, the cost and the confusion will be big

I'm not good at wording but maybe we should use abstract words for that like Vue.add(Props), Vue.use(Props) etc.

I like very much the idea of abstract words.

how about something like this?

// Component allways extends Vue
class App extends Vue {

}

// using Props
class App extends Vue.useProps(Props) {

}

// using Mixins
class App extends Vue.useMixins(Mix1, Mix2) {

}

// Chaining 
class App extends Vue.useProps(Props).useMixins(Mix1, Mix2) {

}

what you think?

[coyotte508]

I, for one, am a very happy user of vue-property-decorator, and it works well:

class MyComponent extends Vue {
  @Prop()
  simpleOptionalProp?: string;

  @Prop({type: String})
  propWithTypeValidation!: string

  @Prop({default: 'test'})
  propWithDefaultValue!: string
}

It makes code really readable / simple, with everything in the class definitions and not imported types. I understand the concerns with the uncertainty of the spec but we'd just have to move to the next major version of vue-class-component if the times comes. Wouldn't already need to do so because Options is a decorator anyway?

I would further add that:

• The title of this repo is 'ECMAScript / TypeScript decorator for class-style Vue components.'
• vue-class-component has 390k weekly downloads on NPM, vue-property-decorator has 358k weekly downloads. Dirty math makes it that 92% of vue-class-component's users also download vue-property-decorator and most likely use @Prop.

[ktsn]

Well, the uncertainty is not the only reason to propose this approach as stated in the original post. And decorator cannot properly type the Props type.

[coyotte508]

I'm assuming you mean the type of this.$props, apologies if I'm wrong.

A large library like Vuetify only uses $props 4 times in its whole codebase, to forward props to rendered components.

I understand the argument but I think that the convenience of the decorator needs to be weighed against the few times $props is used and would not be type-checked.

And I understand if the role of vue-class-component is to be perfect / and libraries like vue-property-decorator are there to offer more convenience at the cost of a little of that perfection, it's just that at the moment its maintainer is staying silent about Vue 3.

[ktsn]

It's not just perfection but we can utilize props type checking feature in TSX and Vetur. Please carefully read the proposal.

[ktsn]

Regarding the naming, I came up with Vue.with(Props). It may describe itself clearer as we can read it "Vue (Component) with Props". Besides, we can extend it when we introduce more functionality with the static method like Vue.with({ Props, otherOptions }).

[TiBianMod]

• Related to useDefineForClassFields property.
  Be aware of behavior changes after enabling the useDefineForClassFields.

I'm very sad that I didn't know this property before :(

The quote is from #447 (comment)

Personally I don't like the idea of props to be proxied on this, I really hope we change this behavior and all props to be accessible only through this.$props

const Props = props({
    something: String,
});

export class SomeComponent extends Props {

    something = 'CLASS PROPERTY aka Data';

    public render() {
        return (
            <div>
                {this.$props.something} - {this.something}
            </div>
        );
    }

}

<SomeComponent something="PROP VALUE" />

The result of this component is:

<div>
    PROP VALUE - PROP VALUE
</div>

but where is the value of the something property?

I really hope we change this behavior @ktsn !!!

Like you can see in the above example, if you have same property name on class and props, the props will take always present and you don't have access of the class property

The results of this component will be..

<div>
     PROP VALUE - PROP VALUE
</div>

After specifying "useDefineForClassFields": true on your tsconfig this behavior will change.
The result of this component without any other change will be..

<div>
     PROP VALUE - CLASS PROPERTY aka Data
</div>

Now like you can see the class property is respected and present, and thanks to vue-class-component the class property is fully reactive.

So the class property will be always respected first and if the class property does not exist then will check for component props

REALLY REALLY NICE :)

For me this was the behavior I was looking for and I hope no one changes this behavior in the future.

@ktsn

I hope in the next version we can access props only through this.$props :)

[azampagl]

Just going to add 2 cents for consideration in regards to decorators. I’ve tried to follow all of the threads regarding the subject and completey understand the direction.

My team and I have a major application (100k’s lines of code) and many of the components utilize this library - the decorator approach was very elegant.

Even if decorators are not the suggested / ideal, it would be nice to have for backwards compatibility even if it means losing the ability to properly type the Props type for the time being (and other benefits). It at least provides us the option of upgrading our code base to Vue 3, and slowly implementing your preferred prop helper approach over time.

Love the library, thanks for all the hard work!