Skip to content

Converting Your Vue 2 Mixins into Composables Using the Composition API


There are two main ways to add additional functionality to our Vue components: mixins and composables. Adding mixins is similar to adding properties through the options API because you can add them by creating and "injecting" the properties into your Vue components. However, this comes with a couple of problems, the primary one being that mixins can lead to messy code and conflicting names. This is because they dump their properties into the component.

With the composition API that was introduced in Vue 3, we can mitigate the problems we just mentioned by using composables. The Vue team created composables as a better alternative to mixins that allow for greater code reuse and structure. Additionally, they are designed specifically for each component, and don't cause any naming issues. We'll see more of this later on. In this article, we'll show you how to take your mixins and turn them into composables for even more functionality and ease of maintenance.

The Structure of a Mixin

Now, before we say goodbye to mixins and embrace composables, we need to understand the main differences between the two. In a way, a mixin is like a bag of magic tricks you can easily add to your components to do their magic. However, having all these tricks in her one backpack can make it challenging to keep track of what's happening, especially if multiple components use the same mixin. For example; if there was a data property called message in our mixin, and a property by the same name (message) in our component, the mixin message would clash with our component's message (which would have been declared in the data section of our component).

We will be going over composables next. But before we do, here's an example of a mixin:

export const testMixin = {
  data() {
    return {
      message: "This message is in our mixin!"
  methods: {
    printMessage() {

In this example, the mixin contains a data function that returns an object with a message property, as well as a printMessage method that logs the given message to the console. To use this mixin in a component, the component would need to import the mixin, and add it to its mixins option:

import testMixin from './testMixin.js';

export default {
  mixins: [testMixin],
  // The rest of your code

Creating the Composable

Composables are a new feature that was added within the Vue 3 composition API. Composables are also called composition functions. They allow us to add functionality to components in a cleaner, more maintainable way. Instead of merging properties and methods directly into the component like in a mixin, composables are explicitly tailored to the component, and return a value or a set of reactive properties. What this means is that with composables, you can group all the functionality that is related together (rather than in separate data, computed, and methods sections). Again, you also don't have name collisions anymore because each call to a composable will give you an object that is not tied to your existing component. That means that you can resolve any naming conflicts at development time rather than breaking your application because of the same thing happening at runtime as is the case with mixins.

Here is a simple composable that achieves the same result as the mixin we had created earlier.

import { ref } from 'vue';

export const useMessage = () => {
  const message = ref("This message is in our composable!");

  const printMessage = () => {

  return { message, printMessage };

Here's how the composable can be used in a .vue file component:

<script setup>
import { useMessage } from './useMessage';

const { message, printMessage } = useMessage();

// You can now access the message and printMessage in your template after extracting them from the useMessage composable

With this setup, the component will access the reactive message property and the printMessage method returned by the composable. Notice that composables allow us to add functionality to components more intuitively and easier to understand without the clutter of a mixin's structure.

In general, the naming convention for composables is useX, where X is the domain our composable is meant to represent. In this case, since our functionality is around our message, our composable is called useMessage.


In this article, we've explored how to convert Vue 2 mixins to Composition API composables. We started by understanding the structure of a simple Vue 2 mixin, which can make components challenging to maintain due to how they merge properties and methods directly into the component.

Next, we looked at how to create a composable in Vue.js 3's Composition API, which allows us to add functionality to cleaner and more maintainable components. Composables are explicitly tailored to the component and return a value or a set of reactive properties, making them easier to understand and use in components.

With this understanding of mixins and composables, developers can now confidently convert their Vue 2 mixins to Vue 3 composables, taking advantage of the new and improved functionality offered by the Composition API. By doing so, developers can create more manageable components to maintain, test, and debug, resulting in a better user experience for their applications.

Also, if you are looking to start a new Vue JS project and are not sure of how to structure your project, feel free to check out our Vue JS GitHub showcases which showcase (no kidding) a mini-GitHub clone application built using Vue in different ways (eg. using Nuxt, Quasar, Vite, etc). Alternatively, if you are simply looking to start a new project without worrying about all the config required to do so, you can check out the Vue JS starter kit instead. Either way, thanks for stopping by!

This Dot Labs is a development consultancy that is trusted by top industry companies, including Stripe, Xero, Wikimedia, Docusign, and Twilio. This Dot takes a hands-on approach by providing tailored development strategies to help you approach your most pressing challenges with clarity and confidence. Whether it's bridging the gap between business and technology or modernizing legacy systems, you’ll find a breadth of experience and knowledge you need. Check out how This Dot Labs can empower your tech journey.

You might also like

Getting Started with Vuetify in Vue 3 cover image

Getting Started with Vuetify in Vue 3

If you're here to learn about Vuetify and how to use it with Vue 3, you've come to the right place. In this article, we'll introduce Vuetify, a Material Design component framework for Vue.js, and walk you through setting it up in a Vue 3 project. We will also build a simple web app that allows us to create and vue jokes. Oh, sorry, view jokes! What is Vuetify? Vuetify is a VueJS Material Design component framework. That is to say that Vuetify provides us with prebuilt components and features (e.g. internationalization, tree shaking, theming, etc.) to help us build Vue applications faster. Additionally, Vuetify components have built-in standard functionality, such as validation in form inputs, or various disabled states in buttons. You can check out a full list of components supported by Vuetify on their official documentation website. Setting things up Before we get started, you will need the following on your machine: - NodeJS installed - A NodeJS package manager e.g. yarn or npm installed - Intermediate knowledge of Vue 3.x with the composition API If you’d like to follow along, feel free to clone the github repository for this article. `shell git clone or `` for ssh then cd into the project directory cd getting-started-with-vuetify ` Installing Vuetify We will be using yarn` to install and setup Vuetify 3 (the version that supports Vue 3) in this case. First, let's create a new Vuetify project. You can do this by running the following command in your terminal or command prompt: `shell yarn create vuetify ` This will create a new Vuetify project. For our jokes app, we will use the Essentials (Vuetify, VueRouter, Pinia)` preset when creating our app. We will also be using TypeScript for our app, but this is not necessary. Since VueJS allows us to build incrementally, if you would like to instead add Vuetify to an existing project, you can use the manual steps provided by the Vuetify team. Testing our application Once we have installed and configured our application, cd` into the project's directly, and run the app using the following command: `shell yarn dev #or npm run dev` (if using npm instead) ` Visit localhost:3000/` to see your app in action. Vuetify project folder structure Our Vuetify project is generally structured as follows: - public` - Contains static assets that do not need preprocessing eg. our application `favicon` - src` - Contains our VueJS source code. We'll mostly be working here. - assets` - Assets that need to be preprocessed eg. our images that may need to be compressed when building for production - components` - layouts` - Layouts - plugins` - Everything gets wired up here (registration of our app as well as vuetify, our router & pinia) - router` - Vue router-related functionality - store` - Pinia store - styles` - views` - our web app's "pages" Worth noting before building It is worth noting that all components in Vuetify start with a v-` for example: - v-form` is a form - v-btn` is a button component - v-text-field` is an input field and so on and so forth. When creating your own components, it is recommended to use a different naming approach so that it is easier to know which components are Vuetify components, and which ones are your components. Building our Vuetify application We will build a web app that allows us to add, view and delete jokes. Here are the steps we will take to build our app: - Delete unnecessary boilerplate from generated Vuetify app - Add a joke` pinia store - we'll be using this to store our jokes globally using Pinia - Create our joke components - components/jokes/CreateJokeForm.vue` - the form that allows us to add jokes - components/jokes/JokeList.vue` - Lists our jokes out. - Add our components to our Home.vue` to view them in our home page Setting up the jokes pinia store In the src/store/` directory, create a new file called `joke.ts` that will serve as our Pinia store for storing our jokes. The file content for this will be as follows: `ts import { defineStore } from "pinia"; export interface Joke { id: number; title: string; punchline: string; } export const useJokeStore = defineStore({ id: "joke", state: () => ({ jokes: [] as Joke[], }), actions: { addJoke(joke: Joke) { this.jokes.push(joke); }, removeJoke(id: number) { this.jokes = this.jokes.filter((joke) => !== id); }, }, }); ` This code defines a special storage space called a "store" for jokes in our Vue.js app. This store keeps track of all the jokes we've added through our app's form. Each joke has an ID, title, and punchline. The addJoke` function in the store is used to add a new joke to the store when a user submits the form. The `removeJoke` function is used to delete a joke from the store when a user clicks the delete button. By using this store, we can keep track of all the jokes that have been added through the app, and we can easily add or remove jokes without having to manage the list ourselves. Creating the joke components CreateJokeForm.vue Create a file in src/components/jokes/` called `CreateJokeForm.vue`. This file defines a Vue.js component that displays a form for adding new jokes. The file should have the following contents: Template section `html Submit Joke ` In the template section, we define a form using the v-form component from Vuetify. We bind the form's submit event to the submitJoke method, which will be called when the form is submitted. Inside the form, we have two text fields" one for the joke title, and one for the punchline. These text fields are implemented using the v-text-field component from Vuetify. The label prop sets the label for each text field, and the outlined prop creates an outlined style for each text field. The required prop sets the fields as required, meaning that they must be filled in before the form can be submitted. Finally, we have a submit button implemented using the v-btn component from Vuetify. The button is disabled until both the title and punchline fields are filled in, which is accomplished using the :disabled prop with a computed property that checks if both fields are empty. Script section `ts import { computed, ref } from "vue"; import { Joke, useJokeStore } from "@/store/joke"; const jokeStore = useJokeStore(); const jokeTitle = ref(""); const jokePunchline = ref(""); const joke = computed(() => ({ id: jokeStore.jokes.length + 1, title: jokeTitle.value, punchline: jokePunchline.value, })); function submitJoke() { jokeStore.addJoke(joke.value); jokeTitle.value = ""; jokePunchline.value = ""; } ` In the script section, we import some functions and types from Vue.js and the joke` store. We then define a `jokeStore` variable that holds the instance of the `useJokeStore` function from the `joke` store. We also define two ref`s, `jokeTitle`, and `jokePunchline`, which hold the values of the form's title and punchline fields, respectively. We then define a computed property, joke`, which creates a new `Joke` object using the `jokeTitle` and `jokePunchline` refs, as well as the length of the `jokes` array in the `jokeStore` to set the `id` property. Finally, we define a submitJoke` function that calls the `addJoke` method from the `jokeStore` to add the new `joke` object to the store. We also reset the `jokeTitle` and `jokePunchline` refs to empty strings. JokeList.vue Template section This one looks bulky. But in essence, all we are doing is displaying a list of jokes when they are found, and a message that lets us know that there are no jokes if we have none that have been added. `html My Jokes {{ joke.title }} {{ joke.punchline }} mdi-delete You have no jokes. Add some! ` In the template section, we define a v-card` component, which is a container component used to group related content in Vuetify. The card contains a title, which includes an excited emoticon icon from the `mdi-emoticon-excited-outline` icon set from Material Design Icons, displayed using the `v-icon` component. The jokes are displayed in a v-list`, which is a component used to display lists in Vuetify. Each joke is represented by a `v-list-item` containing a title and subtitle. The `v-row` and `v-col` components from Vuetify are used to divide each list item into two columns: one column for the joke title and punchline, and another column for the delete button. The delete button is implemented using the v-btn` component from Vuetify. The button is red, and outlined using the `color="error"` and `variant="outlined"` props, respectively. The `@click` event is used to call the `deleteJoke` function when the button is clicked. If there are no jokes in the jokeStore`, the component displays an `v-alert` component with a message to add some jokes. Script section `ts import { Joke, useJokeStore } from "@/store/joke"; const jokeStore = useJokeStore(); function deleteJoke(joke: Joke) { jokeStore.removeJoke(; } ` In the script section, we import some functions and types from the joke` store. We then define a `jokeStore` variable that holds the instance of the `useJokeStore` function from the `joke` store. We also define a deleteJoke` function that takes a `joke` object as an argument and calls the `removeJoke` method from the `jokeStore` to remove the joke from the store. This component is called JokeList.vue` and displays a list of jokes using Vuetify components like `v-card`, `v-list`, `v-list-item`, `v-row`, `v-col`, and `v-btn`. The component includes a `deleteJoke` function to remove a joke from the `jokeStore` as well. Wiring it up To display our form as well as list of jokes, we will go to the src/views/Home.vue` file and change its contents to the following: `html import CreateJokeForm from "@/components/jokes/CreateJokeForm.vue"; import JokeList from "@/components/jokes/JokeList.vue"; ` The Home.vue` file defines a Vue.js view that displays the home page of our app. The view contains a `v-container` component, which is a layout component used to provide a responsive grid system for our app. Inside the v-container`, we have a `v-row` component, which is used to create a horizontal row of content. The `v-row` contains two `v-col` components, each representing a column of content. The `cols` prop specifies that each column should take up 12 columns on small screens (i.e. the entire row width), while on medium screens, each column should take up 6 columns (i.e. half the row width). The first v-col` contains the `CreateJokeForm` component, which displays a form for adding new jokes. The second `v-col` contains the `JokeList` component, which is used to display a list of jokes that have been added through the form. In the script` section of the file, we import the `CreateJokeForm` and `JokeList` components, and register them as components for use in the template. This view provides a simple and responsive layout for our app's home page, with the CreateJokeForm` and `JokeList` components displayed side by side on medium screens and stacked on small screens. Bonus: Layouts & Theming Layouts Even though we had no need to adjust our layouts in our current jokes application, layouts are an important concept in Vuetify. They allow us to pre-define reusable layouts for our applications. These could include having a different layout for when users are logged in, and when they are logged out or layouts for different types of users. In our application, we used the default Layout (src/layouts/default/Default.vue`) but Vuetify offers us the flexibility to build different layouts for the different domains in our applications. Vuetify also supports nested layouts. You can learn more about layouts in Vuetify in the official Vuetify documentation. Theming If you have specific brand needs for your application. Vuetify has a built-in theming system that allows you to customize the look and feel of your application. You can learn more about theming in the official Vuetify theming documentation. Conclusion In this article, we introduced Vuetify, and covered how to set it up with Vue 3. We built a VueJS app that allows us to add and manage jokes. We also discussed how to use various Vuetify components to compose our UI, from v-form` for declaring forms to `v-row` for creating a row/column layout, and `v-list` for displaying a list of items among others. With this knowledge, you can start using Vuetify in your Vue 3 projects and create stunning user interfaces. Also, if you'd like to start your own VueJS project but need help with how to structure it or would like to skip the tedious setup steps of setting up a VueJS project, you can use the Vue 3 kit to skip the boilerplate and start building! Next steps for learning Vuetify and Vue 3 development Now that you have an understanding of Vuetify, it's time to dive deeper into its features, and explore more advanced use cases. To continue your learning journey, consider the following resources: 1. Official Vuetify documentation: The Vuetify documentation is an excellent resource for learning about all the features and components Vuetify offers. 2. Vue 3 documentation: To get the most out of Vuetify, it's essential to have a solid understanding of Vue 3. Read the official Vue 3 documentation and practice building Vue applications. Happy coding, and have fun exploring the world of Vuetify and Vue 3!...

Introducing the Vue 3 and XState kit for cover image

Introducing the Vue 3 and XState kit for is an open source community resource developed by This Dot Labs that provides code starter kits in a variety of web technologies, including React, Angular, Vue, etc. with the hope of enabling developers to bootstrap their projects quickly without having to spend time configuring tooling.* Intro Today, we’re delighted to announce a new starter kit featuring Vue and XState! In this blog post, we’ll dive into what’s included with the kit, how to get started using it, and what makes this kit unique. What’s included All of our kits strive to provide you with popular and reliable frameworks and libraries, along with recommended tooling all configured for you, and designed to help you spin your projects up faster. This kit includes: - Vue as the core JS framework - XState for managing our application’s state - CSS for styling - Cypress component testing - Vue Router to manage navigation between pages - Storybook for visual prototyping - ESlint and Prettier to lint and format your code How to get started using the kit To get started using this kit, we recommend the starter CLI tool. You can pass in the kit name directly, and the tool will guide you through naming your project, installing your dependencies, and running the app locally. Each kit comes with some sample components, so you can see how the provided tooling works together right away. `js // npm npm create @this-dot/create-starter -- --kit vue3-xstate-css // yarn yarn create @this-dot/create-starter --kit vue3-xstate-css ` Now let’s dive into some of the unique aspects of this kit. Vue 3 Vue is a very powerful JS framework. We chose to use Vue directly to highlight some of the features that make it such a joy to work with. One of our favorite features is Vue’s single file components (SFC). We can include our JavaScript, HTML, and CSS for each component all in the same file. This makes it easier to keep all related code directly next to each other, making it easier to debug issues, and allowing less file flipping. Since we’re in Vue 3, we’re also able to make use of the new Composition API, which looks and feels a bit more like vanilla JavaScript. You can import files, create functions, and do most anything you could in regular JavaScript within your component’s script tag. Any variable name you create is automatically available within your HTML template. Provide and Inject Another feature we got to use specifically in this starter kit is the new provide and inject functionality. You can read more details about this in the Vue docs, but this feature gives us a way to avoid prop drilling and provide values directly where they’re needed. In this starter kit, we include a “greeting” example, which makes an API call using a provided message, and shows the user a generated greeting. Initially, we provided this message as a prop through the router to the greeting component. This works, but it did require us to do a little more legwork to provide a fallback value, as well as needing our router to be aware of the prop. Using the provide / inject setup, we’re able to provide our message through the root level of the app, making it globally available to any child component. Then, when we need to use it in our `GreetView``` component, we inject the “key” we expect (our message), and it provides a built-in way for us to provide a default value to use as a fallback. Now our router doesn’t need to do any prop handling! And our component consistently works with the provided value or offers our default if something goes wrong. ` // src/main.ts const app = createApp(App); app.provide('query', 'from This Dot Labs!'); ` ` // src/views/GreetView.vue import { inject } from 'vue'; const providedQuery = inject('query', ''); const { state } = useMachine(greetMachine(providedQuery)); ` Using XState If you haven’t had a chance to look into XState before, we highly recommend checking out their documentation. They have a great intro to state machines and state charts that explains the concepts really well. One of the biggest mindset shifts that happens when you work with state machines is that they really help you think through how your application should work. State machines make you think explicitly through the different modes or “states” your application can get into, and what actions or side effects should happen in those states. By thinking directly through these, it helps you avoid sneaky edge cases and mutations you don’t expect. Difference between Context and State One of the parts that can be a little confusing at first is the difference between “state” and “context” when it comes to state machines. It can be easy to think of state as any values you store in your application that you want to persist between components or paths, and that can be accurate. However, with XState, a “state” is really more the idea of what configurations your app can be in. A common example is a music player. Your player can be in an “off” state, a “playing” state, or a “paused” state. These are all different modes, if you will, that can happen when your music player is interacted with. They can be values in a way, but they’re really more like the versions of your interface that you want to exist. You can transition between states, but when you go back to a specific state, you expect everything to behave the same way each time. States can trigger changes to your data or make API calls, but each time you enter or leave a state, you should be able to see the same actions occur. They give you stability and help prevent hidden edge cases. Values that we normally think of as state, things like strings or numbers or objects, that might change as your application is interacted with. These are the values that are stored in the “context” within XState. Our context values are the pieces of our application that are quantitative and that we expect will change as our application is working. ` export const counterMachine = createMachine( { id: 'Counter', initial: 'active', context: { count: 0, }, states: { active: { on: { INC: { actions: 'increment' }, DEC: { actions: 'decrement' }, RESET: { actions: 'reset' }, }, }, }, }, { actions: { increment: assign({ count: (context) => context.count + 1 }), decrement: assign({ count: (context) => context.count - 1 }), reset: assign({ count: (context) => (context.count = 0) }), }, } ); ` Declaring Actions and Services When we create a state machine with XState, it accepts two values- a config object and an options object. The config tells us what the machine does. This is where we define our states and transitions. In the options object, we can provide more information on how the machine does things, including logic for guards, actions, and effects. You can write your actions and effect logic within the state that initiates those calls, which can be great for getting the machine working in the beginning. However, it’s recommended to make those into named functions within the options object, making it easier to debug issues and improving the readability for how our machine works. Cypress Testing The last interesting thing we’d like to talk about is our setup for using component testing in Cypress! To use their component testing feature, they provide you with a mount command, which handles mounting your individual components onto their test runner so you can unit test them in isolation. While this works great out of the box, there’s also a way to customize the mount command if you need to! This is where you’d want to add any configuration your application needs to work properly in a testing setup. Things like routing and state management setups would get added to this function. Since we made use of Vue’s provide and inject functions, we needed to add the provided value to our `mount``` command in order for our greeting test to properly work. With that set up, we can allow it to provide our default empty string for tests that don’t need to worry about injecting a value (or when we specifically want to test our default value), and then we can inject the value we want in the tests that do need a specific value! ` // cypress/support/component.ts Cypress.Commands.add('mount', (component, options = {}) => { = || {}; = || {}; return mount(component, options); }); ` Conclusion We hope you enjoy using this starter kit! We’ve touched a bit on the benefits of using Vue 3, how XState keeps our application working as we expect, and how we can test our components with Cypress. Have a request or a question about a [] project? Reach out in the issues to make your requests or ask us your questions. The project is 100% open sourced so feel free to hop in and code with us!...

Nuxt 3 Demo App with Prerender and SSR cover image

Nuxt 3 Demo App with Prerender and SSR

Introduction The quest for an optimal web application involves numerous factors, such as performance, user experience, and search engine optimization (SEO). Nuxt 3 provides excellent features out-of-the-box that can help you tackle these aspects efficiently. This article will guide you in creating a Nuxt 3 application using Server Side Rendering (SSR) and pre-rendering capabilities. We'll craft an application that offers a seamless user experience, superior performance, and improved SEO. Server Side Rendering in Nuxt 3 Enhancing User Experience and SEO with SSR In the world of web development, Server Side Rendering (SSR) has gained significant traction. It refers to the server rendering the webpage upon each request rather than the client. With SSR, your web page arrives fully formed at the client's doorstep, reducing the time for the first painting. The advantage of SSR extends beyond just performance and user experience. It's also a darling of search engine crawlers, which find it easier to index your website with fully formed page content at the time of their crawl. In simple terms, it's like providing a tour guide to lead the search engine around your website, ensuring they get all the spots! The Power of SSR in Nuxt 3 Nuxt 3 has built-in support for SSR by default. It allows you to optimize your application by loading the data before rendering the page. To take advantage of SSR, you simply build your application as you usually would. In this case, using the fetch() method to load some. `html import { ref } from 'vue' const data = ref(null) async function fetchData() { const response = await fetch('') const jsonData = await response.json() data.value = jsonData } fetchData() Data fetched from the server {{ data }} ` In this example, the fetchData function fetches the data before rendering the page. The data then gets displayed within the ` tag. Sidenote, if you wanted to disable SSR in your Nuxt application, you would do so in your nuxt.config.ts file: `ts export default defineNuxtConfig({ ssr: false # this usually defaults to true }) `` More details on how this works can be found in the rendering modes section in the official Nuxt 3 documentation. Pre-rendering in Nuxt 3 Amplifying Application Performance with Pre-rendering While SSR has its advantages, another superhero in our story is pre-rendering. Pre-rendering refers to the process of generating the static HTML pages of a site in advance. It's like preparing a feast before the guests arrive so you can serve them promptly. Like SSR, pre-rendering enhances SEO, as search engines can index fully rendered pages. Especially for content-heavy applications, pre-rendering can give a turbo boost to performance, leading to better user engagement and retention. Leverage Pre-rendering with Nuxt 3 Nuxt 3 supports SSR and Static Site Generation (SSG), including pre-rendering. To enable prerendering, you need to export your routes in nuxt.config.ts`: `ts export default defineNuxtConfig({ nitro: { prerender: { routes: ['/route1', '/route2', '/route3'] } } }) ` These routes will be pre-rendered during the build phase, allowing for swift navigation. Let's update our application to pre-render the users' list: `html import { ref } from 'vue' const users = ref([]) async function fetchUsers() { const response = await fetch('') const userJson = await response.json() users.value = userJson } fetchUsers() Users {{ }} ` In the nuxt.config.ts`, include the users' route for pre-rendering: `ts export default defineNuxtConfig({ nitro: { prerender: { routes: ['/users'] } } }) ` Going beyond with Nuxt 3 While SSR and pre-rendering are significant for performance and SEO, Nuxt 3 offers more advanced features like hot module replacement, Vue 3 integration, improved error handling, and more. Nuxt 3 also has different kinds of rendering modes for different applications; in our SSR case, we used the default Universal rendering mode. Leveraging these features allows you to develop robust, high-performance, and user-friendly applications. Conclusion In this article, we delved into the concepts of SSR and pre-rendering in Nuxt 3. We explored how these techniques contribute to enhancing performance, user experience, and SEO. You can create exceptional web applications by integrating Vue 3's capabilities with Nuxt 3's robust features. A well-structured, performant, and SEO-friendly application not only attract users but also retains them. Embrace the power of Nuxt 3 and Vue 3 in your development journey. Happy coding!...

Testing a Fastify app with the NodeJS test runner cover image

Testing a Fastify app with the NodeJS test runner

Introduction Node.js has shipped a built-in test runner for a couple of major versions. Since its release I haven’t heard much about it so I decided to try it out on a simple Fastify API server application that I was working on. It turns out, it’s pretty good! It’s also really nice to start testing a node application without dealing with the hassle of installing some additional dependencies and managing more configurations. Since it’s got my stamp of approval, why not write a post about it? In this post, we will hit the highlights of the testing API and write some basic but real-life tests for an API server. This server will be built with Fastify, a plugin-centric API framework. They have some good documentation on testing that should make this pretty easy. We’ll also add a SQL driver for the plugin we will test. Setup Let's set up our simple API server by creating a new project, adding our dependencies, and creating some files. Ensure you’re running node v20 or greater (Test runner is a stable API as of the 20 major releases) Overview `index.js` - node entry that initializes our Fastify app and listens for incoming http requests on port 3001 `app.js` - this file exports a function that creates and returns our Fastify application instance `sql-plugin.js` - a Fastify plugin that sets up and connects to a SQL driver and makes it available on our app instance Application Code A simple first test For our first test we will just test our servers index route. If you recall from the app.js` code above, our index route returns a 501 response for “not implemented”. In this test, we're using the createApp` function to create a new instance of our Fastify app, and then using the `inject` method from the Fastify API to make a request to the `/` route. We import our test utilities directly from the node. Notice we can pass async functions to our test to use async/await. Node’s assert API has been around for a long time, this is what we are using to make our test assertions. To run this test, we can use the following command: By default the Node.js test runner uses the TAP reporter. You can configure it using other reporters or even create your own custom reporters for it to use. Testing our SQL plugin Next, let's take a look at how to test our Fastify Postgres plugin. This one is a bit more involved and gives us an opportunity to use more of the test runner features. In this example, we are using a feature called Subtests. This simply means when nested tests inside of a top-level test. In our top-level test call, we get a test parameter t` that we call methods on in our nested test structure. In this example, we use `t.beforeEach` to create a new Fastify app instance for each test, and call the `test` method to register our nested tests. Along with `beforeEach` the other methods you might expect are also available: `afterEach`, `before`, `after`. Since we don’t want to connect to our Postgres database in our tests, we are using the available Mocking API to mock out the client. This was the API that I was most excited to see included in the Node Test Runner. After the basics, you almost always need to mock some functions, methods, or libraries in your tests. After trying this feature, it works easily and as expected, I was confident that I could get pretty far testing with the new Node.js core API’s. Since my plugin only uses the end method of the Postgres driver, it’s the only method I provide a mock function for. Our second test confirms that it gets called when our Fastify server is shutting down. Additional features A lot of other features that are common in other popular testing frameworks are also available. Test styles and methods Along with our basic test` based tests we used for our Fastify plugins - `test` also includes `skip`, `todo`, and `only` methods. They are for what you would expect based on the names, skipping or only running certain tests, and work-in-progress tests. If you prefer, you also have the option of using the describe` → `it` test syntax. They both come with the same methods as `test` and I think it really comes down to a matter of personal preference. Test coverage This might be the deal breaker for some since this feature is still experimental. As popular as test coverage reporting is, I expect this API to be finalized and become stable in an upcoming version. Since this isn’t something that’s being shipped for the end user though, I say go for it. What’s the worst that could happen really? Other CLI flags —watch` - —test-name-pattern` - TypeScript support You can use a loader like you would for a regular node application to execute TypeScript files. Some popular examples are tsx` and `ts-node`. In practice, I found that this currently doesn’t work well since the test runner only looks for JS file types. After digging in I found that they added support to locate your test files via a glob string but it won’t be available until the next major version release. Conclusion The built-in test runner is a lot more comprehensive than I expected it to be. I was able to easily write some real-world tests for my application. If you don’t mind some of the features like coverage reporting being experimental, you can get pretty far without installing any additional dependencies. The biggest deal breaker on many projects at this point, in my opinion, is the lack of straightforward TypeScript support. This is the test command that I ended up with in my application: I’ll be honest, I stole this from a GitHub issue thread and I don’t know exactly how it works (but it does). If TypeScript is a requirement, maybe stick with Jest or Vitest for now 🙂...