Vue 3 docs are a lot more confusing than vue 2 docs about how we should code

[yann-yinn]

Hi there, (sorry for my inaccurate language, i'm french)

First i want to say how much Vue 3 is better than Vue 2, and how much I love the new composition API; and i know how fucking hard it is to write documentation; kudos for brave people working hard on this.

This issue is pretty meta and only about one thing:

When i first read Vue 2 docs, i was super happy: I knew exactly how to code and, from day one, I was able to code in production. It was so easy: option API, data() for reactivity, no TypeScript, Vuex if I need state management, and i can use <style scoped> for CSS. Let's go ! Code, git push, this is in prod, i'm a Vue developper \o/

But learning Vue 3 and reading the (very good) docs, i was confused because I didn't know how I was suppose to code anymore:

• Should I use only composition API ? ( my answer today is "yes" and "do not use option API anymore")
• Shoud I use TypeScript or not when starting a new Projet ? Vue 3 has be rewritten in TypeScript, but should i use it ? (my answer today is "yes, you should")
• if TypeScript, should I use "class component" or not ? (my answer is "no" for now)
• ref() or reactive() ? Technically, i can use objects with ref() AND reactive. Still not sure about when I shoud use one or the other, sometimes i switch from one to the other... (i'm tempted to use only ref, writing ".value" is not so annoying and at least we know that we MUST always write value, from computed to reactive variables)
• script or <script setup> ? If i'm using only composition API, should i write always "export default {setup()}" or should i use <script setup> ? My VSCode editor seems happier with keeping "export default {setupt()}" notation...

[skirtles-code]

The addition of the Composition API does pose a challenge from a documentation perspective. It allows projects to adopt significantly different styles and the documentation needs to negotiate that somehow. There's a certain amount of historical momentum in the Vue 3 docs and we're still working to try to address that. In particular, the guides don't give enough emphasis to single-file components, which is something we hope to address going forward.

Many of the points you raised are quite subjective and the documentation tries to reflect how Vue is used in the community rather than trying to force everyone to use it in a particular way. I can share my own preferences and try to describe what I've seen elsewhere (mostly in discussions on the Vue Discord) but you'll find differing opinions depending on who you ask.

Should I use only composition API ?

The Options API is alive and well and is still very popular with many people in the community. I personally use it by default for most components, only using the Composition API for components with more complex needs. I would usually try to avoid mixing the two within a single component though.

I know of other teams that have chosen to switch to the Composition API entirely. I don't think this is common but if there's a consensus within your team then it's a perfectly valid option.

Personally, I think the Options API is easier for beginners. The coding style required to use the Composition API (which some might call a 'functional style') can be a major obstacle for those who haven't encountered something similar before.

Shoud I use TypeScript or not when starting a new Projet ? Vue 3 has be rewritten in TypeScript, but should i use it ?

I do not use TypeScript. This is a decision you have to make for yourself, Vue doesn't really push you one way or the other.

if TypeScript, should I use "class component" or not ? (my answer is "no" for now)

In Vue 2, there was a strong case for using 'class component' syntax if you wanted TypeScript. That doesn't really hold true with Vue 3. While it is still supported, I don't think using class components is encouraged.

ref() or reactive() ?

As I've noted here, wondering about whether to use reactive or ref is a common question: #849 (comment)

We do hope to improve the documentation in this area.

When used with an object, reactive only allows the properties of the object to be changed. ref allows the object itself to be reassigned. They can be viewed as the reactive equivalents of using const and let. With const and let, it is theoretically possible to always use let. In the same way, you could always use ref. However, using const expresses some extra information, that the value is never reassigned. reactive provides that same benefit.

It is also worth noting that ref still uses reactive internally to proxy its value, so by using ref you are adding an extra wrapper around reactive.

script or <script setup> ? If i'm using only composition API, should i write always "export default {setup()}" or should i use <script setup> ? My VSCode editor seems happier with keeping "export default {setupt()}" notation...

<script setup> only left experimental status in 3.2, which was released a few days ago. Some new documentation was added as part of that release. See https://v3.vuejs.org/api/sfc-script-setup.html, which includes a recommendation to use <script setup> if you're using SFCs with the Composition API.

If you're having trouble with VSCode then make sure you're running the latest version of Volar.

[yann-yinn]

What an answer, thanks you so much @skirtles-code , your advices are super useful on thoses topics and your issue about reactivity is super interesting too.

Everything is subjective but it take so much times to explore by ourselves all the possible alternative, so recommendations feels very great.

So for someone like me who:

• likes "functionnal" style
• Interested in TypeScript
• Starting a new project with Vue 3

A possible recommendation could be:

1. Use only composition API (if the whole team is comfortable with that)
2. Use TypeScript (without the "component class" syntax)
3. Use <script setup>, which is officially the recommended syntax if you are using both SFCs and Composition API

Update: I tried 3) without success, even with "volar" VSCode plugin, my editor becomes crazy about unexisting macros, non-used variables. I'm sticking with defineComponents() for now.

[skirtles-code]

@yann-yinn From everything you've said, that does sound like an appropriate recommendation for your project.

The problems you're having in VSCode might be caused by the Vue ESLint plugin. I haven't experimented with it myself yet but I have seen other people mention a similar problem. Now that Vue 3.2 is officially released, I would imagine any tooling problems would be resolved pretty quickly.

[bencodezen]

Seconded on the things that @skirtles-code mentions.

We are certainly going through a bit of a challenge in how to embark with docs going forward as more paths open up for developers. That said, we appreciate you bringing up your concern and will keep this in mind as we keep iterating on the docs. Appreciate it @yann-yinn!

[yann-yinn]

@bencodezen thanks for your anwser. I found a lot of answers by Evan inside this discusion vuejs/rfcs#378 (comment) (thanks @edimitchel for the links).

I just understood that using volar, you should disabled vetur

[NataliaTepluhina]

Closing as we have a new docs now that should have made the explanation more clear