Composition API vs Options API Special

So one of the big issues in Vue 2 is TypeScript support isn't quite there. So options API, when it was designed, didn't really even take type inference in mind. So it wasn't really designed in a way to be easily type friendly, especially with mixins. Mixins are extremely hard to type properly. So nowadays in Vue 3, if you use options API with mixing, we can actually infer most of the stuff, which is amazing.

But if you look at the types that we have to write to get mixins inferred properly, it's just, you know, it's just so much extra effort compared to composition API where everything is just functions. It just naturally works with TypeScript, has better type inference performance. It's easier to reason about in type land in most cases. So that's one of the things that kind of pushed us to think about a different API that is designed with type inference in mind. Unfortunately, we can't

we can't just get rid of options API, so we have to carry along the burden of all the types that we wrote for options API. But, you know, in a way, like, we we want a new API that's just more type friendly from the get go. And also, mixins mixins is like the bane of both maintainability and type inference. Right? It's hard to hard to infer types also for users.

If you use a bunch of mixins, you don't even know where these properties come from. Right? So we really wanted a API that enables better logic reuse compared to mixins and also wanted the API to allow people to have a more higher upper ceiling in how to organize your code. Right? Options API forces you to group everything by type.

So if we go back to like single file components, when it first came out, there were a bunch of people who were like, oh, you're mixing 3 different languages in a single file. Where is separation of concern? Right? This very old argument about you should have 3 directories, HTML, CSS, JavaScript, and put all your files in these three categories. That's like options API to me nowadays, right?

So when you transition over to thinking about components, a component is a unit self contained unit that contains the cross cutting concerns from all 3 different layers, but they are grouped they are related to the same units of logical concern. And Composition API essentially gives you the ability to think about all your logic in the same way. So instead of thinking about here's data, here's computed, here's methods, it's like HTML, CSS, JavaScript, you can now choose to cut a piece of it out and say here's a composable, it has all the things that's related to this specific logical concern. I can move it anywhere I want. I can put it inside my component, I can move it outside of the component and share it between multiple components, or I can even extract it into a library and share with other people, share with other projects.

I think that's super powerful. And you can do that while having proper type inference all the way through. And you never get lost with where a property comes from because they always get returned from function calls. You can always just go to definition. You see exactly how they are created.

So this all of these just adds up to the overall maintainability of large projects with which we have seen over the years people just struggle with Options API. Like, I think a lot of proponents of Options API really, like, I think it works for them. It's great because their project just isn't huge. Right? There is a scaling limit to options API where if you have a huge project, multiple people working on, you have a component that's 100 of lives long, It's not gonna be fun.

It's just not. But with with composition API, a thing people don't realize is, it's kinda like building, you know, some like a model kit. One version is like it only has a fixed way of putting it together and you have to strictly follow instructions. So you don't need to use too much of your brain. You just follow all the instructions and things fall into place and you have something.

But that's the only thing you can build. And if you follow the instruction, that's the only outcome that's possible, right? But on the other hand, if you're something like Lego, like you can use your creativity a bit more, but if you don't use your brain, you just randomly put things together, it's gonna be a mess. But if you use your brain and think about a design and you think about I'm going to build this nice piece of Lego, now you can use your creativity to build something that's probably better than an off the shelf you know, thing that you can you can think of. Right?

So the upper ceiling is higher without composition API. And I also compare that to writing composition API code is more similar to writing normal JavaScript. Right?

You think about all that when you're writing normal JavaScript. Composition API kind of forced you to think about these same concerns. You're writing new component code. So that is indeed a lot more you need to think about compared to options API. But that also allows you to apply all your JavaScript skills in terms of like how do you write nice abstractions, how you organize code neatly, how do you make them maintainable, All these skills that's applicable to writing good JavaScript now apply to writing good composition API code.

Right? So so anyway, if you are a good JavaScript developer, you will find composition API more, you know, liberating because now you can you can like fully leverage your skills as a JavaScript developer. Right? But I also understand like if you don't want to just spend time thinking about writing good JavaScript code, you know, like I want to just get my hands held all the time. I don't wanna think.

