[Style Guide] Outdated styleguide - it's about time

[Nagell]

Hi guys,

as you surely know, the style guide is quite outdated.

Vue 3 is there for a while. <script setup> is really great.
I could even say that this is the most flexible, save and user friendly syntax, but there is no guide for it at all.
All in all the docs are giving me a vibe of <script setup> not being that interesting anymore.
Maybe even docs itself are not the most interesting thing for dev team right now, but for newcomers they are!

This harms the image of once greatly documented mature ecosystem.
There is always more and more adoption in business, but it means at the same time that we have more and more
inexperienced colleagues trying to make something in vue from time to time. And they are producing spaghetti - lots of it.
Since the composition API we can put any amount of features in a single component and mix everything as we like,
but "with the great power comes..." - you know the drill.

Side note: I already regret this decision. At the end of the day we have two extremes:

• ordering props/emits/... as if it would not be Composition API at all (old order)
• creating a 1500 lines long unreadable component + 500 lines of style
  (yes, i was there, saw it with my own eyes... and they still hurt)

I'm quite sure, that there are more experienced guys there to speak of the best practices.
Not trying to just toss a topic and run. Nothing like this. If I'll find a couple of 'I know the sh...'-guys I can gladly exchange ideas
and take responsibility for moderating it and writing it down.

Want to help? Maybe you know someone? Please, let me know.

In hope that it will get some traction,
kind regards

[NataliaTepluhina]

@Nagell just to make it clear: you would like to see a new section in the styleguide that would recommend how to structure the code written with Composition API in <script setup>?

[Nagell]

@NataliaTepluhina the short answer is: yes.
A bit longer one is: I would advocate that it might be recommended to use <script setup> over the setup() function as it is saver (my reasoning is below) but generally speaking it's about any rules for Composition API as there are not so many in the Style Guide for now. A recommendation of "how to structure the code written with Composition API" would be an essential part of it, if we are able to agree on what is a good practice at all.

Composition API gives so much freedom that sometimes it's hard for me to tell if it's not to much 😅

Btw. I could swear I saw a red notice at the top of the style guide a few weeks ago that there are plans to add some rules for the composition API. Has anything changed there?

---

I realized that my previous post was a bit tangled and way to emotional (sorry about that), so I'll try to break it up into more sections.

Why bother at all

One could say that Composition API is for experienced users (docs mentions the Options API as more beginner-friendly). But there are many cases of a new person coming from another company and facing a new technology (Vue) and being forced to use Composition API right away. If we speak about a whole team of Backend guys approaching something done by a person which is not there anymore, it is a recipe for a disaster. In my case also this person wasn't a Vue dev, but rather a React?? dev forced to write Vue. Therefore some rules / tips about good practices around Composition API could be very helpful and save some headache.

In some cases described below, we could ask if Vue should be made responsible for it at all, but we even put this phrase in the docs:

Go with Composition API + Single-File Components if you plan to build full applications with Vue

which is de facto the default choice for every company, no matter the experience of the coworkers with Vue or JS at all.

It could also help provide a good first experience with our beloved framework for those who are forced to use the Composition API in their first attempt to learn Vue. At the end of the day, Vue is mostly chosen because of the rumor that it's easy to learn. But it should also be easy to maintain.

Why <script setup> over setup()?

By working with less experienced colleagues I realized that putting everything in the return statement at the end of the setup() to expose it for the <template> section of SFC has one side effect and quickly becomes an antipattern. If you import such component in an other one as a reference like so:

components: {
    CustomerDialog
},
setup() {
    const customerDialog = ref();
    //...
    customerDialog.value.show(customer.value);
    //...

you will end up with having access to everything which was put in the return statement of the imported component (CustomerDialog). This breaks encapsulation and makes it very hard to change anything in such component as you cannot be sure what is possibly used somewhere outside. Whereas the defineExpose() alternative from <script setup> is very explicit about what is approachable from outside and minimizes the risk of breaking things.

The whole <script setup> syntax is also way easier to use as:

• everything is automatically exposed for the <template>
• shorter TS syntax
• there is no need to deal with this

What other recommendations could be helpful?

Not everything has to be a const

In the Options API there was a thing about using arrow functions in methods -> article but as this in no longer exposed in <script setup> we are free to do whatever we want. But computed, ref and reactive (i consider them being a semantic variables or at least variable storages) somehow lead my less experienced colleagues to the assumption that const and arrow functions are the way to go with everything. As a new Frontend dev in an almost purely Backend team I found out that everything in our code looks like this:

const fillSelectedZipCode = async () => { //...
const handleSelectZipInput = (event) => { //...
const isKeyAccountChanged = () => { //...
// Well almost everything...
const fetchCityZipCodes = async function () { //...

but not a single

function something() { //...

in an entire codebase.

It makes the code way harder to read, as most of the time you have to read the whole line to find out if it's a function or a computed/ref/reactive.

When to split a component

Options API is a good choice if the component should be small. If it's big the Composition API would be the way to go, as you are free to put everything in any order you like and it should be more readable.

Well... till some point it is. I saw components with over 1500 lines of code (not counting style) which definitely should be split. Refs and functions all over the place. Tabs, Search, server communication and 'Domain specific conditional rendering' logic mixed with something which should rather be a state management in pinia.

But why should we mention such basic good practice of code writing at all? When Composition API was created, the main reason for this was exactly this mentioned freedom of grouping features (which was encouraged and advised). As I mentioned earlier(#why-bother-at-all) it is the default choice for every big project, but as a side effect it made writing huge and very tangled components almost to easy.

So maybe similar advice would be appropriate:
"if your component implements X, Y and Z' you should consider splitting it / using pinia" or
"if your component is longer than 500 (just an example) lines of code you should be alarmed and ..."

explanation

[NataliaTepluhina]

@Nagell thank you for the detailed explanation, it's much appreciated (and the potato meme too xD). I think it's a reasonable request, although documenting good practices for Composition API won't be easy - giving a clear straightforward guidance on something that has this level of "freedom" is always tricky (besides script setup point, this one is rather clear).

I'll try to compose a few recommendations and run them through the team, any additional suggestions are very welcome!

[Nagell]

@NataliaTepluhina Thank you very much for your feedback. I really appreciate it. In the coming days I'll run it through again in my head. In case of any new ideas, I'll let you know :)

[Nagell]

@NataliaTepluhina I just realized that whit this another Pandora's box could be opened, but there is no mention of TS syntax in the style guide.

For example in props rule this could be an additional recommendation for TS use cases:

const Status = {
    syncing: 'syncing',
    synced: 'synced',
    versionConflict: 'version-conflict',
    error: 'error',
} as const

export interface ButtonProps {
    status: typeof Status[keyof typeof Status]
}

const props = withDefaults(defineProps<ButtonProps>(), {
    status: 'syncing',
})

Depending on the idea/case in this example, maybe an enum would be better, but you get the idea.
In general, integration with TS has become a big part of the Vue ecosystem, so adding it to the best practices seems like a logical next step.

---

Btw. Did you have some time and the opportunity to throw some ideas on the team? If so, how did they reacted? I know it's not an easy topic and probably everyone has a bit another approach. I'm excited to hear what you've come up with.

[kissu]

@pikax is probably the guy for some TS-heavy docs improvements. 😋

[pikax]

@pikax is probably the guy for some TS-heavy docs improvements. 😋

Maybe I am already 👀 #2577

---

As a composition-API + TS "connoisseur" myself 😆 I think composition-api is just simpler on small components in comparison with options-api.

One could say that Composition API is for experienced users (docs mentions the Options API as more beginner-friendly). But there are many cases of a new person coming from another company and facing a new technology (Vue) and being forced to use Composition API right away.

"Composition API is for experienced users" - I cannot find that mentioned in the docs, you could possibly deduce it based on the statement "The Options API... It is also more beginner-friendly", but just because Options-API is more beginner friendly, it does not mean Composition-API is for experienced users only.

If a company or someone started a project and decided in using composition-api and then a new person comes in and is faced with a new technology "forced" on them, I don't really think is Vue responsibility to do something about it, since that's the company/person decision to do it in composition-api and then it was the company decision to hire someone not familiar with the technology to maintain it, you can make the exact same argument with the same technology, I don't think this is composition-api or vue docs fault.

"Go with Composition API + Single-File Components if you plan to build full applications with Vue" - which is de facto the default choice for every company, no matter the experience of the coworkers with Vue or JS at all.

I agree with the docs, the goal for composition-api was to bring better tools for bigger projects, since Vue started to be used in bigger and bigger projects, Options-API is IMO inferior for those projects.

Companies probably start with composition-api with the expectation the project become bigger and bigger over time.

It could also help provide a good first experience with our beloved framework for those who are forced to use the Composition API in their first attempt to learn Vue. At the end of the day, Vue is mostly chosen because of the rumor that it's easy to learn. But it should also be easy to maintain.

I personally think Vue, especially since v3 is aimed for more complex usages, whilst still maintaining the same simple API that myself found in love with, but as the tech evolves and the ecosystem also evolves, we need to adapt and decide on what tech to use for projects.

By working with less experienced colleagues I realized that putting everything [...]
you will end up with having access to everything which was put in the return statement of the imported component (CustomerDialog). This breaks encapsulation and makes it very hard to change anything in such component as you cannot be sure what is possibly used somewhere outside.

Exposed variables must be used careful, but the same argument is also valid in OptionsAPI, since everything is automatically exposed to whoever needs to change it, so not sure where this fits into Composition-API caused issue 🤔

but not a single

function something() { //...

in an entire codebase.

It makes the code way harder to read, as most of the time you have to read the whole line to find out if it's a function or a computed/ref/reactive.

I mean there's actual differences between arrow and function, if the differences are not a blocker, it just becomes a mater of syntax preference.

But why should we mention such basic good practice of code writing at all? When Composition API was created, the main reason for this was exactly this mentioned freedom of grouping features (which was encouraged and advised). As I mentioned earlier(#why-bother-at-all) it is the default choice for every big project, but as a side effect it made writing huge and very tangled components almost to easy.

Not sure if I understand, ever since the composition-api was introduced this picture has been used, not sure where is easier to tangle features (seen here):

Don't forget the biggest advantage of Composition-API is composables, which allows you to move a domain or functional to a composable function built to be reusable and easy to test, see VueUse

---

Bad code will be written regardless of how good the framework or tools being used :D

[kissu]

This is what I was referring to indeed. 😉

[Nagell]

@pikax Thank you for your time and answer and up front: sorry for another long post.

Maybe I am already 👀 #2577

That's cool :)

If a company or someone started a project and decided in using composition-api and then a new person comes in and is faced with a new technology "forced" on them, I don't really think is Vue responsibility to do something about it, since that's the company/person decision to do it in composition-api and then it was the company decision to hire someone not familiar with the technology to maintain it, you can make the exact same argument with the same technology, I don't think this is composition-api or vue docs fault.

They brought it onto themselves. A bunch of backend/fullstack devs asked external consultants, what would be the easiest approach to meet their company needs. They never worked before with reactive frameworks. That's why they have got into Vue - because it has a reputation of being easy to learn and having a mild learning curve.

As we seemingly agree, it is to be expected that they will opt for the composition-API if the project should grow over time.

And you are right, framework don't have to be responsible for being newbe friendly. But till the v3 it was its strength and it was the reason for many companies why they adapted Vue even if they had other good alternatives.

The clue of my call is the feeling that during the evolution of the ecosystem docs became somewhat confusing to the newcomers. V2 was indeed easy to learn and due to more opinionated approach it was also easier to learn good practices. In v3 there are at least three ways of writing components (not even including the + 'TS' variant), whereas two of them are intertwined in the docs (setup() / <script setup>). This freedom is neat but also confusing even for Frontend devs switching from v2.

Many companies will start not having much experience and directly using composition-API, driven by a good reputation of the framework. I saw this pattern couple of times. If Vue want to keep its reputation, docs should not only concentrate on people having v2 background, but also take care of the new guys starting directly with the v3.

Maybe it's not even about the Style Guide itself. Maybe it should be 'Best Practices' and 'How to structure your project and code'? Or 'How to solve common SPA problems with Vue':

• API calls - external services? calls in pinia? fetch directly in the components?
• Shared state - props and emits, plugins, pinia?

In other words: 'how to make my code DRY in a typical app and not die buried under a bunch of repetitions and endless props-emits chains'? Because this is what I see every time when someone is starting with Vue. Their fault? Company fault? Maybe...

But maybe we could take care of it, like the others:

• https://react.dev/learn/thinking-in-react
• https://angular.io/guide/styleguide#t-dry-try-to-be-dry
• https://kit.svelte.dev/docs/project-structure

If you are googleing 'best practices vue' you will find outdated 'Style Guide' for v2 and even if you will somehow find v3 it's mostly about syntax. 'How to keep it DRY', 'way of thinking' or 'project structuring' are not mentioned at all.

Right now when someone is asking me 'Where should I start?', the answer is 'Vue School' or 'Vue Mastery'. Shouldn't it be rather: 'just go to the docs. It will take you through all basics and best practices in no time'?

I think I can save us a bit of time not going into every detail. I don't want to argue over personal preferences. Many of my thoughts were only samples. I just hope that we can keep up with a the biggest strength of the ecosystem (at least till recenlly):

• great tools
• great docs
• easy to jump in

Not 'to many choices and easy to create a need for refactoring', because this leads to bad DX.
Even the State of JS is showing that something is missing. More or less since the v3 there's a significant interest drop for Vue and other reports are also showing that less users are willing to continue using Vue.

• Stackoverflow Survey 2022 - loved: 63.16%
• Stackoverflow Survey 2023 - admired: 57.87%

This is concerning.

---

Just to clarify:

Exposed variables must be used careful, but the same argument is also valid in OptionsAPI, since everything is automatically exposed to whoever needs to change it, so not sure where this fits into Composition-API caused issue 🤔

In this case I compared setup() and <script setup>. The first one forces you to expose everything to the outside world even if you just want to use it in the . In the second one you have to be explicit about it and without defineExpose nothing is available from outside.

<script setup> was as I thought the easiest and safest option, if someone is new and is jumping on the composition API.
It's less verbose, doesn't have this and it's a bit safer (slightly easier not to introduce bad practices). Again, it's not about a personal preference, but rather DX. Because of this reasons, I thought that it could be recommended or be the 'default' for business usage, as it seems to me to be a bit more newbe friendly.

Not sure if I understand, ever since the composition-api was introduced this picture has been used, not sure where is easier to tangle features [...]

Not sure if it sarcasm, but as I mentioned I saw many way to big components. If they should follow this picture they would have to end up with many setup() onMounted etc functions. Maybe this it the idea behind it. I cannot tell coz every time I see this image, I don't see a clear example of how to utilize it and the image itself is simply to small, thus the idea behind it stays unclear to me.

My rule of thumbs would be: if I'm loosing the overview and feel that another setup() function is needed, then my component is probably to big and something should be: split and put somewehre else (smaller somponents, store, reusables, helpers). But maybe I am wrong?

Don't forget the biggest advantage of Composition-API is composables, which allows you to move a domain or functional to a composable function built to be reusable and easy to test, see VueUse

I saw little push towards Reusables and VueUse is in my experience known only to experienced guys as Docs barley mentions it. Such essential part could be mentioned more often. It could also be a part of 'Recommended / Good practices'.

[kissu]

They brought it onto themselves. A bunch of backend/fullstack devs asked external consultants

So far, this is more of a human problem and the need for more communication/better decision making etc, not a framework responsibility. If people are biased or not experienced enough, they should probably reconsider it and talk to FE experts.

Learning to use is also quite relative overall. Really depends on the ecosystem/the community IMO.
Every JS framework is quite complex nowadays but things like AlpineJS IMO because we add TS, SSR, modularity, build tools, linters etc etc...on top of it. Having several people helping people and improving the docs when there is such a need is IMO the efficient way to go. We mainly need a place to refer people to, in case they have some questions.

Thought about it but never knew how to implement it. Having some external website with questions/answers could be a good way but would also need to be maintained constantly. To have a proper search etc with it, it could be quite tricky.
@skirtles-code actually wrote something here: https://github.com/vue-land/vue-land.github.io
StackOverflow is also a good place for that but it requires quite a lot of maintenance to be truly efficient + it is not always a good way of teaching to the crowd, can be quite 1 to 1 unfortunately.

I'm working on a community project to kinda fill in the gaps there and maybe help some people improve together.
Still, building a good ecosystem is more needed than just good docs IMO.

The clue of my call is the feeling that during the evolution of the ecosystem docs became somewhat confusing to the newcomers. V2 was indeed easy to learn

The v2 was IMO easier to learn because you could inspect a single piece of state and debug with it (something like $vm0 in the devtools was really nice), nowadays it's all composables so you kinda need to look for those pieces yourself. Which makes it indeed more difficult.

This freedom is neat but also confusing even for Frontend devs switching from v2.

This, Vue3 is more flexible. Allows for more freedom. Hence, you need to actually know how to code properly and organize your codebase well. You are not constrained to 1 single way of writing it, hence you can do more advanced and better-organized patterns but at the same time, you can also make it crappier if you do not have some good foundations.

Not really a Vue issue either, more of a JS or even coding fundamentals. Even people like Michael Thiessen, Lachlan Miller (etc...), or instructors from VueMastery/VueSchool can just give you a gist of a decent approach but that may not apply to your specific use-case or specific challenge.
An experienced developer will know how to organize his/her code well, whatever may the framework be. It's even better this way if you're not constrained by it.

TLDR: being a good developer goes beyond some framework-specific knowledge. Vue can't find that one.
Working in several teams, with several tools/frameworks can help you grow, on top of self-improvement in terms of code organization. Also, it's hard to make a generic statement because every company is different (startup VS 20k devs bank as a quick and dirty example).

Many companies will start not having much experience and directly using composition-API

Future-proofing and playing it safe. Again, not Vue's responsibility IMO.

Maybe it's not even about the Style Guide itself. Maybe it should be 'Best Practices'

Some rules may help but again, common sense is required. And it depends on the company's needs/bandwidth in terms of human resources. Broad topic.

In other words: 'how to make my code DRY in a typical app

Using Nuxt is a decent start, if that fits your approach. Then, you could check some open-source projects built with it, like elk or any other one that may be complex enough to serve as an example.
You can also watch people code like Daniel Roe or Anthony Fu if you want to see how Core maintainers are doing it. You may agree with their approach or not, but that's another step towards some coding style/code organization.

The examples from:

• React, basic example that just covers the basics. React has some many ways of doing things anyway, no point listing them all. I feel like Vue covers this in its tutorial tbh.
• Angular, comes with quite a lot of opinionated things and is overall more strict as to how to do things. Those are hence a good starting point but nothing that we do not have on our side either, if you mix Vue's guidelines + Nuxt practices as a whole.
• Sveltekit, we have the same in Nuxt. The presentation may look a bit different, but the idea is the same.

Even the State of JS is showing that something is missing

Nothing concerning here. Every JS framework will follow that trend after some time because the novelty wears off + you have always new things to try in our ecosystem. Trying the latest Marko, Solid or Qwik is more exciting than the old boring Vue that you've been working on for 5 years. Makes sense.

Those are also stats and scoped to people who have submitted their results. Prone to bias and not representing the whole state of a given framework. If the % drops, that does not mean that it's becoming bad, there is more nuance to it.

Not sure if it sarcasm, but as I mentioned I saw many way to big components. If they should follow

Again, linters/conventions/code reviews/mentoring/good consulting/watching conferences/connecting with the community/taking some workshops or courses could help with those.
People who had 8000 lines of code in one .vue file with Vue2 Options API, will make the same mistake in Vue3 with Composition API. Vue3 helps with it, but bad practices are transferable.
Not a Vue concern.

the image itself is simply to small, thus the idea behind it stays unclear to me.

The point of this image is to explain that your code is grouped by what it does in CAPI, rather than being constrained into specific parts of your codebase. This way, you do not need to hop from props, to computed, to mounted as you previously needed.

Quoting the docs

Notice how code dealing with the same logical concern is forced to be split under different options, located in different parts of the file. In a component that is several hundred lines long, understanding and navigating a single logical concern requires constantly scrolling up and down the file, making it much more difficult than it should be. In addition, if we ever intend to extract a logical concern into a reusable utility, it takes quite a bit of work to find and extract the right pieces of code from different parts of the file.

Extracting the code to make it more reusable, versatile, and composable is your responsibility. It's just easier with CAPI because not forced to use mixins, have type inference etc...

My rule of thumbs would be: if I'm loosing the overview and feel that another setup() function is needed, then my component is probably to big and something should be: split and put somewehre else (smaller somponents, store, reusables, helpers). But maybe I am wrong?

Exactly. 👍🏻
Not something specific to Vue, is valid for any JS framework piece of code. 😄
Hence why it is not documented more in-depth in the Vue documentation.

I saw little push towards Reusables and VueUse is in my experience known only to experienced guys as Docs barley mentions it. Such essential part could be mentioned more often. It could also be a part of 'Recommended / Good practices'.

VueUse is mentioned 4 times and on the proper pages IMO. If somebody does not go through the documentation more thoroughly, I guess it's on them.

Also, a simple query on my side looks decent when it comes down to leading people towards being curious and checking what is Vueuse. The Stackoverflow answer on the image mentions VueUse.

And if you're coming from any JS framework, you would grasp what it is immediately. If you don't, some people will tell you about it.

---

Quite a lot of people are pushing a good amount of awareness around the tools available in the Vue ecosystem, on Twitter, LinkedIn, or other places on the Internet/real world. I do agree that some extra work could be done to polish it even more. But overall, some things are to be kept separate from the framework.

When I was helping daily on Stackoverflow, I noticed a lot of people who could not use a .filter properly on an array because they were lacking some JS basics (jumping too soon into a JS framework). That's on them, no documentation should explain the foundations to what is a function, what is a variable etc...same applies to more advanced codebase patterns or reusability.

[kissu]

Taking the example of TS, it's great to show how to use it in the context of Vue so that people know the basics of how to make them work well together. But going more in-depth is not a Vue concern, because you should learn TS by yourself before trying to make them work together.
Meanwhile, some people will come to the framework without those basics and struggle with it.

I am part of those people. Do I blame the Vue docs for it?
Nah, I need to understand TS better that's all.

There is only so much abstraction that you can add and you need a good middle-ground. Docs cannot fill all the gaps in those abstractions. Also coming from a guy who discovered GraphQL through some Apollo Nuxt module, was a hardcore ride to debug my issues (not a Nuxt docs or module issue). 😂

[Nagell]

I surrender. It seems that the only option in your opinion is based on the assumption that people are generally passionate about frontend and its concepts, or at least want to master what they got into. Well... the only thing left for me is to tell my colleagues that there is no shortcut and that if they took a fullstack approach, that's their problem, not mine and not the frameworks either. ...although it is my problem, so I can only hope they take it seriously, otherwise I'm doomed to write tutorials and internal style guides for every typical problem and constantly check their commits. Maybe one day I'll publish it in some forgotten corner of the internet.
The latter is more likely, by the way, since they're already deep into backend issues 😞

I suppose that's why large companies with varying levels of knowledge among developers use more opinionated frameworks. Sadly, I don't have this option anymore. Maybe one day we will rewrite our projects or I will somehow manage to teach other five guys and surpass them in fixing their code.

In any case, thank you for your time, the explanations for drops in the stats and presenting your take on that topic. At least my brain has something to work with :)

I'm working on a community project to kinda fill in the gaps there and maybe help some people improve together.

This indeed could help. Maybe this could be a place to publish my guides some day.

Going back to thinking about, how to explain chaotic nature of the freedom given by pinia + props-emits and watchers to someone used to more linear request > middleware > route > controller > model > ORM and back approach 😉

Edit:
Thank you for the link to https://vue-land.github.io/ - something like this could help very much. Looking forward to see your project.

I suppose this thread can be closed. Up to you guys.

[pikax]

MO this issue has some merit, we are always open to get better documentation, but we need to know exactly what people think we are lacking.

Just like in code, we must separate some of the concerns, Vue as a library is a tool to build web based apps, theres two main ways for you to build your app components, options-api and composition-api, you can use both in the same project, as you see fit. Vue it self just gives you the tools, you must know how to use the tool (that's valid for anything).

Vue can be basically be broken down into two main parts, reactivity and rendering, the sfc is just a sugar for rendering to provide better DX. Everything outside that is placed elsewhere, router, store, SSR, builder, etc. Vue core as a project does not handle router directly nor it should, but the Vue-router is maintained by Core team members and other core libraries are also maintained by the core team, but they are not Vue core, they might have a mentioned in the docs but each project has their own docs.

Nuxt and quasar are great examples of awesome libraries that are more opinated and do a lot of the heavy lifting for developers.

---

Expecting pure backend developers transition to frontend without any bumps, is expecting a plumber do your house electrical wiring without any issues, they might know that is just cables in the house but don't know the details of each cable size, how many lines you need, etc.