Patterns for Large Scale Vue.js Applications

♪♪ Hey y'all, I'm really excited to be with you today and get to share a few things, a few tips and tricks that I've picked up during my time as a developer. My name is Daniel Kelly and I'm a teacher with vue School. I've actually only been with vue School for about six months now, but ever since I've joined the team, I've really enjoyed the opportunity to get to contribute back to the vue community that has really given me so much throughout my development career. Before I joined on at vue School, I was a full stack developer and I've worked with a number of technologies over the years such as PHP in Laravel and of course javascript in vue. When I'm not coding, I spend my time as a husband and a father and to be honest, I don't know what I wrestle with more, my children or my code. When you have three, there's a lot of that that goes on. Anyways, that's enough about me. Let's get to what you really came here to hear about today and that is what is the best way to structure a vue.js application so that it is maintainable and scalable the more it grows? Well, if I may be so bold, I'm going to try to answer that often asked question with a single word and here it is. Predictability. When it comes to building a scalable project, you want everything about it to be as absolutely predictable as possible. What does that mean on a practical level though? Well, to me, it's about the ability to go from a feature request or a bug report to the exact location or maybe few multiple locations in the code where said feature or bug report can be addressed. Not only that, I think it's the ability to know what tools and what data you have access to at that location in the code. Now, why is this important? Why is it important that we have predictable code bases? Well, if you're anything like me, you've definitely felt like this before. You've opened up the code base in your editor and you've been assigned a task and you think, I don't even know where to start. I'm lost, I have no idea what I'm doing and yeah, I think we've all been there. Maybe it's because we're new to the team. Maybe it's because we're new to a project and maybe that's a little bit more understandable. But maybe it's even a project we've been working on for quite a while and we just don't even know where to start. Well, that's the goal of a predictable code base, is to alleviate this experience as much as humanly possible. And with it, it's going to get rid of a lot of headaches and is going to eliminate a lot of frustration and get back for you a lot of your time. Now, real quick, let's just take a look at what I'm not saying. First of all, I'm not saying that your code base can be 100% predictable. I'm not saying you won't ever have to do any digging to kind of find what you're looking for. That's simply not possible. I'm also not saying that your code base can be 100% understood as a whole. In fact, most applications, or at least a lot of very large applications, are just simply too complex to be able to hold the whole thing in your head at one time. And therefore, a code base being predictable isn't necessarily about being able to understand the whole thing at one time. To me, predictability is really more about being able to predict where a certain piece in that code base fits in and really be able to only focus on that one piece at a time without having to think about the rest. In fact, I think that's a measure of a really good code base. Alright, so how do we accomplish predictability? That's the question, isn't it? Well, once again, if I may be so bold, I'm going to try to answer it in a single word. And that word is standards. Why standards? Well, because really this is how you make anything predictable, right? I can know with a pretty much 100% assurity that when I go to change the sheets on my son's bed tonight that the sheets I get out of the closet will fit because there's a standard sizing system. And it's just made that way with a standard. Now, I may get the wrong size sheets out of the closet for my bed instead of his, but we've been there. But that's on me. That's not the standards' fault. Alright, now, once again, I'm not saying standards is a silver bullet. It's not something that's going to solve all your development woes. But I think it's the single largest predictor of a maintainable code base if you're following the standards. So that begs the question, what kind of standards exist for the vue community at large? What are those standards out there that we can all share together and all know about whether we're working on, you know, by ourselves, on a small team, or anywhere across the world? And in my eyes, there are four sources of standards across the vue.js community. The first is the vue.js style guide, and probably the most obvious, because its literal purpose is to provide a set of standards for us all. The next is the scaffolding generated by the vue CLI. Now, I'm not getting into vue CLI or vite here, because really I prefer vite, but I'm really just talking about that file structure that we're all used to seeing. Another source is the official vue.js libraries, and those are all the libraries listed on the official vue documentation website under the official projects piece there. And then lastly, and yes, admittedly, maybe a little bit more loosely, we have the most popular component frameworks, things such as vue.defy or Quasar or Bootstrap vue. All right, so let's first of all dive a little deeper into those last two items. That is, the official component, the official and component libraries. Admittedly, their primary purpose is functionality. However, as a side effect of them being so widely used, they also provide shared standards. What do I mean by that? Well, take vue Router, for instance. If you end up using vue Router as your routing solution for your vue.js project, you're not just opting in to a package, you're really opting in to a community of people who use the exact same package, and therefore you're able to interact with others all across the world who are knowledgeable and familiar with that package. So that's part of what these official libraries and these component libraries provide for us, is this set of standards to follow. vuex embraces this by saying on its official website that it's a state management pattern plus library. It understands the importance of having a pattern, a standard to follow. Now, what is my point in saying this? Some of this may seem a little bit obvious, but my point is you should really consider using the existing solution before trying to roll your own or go with some other solution. If there's already a solution out there to meet your needs, go and try to use it unless you have a really good reason not to. Because not only does that solution come with built-in tests, not only does it come with great documentation, but it also comes with standards, standards that people beyond your team are aware of, and that'll make onboarding new people just that much easier. Now, this applies, I think, to all the component libraries as well, just on a little bit looser level, but the same idea. All right. That next standard is the structure provided by the vue CLI. And I really don't have a whole lot to say about this other than it's something we're all familiar with, so let's not mess with it unless we have a really good reason to. All right. If we drill down now into the components directory and if we look in the vue.js style guide, you'll see that we have some component standards described for us in the style guide that will really go a long way to making our code more predictable. So let's take a look at a few of those standards today. The first one mentioned in the style guide is that we really should be using dedicated single file components. There's really no good reason, unless you're not using a build tool, to not just put all your components in a dedicated vue file. Also, your single file components should be named in Pascal case. Your base components should be prefixed with either app or base, and this just kind of groups them all together in the file structure and provides that standard where other people can look at the app, or excuse me, look at the component and say, oh, that's kind of an app-wide reusable component. I know exactly when and where I can use that. I actually prefer to use app all the time, because it starts with an A and is typically going to group all of those and put all of those at the very top of my components directory. All right. Another thing in the vue.js style guide is to use multi-worded names for your components. And this is really more than just a stylistic thing. This is in order to prevent clashing with future or existing html elements, as they are by definition always a single word. Another standard in the vue.js style guide is to prefix all your single instance components with the word the. That is components that will only ever be used once per page, things like the header or the sidebar. Once again, that predictability makes a new developer or someone brand new to the project know instantly what these components are about. It also suggests to prefix tightly coupled child components with the component name that they're tightly coupled to. For instance, you could have a to-do list and then items within that to-do list. And so you would have a to-do list component and a to-do list item component. Likewise, you could have a job form and then a special location map field on that form. And therefore that component would be called job form location map field. All right. Sometimes, yes, this can get a little bit wordy, but it really groups them together and helps people know that they are coupled and they cannot be used one without the other. And then lastly, begin with the most general term within your component and end with the most specific. This just groups things together once again. And when you're searching for them in your IDE's quick find or whatever, you can kind of see everything grouped together in one fail search. So, for instance, you've got the search widget, you've got the search widget input, and lastly, the search widget results list. All right. The vue.js Style Guide actually has a whole lot of other really valuable things in it, but I won't regurgitate them all for you here today. But I do really encourage you, go check it out. It was actually a little bit, it was actually quite a long ways into my time developing with vue before I even realized that the vue.js Style Guide existed. And if I'd been utilizing it earlier in my career, earlier in my vue development, then I probably would have saved myself some headache and some troubles when it came to communicating and coding with my teammates about vue. Now, if you want to actually make the recommendations from the Style Guide a little bit more available to you and a little bit more real time, you can use the official ESLint plugin, which will, you know, of course, combined with the powers of your editor, mark errors for you right there in line while you're editing your files. And not only will this include javascript errors in your single file components, but it will also warn you of some offenses against the vue.js Style Guide. So I really encourage you, go check that out and use that in your projects so that you can adhere to these standards as best you can that are mentioned in the Style Guide. All right, so that does it for the community-wide standards that we have available to us. But I think I'd really be remiss if I didn't recommend a few personal or team-wide standards that I found useful. I think these are just absolutely necessary because the community-wide standards simply aren't comprehensive enough to cover all our needs. Now, I'm not saying that's the community's fault. There are plenty of standards out there. We just have a lot of different applications, a lot of different ways of doing things, and that's just kind of the way the development world goes. But I really think it's essential that for our own personal development or for our teams, that we craft some standards for ourselves. It's really going to make your development process much smoother. All right, so my first recommendation for your personal or team standard is a flat component directory. Now, I know some of you might look at this and think it might seem a little crazy. But just hear me out and don't tune out just yet. I think there are a number of different benefits that the flat component directory provides. The first one is that you can quickly navigate from the vue devtools to the component file. You just look at the component name in the devtools, and then you can go directly to it in your file structure without having to surf through different directories and browse through different directories and all this. They're just all in that flat components directory listed alphabetically for you. It really also encourages navigation with your IDE's quick find feature. That is because navigating through that long list becomes a little bit more difficult. It really makes you and forces you to try and do the search thing. And if you're naming your components correctly, as the style guide suggests, all your grouping that would normally be done with folders anyway will kind of come out of the box for you. And there's a few other benefits to it that I just don't have time to go over today. But I'm going to be sharing these slides on Twitter after the talk, so if you want to look at that more, you can at that point. Now, I actually have a little bit of a confession to make. And that is, I've never actually used the flat component structure in my own projects and in the projects that I've done at work. But I wanted to share it with you guys because I've heard it on the basis of some really smart folks that this really can work well, even for apps at a very large size. But since it's not something that I've used personally myself, I can't 100% recommend it and want to show you the alternative that I have used. But it's very close. And I'll call it today an almost flat component structure. And the reason I'll call it an almost flat component structure is because our components directory actually still is flat. My only difference is that for components that are page specific, I like to store those in a partials directory with my page components. So, for example, as you can see in the screenshot, there's the views directory. And I have a number of different pages that have to do with the client's resource of my application. And within that client's folder are my pages and a directory called partials. Now, what lives in partials here are components that go only on those client pages. They're not full pages within them within and of themselves, but they're just pieces of those client pages. And I find this works out really well as kind of a compromise between the flat component structure and domain driven design. It's kind of an in between that works out nicely for me. All right. The next standard that I want to recommend that you utilize in your personal projects or your team projects is a standardized route naming convention. And in fact, we kind of saw that in action in the screenshot we put up just a minute ago. Here we see clients create, clients edit, clients index and client show. If you're familiar with Laravel, this probably looks really familiar to you because it's a standard that they adhere to. And it works great for Laravel. So why not adopt it for the view community? Most applications, most CRUD applications have four typical needs for a particular resource. For instance, you would have to have a way to list all of them, a way to create one of them, a way to show a single one of them, and a way to edit a single one of them. And of course, a way to delete them as well. But that typically doesn't need a whole page. And so you would see what a resource called users would look like with this standardized route naming convention for a CRUD application. And I'm not going to go through them all because we just don't have the time to. But this really works well and makes your routes very predictable. All right. I want to go now a little bit beyond predictability and talk about some other miscellaneous tips for large scale applications. My first tip here is wrap your third party libraries and components. What do I mean by that? Well, let's take a look at this little example. Let's say you're using Axios as your HTTP client. And what I would recommend you do is actually wrap Axios in a maybe more generically named class such as HTTP. And then actually just use Axios under the hood to do the actual grunt work. Now, why in the world would I do this? Like, unless I'm being paid by the line, right? It seems like it just creates a little extra friction, a little extra work. But there are a few benefits. The first is that if for some reason you ever have to switch out Axios for some other HTTP solution, you only have to do it in the one place. Like in this example, I've switched out Axios with Fetch. I didn't have to go throughout my entire code base and switch things out, but rather I just had to target that HTTP class. And the rest of the code base continues using the HTTP class as normal. In fact, the people who are using that HTTP class throughout the rest of the code base, they don't even really have to know that the underlying dependency changed. They just keep using the same interface for that class as they've been used to using. Another benefit of it to me is that it really exposes ways to kind of expand the functionality of your utility classes. For instance, here I've kind of built in a way to alert a user or perform some kind of action whenever an HTTP request fails from Fetch. Now, alert obviously maybe isn't the best solution, isn't the best user-friendly thing, but you get the idea. Now, of course, with Axios, there are also certain hooks you can hook into to do similar things, but to me, they're just not as obvious. And for some third-party libraries, those hooks simply may not exist. And so if you wrap them, the ability to extend and augment your third-party libraries really becomes a lot more clear and a clean path for how to do that. All right, and this is just one more example of how you could do the same thing by extending your HTTP class with some caching. All right, so not only can you do that with libraries, though, things that are more functional in nature, but you can actually even do it with third-party components. So, for instance, I could create a wrapper component called AppIcon, and we've called it AppIcon because of standards, right? And so what this AppIcon does is actually provides a singular interface for working with multiple types of third-party icons, in this case, Font Awesome and Material design icons. My next tip for you guys is to interact with REST APIs with SDKs. Maybe your service already provides an SDK, and if it does, then great, use it. But if all it provides is an api endpoint to hit, I encourage you, wrap that api in a simple SDK of your own. And that could be an SDK you end up using just for that project, or it's something you could even share between multiple projects. But it really helps you eliminate the opportunity for typos and gives you something a little bit smarter to work with, something like a class with a method on it that your IDE can autocomplete for you. Plus, should the REST api change sometime down the road, you only have to update your SDK, and the rest of your code base can remain untouched. Also, auto-register base components. They need to be available globally anyway, so you might as well go ahead and auto-register them with a simple piece of code, such as this, and you don't even have to think about importing and registering them yourself. And then lastly, just do your testing. I know there's a lot of times that we just don't feel like doing it, and it's not the most exciting thing in the world, but for your large-scale applications, I promise you, it's better to do the work up front than to have to deal with the bugs and the regression issues down the road. On a personal level, yes, sometimes testing can be frustrating, but I have never, ever regretted doing or creating a test. There have been plenty of times where I have regretted not creating a test. And also, just to let you guys know, the recommended library now for testing your vue.js components is the vue.testing library, not vue.testutils. vue.testing library is actually built on top of vue.testutils, but gives you just a little bit higher abstraction to make writing your test that much easier. Alright, that wraps up my talk on patterns for large-scale vue.js applications. But maybe you're in the middle of writing your own vue.js application, and you could use a little help. Well, over at vue School, we'd be happy to lend a hand. You see, we offer a number of business services, including development, consulting, and team training in the form of educational videos, as well as live workshops. So, if you're interested in any of these services, reach out to us at team at vue school dot io, and we'd be happy to help. Also, if you want to build your very own real-world vue.js application, you should check out the vue.js 3 Masterclass. In it, Alex and I teach the essentials, things like vue router and single file components, but also do deeper dives into more complex topics like state management with vuex, seo, and more. Plus, if you sign up for our subscription service, you get access to the vue.js 3 Masterclass, plus access to a number of other great courses that will teach you how to be an expert with vue. Plus, there's a number of these courses that are free, so you really have no excuse to not go and just check them out today. Alright, y'all. I really enjoyed being here with you, and thank you for your time. vue.js 3 Masterclass