Right? Options API might still be a better fit, but as I said, Vue's user base changed over time. Like, we now have real view users who are trying to build really complex stuff and maybe they are really good at skilled developers who can write really well maintained JavaScript code. So it would be a pity if we lock them into the upper ceiling created by options API forever, Right? So in a way, my motivation is to create this alternative API that unlocks that ceiling for them.

Right? So, unfortunately, to some users, it might not be the most, you know, ideal trade off because they probably never hit that ceiling. So to them, Composition API API is just there's something I need, right,

Right? In fact, you can even easily leverage composables used by other people if you still prefer to write options. Right? You just use the set of a hook and you can still use composables. So we definitely tried our best to find find the right balance.

I think it's just it's not quite possible to make everything perfect for everyone. Someone will complain, but I think we tried our best. I'm pretty happy with the outcome in general. I think composition API achieved all the goals that we set out to do. It had better types of support.

It unlocked logic reuse and composition. It increased the maintainability ceiling. I it spawned projects like VueUse, and it's now the preferred way to write components for most new users. So, so I think we achieved the most of the things you wanna achieve with composition API, but options API is probably gonna be here to stay for as long as we know.

And, of course, people were like, okay. Will the Options API stay? Like, you you said multiple times it will. You also made this tweet on Twitter. But, like, is there is there, like, an end of life at some point plan for the options API? Will it probably around for for years to come or even, quote unquote, forever?

Like, one thing that we acknowledge, is that actually, I've heard this from some people who've recently picked up Vue and they're pretty advanced developers. So their primary question is when they first look at the documentation, they see the API style toggle. Yep. And naturally, they want to understand what both how both API works because they want to make an informed decision. But unfortunately, that just creates this extra mental overhead for, like, people hate having to make decisions when they're first learning something, but we throw this big decision right in front of them at the very beginning.

It's kind of off putting to new users. I think at one point, we'll just have to be more opinionated and just, like, be the doc. Like, we will assume a lot more things because right now, like, we have to assume, do you use a build tool? Do you prefer options API or composition API? Like, this just leads to all these different branches.

It's a whole decision matrix, and that kind of blurs people because I think most new users nowadays, especially when they try to compare Vue to other frameworks, for example, Svelte, it has only one default way of using it, that's with a build tool. Right? So, so if people are comparing that, they're like, okay, Svelte just directly shows me the only way of doing things, but Vue gives me this, like, 4 different branches. Now I have to figure it out and just kind of, you know, creates a bunch of barrier they have to jump through before they get to know, oh, this is actually the happy place, you know, but that takes time, right? Because when we first did 1 view 3, the new documentation, I think having both conversation between options API in there is still definitely necessary.

Like, we kinda want to give them equal weight, equal treatment.

So that's I think that's that's kind of a mistake on our side. We should have just, like, shipped with script setup straight away, but unfortunately, we kind of, again, didn't do that upfront. In hindsight, we should have just maybe shipped composition API with script setup from day 1. But when people say, show me what a Vue component looks like, we'll show them the default. That's SFC with script setup because we believe that is the most reasonable way for you to start a new application nowadays given all the support, given all the ecosystem tooling and everything and the maturity.

So, it's at a point where we can now recommend that as a default. So probably, in the next year, we're gonna do another revamp of the documentation and start to kind of be more opinionated on, like, if you're just getting started, this is the way of doing things. There's no decisions to make. When you get a bit more comfortable with this, you can then explore alternative options, you know. We'll make you aware of those options exist.

We'll still properly document them, but we want the default onboarding path to be to get rid of all those decision matrix and just like one straight away. And you get to something that you can like confidently say, now I know HOBE works, I can build something with it. And now I discover, okay, there are also other all these other ways of doing it. But if I am I'm already happy with the default way, I don't I probably don't even need to, you know, spend too much brain trying to figure out whether I should even use them.

Have you have you thought about that a bit more, and or is it a way you could imagine pursuing or or maybe not, like, in the in the future, like, not tomorrow, of course?

I'm personally leaning towards we probably can consider doing it in Vue 4. You know, I think in a lot of things we do in Vue 4 that will be considered breaking changes just really like changing how something works by default rather than changing the way it completely works. You know, like, I think future to Vue 3, the biggest, like, issue in the breaking changes is a lot of them are kind of like these low level changes where it makes it really difficult for automatic migration.

That might be a bit tricky. Also, Evan, I agree that, like, that the learning story for people coming to Vue is now, okay. We have these 2 APIs, and then you could technically even use, like, composition API without script setup, which is probably not in the docs anymore. But still, you could just use a setup function also for migration, so on. So what do you think could be, like, a solution to a a better learning path for for the users?

Yeah. Don't do part options, part composition because that's the best way to get lost in this component forever and for reviewers too. So maybe separating and maybe I remember the discussion about eventually deprecating one of the things, but the point is there are many people around who like options API.

Like, composition is amazing, and it also gives you a lot of freedom, which is a benefit if you're developing your own project or you have a few colleagues and you all agreed on like this. For bigger ones, you will need to invent your own convention. Otherwise, it will be really hard. And those conventions can be as silly as you want. I saw people grouping Composition API just like options API. They literally have data, like, methods

Yeah. So I think maybe the best way forward, maybe I'm just a bit too optimistic, is to actually offer this kind of convention very well explained. I'm sure not in the Vue docs because this is not the responsibility. Yep. It should be adapted adapted to the project.

But there should be some kind of the guide, like, okay, you have this kind of how do you decide on your conventions? How do you shape your code so that everyone can understand? So composition API is the way to go. Like, I think we all understand that it's kind of the future. There are libraries that only work with composition API.

Yes. People want predictability from the code. Yeah. Options give them this predictability with some price. And this price being not the flexible code, like, very opinionated grouping.

Like, how what can we offer them instead? How can they use the composition API and still keep the convention in place so they feel more comfortable with the code of the bigger team? So, yeah, that's the problem to solve.

Otherwise, you probably wouldn't be asked to to help out. But still, it's it's super interesting that not that many people are like, okay. Like, in normal JavaScript, you write a function to, like, encapsulate your code.

I can, like, add a composables folder, put my composable in there, and then I use it in one component. Wow. But just leaving it in there and then, like, okay, I call my composables and reusable functions for that component just on the top. Maybe I pass in some state I get from other composables in there, or, like, Okay, I have my v model bound to something that I passed in there. That totally makes sense.

But making that connection, that took a little bit. And I hope that something like this, like, more architectural patterns, like how to deal with certain scenarios, maybe there will be somewhere documented to have, like, a bit of maybe something like a cookbook or best practices because then

We had other people from the Vue core team also on on that, tons of, like, Twitter and Reddit discussion. So, yeah, I think the the 3 of us are on the on the same line there, but there are still people and I also understand that to some of you select options API is a way because, let's say, big team, not everybody is, like, a front end expert. Some back end just have to write front end code and so on. It's like, okay. Review is easy.

Everything looks kinda the same. I don't have to think about abstractions, and also guidance and structure. So I understand even though I wouldn't touch the Objection API nowadays anymore if I don't have to.

And up next, we hear all about someone who wrote a lot of React, Swells, and, of course, also Vue. Js, especially on the side from the one only CJ Reynolds from Syntax.fm and also from CodingGarden. So let's jump into what he really likes about the composition API in Vue. Js.

And to me, that is in line with how most Vue code has been, which is, like, as little as possible to get the work done and and simple. But I think one of the issues is and and I've talked to a lot of people about it since, and I and I did a talk on the view composition API at at Denver script. And some of the feedback was like, isn't this just gonna create, like, really messy code bases? Like like, I've basically it takes a certain amount of discipline to write it in a in a composable or write it in a way that can be maintained as well. And and it's super interesting to see it.

Like, there are some people who were telling me, like, at their company, they introduced the composition API, and the developers would write comments, dates, methods, computed. And so they're basically, like, recreating the options API with all of these composition functions. Correct. So, yeah, I I think it's also a it's a it's a learning thing as well because I've I've realized in my career, like, architecting code in a scalable and maintainable way is is a hard thing to do. And so if if the framework isn't showing you how to do that, then a lot of developers aren't gonna do that because they're gonna do the minimum to get it done.

So, ultimately, I like it, especially when they introduced a script setup. I think I think when they released it, it came out with script setup. But

Just, like, write your code, and so that was really cool to see. But, yeah, I understand people's reasons for not using it or not liking it because, like, it it can be hard. It definitely takes some practice and some work to know how to structure those composition APIs in a way that will be maintainable. But at the end of the day, I think it was a good change also potentially for React developers that are moving over to Vue because it it's not the same, but it has a similar feel in that you have these little functions like useEffect or useState or all the things you're familiar with in React, but now you can use them inside of Vue.

It's one of my most popular ones of, like, organizing code with the composition API because, like, I I I really think if you use composition API and do that, then that like, you as you said, you replicate the structure, why you should just group things by logical concerns, say, the code that belongs together logically and not by type, by, like, oh, all the computers, all the the state, that should go together. And another thing I see people not doing very often is what you do in a normal JavaScript or TypeScript file. You create functions. Right? And people, when they use reactivity and, like, refs and and computeds, they put them, yeah, next to each other, but they don't put them an extra function because then, like, okay, what should I do with that?

So Yeah. Or or they they do that. They they write a new file, like, in a composables folder and say use whatsoever dot ts, and then they put it in there. But if it just lives in one component, just write a function at the very end of it, like, you really like newspaper code style and call it, I don't know. Yeah.

Use, I don't know, message or whatever. Do give me their call at the top, and you have a wonderful architecture and structure. If if you can't fully split the component up even. Right? That's that's also an option.

But if you have a component that's, like, orchestrating a lot of things, then, like, these concern based, inline composables, they help a lot. And, funnily, that there was always how the composition API was was imagined to be. And maybe you remember that that screenshot with, like, that color, that the color blocks in the RFC of the composition API with, like, options API or composition API. And lots of people are like, oh, yeah. Can we get that at some time, like, unblurred?

It's technically, it's not even important. But if you take the new file of the composition API that Evan rewrote for that, RFC, it was, like, part of the Vue CLI. He even does that. He even used these, like, inline composables that says, okay. Like, the first ten lines after imports are, like, calling these functions in the bottom.

So I think also there, it's just people were so used to options API. And then, like, oh, composables. We can share code now. Let's extract everything. It just it was a lot of overcorrecting.

But also by now, I think that's that's way more clear. And as you said before, you need some guidance, need some structure, some architectural patterns as well to actually make the composition API work well, as in, like, not writing spaghetti code. And everyone could also say, like, yeah, skill issues, like we like we had before, which is in any way, it's kind of fair. I still think it's worth to put in that effort to make the composition API work also because it's the future and also because there are a lot of shortcomings in the options API that were resolved for it, especially TypeScript, but, of course, also sharing logic, less, well, less magic, even less this dot whatsoever. So, it's it's nice that it's there.

I think it's ultimately, I think if there and and maybe you've created this, like, a a a place of a lot of examples of how things can be structured. That that that will help a lot of people. Because I know a lot of programmers that get onboarded to a new code base, they potentially try to follow the patterns that they see in the code base already. And so if they can see, oh, this is a good example of of how I can use the composition API effectively, and, oh, I don't have to pull out everything because because it can go in both directions. You can, like, refactor too hard, and now, like, all your stuff is in other files and it's hard to find, or you don't refactor at all, and now it's all just in one component.

And so because it's up to the developer yeah. Yeah.

Like, if they're yeah. The Instructure. I need Structure, and so they stick with the options API.

That repo is the bible of Vue.js. Like, without the repo, you cannot develop. But then I don't think, creating actual components. So UI component with the composition API has made the overall development cleaner. More importantly for me, it's made it harder for people to enter into the Vue ecosystem. It was easier to teach people with the option API that it is now that to teach it with the composition API.

inside, they probably felt more confident or comfortable with the other version, but they will, you know, feel like they have to say that it's cool because everyone else is saying it's cool. So I like to really people, give, you know, show everyone else that, you can't say no.

In our podcast with Sumit, we did actually a 2 part episode of that, and he focuses a lot on the business value of software development. And so his take on composition API versus options API is a little bit different than some of the other guests.

So we are slowly getting there, and I'm getting more familiar with the composition API as well. So I'm warming up to it. Me personally, my team my team loves it, but it's not everything is like we try to rewrite or change only what's necessary to make it work. So most of the code is still options API and yeah. But especially new components are our composition. And we did it in the beginning. We had, what was the view composition API package or something?

Well, that one millisecond, it doesn't really matter. I really like the the principle there in terms of if you touch a component, if you have to implement something, then maybe it's good there to migrate over if it's not like, I don't know, 3,000 line component, which theoretically shouldn't exist, but we all know that can happen every now and then or like a big page component. So that totally makes sense. And because otherwise, yeah, migrations with 150 lines like, 1000000 lines of codes, they would take forever and ever.

And if these benefits or the downsides of it are, you know, either not important to you or you want to avoid them, then I don't know. The options up here is still valid as far as I know, but, I see many people advocating for it. And some of the benefits still have to emerge in my head, but, other people are seeing it. And this is something the only thing I I can think of where where I thought maybe even is wrong on this one. And but I I wish he's much smarter than me, so I'm sure, I will I will see the benefit at some point that he is.

And what I usually know from these front end or from programming in general, solutions like libraries and frameworks, etcetera, you understand them best if you experience the pain that they solve. And I probably haven't experienced the pain that the composition app is solving for me, not yet at least. And, at some point, I will get there, I'm sure, and and I will get it. And, again, I'm warming up to it. It's much much easier, in my opinion, or much more pleasant to use it with the script setup tag instead of having it having setup as an option.

This is this is something where when it's mixed, it's really painful with the return and everything, and, well, it's we have a lot of mixed components as well, and they are painful. So, that should not and we only have this mixed components because of, libraries like tanstack query that only support that while we were, you know, we were using async data a lot because it's great when you do server side rendering and have stuff pre rendered and prefetched. But now it doesn't work anymore, and we introduced this new framework and the, the, tanstack query, and then you need to use the setup. And it's just yeah. It's very messy.

But again, new components are very clean. They all use the composition API, and when you use script setup, it's much more pleasant, simply because you don't have to return this. You can structure structure it a little better. Just today, I was working on something, and I was refactoring something. And I liked that I immediately saw that, you know, every function, every computed prop, I saw that if it's not used in the in the template, my my IDE shows it to me, things like that.

And I know there are many more benefits that I just haven't experienced yet, especially with TypeScript, especially with, like, using composables more. Definitely. My team is very proficient, and they they use this all the time. I personally have never abstracted anything into a composable yet because I wasn't, like I always thought, you know, adding something into a composable means I want to reuse it. And I couldn't warm up the idea of putting something in the composable just to structure it differently.

Like, you know, having not, like, a 1,000 lines of code in one component, but, like, putting it into a different file via a composable. Like, I haven't warmed up to this idea yet, and just scrolling through a large component feels a lot more messy in the composition API because the code is mixed. Like, you can you can structure it by topic, but it's like, how do you structure it with code comment? Like, I put code comments and this is the logic for this. This is the logic for this. They get

In general, the new approach seems to be something that makes me more productive, especially if you join it or merge it with some great tools by Anthony Fu, such as the autoimports, for example. This is one of my favorite things in web development is when you have the same result, but you have to write less amount of lines of code.

All your data props are in the same your your what you would call refs now are in the same block. Your props are in the same block. That, you know, it makes sense conceptually, but at the same time, once you have bigger components or just more complicated workflows or, god forbid, you wanna share, methods between components, that gets tricky pretty quick. And we noticed the same with some type safety things as well because of you know, to access all the data, you go this dot data, blah blah blah blah. It also meant that sort of getting TypeScript to work well into that mix in those days was basically you could kinda with a with some pain and suffering, but it really wasn't worth it wasn't worth the effort yet.

Right? So the composition API sort of removed a lot of those pain points because now I could group my files by okay. Here's everything that has to do with sort of this, this responsibility and just get all the refs and all the computeds and all of the methods just in the same vibe, in the same part of the file. And it also helps that it became a little bit less opinionated again, funnily enough, or in the sense that it's it's I'm catching myself in the funny irony that I said earlier that it was more opinionated. That's a good thing.

But it it does it did mean that you didn't have to go searching through, like, this dot chain to find some data because you had a variable that you defined yourself, and that's the thing that you're talking to. So I think from a mental model, that that sort of simplified things a little bit.

Just let me update a variable. What what are we? What what are we doing here? So when, you know, the very, very earliest thoughts about pina came out that it was like, oh, this is literally just a ref like I would use in my own components, but in a separate file. Well done. There we go. High fives all around. High fives all around. This is all I need.

Or how do you think through this problem yourself? Maybe there isn't like a like, a single answer or best practice, but, like, at least just, like, yeah, take us through your thinking on that.

I think it has been covered in other episodes with Evan You. So when you use the setup stores, which I will really encourage people to to use most of the time because they are really more powerful and flexible, you really have something that looks like a composable, and that's very intentional. Right? I want that to feel as close to pinion as possible because you can reuse all the patterns and the knowledge that you already know. You're not really wasting your time learning.

So they cannot you cannot say, oh, but I maybe this disappears later on, and then I will have learned something that I will never use because that's not the case. Yeah. I think another thing that maybe helps some people click is that when we look at stores with the options API, so state, actions, and getters, they are so simple that it doesn't come off as something very flexible or something where you can have a service. And so when you start using setup stores, because you have the full flexibility of just a function and returning whatever you want, Until you don't do that, you don't get to see the full picture of what you can do. And so I have this talk of that is called, disaster class Pina.

I think you've probably seen it in person or you were there, but it it talks a little bit about this, and it sees that it says I say at some point that I like to see sort our composable singletons with ASR Sport. So it's like a composable where you have the full power of a composable, but it only happens once too. There are, like, tons of ways of using pinion, and I know sometimes it's just the lazy way. And this is when it's just the lazy way, it's probably not the the good tool. Right?

You could use just the rest sometimes. Also, if you don't have SSR, right, you can use a global ref, and it works well. Although I wouldn't recommend that because you never know. You move to next year. You move to suicide generation. We get into the complexities of of what Yeah. Development too.

Just because you have pina doesn't mean you can't, like, you can't just stop thinking about what you're doing. You know?

In November, Alex and I had the honor to host a panel at VueConf Toronto, and the discussion was wide ranging, covering a number of different topics. But one that we made sure to get in there at the end was what different people thought about the composition API.

We've got some downtime on the weekend and evening, you know, maybe while you're working even. Go check out those episodes. We've got, I think, 40, 41, 42 at this point. I'm I'm losing count.

Let us know on the socials, like on Bluesky. Let us know in the the comments, of course, on, like, Spotify or YouTube. We'll we'll check them all, respond to them. And, well, of course, you can also guess our opinions in terms of composition API or options API, at least if you listen to all the episodes and that little supercut here. So, yeah, looking forward to see you in the older episodes.

Michael said the next stuff as well. There are a lot more coming every week, and we have some amazing guests lined up, so can't wait for that. And, of course, hope you all enjoyed a few more quiet and relaxed days.