If you work in software development, you probably know a thing or two about using and maintaining third-party packages. While third-party tooling has its fair share of downsides, there are plenty of advantages as well. The efficiency you get from code that someone else has already written speeds up development and is hard to deny. Sure, there are all sorts of considerations to take in before plopping code from a third party — accessibility, technical debt, and security, to name a few — but the benefits may make taking on those considerations worthwhile for your team.

Upgrades are also part of that set of considerations. Usually, your team may treat this sort of maintenance as a simple task or chore: upgrading dependencies and (automatically) validating that all of the features keep functioning as expected. You probably even have automated checks for keeping all package versions up to date.

But what if the third-party tooling you adopt is big? I mean big, big. That’s common in large organizations. I happen to work for a fairly large organization that leverages big third-party resources, and upgrading those tools is never as simple as running a package update and moving on. I thought I’d share what’s involved in that process because there are many moving pieces that require ample planning, strategy, and coordination. Our team has learned a lot about the process that I hope will benefit you and your team as well.

Some Context On My Organization

I work for Jumbo Supermarkten in the Jumbo Tech Campus (JTC), which is a department of over 350 developers working in agile teams on a range of digital products that help facilitate our core grocery and e-commerce processes.

We have a variety of responsibilities, where 70% of the work is allocated to the primary objectives for each team, and the remaining 30% is dedicated to anything a team wants, as long as it is beneficial to the JTC, which is very useful if you want to deliver value outside of your own team.

When we look at maintaining tooling and packages, balancing the goals of each team with the goals of JTC means that teams effectively maintain their own codebases while also collectively maintaining internally shared codebases that serve as the tooling and foundation of our applications.

Centralized Code As A Bottleneck

To build our applications with consistent standards, we rely on an internal design system and the component library we call Kompas (Dutch for “Compass”). We have built this system ourselves and rely on Vue to render our components and build interactions. Kompas is a hard dependency for virtually all of our applications to ensure uniformity.

This project was not allocated to a dedicated team. Instead, we adopted a strategy that introduced plenty of guidance to allow all front-end developers to contribute. Any developer can add new components to the library as well as features to existing components and keep everything in sync with the designs.

Teams normally work on business features since product owners love delivering customer value. The way we set up our process would allow a team to, in one sprint:

• Make the required change in Kompas,
• Have it reviewed by peers from both inside and outside a particular team,
• Publish the latest version of the component library, and
• Use that version in that team’s own application to deliver to the end user.

We can only do this with automation on repetitive processes — linting, formatting, quality assurance, testing, visual comparisons, and publishing — in order to provide enough room for developers to contribute to the process. Our component library is very much a living document of our design system, with multiple minor releases and patches a week. With semantic versioning, we can keep our own applications up to date easily and with confidence.

For bigger undertakings, such as setting up visual snapshot tests, we established temporary working groups alongside our existing teams that we called “front-end chapters” where members join on a voluntary basis. In these meetings, we discuss what needs to be done, and in the available 30% of free time we are allotted, the members of these teams carry out the work and report back to the chapter.

As you can imagine, we’ve spent a lot of time and effort ensuring the quality and making it a reliable part of our landscape.

This all began when Vue was in Version 2. That’s the version we baked into Kompas, which means we effectively forced our whole application landscape to follow suit. This worked perfectly for us; people could focus on their team’s needs while leaning on the support of the entire front-end chapter that works on Kompas.

Following the Vue ecosystem that we introduced, Vuex and Nuxt became part of our environment. And then Vue 3 was announced, and it was a massive breaking change from Vue 2! With the announcement, the end-of-life date for Vue 2 was set for December 31, 2023. We still have some time as of this writing, but the news had a massive impact that cascaded throughout our organization.

We Needed A Strategy

We needed to upgrade Vue from 2 to 3. The first thing that we needed to figure out was when we could reasonably start the process. To assess and strategize, we formed a small virtual team of developers consisting of members from various teams so that multiple perspectives were represented.

We figured that there would be a period of time when we would need to support both versions in order to allow time for migrating between teams. It would be nearly impossible to orchestrate a monolithic release. Thus, we prefer gradual incrementing over massive sweeping changes. On the other hand, having to maintain two versions of Vue for, basically, the same business feature presented costs in time and complexity.

So, in order to execute this process as responsibly as possible, we set out to figure out when we could start, taking into account the longevity of maintaining two codebases while getting early experience from upgrading. We started to map the different tech stacks for each team and plotted out potential bottlenecks for the sake of making the process of our work as widely visible as possible. At this time, our organization had a very flat structure, so we also needed to get internal stakeholders (i.e., product owners, architects, and managers) involved and convey the effect this upgrade would have on teams across the board.

Creating A Map

With our starting point set, we move on to establish a direction. Not having a dedicated team did pose some challenges because it meant that we needed to align everybody in a democratic way. This is, in Dutch culture, also known as polderen:

We try to find consensus in a way where everybody is equally happy, or unhappy, about the final direction.

And this can be challenging in a department that consists of many cultures!

One thing we knew we could rely on was the published best practices from official Vue resources to guide our decision-making process. Referencing the documentation, we did notice opportunities for incremental upgrades. The release of Vue 2.7 (Naruto) was really helpful in the sense that it backported features from Vue 3 back to a Vue 2-compatible version.

We also noted that in our landscape, not all applications were actually using Nuxt. A stable release of Nuxt 3 would be a prerequisite for those applications to even be considered for migration since the Vue major version is tightly coupled with the Nuxt major version. Luckily, some applications in our landscape are standalone Vue apps. These are ideal candidates for the first Vue 3-compatible components.

But first, we would need to have components that were compatible with Vue 3.

The Big Divide

By this point, we were confident enough to get to work. We had a plan and clear strategy, after all. The first order of business was to make sure that our component library was compatible with Vue 3, preferably while minimizing duplicative efforts.

We found a really nice way of doing this:

We created a new workspace called “Kompas-next” next to the regular components folder, which was scaffolded out using Vue 3. Then we imported the components from the original library.

“

This only works because:

• The backported features in Vue 2.7 allowed us to move closer toward the Vue 3 composition API (among other things).
• The component syntax between Vue 2 and Vue 3 isn’t radically different anymore.
• Vue Demi allowed us to convert components, one by one, to be compatible with both versions.
• We made sure that Kompas-next runs isolated tests to ensure stability.

We did have to slightly modify each and every component to adapt to the new standards. We’ll get to that process in a minute.

That said, we were able to publish two versions of our component library: one that is compatible with Vue 2 (Kompas) and one that is compatible with Vue 3 (Kompas-next). This, in turn, meant that the teams that did not have Nuxt as a dependency could potentially start migrating!

Getting Organized

Up to this point, most of the groundwork had been done in a relatively small team. We were in charge of the investigations, communication, and alignment. But we still needed to get stuff done — a lot of stuff!

With every developer being able to contribute, we came to an agreement that fits with the way everybody was already contributing to the component library:

If you touch a component that is not yet compatible, convert it to be compliant with both Vue 2 and Vue 3 using Vue-demi. Add the existing component with tests to the imports of the Kompas-next folder.

Having communicated this strategy early in the process, we immediately saw the Kompas-next library growing. The Vue core team has put so much effort into closing the gap between the two versions, which made our lives much easier.

Feedback From Early Adopters

The teams that were not blocked by a Nuxt 3 release could spend their time migrating their complete app to Vue 3, providing feedback along the way on how we were setting up our packages and converting components.

Seeing the first applications using Vue 3 was a milestone we could all be proud of since we managed to reach it together, collaboratively, and with a united strategy. The strategy worked for us because it closely resembled the way we were already working.

There were indeed some components that were not migrated using this strategy, which indicated to us that they were stale in terms of development. We reasoned that “stale” equals “stable” and that it would be perfectly fine to migrate them by manual assignment and distribution since we can expect it to be close to a one-off migration per component.

We also started to add Vue 3-specific capabilities to our component library, such as our own composables. I think that’s a nice testament to the investment and adoption by our front-end chapter.

With the component library now supporting Vue, we cleared a significant migration hurdle in our organization. We enabled teams to start migrating to Vue 3, and we encouraged new applications to use the latest standards. As a result, we could start thinking about a deprecation path for our Vue 2 codebase. We were cautiously optimistic and aligned the end-of-life date for Kompas with the same date for Vue 2: December 31, 2023.

So, yes, we are not yet finished and still have work to do. In fact, we had…

Two (Minor) Elephants In The Room

To support communication between micro-applications that run on our e-commerce domain, we had resorted to using Vuex in the past. We used to register stores globally so other applications could dispatch actions and retrieve a shared state. This is now gradually being migrated in the sense that we are replacing Vuex with Pinia for internal state management.

For cross-app communication, we are in the process of decoupling Vuex as an external interface and promoting the use of custom events tied to a specific domain. This prevents us from locking ourselves out of future state management tooling.

We are also in the process of preparing our Nuxt applications to be cleared for migration as well. Within our e-commerce domain, we’ve been building specific modules that take a lot of overhead out of our hands: They handle tasks like setting meta headers, security, and analytics. These are being rewritten to use plugins rather than modules. The impact of this breaking change is smaller because it is limited to the teams that use these modules. We see that these teams are using a similar strategy, albeit on a smaller scale, to organize and structure the tasks at hand.

Looking Back

I believe we have a few key takeaways from how we upgraded (and continue to upgrade) from one version of a large third-party resource to another within our large network of teams and shared codebases. I believe the lessons we learned are relevant beyond Vue and can be applied to the processes of other large organizations migrating between versions of a core piece of architecture.

Let’s review what we learned:

• Ensure the transition period is clear and as short as possible.
• Facilitate breaking the work down into small steps that progress iteratively and solicit feedback from those involved in the process as early and as often as possible.
• Onboard key stakeholders to make sure your team has ample time and resources to do the work.
• Define a strategy that fits with your organization’s culture.
• Foster a collaborative mindset and establish clear communication between teams.
• Celebrate wins, even the smallest ones!

The Work Is Never Done, Really

As I mentioned earlier, maintenance is a never-ending piece of the software development process. As Vue creator Evan You stated in the State of the Vuenion 2023, Vue plans to ship more frequent updates and releases. This will keep impacting our work, but that’s okay. We have a plan and blueprint for future releases.

We’re not there yet, but we now know how to get there!

Further Reading On SmashingMag

• How To Maintain A Large Next.js Application, Nirmalya Ghosh
• Moving From Vue 1 To Vue 2 To Vue 3: A Case Study Of Migrating A Headless CMS System, Lisi Linhart
• Optimizing A Vue App, Michelle Barker
• Why Web Application Maintenance Should Be More Of A Thing, Darren Beale

(gg, yk, il)

More often than not, web engineers always have causes to build out forms, from simple to complex. It is also a familiar pain in the shoe for engineers how fast codebases get incredibly messy and incongruously lengthy when building large and complex forms. Thus begging the question, “How can this be optimized?”.

Consider a business scenario where we need to build a waitlist that captures the name and email. This scenario only requires two/three input fields, as the case may be, and could be added swiftly with little to no hassle. Now, let us consider a different business scenario where users need to fill out a form with ten input fields in 5 sections. Writing 50 input fields isn’t just a tiring job for the Engineer but also a waste of great technical time. More so, it goes against the infamous “Don’t Repeat Yourself” (DRY) principle.

In this article, we will focus on learning to use the Vue components, the v-model directive, and the Vue props to build complex forms in Vue.

The v-model Directive In Vue

Vue has several unique HTML attributes called directives, which are prefixed with the v-. These directives perform different functions, from rendering data in the DOM to manipulating data.

The v-model is one such directive, and it is responsible for two-way data binding between the form input value and the value stored in the data property. The v-model works with any input element, such as the input or the select elements. Under the hood, it combines the inputted input value and the corresponding change event listener like the following:

<!-- Input element -->
<input v-model="inputValue" type="text">

<!-- Select element -->
<select v-model="selectedValue">
  <option value="">Please select the right option</option>
  <option>A</option>
  <option>B</option>
  <option>C</option>
</select>

The input event is used for the <input type= "text"> element. Likewise, for the <select> … </select>, <input type= "checkbox"> and <input type= "radio">, the v-model will, in turn, match the values to a change event.

Components In Vue

Reusability is one of the core principles of Software Engineering, emphasizing on using existing software features or assets in a software project for reasons ranging from minimizing development time to saving cost.

One of the ways we observe reusability in Vue is through the use of components. Vue components are reusable and modular interfaces with their own logic and custom content. Even though they can be nested within each other just as a regular HTML element, they can also work in isolation.

Vue components can be built in two ways as follows:

• Without the build step,
• With the build step.

Without The Build Step

Vue components can be created without using the Vue Command Line Interface (CLI). This component creation method defines a JavaScript object in a Vue instance options property. In the code block below, we inlined a JavaScript string that Vue parses on the fly.

template: `
  <p> Vue component without the build step </p>
  `

With The Build Step

Creating components using the build step involves using Vite — a blazingly fast, lightweight build tool. Using the build step to create a Vue component makes a Single File Component (SFC), as it can cater to the file’s logic, content, and styling.

<template>
  <p> Vue component with the build step </p>
</template>

In the above code, we have the <p> tag within the HTML <template> tag, which gets rendered when we use a build step for the application.

Registering Vue Components

Creating a Vue component is the first step of reusability and modularity in Vue. Next is the registration and actual usage of the created Vue component.

Vue components allow the nesting of components within components and, even more, the nesting of components within a global or parent component.

Let’s consider that we stored the component we created using the build step in a BuildStep.vue file. To make this component available for usage, we will import it into another Vue component or a .vue, such as the root entry file. After importing this component, we can then register the component name in the components option property, thus making the component available as an HTML tag. While this HTML tag will have a custom name, the Vue engine will parse them as valid HTML and render them successfully in the browser.

<!-- App.vue -->
<template>
  <div>
    <BuildStep />
  </div>
</template>

<script>
import BuildStep from './BuildStep.vue'

export default {
  components: {
    BuildStep
  }
}
</script>

From the above, we imported the BuildStep.vue component into the App.vue file, registered it in the components option property, and then declared it within our HTML template as <BuildStep />.

Vue Props

Vue props, otherwise known as properties, are custom-made attributes used on a component for passing data from the parent component to the child component(s). A case where props can come in handy is when we need a component with different content but a constant visual layout, considering a component can have as many props as possible.

The Vue prop has a one-way data flow, i.e., from the parent to the child component. Thus, the parent component owns the data, and the child component cannot modify the data. Instead, the child component can emit events that the parent component can record.

Props Declaration In Vue

Let us consider the code block below:

<template>
  <p> Vue component {{ buildType }} the build step</p>
</template>

<script>
export default {
  props: {
    buildType: {
      type: String
    }
  }
}
</script>

We updated the HTML template with the interpolated buildType, which will get executed and replaced with the value of the props that will be passed down from the parent component.

We also added a props tag in the props option property to listen to the props change and update the template accordingly. Within this props option property, we declared the name of the props, which matches what we have in the <template> tag, and also added the props type.

The props type, which can be Strings, Numbers, Arrays, Boolean, or Objects, acts as a rule or check to determine what our component will receive.

In the example above, we added a type of String; we will get an error if we try to pass in any other kind of value like a Boolean or Object.

Passing Props In Vue

To wrap this up, we will update the parent file, i.e., the App.vue, and pass the props accordingly.

<!-- App.vue -->
<template>
  <div>
    <BuildStep buildType="with"/>
  </div>
</template>

<script>
import BuildStep from './BuildStep.vue'

export default {
  components: {
    BuildStep
  }
}
</script>

Now, when the build step component gets rendered, we will see something like the following:

Vue component with the build step

With props, we needn’t create a new component from scratch to display whether a component has a build step or not. We can again declare the <BuildStep /> component and add the relevant build type.

<!-- App..vue -->
<template>
  <div>
    <BuildStep buildType="without"/>
  </div>
</template>

Likewise, just as for the build step, when the component gets rendered, we will have the following view:

Vue component without the build step

Event Handling In Vue

Vue has many directives, which include the v-on. The v-on is responsible for listening and handling DOM events to act when triggered. The v-on directive can also be written as the @ symbol to reduce verbosity.

<button @click="checkBuildType"> Check build type </button>

The button tag in the above code block has a click event attached to a checkBuildType method. When this button gets clicked, it facilitates executing a function that checks for the build type of the component.

Event Modifiers

The v-on directive has several event modifiers that add unique attributes to the v-on event handler. These event modifiers start with a dot and are found right after the event modifier name.

<form @submit.prevent="submitData">
 ...
<!-- This enables a form to be submitted while preventing the page from being reloaded. -->
</form>

Key Modifiers

Key modifiers help us listen to keyboard events, such as enter, and page-up on the fly. Key modifiers are bound to the v-on directive like v-on:eventname.keymodifiername, where the eventname could be keyup and the modifiername as enter.

<input @keyup.enter="checkInput">

The key modifiers also offer flexibility but allow multiple key name chaining.

<input @keyup.ctrl.enter="checkInput">

Here the key names will listen for both the ctrl and the enter keyboard events before the checkInput method gets called.

The v-for Directive

Just as JavaScript provides for iterating through arrays using loops like the for loop, Vue-js also provides a built-in directive known as the v-for that performs the same function.

We can write the v-for syntax as item in items where items are the array we are iterating over or as items of items to express the similarity with the JavaScript loop syntax.

List Rendering

Let us consider rendering the types of component build steps on a page.

<template>
  <div>
    <ul>
        <li v-for="steps in buildSteps" :key="steps.id"> {{ steps.step }}</li>
      </ul>
  </div>
</template>

<script>
export default {
 data() {
   return {
     buildSteps: [
      {
       id: "step 1",
       step:'With the build step',
      },
      {
        id: "step 2",
       step:'Without the build step'
      }
    ]
   }
 }
}
</script>

In the code block above, the steps array within the data property shows the two types of build steps we have for a component. Within our template, we used the v-for directive to loop through the steps array, the result of which we will render in an unordered list.

We added an optional key argument representing the index of the item we are currently iterating on. But beyond that, the key accepts a unique identifier that enables us to track each item’s node for proper state management.

Using v-for With A Component

Just like using the v-for to render lists, we can also use it to generate components. We can add the v-for directive to the component like the following:

<BuildStep v-for="steps in buildSteps" :key="steps.id"/>

The above code block will not do much for rendering or passing the step to the component. Instead, we will need to pass the value of the step as props to the component.

<BuildStep v-for="steps in buildSteps" :key="steps.id" :buildType="steps.step" />

We do the above to prevent any tight fixation of the v-for to the component.

The most important thing to note in the different usage of the v-for is the automation of a long process. We can move from manually listing out 100 items or components to using the v-for directive and have everything rendered out within the split of a second, as the case may be.

Building A Complex Registration Form In Vue

We will combine everything we have learned about the v-model, Vue components, the Vue props, the v-for directive, and event handling to build a complex form that would help us achieve efficiency, scalability, and time management.

This form will cater to capturing students’ bio-data, which we will develop to facilitate progressive enhancement as business demands increase.

Setting Up The Vue App

We will be scaffolding our Vue application using the build step. To do this, we will need to ensure we have the following installed:

• Node.js;
• npm or yarn.

Now we will proceed to create our Vue application by running the command below:

# npm
npm init vue@latest vue-complex-form

where vue-complex-form is the name of the Vue application.

After that, we will run the command below at the root of our Vue project:

npm install

Creating The JSON File To Host The Form Data

We aim to create a form where users can fill in their details. While we can manually add all the input fields, we will use a different approach to simplify our codebase. We will achieve this by creating a JSON file called util/bio-data.json. Within each of the JSON objects, we will have the basic info we want each input field to have.

[
  {
    "id": 1,
    "inputvalue":"  ",
    "formdata": "First Name",
    "type": "text",
    "inputdata": "firstname"
  },
  {
    "id": 2,
    "inputvalue":"  ",
    "formdata": "Last Name",
    "type": "text",
    "inputdata": "lastname"
  },
]

As seen in the code block above, we created an object with some keys already carrying values:

• id acts as the primary identifier of the individual object;
• inputvalue will cater to the value passed into the v-model;
• formdata will handle the input placeholder and the labels name;
• type denotes the input type, such as email, number, or text;
• inputdata represents the input id and name.

These keys’ values will be passed in later to our component as props. We can access the complete JSON data here.

Creating The Reusable Component

We will create an input component that will get passed the props from the JSON file we created. This input component will get iterated on using a v-for directive to create numerous instances of the input field at a stretch without having to write it all out manually. To do this, we will create a components/TheInputTemplate.vue file and add the code below:

<template>
  <div>
    <label :for="inputData">{{ formData }}</label>
    <input
      :value= "modelValue"
      :type= "type"
      :id= "inputData"
      :name= "inputData"
      :placeholder= "formData"
      @input="$emit('update:modelValue', $event.target.value)"
    >
  </div>
 </template>
 
<script>
export default {
  name: 'TheInputTemplate',
  props: {
    modelValue: {
      type: String
    },
    formData: {
      type: String
    },
    type: {
      type: String
    },
    inputData: {
      type: String
    }
  },
  emits: ['update:modelValue']
}
</script>
<style>
label {
  display: inline-block;
  margin-bottom: 0.5rem;
  text-transform: uppercase;
  color: rgb(61, 59, 59);
  font-weight: 700;
  font-size: 0.8rem;
}
input {
  display: block;
  width: 90%;
  padding: 0.5rem;
  margin: 0 auto 1.5rem auto;
}
</style>

In the above code block, we achieved the following:

• We created a component with an input field.
• Within the input field, we matched the values that we will pass in from the JSON file to the respective places of interest in the element.
• We also created props of modelValue, formData, type, and inputData that will be registered on the component when exported. These props will be responsible for taking in data from the parent file and passing it down to the TheInputTemplate.vue component.
• Bound the modelValue prop to the value of the input value.
• Added the update:modelValue, which gets emitted when the input event is triggered.

Registering The Input Component

We will navigate to our App.vue file and import the TheInputTemplate.vue component from where we can proceed to use it.

<template>
  <form class="wrapper">
    <TheInputTemplate/>
  </form>
</template>
<script>
import TheInputTemplate from './components/TheInputTemplate.vue'
export default {
  name: 'App',
  components: {
    TheInputTemplate
  }
}
</script>
<style>
html, body{
  background-color: grey;
  height: 100%;
  min-height: 100vh;
}
.wrapper {
  background-color: white;
  width: 50%;
  border-radius: 3px;
  padding: 2rem  1.5rem;
  margin: 2rem auto;
}
</style>

Here we imported the TheInputTemplate.vue component into the App.vue file, registered it in the components option property, and then declared it within our HTML template.

If we run npm run serve, we should have the following view:

At this point, there is not much to see because we are yet to register the props on the component.

Passing Input Data

To get the result we are after, we will need to pass the input data and add the props to the component. To do this, we will update our App.vue file:

<template>
  <div class="wrapper">
    <div v-for="bioinfo in biodata" :key="bioinfo.id">
      <TheInputTemplate v-model="bioinfo.inputvalue":formData= "bioinfo.formdata":type= "bioinfo.type":inputData= "bioinfo.inputdata"/>
    </div>
  </div>
<script>
//add imports here
import biodata from "../util/bio-data.json";
export default {
  name: 'App',
 //component goes here
  data: () => ({
    biodata
  })
}
</script>

From the code block above, we achieved several things:

• We imported the bio-data JSON file we created into the App.vue file. Then we added the imported variable to the data options of the Vue script.
• Looped through the JSON data, which we instantiated in the data options using the Vue v-for directive.
• Within the TheInputTemplate.vue component we created, we passed in the suitable data to fill the props option.

At this point, our interface should look like the following:

To confirm if our application is working as it should, we will open up our Vue DevTools, or install one from https://devtools.vuejs.org if we do not have it in our browser yet.

When we type in a value in any of the input fields, we can see the value show up in the modelValue within the Vue Devtools dashboard.

Conclusion

In this article, we explored some core Vue fundamentals like the v-for, v-model, and so on, which we later sewed together to build a complex form. The main goal of this article is to simplify the process of building complex forms while maintaining readability and reusability and reducing development time.

If, in any case, there will be a need to extend the form, all the developer would have to do is populate the JSON files with the needed information, and voila, the form is ready. Also, new Engineers can avoid swimming in lengthy lines of code to get an idea of what is going on in the codebase.

Note: To explore more about handling events within components to deal with as much complexity as possible, you can check out this article on using components with v-model.

Further Reading on Smashing Magazine

• “Optimizing A Vue App,” Michelle Barker
• “Three Insights I Gained While Researching Vue.js Accessibility,” Marcus Herrmann
• “Tools And Practices To Speed Up The Vue.js Development Process,” Uma Victor
• “Moving From Vue 1 To Vue 2 To Vue 3: A Case Study Of Migrating A Headless CMS System,” Lisi Linhart

(yk, il)

This article is sponsored by Storyblok

One of the greatest challenges in software development is not in creating new functionality but in maintaining and upgrading existing systems. With growing dependencies and complexity, it can be a tedious task to continuously keep everything updated. This becomes even more challenging when upgrading a base technology that the whole system runs on.

In this article, we will discuss how Storyblok solved the challenges of migrating the front-end interface of our headless content management system from Vue 1 to Vue 2 to Vue 3 within six years of growing the startup.

While migrating larger front-end systems can be a daunting task, it can be helpful to understand the reasons and strategies behind it. We’ll delve into the considerations and steps involved in such a migration and explore the potential benefits and drawbacks. With a clear understanding of the process, we can approach the migration with more confidence and ensure a smooth transition for our users and stakeholders.

The Vue Ecosystem & Storyblok’s Early Days

The Vue.js framework’s first large pre-beta release happened in late 2016, and Storyblok began work on a full prototype built on top of Vue in late 2015. At the time, Vue was still a relatively new framework, and other more established options like React were available. Despite this, Storyblok decided to take a chance on Vue and built their own prototype on top of it. This turned out to be a good decision, as the prototype worked well, and up to today, Vue is kept as the underlying framework for the front-end interface.

Over the years, Storyblok has played a key role in the growth and development of Vue, participating in forums, conferences, and meetups, sponsoring certain projects, as well as contributing to the Vue ecosystem through open-source projects and other initiatives. As Storyblok grew together with the Vue community over the years, Vue started upgrading its framework, and Storyblok began growing out of its prototype to become a fully-fledged product. This is where our migration story starts.

Ground-up Migration vs. Soft Migration

There were two main points in time when Storyblok was facing large migration challenges. The first one was when the upgrade from Vue 1 to Vue 2 happened. This went hand in hand with the update from Storyblok Version 1 to Storyblok Version 2. The decision was to completely rebuild the system from scratch. This is what we’ll call Ground-up migration. The second large migration happened when going from Vue 2 to Vue 3, where the front-end interface did not change. The existing codebase was updated in the background without visual changes for the user, and this is what we’ll call Soft migration.

Ground-up migration allows for greater flexibility and control over the design and architecture of the new system, but it can be a time-consuming and resource-intensive process. For Storyblok, it allowed the development of an open-source Blok Ink design system as the core of the new system. This design system could then simultaneously be used by our customers to build their own extensions.

Soft migration, on the other hand, can be quicker and more cost-effective, but it’s strongly limited and influenced by the current design and architecture of the existing system. Upgrading large codebases and all their dependencies can take months to achieve, and the time for this can be hard to find in a growing business. When thinking about customers, soft migration tends to be easier because the user doesn’t have to relearn a whole new interface, and no large marketing and communication resources need to be allocated towards this kind of migration.

How were these migration decisions made from a business perspective? After Storyblok was launched as a product in 2017 with Vue 1, it was continuously improved and extended with new features. In 2019, the team received its first seed investment, which allowed them to hire more developers to work on Storyblok. In 2020, work began on Storyblok V2 with Vue 2, with around five developers starting on the project for the first time. Instead of updating the old codebase from Vue 1 to Vue 2, the team decided to start with a completely new codebase. This gave the new team two main benefits:

1. The developers were fully involved in creating the architecture of the new system;
2. They learned how the system worked by rebuilding it.

In the core, the decision to make a ground-up migration was correct because the flexibility of that migration allowed the team to build a better, newer, and more stable version of the prototype while also understanding how it works. The main drawbacks of the ground-up migration were the cost of time and resources and getting the buy-in from the customers to switch from the old to the new version.

As Storyblok continued to evolve and improve, the codebase needed to be upgraded from Vue 2 to Vue 3. Migrating to the new version involved updating large amounts of code and ensuring that everything continued to work as expected. In this migration, we had to invest a lot of resources in retesting the interface, as well as allocating time for the developers to learn and understand the changes in Vue 3. This can be especially challenging when working with a large team, as there may be different codebases and business needs to consider.

Ultimately, the decision between these two approaches will depend on the specific needs and circumstances of the migration, including the following:

• Resources and expertise available,
• Complexity and size of the system,
• Desired level of control and flexibility over the design and architecture of the new system.

It’s important to have a clear plan in place to guide the migration process and ensure a smooth transition, so in the next chapter, we will look into what that plan looked like for us.

Strategies For Large Migrations

These five factors are essential to consider when planning a migration:

Creating A Timeline

One of the main challenges of migration is getting the buy-in from the organization, clients, and teams. Since migrations aren’t adding any new functionality, it can be hard to convince a team and the product owners of the importance of migration. However,

In the long term, migrations are necessary, and the longer you put them off, the harder they will become.

“

Secondly, migrations tend to take more than a few weeks, so it’s a harder and more tedious process that has to be planned with all the developers and stakeholders. Here is what our timeline looked like:

Going from Vue 1 to Vue 2

This process took us around two years from start to finish:

• Before Mid–2020: Develop new features in the old version.
• 2020 June: Identify and develop ‘core’ components in a new open-source design system.
• 2020 November: Create a new Vue 2 project.
• 2020 Nov — 2021 August: Redevelop all parts of the old app in the new app with the new design system.
• 2021 August: Beta Release of parts of the new application (e.g., our Visual Editor).
• 2021 August — 2022 August: Add all the missing functionality from the old app, add new features, and improve overall UX through customer feedback.
• 2022 August: Official release of the new app.
• During that time: onboard 20+ developers, designers, QAs, and product owners.

Going from Vue 2 to Vue 3

This process took us around eight months:

• 2022 July — 2022 November: Start migrating the Design System to Vue 3.
• 2022 November — 2023 January: remove all the ‘old’ breaking functionality and update or replace old dependencies that depend on Vue 2.
• 2022 December: Several meetings to explain what changed in Vue 3 with developers and stakeholders and how the transition will happen.
• 2023 January: Introduce the Vue 3 codebase, switch developers to the new codebase, and thoroughly test and start developing in Vue 3.
• 2023 February: Launch the Vue 3 version into production.

To create a timeline, you need to identify all the parts of the migration first. This can be done in an excel sheet or a planning tool like Jira. Here is an example of a simple sheet that could be used for creating a rough timeline. It can be useful to split different areas to separate sheets to divide them into the teams they belong to.

Identifying And Prioritizing Functionality to Migrate

In order to manage the cost and resources required for the migration, it is essential to identify and prioritize the critical features and functionality of the system that need to be migrated. For us, it meant starting bit by bit with more important functionality. When we built the new version of Storyblok, we started with our most important core feature, the “Visual Editor,” and built an entirely new version of it using our Design System. In any migration, you should ask yourself these questions to find out what the priorities are:

• Is the goal to create a completely new version of something?
• What parts does the system have? Can some of them be migrated separately?
• Which parts of the system are most important to the customer?
• Who knows the system well and can help with the migration?
• Does every developer need to work on the migration, or can a few ‘experts’ be selected to focus on this task?
• Can I estimate how long the migration will take? If not, can I break down the parts of the system more to find out how long smaller parts of the system can be migrated?

If you have multiple sub-parts that can be migrated separately, it’s easier to split them to different people to work on the migration. Another big decision is who is working on the migration. For our Vue 1 to Vue 2 migration, all our developers worked on creating the new functionality, but on the Vue 2 to Vue 3, it was one expert (the person who is writing this article) who did most of the migration and then it was handed over to the teams to finish and retest the whole application to see if everything was still working as it should.

At the same time, I organized some training for the developers to dive deeper into Vue 3 and the breaking changes in the system.

The core of the migration strategy always depends on the knowledge of the system as well as the importance of the features to be migrated.

More important features will be migrated and worked on first, and less important things can be kept to be improved in the end.

Use Automation And Tools to Support The Migration

Since a migration process is always very time-consuming, it pays off to invest in some automation of tedious tasks to find out all the problems of the migration. For our migration from Vue 2 to Vue 3, the migration build and its linting were very helpful in finding all the potential problem areas in the app that needed to be changed. We also worked with hand-written scripts that iterate through all Vue files in the project (we have over 600 of them) to automatically add all missing emit notations, replace event names, that updated in Vue 3 and update common logic changes in the unit tests, like adding the global notation.

These scripts were a large timesaver since we didn’t have to touch hundreds of files by hand, so investing time in writing such scripts can really pay off. In the core, utilizing regex to find and replace large logic chunks can help, but for the last final stretch, you will still spend hours fixing some things manually.

In the final part, all the unit and end-to-end tests we already had, helped to find some of the potential problems in the new version of our app. For unit testing, we used Jest with the built-in Test Utils as well as the Vue Testing Library, for the e2e tests, we’re using Cypress with different plugins.

Engage And Communicate With Users

If you create a new version of something, it’s essential to make sure that the experience is not getting worse for the customer. This can involve providing training and support to help users understand and use the new version, as well as collecting feedback and suggestions from users to help improve the new system. For us, this was a very important learning during the ground-up migration from Vue 1 to Vue 2 because we continuously collected feedback from the customer while rebuilding the app at the same time. This helped us to ensure that what we were building was what the customers wanted.

Another way was to have the beta version accessible way ahead of the new version being finished. In the beginning, we only made the Partner Portal available, then the Visual Editor, then the Content Editing, and lastly, the missing parts of the app. By gradually introducing the new parts, we could collect feedback during the development time and adjust things where the customer experience was not perfect yet.

In any scenario, it will be important to ask yourself these questions in a ground-up migration:

• How can we collect feedback from our customers early and often to ensure what we’re building is working?
• How can we communicate with the existing customers to make them aware of using the new version?
• What are the communication channels for the update? Can we leverage the update with the marketing team to make users more excited about it?
• Who do we have internally that handles communication, and who are the stakeholders who should be updated regularly on the changes?

For us, this meant building ‘feedback buttons’ into the interface to collect feedback from the users starting to use the new version. It pointed to a form where the users could rate specific parts but also give open feedback. This feedback was then handed back to the design team to evaluate and forward if it was valid feedback. Further, we added channels in our Discord to hear directly from developers using the system and introduced ‘tour’ functionalities that showed users where all the buttons and features are located and what they do. Finally, we added buttons to the old app to seamlessly switch between the old and new versions. We did various campaigns and videos on social media to hype our community about using the new version.

In all cases, it’s crucial to find out who the core stakeholders and communicators of the migration are. You can find that out with a simple impact/influence matrix. This matrix documents who is impacted by the migration and who should have how much influence over the migration. This can indicate who you should be in close contact with and who might only need to be communicated with occasionally.

Monitor And Evaluate The Migration Process

Since a migration process will always take a few months or even years to accomplish, it’s essential to monitor the process and make sure that after a few months, it’s still going in the right direction.

Here are some questions that can help you figure out if you’re on the right track:

• Have all the areas and functionalities that need to be migrated been defined? How are we tracking the process of each area?
• Are all stakeholders, including users and other teams, being effectively communicated with and their concerns addressed?
• Are there unexpected issues that have arisen during the migration that require you to adjust the budget and time frame of the migration?
• Is the new version being properly tested and validated before being put into production?
• Are the final results of the migration meeting the expectations of the users and stakeholders?

During the different migration phases, we hit several roadblocks. One of them was the customer’s expectations of having the exact same functionality from the old app in the new app. Initially, we wanted to change some of the UX and deprecate some features that weren’t satisfying to us. But over time, we noticed that it was really important to customers to be close to what they already knew from the older version, so over time, we moved many parts to be closer to how the customer expected it to be from before.

The second big roadblock in the migration from Vue 2 to Vue 3 was the migration of all our testing environments. Initially, we didn’t expect to have to put so much effort into updating the unit tests, but updating them was, at times, more time-consuming than the app itself. The testing in the “soft migration” had to be very extensive, and it took us more than three weeks to find and fix all the issues. During this time, we depended heavily on the skills of our QA engineers to help us figure out anything that might not work anymore.

The final step in the migration from Vue 2 to Vue 3 was to put the new version of the app into production. Since we had two versions of our app, one in Vue 2 and one in Vue 3, which looked essentially the same, we decided to do a blue/green deployment. This means that we transferred a subset of the user traffic to the new app while the majority of the users were still using the stable old app. We then tested this in production for a week with only a small subset of our users.

By slowly introducing the new version to just a percentage of the users, we could find more potential issues without disrupting all of our users. The essential part here was to have direct communication with our Sales and Support teams, who are in direct contact with important clients.

Lessons Learnt

Migration to Vue 2

The core lesson when we completely rebuilt Storyblok in Vue 2 was that migrating a large system can be a significant challenge for the development team that consists of new developers who are not familiar with the system yet. By handing the power over to the developers, they could be directly involved in forming the architecture, quality, and direction of the product. In any migration or significant change, the onboarding and training of developers will be an essential part of making the migration successful.

Another big lesson was the involvement of the existing users to improve the quality of the newer version we were building. By slowly introducing the new design and features in different areas of the system, the customers had the opportunity to get used to the new version gradually. With this gradual change, they could give feedback and report any issues or problems they encountered.

Overall, customers have a number of expectations when it comes to software, including:

• Reliability and stability,
• Ease of use,
• Regular updates and improvements,
• Support and assistance,
• Security and privacy.

Migrating a large system can impact these expectations, and it’s important to carefully consider the potential impacts on customers and take steps to ensure a smooth transition for them.

Migration to Vue 3

As we got more teams and more customers, it kept getting more critical to keep our production version of the app as stable as possible, so testing was an important part of making sure the quality was monitored and bugs were eliminated. All that time we had invested in unit and e2e testing in the Vue 2 version helped us to find problems and bugs during the migration process to Vue 3.

We found that it was essential to test the migrated system extensively to ensure that it was functioning correctly and meeting all of the required specifications. By carefully planning and executing our testing process, we were able to identify and fix the majority of the issues before the migrated system was released to production.

During the Vue 3 migration, we also saw the advantages of having a ‘separate’ part of the system, our design system, that could be migrated first. This allowed us to learn and study the migration guide there first and then move to the more complex migration of the app itself.

Lastly, a big thing we learned was that communication is essential. We started creating internal communication channels on Slack to keep marketing and other teams up to date on all the functionality changes and new features. Certain people could then weigh in on the ways new features were built.

Conclusion

Migrating Storyblok from Vue 1 to Vue 2 to Vue 3 was a significant challenge for the whole organization. A well-formed migration plan should outline the steps to be taken, the areas and functionalities that need to be migrated and in what way (rebuild or create a new version), the people to be involved, and the expected timeline.

For us, some key takeaways were the importance of involving the development team in forming the architecture and direction of the product, as well as onboarding and training them properly. It was also essential to communicate effectively with stakeholders, including users and other teams, to address their concerns and ensure their expectations were met.

Testing plays a crucial role in ensuring the migrated system functions correctly, and the better your QA engineers, the more smoothly the migration will go. Gradually introducing the new version to a subset of users before a full release can help identify any potential issues without disrupting all users. Another approach is gradually introducing new parts of the system one by one. We made use of both of them.

If you’re planning a large system migration, starting with a well-defined plan is important. Make sure to consider budget and time frame, build in time for testing and validation, continuously monitor the progress of the migration and adjust the plan as necessary.

It’s also important to involve existing users in the migration process to gather feedback and identify any potential issues. Make sure your migration is actually improving the experience for the users or developers. Internal communication is key in this process, so ensure that all stakeholders are effectively communicated with throughout the migration to make sure everyone is on board. Consider gradually migrating different parts of the system to help manage complexity or introducing a new system only to a subset of users first.

And lastly, work with your team. Migrating really takes a lot of hands and time, so the better your teams can work together, the smoother the transition will go.

(yk, il)

Single Page Applications (SPAs) can provide a rich, interactive user experience when dealing with real-time, dynamic data. But they can also be heavy, bloated, and perform poorly. In this article, we’ll walk through some of the front-end optimization tips to keep our Vue apps relatively lean and only ship the JS we need when it’s needed.

Note: Some familiarity with Vue and the Composition API is assumed, but there will hopefully be some useful takeaways regardless of your framework choice.

As a front-end developer at Ada Mode, my job involves building Windscope, a web app for wind farm operators to manage and maintain their fleet of turbines. Due to the need to receive data in real time and the high level of interactivity required, an SPA architecture was chosen for the project. Our web app is dependent on some heavy JS libraries, but we want to provide the best experience for the end user by fetching data and rendering as quickly and efficiently as possible.

Choosing A Framework

Our JS framework of choice is Vue, partly chosen as it’s the framework I’m most familiar with. Previously Vue had a smaller overall bundle size compared to React. However, since recent React updates, the balance appears to have shifted in React’s favor. That doesn’t necessarily matter, as we’ll look at how to only import what we need in the course of this article. Both frameworks have excellent documentation and a large developer ecosystem, which was another consideration. Svelte is another possible choice, but it would have required a steeper learning curve due to unfamiliarity, and being newer, it has a less developed ecosystem.

As an example to demonstrate the various optimizations, I’ve built a simple Vue app that fetches data from an API and renders some charts using D3.js.

Note: Please refer to the example GitHub repository for the full code.

We’re using Parcel, a minimal-config build tool, to bundle our app, but all of the optimizations we’ll cover here are applicable to whichever bundler you choose.

Tree Shaking, Compression, And Minification With Build Tools

It’s good practice to only ship the code you need, and right out of the box, Parcel removes unused Javascript code during the build process (tree shaking). It also minifies the result and can be configured to compress the output with Gzip or Brotli.

As well as minification, Parcel also employs scope hoisting as part of its production process, which can help make minification even more efficient. An in-depth guide to scope hoisting is outside of the scope (see what I did there?) of this article. Still, if we run Parcel’s build process on our example app with the --no-optimize and --no-scope-hoist flags, we can see the resulting bundle is 510kB — around 5 times higher than the optimized and minified version. So, whichever bundler you’re using, it’s fair to say you’ll probably want to make sure it’s carrying out as many optimizations as possible.

But the work doesn’t end here. Even if we’re shipping a smaller bundle overall, it still takes time for the browser to parse and compile our JS, which can contribute to a slower user experience. This article on Bundle Size Optimization by Calibre explains how large JS bundles affect performance metrics.

Let’s look at what else we can do to reduce the amount of work the browser has to do.

Vue Composition API

Vue 3 introduced the Composition API, a new set of APIs for authoring components as an alternative to the Options API. By exclusively using the Composition API, we can import only the Vue functions that we need instead of the whole package. It also enables us to write more reusable code using composables. Code written using the Composition API lends itself better to minification, and the whole app is more susceptible to tree-shaking.

Note: You can still use the Composition API if you’re using an older version of Vue: it was backported to Vue 2.7, and there is an official plugin for older versions.

Importing Dependencies

A key goal was to reduce the size of the initial JS bundle downloaded by the client. Windscope makes extensive use of D3 for data visualization, a large library and wide-ranging in scope. However, Windscope only needs part of it (there are entire modules in the D3 library that we don’t need at all). If we examine the entire D3 package on Bundlephobia, we can see that our app uses less than half of the available modules and perhaps not even all of the functions within those modules.

One of the easiest ways to keep our bundle size as small as possible is only to import the modules we need.

Let’s take D3’s selectAll function. Instead of using a default import, we can just import the function we need from the d3-selection module:

// Previous:
import * as d3 from 'd3'

// Instead:
import { selectAll } from 'd3-selection'

Code Splitting With Dynamic Imports

There are certain packages that are used in a bunch of places throughout Windscope, such as the AWS Amplify authentication library, specifically the Auth method. This is a large dependency that contributes heavily to our JS bundle size. Rather than import the module statically at the top of the file, dynamic imports allow us to import the module exactly where we need it in our code.

Instead of:

import { Auth } from '@aws-amplify/auth'

const user = Auth.currentAuthenticatedUser()

We can import the module when we want to use it:

import('@aws-amplify/auth').then(({ Auth }) => {
    const user = Auth.currentAuthenticatedUser()
})

This means that the module will be split out into a separate JS bundle (or “chunk”), which will only be downloaded by the browser if and when it is needed. Additionally, the browser can cache these dependencies, which may change less frequently than the code for the rest of our app.

Lazy Loading Routes With Vue Router

Our app uses Vue Router for navigation. Similarly to dynamic imports, we can lazyload our route components, so they will only be imported (along with their associated dependencies) when a user navigates to that route.

In our index/router.js file:

// Previously:
import Home from "../routes/Home.vue";
import About = "../routes/About.vue";

// Lazyload the route components instead:
const Home = () => import("../routes/Home.vue");
const About = () => import("../routes/About.vue");

const routes = [
  {
    name: "home",
    path: "/",
    component: Home,
  },
  {
    name: "about",
    path: "/about",
    component: About,
  },
];

The code for the ‘About’ route will only be loaded when the user clicks the ‘About’ link and navigates to the route.

Async Components

In addition to lazyloading each route, we can also lazyload individual components using Vue’s defineAsyncComponent method.

const KPIComponent = defineAsyncComponent(() => import('../components/KPI.vue))

This means the code for the KPI component will be dynamically imported, as we saw in the router example. We can also provide some components to display while it’s in a loading or error state (useful if we’re loading a particularly large file).

const KPIComponent = defineAsyncComponent({
  loader: () => import('../components/KPI.vue),
  loadingComponent: Loader,
  errorComponent: Error,
  delay: 200,
  timeout: 5000,
});

Splitting API Requests

Our application is primarily concerned with data visualization and relies heavily on fetching large amounts of data from the server. Some of these requests can be quite slow, as the server has to perform a number of computations on the data. In our initial prototype, we made a single request to the REST API per route. Unfortunately, we found this resulted in users having to wait a long time — sometimes up to 10 seconds, watching a loading spinner before the app successfully received the data and could begin rendering the visualizations.

We made the decision to split the API into several endpoints and make a request for each widget. While this could increase the response time overall, it means the app should become usable much quicker, as users will see parts of the page rendered while they’re still waiting for others. Additionally, any error that might occur will be localized while the rest of the page remains usable.

You can see the difference illustrated here:

Conditionally Load Components

Now we can combine this with async components to only load a component when we’ve received a successful response from the server. Here we’re fetching the data, then importing the component when our fetch function returns successfully:

<template>
  <div>
    <component :is="KPIComponent" :data="data"></component>
  </div>
</template>

<script>
import {
  defineComponent,
  ref,
  defineAsyncComponent,
} from "vue";
import Loader from "./Loader";
import Error from "./Error";

export default defineComponent({
    components: { Loader, Error },

    setup() {
        const data = ref(null);

        const loadComponent = () => {
          return fetch('https://api.npoint.io/ec46e59905dc0011b7f4')
            .then((response) => response.json())
            .then((response) => (data.value = response))
            .then(() => import("../components/KPI.vue") // Import the component
            .catch((e) => console.error(e));
        };

        const KPIComponent = defineAsyncComponent({
          loader: loadComponent,
          loadingComponent: Loader,
          errorComponent: Error,
          delay: 200,
          timeout: 5000,
        });

        return { data, KPIComponent };
    }
}

To handle this process for every component, we created a higher order component called WidgetLoader, which you can see in the repository.

This pattern can be extended to any place in the app where a component is rendered upon user interaction. For example, in Windscope, we load a map component (and its dependencies) only when the user clicks on the ‘Map’ tab. This is known as Import on interaction.

CSS

If you run the example code, you will see that clicking the ‘Locations’ navigation link loads the map component. As well as dynamically importing the JS module, importing the dependency within the component’s <style> block will lazyload the CSS too:

// In MapView.vue
<style>
@import "../../node_modules/leaflet/dist/leaflet.css";

.map-wrapper {
  aspect-ratio: 16 / 9;
}
</style>

Refining The Loading State

At this point, we have our API requests running in parallel, with components being rendered at different times. One thing we might notice is the page appears janky, as the layout will be shifting around quite a bit.

A quick way to make things feel a bit smoother for users is to set an aspect ratio on the widget that roughly corresponds to the rendered component so the user doesn’t see quite as big a layout shift. We could pass in a prop for this to account for different components, with a default value to fall back to.

// WidgetLoader.vue
<template>
  <div class="widget" :style="{ 'aspect-ratio': loading ? aspectRatio : '' }">
    <component :is="AsyncComponent" :data="data"></component>
  </div>
</template>

<script>
import { defineComponent, ref, onBeforeMount, onBeforeUnmount } from "vue";
import Loader from "./Loader";
import Error from "./Error";

export default defineComponent({
  components: { Loader, Error },

  props: {
    aspectRatio: {
      type: String,
      default: "5 / 3", // define a default value
    },
    url: String,
    importFunction: Function,
  },

  setup(props) {
      const data = ref(null);
      const loading = ref(true);

        const loadComponent = () => {
          return fetch(url)
            .then((response) => response.json())
            .then((response) => (data.value = response))
            .then(importFunction
            .catch((e) => console.error(e))
            .finally(() => (loading.value = false)); // Set the loading state to false
        };

    /* ...Rest of the component code */

    return { data, aspectRatio, loading };
  },
});
</script>

Aborting API Requests

On a page with a large number of API requests, what should happen if the user navigates away before all the requests have been completed? We probably don’t want those requests to continue running in the background, slowing down the user experience.

We can use the AbortController interface, which enables us to abort API requests as desired.

In our setup function, we create a new controller and pass its signal into our fetch request parameters:

setup(props) {
    const controller = new AbortController();

    const loadComponent = () => {
      return fetch(url, { signal: controller.signal })
        .then((response) => response.json())
        .then((response) => (data.value = response))
        .then(importFunction)
        .catch((e) => console.error(e))
        .finally(() => (loading.value = false));
        };
}

Then we abort the request before the component is unmounted, using Vue’s onBeforeUnmount function:

onBeforeUnmount(() => controller.abort());

If you run the project and navigate to another page before the requests have been completed, you should see errors logged in the console stating that the requests have been aborted.

Stale While Revalidate

So far, we’ve done a pretty good of optimizing our app. But when a user navigates to the second view and then back to the previous one, all the components remount and are returned to their loading state, and we have to wait for the request responses all over again.

Stale-while-revalidate is an HTTP cache invalidation strategy where the browser determines whether to serve a response from the cache if that content is still fresh or “revalidate” and serve from the network if the response is stale.

In addition to applying cache-control headers to our HTTP response (out of the scope of this article, but read this article from Web.dev for more detail), we can apply a similar strategy to our Vue component state, using the SWRV library.

First, we must import the composable from the SWRV library:

import useSWRV from "swrv";

Then we can use it in our setup function. We’ll rename our loadComponent function to fetchData, as it will only deal with data fetching. We’ll no longer import our component in this function, as we’ll take care of that separately.

We’ll pass this into the useSWRV function call as the second argument. We only need to do this if we need a custom function for fetching data (maybe we need to update some other pieces of state). As we’re using an Abort Controller, we’ll do this; otherwise, the second argument can be omitted, and SWRV will use the Fetch API:

// In setup()
const { url, importFunction } = props;

const controller = new AbortController();

const fetchData = () => {
  return fetch(url, { signal: controller.signal })
    .then((response) => response.json())
    .then((response) => (data.value = response))
    .catch((e) => (error.value = e));
};

const { data, isValidating, error } = useSWRV(url, fetchData);

Then we’ll remove the loadingComponent and errorComponent options from our async component definition, as we’ll use SWRV to handle the error and loading states.

// In setup()
const AsyncComponent = defineAsyncComponent({
  loader: importFunction,
  delay: 200,
  timeout: 5000,
});

This means we’ll need to include the Loader and Error components in our template and show and hide them depending on the state. The isValidating return value tells us whether there is a request or revalidation happening.

<template>
  <div>
    <Loader v-if="isValidating && !data"></Loader>
    <Error v-else-if="error" :errorMessage="error.message"></Error>
    <component :is="AsyncComponent" :data="data" v-else></component>
  </div>
</template>

<script>
import {
  defineComponent,
  defineAsyncComponent,
} from "vue";
import useSWRV from "swrv";

export default defineComponent({
  components: {
    Error,
    Loader,
  },

  props: {
    url: String,
    importFunction: Function,
  },

  setup(props) {
    const { url, importFunction } = props;

    const controller = new AbortController();

    const fetchData = () => {
      return fetch(url, { signal: controller.signal })
        .then((response) => response.json())
        .then((response) => (data.value = response))
        .catch((e) => (error.value = e));
    };

    const { data, isValidating, error } = useSWRV(url, fetchData);

    const AsyncComponent = defineAsyncComponent({
      loader: importFunction,
      delay: 200,
      timeout: 5000,
    });

    onBeforeUnmount(() => controller.abort());

    return {
      AsyncComponent,
      isValidating,
      data,
      error,
    };
  },
});
</script>

We could refactor this into its own composable, making our code a bit cleaner and enabling us to use it anywhere.

// composables/lazyFetch.js
import { onBeforeUnmount } from "vue";
import useSWRV from "swrv";

export function useLazyFetch(url) {
  const controller = new AbortController();

  const fetchData = () => {
    return fetch(url, { signal: controller.signal })
      .then((response) => response.json())
      .then((response) => (data.value = response))
      .catch((e) => (error.value = e));
  };

  const { data, isValidating, error } = useSWRV(url, fetchData);

  onBeforeUnmount(() => controller.abort());

  return {
    isValidating,
    data,
    error,
  };
}

// WidgetLoader.vue
<script>
import { defineComponent, defineAsyncComponent, computed } from "vue";
import Loader from "./Loader";
import Error from "./Error";
import { useLazyFetch } from "../composables/lazyFetch";

export default defineComponent({
  components: {
    Error,
    Loader,
  },

  props: {
    aspectRatio: {
      type: String,
      default: "5 / 3",
    },
    url: String,
    importFunction: Function,
  },

  setup(props) {
    const { aspectRatio, url, importFunction } = props;
    const { data, isValidating, error } = useLazyFetch(url);

    const AsyncComponent = defineAsyncComponent({
      loader: importFunction,
      delay: 200,
      timeout: 5000,
    });

    return {
      aspectRatio,
      AsyncComponent,
      isValidating,
      data,
      error,
    };
  },
});
</script>

Updating Indicator

It might be useful if we could show an indicator to the user while our request is revalidating so that they know the app is checking for new data. In the example, I’ve added a small loading indicator in the corner of the component, which will only be shown if there is already data, but the component is checking for updates. I’ve also added a simple fade-in transition on the component (using Vue’s built-in Transition component), so there is not such an abrupt jump when the component is rendered.

<template>
  <div
    class="widget"
    :style="{ 'aspect-ratio': isValidating && !data ? aspectRatio : '' }"
  >
    <Loader v-if="isValidating && !data"></Loader>
    <Error v-else-if="error" :errorMessage="error.message"></Error>
    <Transition>
        <component :is="AsyncComponent" :data="data" v-else></component>
    </Transition>

    <!--Indicator if data is updating-->
    <Loader
      v-if="isValidating && data"
      text=""
    ></Loader>
  </div>
</template>

Conclusion

Prioritizing performance when building our web apps improves the user experience and helps ensure they can be used by as many people as possible. We’ve successfully used the above techniques at Ada Mode to make our applications faster. I hope this article has provided some pointers on how to make your app as efficient as possible — whether you choose to implement them in full or in part.

SPAs can work well, but they can also be a performance bottleneck. So, let’s try to build them better.

Further Reading on Smashing Magazine

• Refactoring CSS (Part 1–3)
• Five Data-Loading Patterns To Boost Web Performance
• Performance Game Changer: Browser Back/Forward Cache
• Reducing The Web’s Carbon Footprint: Optimizing Social Media Embeds

(vf, yk, il)

What’s different about the file uploader we’re building in this article versus the previous one? The previous drag-and-drop file uploader was built with Vanilla JS and really focused on how to make file uploading and drag-and-drop file selection work, so its feature set was limited. It uploaded the files immediately after you chose them with a simple progress bar and an image thumbnail preview. You can see all of this at this demo.

In addition to using Vue, we’ll be changing the features up: after an image is added, it will not upload immediately. Instead, a thumbnail preview will show up. There will be a button on the top right of the thumbnail that will remove the file from the list in case you didn’t mean to select an image or change your mind about uploading it.

You’ll then click on the “Upload” button to send the image data to the server and each image will display its upload status. To top it all off, I crafted some snazzy styles (I’m no designer, though, so don’t judge too harshly). We won’t be digging into those styles in this tutorial, but they’ll be available for you to copy or sift through yourself in the GitHub Repository — though, if you’re going to copy them, make sure you set up your project to be able to use Stylus styles (or you can set it up to use Sass and change lang to scss for the style blocks and it will work that way). You can also see what we’re building today on the demo page.

Note: I will assume that readers have strong JavaScript knowledge and a good grasp of the Vue features and APIs, especially Vue 3’s composition API, but not necessarily the best ways to use them. This article is to learn how to create a drag-and-drop uploader in the context of a Vue app while discussing good patterns and practices and will not go deep into how to use Vue itself.

Setup

There are a lot of ways to set up a Vue project: Vue CLI, Vite, Nuxt, and Quasar all have their own project scaffolding tools, and I’m sure there are more. I’m not all that familiar with most of them, and I’m not going to prescribe any one tool as of right for this project, so I recommend reading the documentation for whichever you choose to figure out how to set up the way we need it for this little project.

We need to be set up with Vue 3 with the script setup syntax, and if you’re snatching my styles from the Github repo, you’ll need to make sure you’re set up to have your Vue styles compiled from Stylus (or you can set it up to use Sass and change lang to “scss” for the style blocks and it will work that way).

Drop Zone

Now that we have the project set up, let’s dive into the code. We’ll start with a component that handles the drag-and-drop functionality. This will be a simple wrapper div element with a bunch of event listeners and emitters for the most part. This sort of element is a great candidate for a reusable component (despite it only being used once in this particular project): it has a very specific job to do and that job is generic enough to be used in a lot of different ways/places without the need of a ton of customization options or complexity.

This is one of those things good developers are always keeping an eye out for. Cramming a ton of functionality into a single component would be a bad idea for this project or any other because then 1) it can’t be reused if you find a similar situation later and 2) it’s more difficult to sort through the code and figure out how each piece relates to each other. So, we’re going to do what we can to follow this principle and it starts here with the DropZone component. We’ll start with a simple version of the component and then spruce it up a bit to help you grok what’s going on a bit easier, so let’s create a DropZone.vue file in the src/components folder:

<template>
    <div @drop.prevent="onDrop">
        <slot></slot>
    </div>
</template>

<script setup>
import { onMounted, onUnmounted } from 'vue'
const emit = defineEmits(['files-dropped'])

function onDrop(e) {
    emit('files-dropped', [...e.dataTransfer.files])
}

function preventDefaults(e) {
    e.preventDefault()
}

const events = ['dragenter', 'dragover', 'dragleave', 'drop']

onMounted(() => {
    events.forEach((eventName) => {
        document.body.addEventListener(eventName, preventDefaults)
    })
})

onUnmounted(() => {
    events.forEach((eventName) => {
        document.body.removeEventListener(eventName, preventDefaults)
    })
})
</script>

First, looking at the template, you’ll see a div with a drop event handler (with a prevent modifier to prevent default actions) calling a function that we’ll get to in a moment. Inside that div is a slot, so we can reuse this component with custom content inside it. Then we get to the JavaScript code, which is inside a script tag with the setup attribute.

Inside the script, we define an event that we’ll emit called ‘files-dropped’ that other components can use to do something with the files that get dropped here. Then we define the function onDrop to handle the drop event. Right now, all it does is emit the event we just defined and add an array of the files that were just dropped as the payload. Note, we’re using a trick with the spread operator to convert the list of files from the FileList that e.dataTransfer.files gives us to an array of Files so all the array methods can be called on it by the part of the system that takes the files.

Finally, we come to the place where we handle the other drag/drop events that happen on the body, preventing the default behavior during the drag and drop (namely that it’ll open one of the files in the browser. We create a function that simply calls preventDefault on the event object. Then, in the onMounted lifecycle hook we iterate over the list of events and prevent default behavior for that even on the document body. In the onUnmounted hook, we remove those listeners.

Active State

So, what extra functionality can we add? The one thing I decided to add was some state indicating whether the drop zone was “active”, meaning that a file is currently hovering over the drop zone. That’s simple enough; create a ref called active, set it to true on the events when the files are dragged over the drop zone and false when they leave the zone or are dropped.

We’ll also want to expose this state to the components using DropZone, so we’ll turn our slot into a scoped slot and expose that state there. Instead of the scoped slot (or in addition to it for added flexibility), we could emit an event to inform the outside of the value of active as it changes. The advantage of this is that the entire component that is using DropZone can have access to the state, rather than it being limited to the components/elements within the slot in the template. We’re going to stick with the scoped slot for this article though.

Finally, for good measure, we’ll add a data-active attribute that reflects active’s value so we can key off it for styling. You could also use a class if you prefer, but I tend to like data attributes for state modifiers.

Let’s write it out:

<template>
    <!-- add `data-active` and the event listeners -->
    <div :data-active="active" @dragenter.prevent="setActive" @dragover.prevent="setActive" @dragleave.prevent="setInactive" @drop.prevent="onDrop">
        <!-- share state with the scoped slot -->
        <slot :dropZoneActive="active"></slot>
    </div>
</template>

<script setup>
// make sure to import `ref` from Vue
import { ref, onMounted, onUnmounted } from 'vue'
const emit = defineEmits(['files-dropped'])

// Create `active` state and manage it with functions
let active = ref(false)

function setActive() {
    active.value = true
}
function setInactive() {
    active.value = false
}

function onDrop(e) {
    setInactive() // add this line too
    emit('files-dropped', [...e.dataTransfer.files])
}

// ... nothing changed below this
</script>

I threw some comments in the code to note where the changes were, so I won’t dive too deep into it, but I have some notes. We’re using the prevent modifiers on all the event listeners again to make sure that default behavior doesn’t activate. Also, you’ll notice that the setActive and setInactive functions seem like a bit of overkill since you could just set active directly, and you could make that argument for sure, but just wait a bit; there will be another change that truly justifies the creation of functions.

You see, there’s an issue with what we’ve done. As you can see in the video below, using this code for the drop zone means that it can flicker between active and inactive states while you drag something around inside the drop zone.

Why is it doing that? When you drag something over a child element, it will “enter” that element and “leave” the drop zone, which causes it to go inactive. The dragenter event will bubble up to the drop zone, but it happens before the dragleave event, so that doesn’t help. Then a dragover event will fire again on the drop zone which will flip it back to active but not before flickering to the inactive state.

To fix this, we’ll add a short timeout to the setInactive function to prevent it from going inactive immediately. Then setActive will clear that timeout so that if it is called before we actually set it as inactive, it won’t actually become inactive. Let’s make those changes:

// Nothing changed above

let active = ref(false)
let inActiveTimeout = null // add a variable to hold the timeout key

function setActive() {
    active.value = true
    clearTimeout(inActiveTimeout) // clear the timeout
}
function setInactive() {
    // wrap it in a `setTimeout`
    inActiveTimeout = setTimeout(() => {
        active.value = false
    }, 50)
}

// Nothing below this changes

You’ll note a timeout of 50 milliseconds. Why this number? Because I’ve tested several different timeouts and this feels the best.

I know that’s subjective but hear me out. I’ve tested much smaller timeouts and 15ms was about as low as I went where I never saw a flicker, but who knows how that’ll work on other hardware? It has too small a margin of error in my mind. You also probably don’t want to go over 100ms because that can cause perceived lag when a user intentionally does something that should cause it to go inactive. In the end, I settled somewhere in the middle that is long enough to pretty much guarantee there won’t be any flickering on any hardware and there should be no perceived lag.

That’s all we need for the DropZone component, so let’s move on to the next piece of the puzzle: a file list manager.

File List Manager

I guess the first thing that needs to be done is an explanation of what I mean by the file list manager. This will be a composition function that returns several methods for managing the state of the files the user is attempting to upload. This could also be implemented as a Vuex/Pinia/alternative store as well, but to keep things simple and prevent needing to install a dependency if we don’t need to, it makes a lot of sense to keep it as a composition function, especially since the data isn’t likely to be needed widely across the application, which is where the stores are the most useful.

You could also just build the functionality directly into the component that will be using our DropZone component, but this functionality seems like something that could very easily be reused; pulling it out of the component makes the component easier to understand the intent of what is going on (assuming good function and variable names) without needing to wade through the entire implementation.

Now that we’ve made it clear this is going to be a composition function and why, here’s what the file list manager will do:

1. Keep a list of files that have been selected by the user;
2. Prevent duplicate files;
3. Allow us to remove files from the list;
4. Augment the files with useful metadata: an ID, a URL that can be used to show a preview of the file, and the file’s upload status.

So, let’s build it in src/compositions/file-list.js:

import { ref } from 'vue'

export default function () {
    const files = ref([])

    function addFiles(newFiles) {
        let newUploadableFiles = [...newFiles]
            .map((file) => new UploadableFile(file))
            .filter((file) => !fileExists(file.id))
        files.value = files.value.concat(newUploadableFiles)
    }

    function fileExists(otherId) {
        return files.value.some(({ id }) => id === otherId)
    }

    function removeFile(file) {
        const index = files.value.indexOf(file)

        if (index > -1) files.value.splice(index, 1)
    }

    return { files, addFiles, removeFile }
}

class UploadableFile {
    constructor(file) {
        this.file = file
        this.id = `${file.name}-${file.size}-${file.lastModified}-${file.type}`
        this.url = URL.createObjectURL(file)
        this.status = null
    }
}

We’re exporting a function by default that returns the file list (as a ref) and a couple of methods that are used to add and remove files from the list. It would be nice to make the file list returned as read-only to force you to use the methods for manipulating the list, which you can do pretty easily using the readonly function imported from Vue, but that would cause issues with the uploader that we’ll build later.

Note that files is scoped to the composition function and set inside it, so each time you call the function, you’ll receive a new file list. If you want to share the state across multiple components/calls, then you’ll need to pull that declaration out of the function so it’s scoped and set once in the module, but in our case we’re only using it once, so it doesn’t really matter, and I was working under the thought that each instance of the file list would be used by a separate uploader and any state can be passed down to child components rather than shared via the composition function.

The most complex piece of this file list manager is adding new files to the list. First, we’re making sure that if a FileList object was passed instead of an array of File objects, then we convert it to an array (as we did in the DropZone when we emitted the files. This means we could probably skip that transformation, but better safe than sorry). Then we convert the file to an UploadableFile, which is a class we’re defining that wraps the file and gives us a few extra properties. We’re generating an id based on several aspects of the file so we can detect duplicates, a blob:// URL of the image so we can show preview thumbnails and a status for tracking uploads.

Now that we have the IDs on the files, we filter out any files that already exist in the file list before concatenating them to the end of the file list.

Possible Improvements

While this file list manager works well for what it does, there are a number of upgrades that can be done. For one thing, instead of wrapping the file in a new class and then having to call .file on it to access the original file object, we could wrap the file in a proxy that specifies our new properties, but then will forward any other property requests on to the original object, so it is more seamless.

As an alternative to wrapping each file in an UploadableFile, we could have provided utility functions that could return the ID or URL given a file, but that’s slightly less convenient and would mean that you’re potentially calculating these properties multiple times (for each render, and so on), but that shouldn’t really matter unless you’re dealing with people dropping thousands of images at once, in which case you can try memorizing it.

As for the status, that isn’t pulled straight from the File, so a simple utility function like the others wouldn’t be possible, but you could store the status of each file with the uploader (we’ll be building that later) rather than directly with the files. This might be a better way of handling it in a large app so we don’t end up filling the UploadableFile class with a bunch of properties that just facilitate a single area of the app and are useless elsewhere.

Note: For our purposes, having the properties available directly on our file object is by far the most convenient, but it can definitely be argued that it isn’t the most appropriate.

Another possible improvement is allowing you to specify a filter so that it only allows certain file types to be added to the list. This would also require addFiles to return errors when some files don’t match the filter in order to let the user know they made a mistake. This is definitely something that should be done in production-ready applications.

Better Together

We’re far from a finished product, but let’s put the pieces we have together to verify everything is working so far. We’re going to be editing the /src/App.vue file, to put these pieces in, but you can add them to whatever page/section component you want. If you’re putting it inside an alternate component, though, ignore anything (like an ID of “app”) that would only be seen on the main app component.

<template>
    <div id="app">
        <DropZone class="drop-area" @files-dropped="addFiles" #default="{ dropZoneActive }">
            <div v-if="dropZoneActive">
                <div>Drop Them</div>
            </div>
            <div v-else>
                <div>Drag Your Files Here</div>
            </div>
        </DropZone>
    </div>
</template>

<script setup>
import useFileList from './compositions/file-list'
import DropZone from './components/DropZone.vue'

const { files, addFiles, removeFile } = useFileList()
</script>

If you start with the script section, you’ll see we’re not doing a whole lot. We’re importing the two files we just finished writing and we’re initializing the file list. Note, we’re not using files or removeFile yet, but we will later, so I’m just keeping them there for now. Sorry if ESLint is complaining about unused variables. We’ll want files at the very least so we can see if it’s working later.

Moving on to the template, you can see we’re using the DropZone component right away. We’re giving it a class so we can style it, passing the addFiles function for the “files-dropped” event handler, and grabbing the scoped slot variable so our content can be dynamic based on whether or not the drop zone is active. Then, inside the drop zone’s slot, we create a div showing a message to drag files over if it’s inactive and a message to drop them when it is active.

Now, you’ll probably want some styles to at least make the drop zone larger and easier to find. I won’t be pasting any here, but you can find the styles I used for App.vue in the repo.

Now, before we can test the current state of the app, we’ll need the beta version of Vue DevTools installed in our browser (stable version doesn’t support Vue 3 quite yet). You can get Vue DevTools from Chrome web store for most Chromium-based browsers or download Vue DevTools here for Firefox.

After you’ve installed that, run your app with npm run serve (Vue CLI), npm run dev (Vite), or whatever script you use in your app, then open it in your browser via the URL given in the command line. Open up the Vue DevTools, then drag and drop some images onto the drop zone. If it worked, you should see an array of however many files you added when you view the component we just wrote (see screenshot below).

Nice! Now Let’s make this a bit more accessible for users who can’t (or don’t want to) drag and drop, by adding a hidden file input (that becomes visible when focused via keyboard for those that need it, assuming you’re using my styles) and wrapping a big label around everything to allow us to use it despite its invisibility. Finally, we’ll need to add an event listener to the file input so that when a user selects a file, we can add it to our file list.

Let’s start with the changes to the script section. We’re just going to add a function to the end of it:

function onInputChange(e) {
    addFiles(e.target.files)
    e.target.value = null
}

This function handles the “change” event fired from the input and adds the files from the input to the file list. Note the last line in the function resetting the value of the input. If a user adds a file via the input, decides to remove it from our file list, then changes their mind and decides to use the input to add that file again, then the file input will not fire the “change” event because the file input has not changed. By resetting the value like this, we ensure the event will always be fired.

Now, let’s make our changes to the template. Change all of the code inside the DropZone slot to the following:

<label for="file-input">
    <span v-if="dropZoneActive">
        <span>Drop Them Here</span>
        <span class="smaller">to add them</span>
    </span>
    <span v-else>
        <span>Drag Your Files Here</span>
        <span class="smaller">
            or <strong><em>click here</em></strong> to select files
        </span>
    </span>

    <input type="file" id="file-input" multiple @change="onInputChange" />
</label>

We wrap the entire thing in a label that is linked to the file input, then we add our dynamic messages back in, though I’ve added a bit more messages to inform users they can click to select files. I also added a bit for the “drop them” message so that they have the same number of lines of text so the drop zone won’t change size when active. Finally, we add the file input, set the multiple attribute to allow users to select multiple files at a time, then wire up the “change” event listener to the function we just wrote.

Run the app again, if you stopped it, we should see the same result in the Vue DevTools whether we drag and drop files or click the box to use the file selector.

Previewing Selected Images

Great, but users aren’t going to be using Vue DevTools to see if the files they dropped are actually added, so let’s start showing the users those files. We’ll start just by editing App.vue (or whatever component file you added the DropZone to) and showing a simple text list with the file names.

Let’s add the following bit of code to the template immediately following the label we just added in the previous step:

<ul v-show="files.length">
    <li v-for="file of files" :key="file.id">{{ file.file.name }}</li>
</ul>

Now, with the app running, if you add some files to the list, you should see a bulleted list of the file names. If you copied my styles, it might look a bit odd, but that’s alright because we’re changing it soon. Make note that thanks to adding the file’s ID in the file list manager, we now have a key in the loop. The only thing that annoys me personally is that since we wrapped the files, we need to write file.file to access the original file object to get its name. In the end, though, it’s a small sacrifice to make.

Now, let’s start showing the images instead of just listing their names, but it’s time to move this functionality out of this main component. We certainly could, keep putting the file preview functionality here, but there are two good reasons to pull it out:

1. The functionality is potentially reusable in other cases.
2. As this functionality expands, separating it out prevents the main component from getting too bloated.

So, let’s create /src/FilePreview.vue to put this functionality in and we’ll start with just showing the image in a wrapper.

<template>
    <component :is="tag" class="file-preview">
        <img :src="file.url" :alt="file.file.name" :title="file.file.name" />
    </component>
</template>

<script setup>
defineProps({
    file: { type: Object, required: true },
    tag: { type: String, default: 'li' },
})
</script>

Once again, the styles aren’t included here, but you can find them on GitHub. First thing to note about the code we have, though, is that we’re wrapping this in a component tag and setting what type of tag it is with a tag prop. This can be a good way to make a component more generic and reusable. We’re currently using this inside an unordered list, so li is the obvious choice, but if we want to use this component somewhere else at some point, it might not be in a list, so we would want a different tag.

For the image, we’re using the URL created by the file list manager, and we’re using the file name as the alt text and as the title attribute so we get that free functionality of users being able to hover over the image and see the file name as a tooltip. Of course, you can always create your own file preview where the file name is written out where it’s always visible for the user. There’s certainly a lot of freedom in how this can be handled.

Moving on to the JavaScript, we see props defined so we can pass in the file that we’re previewing and a tag name to customize the wrapper in order to make this usable in more situations.

Of course, if you try to run this, it doesn’t seem to do anything because we currently aren’t using the FilePreview components. Let’s remedy that now. In the template, replace the current list with this:

<ul class="image-list" v-show="files.length">
    <FilePreview v-for="file of files" :key="file.id" :file="file" tag="li" />
</ul>

Also, we need to import our new component in the script section:

import  FilePreview  from  './components/FilePreview.vue'

Now if you run this, you’ll see some nice thumbnails of each image you drop or select.

Remove Files From the List

Let’s augment this with the ability to remove a file from the list. We’ll add a button with an “X” in the corner of the image that people can click/tap on to remove the image. To do this, we’ll need to add 2 lines of code to FilePreview.vue. In the template, just above the img tag add the following:

<button @click="$emit('remove', file)" class="close-icon" aria-label="Remove">×</button>

Then add this line somewhere in the script section:

defineEmits(['remove'])

Now, clicking that button will fire a remove event, passing the file along as the payload. Now we need to head back to the main app component to handle that event. All we need to do is to add the event listener to the FilePreview tag:

<FilePreview  v-for="file  of  files" :key="file.id" :file="file"  tag="li" @remove="removeFile" />

Thanks to removeFile already being defined by the file list manager and taking the same arguments that we’re passing from the event, we’re done in seconds. Now if you run the app and select some images, you can click on the little “X” and the corresponding image will disappear from the list.

Possible Improvements

As usual, there are improvements that could be made to this if you’re so inclined and your application is able to reuse this component elsewhere if it is more generic or customizable.

First of all, you could manage the styles better. I know that I didn’t post the styles here, but if you copied them from GitHub and you’re a person that cares a lot about which components control which styles, then you may be thinking that it’d be wiser to have some specific files moved out of this component. As with most of these possible improvements, this is mostly to do with making the component more useful in more situations. Some of the styles are very specific to how I wanted to display the previews for this one little app, but to make it more reusable, we either need to make styles customizable via props or pull them out and let an outer component define the styles.

Another possible change would be to add props that allow you to hide certain elements such as the button that fires the “remove” event. There are more elements coming later in the article that might be good to hide via props as well.

And finally, it might be wise to separate the file prop into multiple props such as url, name, and — as we’ll see later — status. This would allow this component to be used in situations where you just have an image URL and name rather than an UploadableFile instance, so it’s more useful in more situations.

Uploading Files

Alright, we have the drag and drop and a preview of the files selected, so now we need to upload those files and keep the user informed of the status of those uploads. We’ll start with creating a new file: /compositions/file-uploader.js. In this file, we’ll export some functions that allow our component to upload the files.

export async function uploadFile(file, url) {
    // set up the request data
    let formData = new FormData()
    formData.append('file', file.file)

    // track status and upload file
    file.status = 'loading'
    let response = await fetch(url, { method: 'POST', body: formData })

    // change status to indicate the success of the upload request
    file.status = response.ok

    return response
}

export function uploadFiles(files, url) {
    return Promise.all(files.map((file) => uploadFile(file, url)))
}

export default function createUploader(url) {
    return {
        uploadFile: function (file) {
            return uploadFile(file, url)
        },
        uploadFiles: function (files) {
            return uploadFiles(files, url)
        },
    }
}

Before looking into specific functions, note that every function in this file is exported separately so it can be used on its own, but you’ll see that we’ll only be using one of them in our application. This gives some flexibility in how this module is used without actually making the code any more complicated since all we do is add an export statement to enable it.

Now, starting at the top, we have an asynchronous function for uploading a single file. This is constructed in a very similar manner to how it was done in the previous article, but we are using an async function instead (for that wonderful await keyword) and we’re updating the status property on the provided file to keep track of the upload’s progress. This status can have 4 possible values:

• null: initial value; indicates that it has not started uploading;
• "loading": indicates that the upload is in progress;
• true: indicates the upload was successful;
• false: indicates the upload failed.

So, when we start the upload, we mark the status as "loading". Once it’s finished, we mark it as true or false depending on the result’s ok property. Soon we’ll be using these values to show different messages in the FilePreview component. Finally, we return the response in case the caller can use that information.

Note: Depending on which service you upload your files to, you may need some additional headers for authorization or something, but you can get those from the documentation for those services since I can’t write an example for every service out there.

The next function, uploadFiles, is there to allow you to easily upload an array of files. The final function, createUploader, is a function that grants you the ability to use the other functions without having to specify the URL that you’re uploading to every time you call it. It “caches” the URL via a closure and returns versions of each of the two previous functions that don’t require the URL parameter to be passed in.

Using the Uploader

Now that we have these functions defined, we need to use them, so go back to our main app component. Somewhere in the script section, we’ll need to add the following two lines:

import  createUploader  from  './compositions/file-uploader'
const { uploadFiles } = createUploader('YOUR URL HERE')

Of course, you’ll need to change the URL to match whatever your upload server uses. Now we just need to call uploadFiles from somewhere, so let’s add a button that calls it in its click handler. Add the following at the end of the template:

<button @click.prevent="uploadFiles(files)"  class="upload-button">Upload</button>

There you go. Now if you run the app, add some images, and smash that button, they should be headed for the server. But… we can’t tell if it worked or not — at least not without checking the server or the network panel in the dev tools. Let’s fix that.

Showing The Status

Open up FilePreview.vue. In the template after the img tag but still within component, let’s add the following:

<span class="status-indicator loading-indicator" v-show="file.status == 'loading'">In Progress</span>
<span class="status-indicator success-indicator" v-show="file.status == true">Uploaded</span>
<span class="status-indicator failure-indicator" v-show="file.status == false">Error</span>

All the styles are already included to control how these look if you copied the styles from GitHub earlier. These all sit in the bottom right corner of the images displaying the current status. Only one of them is shown at a time based on file.status.

I used v-show here, but it also makes a lot of sense to use v-if, so you can use either one. By using v-show, it always has the elements in the DOM but hides them. This means we can inspect the elements and cause them to show up even if they aren’t in the correct state, so we can test if they look right without trying to do it by putting the app into a certain state. Alternatively, you could go into the Vue DevTools, make sure you’re in the “Inspector” screen, click the three dots menu button in the top right and toggle “Editable props” to true, then edit the props or state in the component(s) to bring about the states needed to test each indicator.

Note: Just be aware that once you edit the file state/prop, it is no longer the same object as the one that was passed in, so clicking the button to remove the image will not work (can’t remove a file that isn’t in the array) and clicking “Upload” won’t show any state changes for that image (because the one in the array that is being uploaded isn’t the same file object as the one being displayed by the preview).

Possible Improvements

As with other parts of this app, there are a few things we could do to make this better, but that we won’t actually be changing. First of all, the status values are pretty ambiguous. It would be a good idea to implement the values as constants or an enum (TypeScript supports enums). This would ensure that you don’t misspell a value such as “loading” or try to set the status to “error” instead of false and run into a bug. The status could also be implemented as a state machine since there is a very defined set of rules for how the state changes.

In addition to better statuses, there should be better error handling. We inform the users that there was an issue with the upload, but they have no idea what the error is. Is it a problem with their internet? Was the file too big? Is the server down? Who knows? Users need to know what the problem is so they know what they can do about it — if anything.

We could also keep the users better apprised of the upload. By using XHR instead of fetch (which I discussed in the previous drag-and-drop uploader article), we can track “progress” events to know the percentage of the upload that was completed, which is very useful for large files and slow internet connections because it can prove to the user that progress is actually being made and that it didn’t get stuck.

The one change that can increase the reusability of the code is opening up the file uploader to additional options (such as request headers) to be able to be passed in. In addition, we could check the status of a file to prevent us from uploading a file that’s already in progress or is already uploaded. To further help with this, we could disable the “Upload” button during the upload, and it should probably also be disabled when there are no files selected.

And last, but most certainly not least, we should add some accessibility improvements. In particular, when adding files, removing them, and uploading them (with all those status changes), we should audibly inform screen reader users that things have changed using Live Regions. I’m no expert on this, and they fall a bit outside the scope of this article, so I will not be going into any kind of detail, but it’s definitely something everyone should look into.

Job’s Done

Well, that’s it. The Vue Drag-and-Drop Image Uploader is done! As mentioned at the beginning, you can see the finished product here and look at the final code in the GitHub Repository.

I hope you spend some time trying to implement the possible improvements that I’ve laid out in the previous sections to help you deepen your understanding of this app and keep sharpening your skills by thinking things through on your own. Do you have any other improvements that could be made to this uploader? Leave some suggestions in the comments and if you implemented any of the suggestions from above, you can share your work in the comments, too.

God bless and happy coding!

Further Reading

• How To Increase Workflow And Reduce Stress With Nature Sounds
• Take A Digital Health Check
• Designing Custom Images For Your Online Content, Faster!
• Hey Designers: Stop Being An Afterthought

(vf, yk, il, mrn)

In this article, I will explain how to use Quasar Framework and its state-of-the-art UI (which follows Material guidelines) to build a notes app. The app will get its data from and store its data to Firebase. This tutorial is meant for anyone interested in building cross-platform applications that work well across all devices simultaneously. At the end of the article, you should have a proper understanding of what Quasar is, how to get started creating apps with Quasar, and also how to use Firebase.

To follow along in this article, you should have:

• an understanding of HTML, CSS, and JavaScript;
• at least a little experience with Vue.js;
• Node.js version 10 or above and npm version 5 or above installed on your machine.
• knowledge of how the command-line interface (CLI) works.

The deployed app is available for viewing, and the final code is on Github.

What Is Quasar Framework?

Quasar Framework is an open-source Vue.js-based cross-platform framework whose motto is: “write code once and simultaneously deploy it as a website, a mobile app and/or an Electron app”. It has many features that enable you, as a web developer, to build apps on desktop and mobile and to create progressive web apps (PWAs) using technologies such as Cordova, Electron, and the web (Vue.js).

Why Quasar Framework?

Quasar is an easy-to-use but powerful UI kit comprising a lot of UI components, layout elements, and helpers. Together, these elements provide a full-featured toolset for building responsive front-end apps, without your having to make use of many different UI libraries. It does the heavy lifting for you, allowing you to focus on features and not boilerplate.

In summary, Quasar offers support for many build modes, including:

• single-page applications;
• progressive web applications;
• server-side rendering;
• mobile apps (iOS and Android), using Cordova or Сapacitor;
• multi-platform desktop apps, using Electron;
• browser extensions.

Getting Started

To get started, let’s look at how to install Quasar on your local machine and set up a project.

Installation

There are three ways to start using Quasar:

• embedding to an existing project via a content delivery network (CDN);
• installing using the Vue.js CLI Quasar plugin;
• installing using the Quasar CLI.

For this tutorial, we will be using the third method, which is the Quasar CLI. The first thing to do is install the Quasar CLI globally on your computer, or check whether it is installed by running the following commands in your CLI:

quasar -v #check if quasar has been installed previously

yarn global add @quasar/cli
# or
npm install -g @quasar/cli

Once this is done, you can now move on to setting up the project.

Project Set-Up

Run the following command in your CLI:

quasar create <folder_name>

Following this, you are going to be asked some questions. Here is my full configuration for the app we will be building.

Now we can move into the project folder and start up the application using the following commands:

cd <folder_name>
quasar dev

With the steps above complete, our app should be running on http://localhost:8080. This is what we should see:

Quasar’s Folder Structure

The default application structure for Quasar is intended to be a great starting point for developers to build any type of application. You can organize the application however you like and create directories whenever you need them.

.
├── public/                  # pure static assets (directly copied)
├── src/
│   ├── assets/              # dynamic assets (processed by Webpack)
│   ├── components/          # .vue components used in pages and layouts
│   ├── css/                 # CSS/Stylus/Sass/… files for your app
│   ├── layouts/             # layout .vue files
│   ├── pages/               # page .vue files
│   ├── boot/                # boot files (app initialization code)
│   ├── router/              # Vue Router
│   ├── store/               # Vuex Store
│   ├── App.vue              # root Vue component of your app
│   └── index.template.html  # template for index.html
├── .editorconfig            # editor config
├── .gitignore               # GIT ignore paths
├── .postcssrc.js            # PostCSS config
├── babel.config.js          # Babel config
├── package.json             # npm scripts and dependencies
├── quasar.conf.js           # Quasar app config file
└── README.md                # readme for your app

The source folder consists of about seven major directories that a beginner should care about:

• quasar.conf.js
  This is the brain behind any Quasar application, because most configurations are done in this file. Amazingly, Quasar handles most of the complex configurations needed by the various tools and packages that you might use in an application. Some of these configurations are for:
  • Quasar components, directives, and plugins that would be needed in your app;
  • icon packs;
  • CSS animation;
  • PWA manifest file and Workbox options;
  • Electron packager and/or Electron builder;
  • and a lot more.
• src/assets
  The assets directory contains your uncompiled assets, such as Stylus or Sass files, images, and fonts.
• src/components
  This is where all of your reusable components will live. These components make up the different parts of the application and can be reused and imported into your pages, layouts, and even other components.
• src/css
  You will not find this in Vue.js, but Quasar provides this so that we can have all of our global CSS in Sass form. It consists of two files: app.sass is where all of our styles will go, while quasar.variables.sass contains all of the reusable variables we would want to make use of when styling our app. You could ignore the CSS directory if you feel it’s of no use to you.
• src/layouts
  This helps us create defined layouts for an app without repeating code. This is useful when you want to include sidebars or fixed bottom bars or have distinct layouts for mobile and desktop.
• src/pages
  The pages directory contains our application’s views and routes. Our pages are injected into the app and managed through Vue Router in /src/router/routes.js. This means that each page needs to be referenced there.
• src/router
  This holds the routing configuration of our app. It consists of two folders:
  • /src/router/index.js holds the Vue Router initialization code.
  • /src/router/routes.js holds the routes of the app, loading our layouts alongside the routes or pages in the app.
    You might not need to do anything to the index.js file in a small project, but if your project will have routes, you will need to add them to the routes.js file.

Building A Notes App

When building an application with Quasar, the first thing we will want to do is create a layout. Quasar has made this process a lot easier than any other framework by making use of a layout builder. For our notes app, we will want something like the following, which is quite similar to the default layout but with a few modifications:

App Layout

In the sidebar of Quasar’s documentation, you will see the “Layout and Grid” option. When you click it, a dropdown will appear with more options, one of which is “Layout Builder”. Click on “Layout Builder”, which will bring you here:

This allows us to choose the options we want and remove the ones we don’t. Then, we would generate the code to paste in the layout file.

The first option helps us to pick the layout parts, while the second allows us to configure the layout parts. Finally, we export the generated layout.

If you want the exact same layout as mine, use the code below:

<template>
  <q-layout view="lHh lpR fFf">
    <q-header elevated class="bg-primary text-white">
      <q-toolbar>
        <q-btn dense flat round icon="menu" @click="left = !left" />
        <q-toolbar-title>
          <q-avatar>
            <img src="https://cdn.quasar.dev/logo-v2/svg/logo-mono-white.svg" />
          </q-avatar>
          Title
        </q-toolbar-title>
      </q-toolbar>
    </q-header>
    <q-drawer show-if-above v-model="left" side="left" bordered>
      <!-- drawer content -->
    </q-drawer>
    <q-page-container>
      <router-view />
    </q-page-container>
  </q-layout>
</template>

<script>
export default {
  data() {
    return {
      left: false
    };
  }
};
</script>

Remove the default layout and paste the code above or the code that you have generated into src/layouts/MainLayout.vue.

The code above is divided into three sections: the header (navbar), the drawer (sidebar), and the page container (which contains the router view).

We’ve made use of the state-of-the-art UI to style the whole page. As I said earlier, when using Quasar, you won’t need additional heavy libraries such as Hammer.js, Moment.js, or Bootstrap.

We will be adding data to the sidebar and editing the navbar. Once you’ve saved, you will notice our app now looks like this:

Let’s work on the layout, adding some items to the sidebar and changing the title of the app, If you scan the layout code that we added, you will see where we are supposed to edit and add these various items.

Here is what my layout looks like after I’ve added items to the sidebar and changed the title:

And here is the code:

<template>
  <q-layout view="lHh lpR fFf">
    <q-header elevated class="bg-primary text-white">
      <q-toolbar>
        <q-btn dense flat round icon="menu" @click="left = !left" />
        <q-toolbar-title class="text-h6">
          My Notes
        </q-toolbar-title>
      </q-toolbar>
    </q-header>
    <q-drawer show-if-above v-model="left" side="left" bordered>
      <q-list class="q-pt-xl">
        <q-item clickable v-ripple to="/">
          <q-item-section avatar>
            <q-icon name="home" size="md" />
          </q-item-section>
          <q-item-section class="text-weight-bold">Home</q-item-section>
        </q-item>
        <q-item clickable v-ripple to="/about">
          <q-item-section avatar>
            <q-icon name="info" size="md" />
          </q-item-section>
          <q-item-section class="text-weight-bold">About</q-item-section>
        </q-item>
      </q-list>
    </q-drawer>
    <q-page-container>
      <router-view />
    </q-page-container>
    <q-footer class="bg-grey-2 text-black ">
      <q-toolbar>
        <q-toolbar-title class="text-subtitle2">
          Designed and Built For this article.
        </q-toolbar-title>
      </q-toolbar>
    </q-footer>
  </q-layout>
</template>
<script>
export default {
  data() {
    return {
      left: false
    };
  }
};
</script>

We removed the logo in the navbar and edited the text, then added a list to the sidebar, making use of Quasar’s state-of-the-art UI. Check out the list items, and copy the code of any you wish to use.

App Design

Earlier on, I said I was going to use Quasar’s state-of-the-art UI (which follows Material guidelines) to build a notes app, and that’s what we will be doing now. Explaining the whole process in an article like this is difficult, but the “Style & Identity” section of Quasar’s documentation covers it well.

This will be a one-page app (index.vue), and here is the code, without any styling applied:

<template>
  <q-page class="">
    <div class="q-pa-md">
      <q-input
        bottom-slots
        v-model="newNoteContent"
        placeholder="Write your note here..."
        counter
        autogrow
        maxlength="300"
      >
        <template v-slot:after>
          <q-btn round dense flat icon="send" />
        </template>
      </q-input>
    </div>
    <q-separator size="10px" />
    <q-list bordered class="rounded-borders" style="max-width: 600px">
      <q-item-label header>You have 3 Note(s)</q-item-label>
      <div>
        <q-item>
          <q-item-section top>
            <q-item-label caption class="text-grey-9">
              He who has imagination without learning has wings but no feet.
            </q-item-label>
          </q-item-section>
          <q-item-section top side>
            <div class="text-grey-9 q-gutter-xs">
              <q-btn size="13px" flat dense round icon="delete" />
            </div>
          </q-item-section>
        </q-item>
        <q-separator size="1px" />
      </div>
      <div>
        <q-item>
          <q-item-section top>
            <q-item-label caption class="text-grey-9">
              He who has imagination without learning has wings but no feet.
            </q-item-label>
          </q-item-section>
          <q-item-section top side>
            <div class="text-grey-9 q-gutter-xs">
              <q-btn size="13px" flat dense round icon="delete" />
            </div>
          </q-item-section>
        </q-item>
        <q-separator size="1px" />
      </div>
      <div>
        <q-item>
          <q-item-section top>
            <q-item-label caption class="text-grey-9">
              He who has imagination without learning has wings but no feet.
            </q-item-label>
          </q-item-section>
          <q-item-section top side>
            <div class="text-grey-9 q-gutter-xs">
              <q-btn size="13px" flat dense round icon="delete" />
            </div>
          </q-item-section>
        </q-item>
        <q-separator size="1px" />
      </div>
    </q-list>
  </q-page>
</template>
<script>
import db from "src/boot/firebase";
export default {
  name: "PageIndex",
  data() {
    return {
      basic: false,
      fixed: false,
      newNoteContent: ""
    };
  }
};
</script>

In the code above, we have an input field from Quasar. We’ve attached a v-model to get the data from the input field once the “Submit” button is clicked. We also have a list of items that will be used to display each note, and each list item has an icon used to delete that particular item when clicked.

Setting Up Local Data

At this point, the design of our app is in place. The next thing we will do is create an array that would contain all of our notes. We will ensure that we can add to and delete from this array before setting up Firebase.

Here is the array that we will be making use of in our app for now. Later, we will remove this array or comment out the code.

notes: [
  {
    id: 1,
    noteContent: "Lorem ipsum dolor sit amet consectetur adipisicing elit. Ea vereprehenderit aspernatur mollitia saepe cupiditate pariatur natus accusantium esse repudiandae nisi velit provident corporis commodi eius fugiat reiciendis non aliquam."
  },
  {
    id: 2,
    noteContent: "Lorem ipsum dolor sit amet consectetur adipisicing elit. Ea vereprehenderit aspernatur mollitia saepe cupiditate pariatur natus accusantium esse repudiandae nisi velit provident corporis commodi eius fugiat reiciendis non aliquam."
  },
  {
    id: 3,
    noteContent: "Lorem ipsum dolor sit amet consectetur adipisicing elit. Ea vereprehenderit aspernatur mollitia saepe cupiditate pariatur natus accusantium esse repudiandae nisi velit provident corporis commodi eius fugiat reiciendis non aliquam."
  }
]

Fetching Data

We now have our array. Let’s add these data to our app. Because we understand Vue.js, all we will do is loop through this array using the v-for directive, use the data gotten from the array, and then put the content wherever we want it to appear.

<div v-for="noteContent in notes" :key="noteContent.id">
  <q-item>
    <q-item-section top>
      <q-item-label caption class="text-grey-9">
        {{ noteContent.note }}
      </q-item-label>
    </q-item-section>
    <q-item-section top side>
      <div class="text-grey-9 q-gutter-xs">
        <q-btn
          size="13px"
          flat
          dense
          round
          icon="delete"
          @click="deleteNote(noteContent)"
        />
      </div>
    </q-item-section>
  </q-item>
  <q-separator size="1px" />
</div>

We also added a click event handler to the delete button, so that it loads this function whenever it’s created.

Adding Notes

Let’s see how to add notes to our app by using the input field. We will use JavaScript’s unShift() methods, which adds one or more elements to the beginning of an array and returns the new length of the array.

The first thing to do is to add a click event handler to the button.

<q-btn round dense flat icon="send" @click="addNote" />

Then, proceed to create this method in the script area.

methods: {
  addNote() {
    let newNote = {
      id: this.notes.length + 1,
     note: this.newNoteContent
    };
    this.notes.unshift(newNote);
    this.newNoteContent = "";
  }
}

In the code above, we created an object for the new note, which comprises the ID and the note itself, and then we added this newNote to the array of notes via the unShift() method.

Deleting Notes

Finally, before proceeding to use Firebase in our app, let’s see how to delete a note. The first thing would be to add an event listener to the delete icon:

<q-btn
  size="13px"
  flat
  dense
  round
  icon="delete"
  @click="deleteNote(noteContent)"
/>

And then we would create a method:

deleteNote(noteContent) {
  let noteId = noteContent.id;

  //doing this to get the real id of the notes
  let index = this.notes.findIndex(noteContent => noteContent.id === noteId);
  this.notes.splice(index, 1);
}

In this code, we got the id of the particular note that we want to delete through the parameter passed to the click event method that was created. Then, we made use of the splice method to remove only that item from the array.

Firebase

Now that these two pieces of functionality work, let’s now see how we can use Firebase in Quasar to add, fetch, and delete data. Firebase will also give us real-time data syncing across all devices. The data in our app won’t be very much, because it’s just for the purpose of learning. In case you are thinking of something big that would be used by millions of people, check out the pricing page.

Firebase is application development software from Google that enables us to develop iOS, Android, and web apps.

Setting Up Cloud Firestore

To get started, visit firebase.google.com and click on either the “Go to console” link in the top-right corner of your screen or the “Get started” button (ensure that you sign in with your Google account).

This will bring us to the console area, where we can create a project. Click on the “Add a project” button, and a form to create your project will appear. The first question will request the project’s name, which could be anything; for this article, we will call it “notesApp”. Let’s also disable Google Analytics because ours is a mini-app.

Click on the “Create project” button (this might take few seconds, so be patient). Then, click on “Continue”, so that we can create our cloud Firestore.

In the sidebar, click on “Firestore”, and then “Create database”.

This will bring up a modal. Click on “Start in test mode”, which will make it easy for us to start working with our database. Bear in mind that, “The default security rules for test mode allow anyone with your database reference to view, edit and delete all data in your database for the next 30 days”.

Click on “Next”, leave the default Cloud Firestore location, and then click on the “Enable” button. Once it loads, our database will be fully ready for us to use.

Note: The Firebase database is made up of collections, and these collections contain documents, and each document is a JavaScript object that has fields in it.

Let’s get started by creating a new collection for our notes.

To create a collection, click on “Start collection”. A modal will pop up for you to enter the collection ID — meaning, a name. Then, click on the “Next” button.

You can now start creating the documents and fields for each note. Auto-generate the ID of the document to ensure that it is unique by clicking “Auto-ID” beside the document field.

Click “Save”, and continue to create more documents. In the end, this is what my database looks like:

Now that we are done, let’s see how to connect Firebase to our app. Go to “Project overview” in the sidebar, and let’s add this to a web app by clicking the “Web” button.

A form will appear for us to “Add Firebase” to our web app. We will give it the same name, “notesApp”, and register the app (don’t check the “Firebase hosting” field).

Once it has loaded, it will bring up an SDK to help us initialize our database in the app. We won’t do it this way, although we will need some information from the generated SDK. The right way to do this in Quasar is to import the modules that we need and use a boot file.

So, leave that tab open, and let’s see how to add the Firebase SDK and initialize Firebase in our Quasar app.

The first thing to do would be to install Firebase in our project with npm.

npm install --save firebase

Once installation is complete, we are going to initialize our app’s connection to Firebase by creating a boot file, so that we have immediate access to the database when our app is ready.

A boot file helps us to run code before the app’s Vue.js root component is instantiated. Quasar’s documentation has more information about boot files and when to use boot files.

To generate a boot file, we will run this command in our CLI:

quasar new boot firebase

Note: You don’t need to use Firebase as the name of the boot file.

Once this is done, you will notice that the file is now created in the boot folder. To make use of this newly created boot file, we’ll need to add it to the quasar.config.js file’s boot array.

Let’s go back to the newly created boot file. Delete all of the code there because we don’t need it. We’ll import the modules that we need and configure our database. Paste in the following code:

import firebase from "firebase/app";
import "firebase/firestore";

const firebaseConfig = {
  // ...
};

// Initialize Firebase
firebase.initializeApp(firebaseConfig);

Here, we’ve imported Firebase itself and Firestore, and we’ve initialized Firebase, making use of the config, which we will be adding now.

At this point, we are almost done configuring our app. We need to add our unique configuration, which was provided in the SDK that was generated when we added Firebase to our web app. Copy only the configuration, and paste it into our array.

We should now have something like this:

import firebase from "firebase/app";
import "firebase/firestore";
const firebaseConfig = {
  apiKey: "***",
  authDomain: "notesapp-ffd7c.firebaseapp.com",
  projectId: "notesapp-ffd7c",
  storageBucket: "notesapp-ffd7c.appspot.com",
  messagingSenderId: "18944010047",
  appId: "1:18944010047:web:ddfb46fc6bc8bba375158a"
};
// Initialize Firebase
firebase.initializeApp(firebaseConfig);

One last thing, since we are making use of Firestore, is that we’ll need to initialize the cloud Firestore by adding this code to our boot file (the last line):

let db = firebase.firestore();
export default db;

This db will give us access to our Firestore database. We also exported it so that we can use it anywhere in our app.

At this point, you might still be a little confused, but if you have followed this guide, then you will have properly initialized Firebase for your application. You can read more about adding Firebase to your JavaScript project in the documentation.

Fetching Data From Firebase

If you have followed the guide so far, everything should work fine once you launch your app. Now let’s grab the notes created in the database and display them in our app.

For this, we will be making use of the .onSnapshot hook, which will be fired any time the data in our collection changes. This will tell us whether a document has been added, removed, or updated. For this guide, we will only deal with the addition and removal of documents. Using hooks like this makes real-time syncing across devices possible. Let’s get started.

The first thing to do would be for us to get access to the database by importing it into the index page of our app.

import db from 'src/boot/firebase';

Then, create a mounted hook, because we want to fetch our data immediately after the app has loaded.

mounted() {
  db.collection("notes").onSnapshot(snapshot => {
    snapshot.docChanges().forEach(change => {

      let noteChange = change.doc.data();

      if (change.type === "added") {
        console.log("New note: ", noteChange);
        this.notes.unshift(noteChange);
      }
      if (change.type === "modified") {
        console.log("Modified note: ", noteChange);
      }
      if (change.type === "removed") {
        console.log("Removed note: ", noteChange);
      }
    });
  });
}

In the code above, we are simply grabbing our notes collection, and every time there is a change in the collection, the onSnapShot method will be fired, which will return a snapShot of all our data. All of these data will be objects with type properties. These type properties will tell us the type of change that has happened and give us access to the data that was either added, modified, or removed.

This might sound confusing, but you will understand what we are doing as you read on.

If you save your code and check the console environment, you will notice that each note has been logged out. We can now push these objects to the notes array that we created earlier, so that we can display real-time data in our application.

The first thing to do is delete or comment out the objects in the notes array, so that we have something like this:

notes: []

Then, pass the objects to this array:

this.notes.unshift(noteChange);

Your code should now look like this:

if (change.type === "added") {
  this.notes.unshift(noteChange);
}

At this point, if you load the app, you will notice that you have successfully fetched your data from Firebase.

Adding Data To Firebase

Let’s see how to add a note to our notes collection in this app. At this point, if you try to use the input field to add a note, it will work but the note will disappear once you refresh the page because it’s not stored in any database.

To do this with Firebase, all that is needed is to update the addNote() method that we created earlier.

addNote() {
  let newNote = {
    // id: this.notes.length + 1,
    note: this.newNoteContent
  };
  // this.notes.unshift(newNote);

  db.collection("notes")
    .add(newNote)
    .then(docRef => {
      console.log("Document written with ID: ", docRef.id);
    })
    .catch(error => {
      console.error("Error adding document: ", error);
    });

  this.newNoteContent = "";
},

The first thing we did here was remove the ID that is used when we made use of the previous array, because we are now going to auto-generate the ID from Firebase. We also removed the unshift() method; it’s no longer useful because data is being fetched for our app once there is an update using the snapShot hook.

If we look at the code responsible for updating the Firestore db, all we are passing to the collection (notes) is the new object (newNote), and this function will automatically generate an ID for each of our documents. The documentation has more information on adding data to Firebase.

Deleting Data From Firebase

We are almost done with our app, but we need to be able to delete data in our app from Firebase. Currently, the delete function works, but if you reload the app, the deleted data will reappear.

As we did before, we are going to delete these data (or documents) from Firebase using the unique ID generated by Firebase.

Currently, we don’t have access to the ID. To access it, we will add it to the noteChange object:

noteChange.id = change.doc.id;

Once that is set, deleting data will be as easy as adding it. All we have to do is go to the deleteNote(noteContent) method that we created previously, delete the previous code, and make use of this:

deleteNote(noteContent) {
  let noteId = noteContent.id;
  db.collection("notes")
    .doc(noteId)
    .delete()
    .then(() => {
      console.log("Document successfully deleted!");
    })
    .catch(error => {
      console.error("Error removing document: ", error);
    });
}

This checks the notes collection for a document with the specified ID and then deletes it. But if we save our code now and click the delete icon, the data will delete but won’t leave the app’s interface unless we refresh our code, meaning that the snapshot hook needs to be updated. Go to the snapshot hook for removed, and add this code:

if (change.type === "removed") {
  console.log("Removed note: ", noteChange);
  let index = this.notes.findIndex(
    noteContent => noteContent.id === noteChange.id
  );
  this.notes.splice(index, 1);
}

This simply gets the ID of the post that we deleted and removes it from the interface.

With that done, we have built an app with Quasar that works with Firebase. One major advantage of Quasar is that it enables us to simultaneously deploy our project as a website, mobile app, or Electron app.

To deploy for iOS, Cordova needs to be installed on our local machine. A MacBook is highly preferable. Navigate to your CLI, and install Cordova globally:

$ npm install - g cordova

To install on Windows, you would make use of Electron. The documentation properly explains how to do this.

Conclusion

In this guide, we have built a notes application using Quasar and Firebase. By following this guide, you are now in a position to improve on and add your own features and functionality. Here are a few ideas to get you started:

• Implement functionality to modify notes.
• Add dates, so that you can order the data by date.
• Style the app, and make it more creative.
• Add images.
• A lot more.

Useful Resources

• Quasar documentation
• Firebase documentation

Further Reading

• How To Boost Your Design Workflow With Setapp
• Composable CSS Animation In Vue With AnimXYZ
• The Era Of Platform Primitives Is Finally Here
• Creating An Effective Multistep Form For Better User Experience

(ks, vf, yk, il, al, mrn)

In this article, you will learn how to use the AnimXYZ toolkit to create unique, interactive, and visually engaging animations in Vue.js and plain HTML. By the end of this article, you will have learned how adding a few CSS classes to elements in Vue.js components can give you a lot of control over how those elements move in the DOM.

This tutorial will be beneficial to readers who are interested in creating interactive animations with few lines of code.

Note: This article requires a basic understanding of Vue.js and CSS.

What Is AnimXYZ?

AnimXYZ is a composable, performant, and customizable CSS animation toolkit powered by CSS variables. It is designed to enable you to create awesome and unique animations without writing a line of CSS keyframes. Under the hood, it uses CSS variables to create custom CSS properties. The nice thing about AnymXYZ is its declarative approach. An element can be animated in one of two ways: when entering or leaving the page. If you want to animate an HTML element with this toolkit, adding a class of xyz-out will animate the item out of the page, while xyz-in will animate the component into the page.

This awesome toolkit can be used in a regular HTML project, as well as in a Vue.js or React app. However, as of the time of writing, support for React is still under development.

Why Use AnimXYZ?

Composable

Animation with AnimXYZ is possible by adding descriptive class names to your markup. This makes it easy to write complex CSS animation without writing complex CSS keyframes. Animating an element into the page is as easy as adding a class of xyz-in in the component and declaring a descriptive attribute.

<p class="xyz-in" xyz="fade">Composable CSS animation with AnimXYZ</p>

The code above will make the paragraph element fade into the page, while the code below will make the element fade out of the page. Just a single class with a lot of power.

<p class="intro xyz-out" xyz="fade">Composable CSS animation with AnimXYZ</p>

Customizable

For simple animations, you can use the out-of-the-box utilities, but AnimXYZ can do so much more. You can customize and control AnimXYZ to create exactly the animations you want by setting the CSS variables that drive all AnimXYZ animations. We will create some custom animations later on in this tutorial.

Performant

With AnimXYZ, you can create powerful and smooth animations out of the box, and its size is only 2.68 KB for the base functionality and 11.4 KB if you include the convenient utilities.

Easy to Learn and Use

AnimXYZ works perfectly with regular HTML and CSS, and it can be integrated in a project using the content delivery network (CDN) link. It can also be used in Vue.js and React, although support for React is still under development. Also, the learning curve with this toolkit is not steep when compared to animation libraries such as GSAP and Framer Motion, and the official documentation makes it easy to get started because it explains how the package works in simple terms.

Key Concepts in AnimXYZ

Contexts

When you want a particular flow of animation to be applied to related groups of element, the xyz attribute provides the context. Let’s say you want three divs to be animated in the same way when they enter the page. All you have to do is add the xyz attribute to the parent element, with the composable utilities and variable that you want to apply.

<div class="shape-wrapper xyz-in" xyz="fade flip-up flip-left">
  <div class="shape"></div>
  <div class="shape"></div>
  <div class="shape"></div>
</div>

The code above will apply the same animation to all divs with a class of shape. All child elements will fade into the page and flip to the upper left, because the attribute xyz="fade flip-up flip-left" has been applied to the parent element.

AnimXYZ makes it easy to animate a child element differently from its parent. To achieve this, add the xyz attribute with a different animation variable and different utilities to the child element, which will reset all animation properties that it has inherited from its parent.

Utilities

AnimXYZ comes with a lot of utilities that will enable you to create engaging and powerful CSS animations without writing any custom CSS.

xyz="fade up in-left in-rotate-left out-right out-rotate-right"

For example, the code above has a fade up utility, which will make the element fade from top to bottom when coming into the page. It will come in and rotate from the left. When the element leaves the page, it will go to the right and rotate out of the page.

With the out-of-the-box utilities, you can, say, flip a group of elements to the right and make them fade while leaving the page. The possibilities of what can be achieved with the utilities are endless.

Staggering

The stagger utility controls the animation-delay CSS property for each of the elements in a list, so that their animations are triggered one after another. It specifies the amount of time to wait between applying the animation to an element and beginning to perform the animation. Essentially, it is used to queue up animation so that elements can be animated in sequence.

<div class="shape-wrapper" xyz="fade up-100% origin-top flip-down flip-right-50% rotate-left-100% stagger">
  <div class="shape xyz-in"></div>
  <div class="shape xyz-in"></div>
  <div class="shape xyz-in"></div>
  <div class="shape xyz-in"></div>
</div>

By adding the stagger utility, each element in a parent div will animate one after another from left to right. The order can be revered by using stagger-rev.

With stagger:

Without stagger:

Using AnimXYZ With HTML and CSS

Let’s build a card and add some cool animation with AnimeXYZ.

First, we need to add the AnimXYZ toolkit to our project. The easiest way is via a CDN. Grab the CDN, and add it to the head of your HTML document.

Add the following lines of code to your HTML.

<p class="intro xyz-in" xyz="fade">Composable CSS Animation with Animxyz</p>
  <div class="glass xyz-in" id="glass"
        xyz="fade flip-down flip-right-50%  duration-10">
        <img src="https://cdn.dribbble.com/users/238864/screenshots/15043450/media/7160a9f4acc18f4ec2cbe38eb167de62.jpg"
            alt="" class="avatar xyz-in">
        <p class="des xyz-in">Image by Jordon Cheung</p>
  </div>

This is where the magic happens. At the top of the page, we have a paragraph tag with a class of xyz-in and an xyz attribute with a value of fade. This means that the p element will fade into the page.

Next, we have a card with an id of glass, with the following xyz attribute:

  xyz="fade flip-down flip-right-50%  duration-10"

The composable utilities above will make the card fade into the page. The flip-down value will set the card to flip into the page from the bottom, and the flip-right value will flip the card by 50% when leaving the page. An animation duration of 10 (i.e. 1 second) sets the length of time that the animation will take to complete one cycle.

Integrating AnimXYZ in Vue.js

Scaffold a Vue.js Project

Using the Vue.js command-line interface (CLI), run the command below to generate the application:

vue create animxyz-vue

Install VueAnimXYZ

npm install @animxyz/vue

This will install both the core package and the Vue.js package. After installation, we will have to import the VueAnimXYZ package into our project and add the plugin globally to our Vue.js application. To do this, open your main.js file, and add the following block of code accordingly:

import VueAnimXYZ from '@animxyz/vue'  // import AnimXZY vue package
import '@animxyz/core' // import AnimXZY core package

Vue.use(VueAnimXYZ)

The XyzTransition Component

The XyzTransition component is built on top of Vue.js’ transition component. It’s used to animate individual elements into and out of the page.

Here is a demo of how to use the XyzTransition component in Vue.js.

Notice that a lot of the complexity that comes with Vue.js’ transition component has been abstracted away in order to reduce complexity and increase efficiency. All we need to care about when using the XyzTransition component are the appear, appear-visible, duration, and mode props.

For a more detailed guide, check out the official documentation.

Let’s use the XYZTransition component to animate an element when a button is clicked.

<div id="app">
    <button @click="isAnimate = !isAnimate">Animate</button>
    <XyzTransition
      appear
      xyz="fade up in-left in-rotate-left out-right out-rotate-right"
    >
      <div class="square" v-if="isAnimate"></div>
    </XyzTransition>
</div>

Notice how the element that we intend to transition is wrapped in the XYZTransition component. This is important because the child element <div class="square" v-if="isAnimate"></div> will inherit the utilities that are applied to the XYZTransition component. The child element is also conditionally rendered when isAnimate is set to true. When the button is clicked, the child element with a class of square is toggled into and out of the DOM.

XyzTransitionGroup

The XyzTransitionGroup component is built on top of Vue.js’ transition-group component. It is used to animate groups of elements into and out of the page.

Below is an illustration of how to use the XyzTransitionGroup component in Vue.js. Notice here again that a lot of the complexity that comes with Vue.js’ transition-group component has been abstracted away in order to reduce complexity and increase efficiency. All we need to care about when using the XyzTransitionGroup component are appear, appear-visible, duration, and tag. The following is taken from the documentation:

<XyzTransitionGroup
  appear={ boolean }
  appear-visible={ boolean | IntersectionObserverOptions }
        duration={ number | 'auto' | { appear: number | 'auto', in: number | 'auto',
                   out: number | 'auto' } }
        tag={ string } >
        <child-component />
        <child-component />
        <child-component />
</XyzTransitionGroup>

Build an Animated Modal With AnimXYZ and Vue.js

Let’s build modal components that will animate as they enter and leave the DOM.

Here is a demo of what we are going to build:

By adding the xyz="fade out-delay-5" property to the XyzTransition component, the modal will fade.

Notice that we are adding .xyz-nested to almost all child elements of the modal component. This is because we want to trigger their animations when a modal component’s element is open.

The ease-out-back property that we added to the dialog container will add a slight overshoot when the dialog is opened and when it has been closed.

Adding in-delay to the child elements of the modal component will make the animation feel more natural, because the element will be delayed until the other contents of the modal have animated in:

  <section class="xyz-animate">
    <div class="alerts__wrap copy-content">
      <div class="alert reduced-motion-alert">
        <p>
          AnimXYZ animations are disabled if your browser or OS has
          reduced-motion setting turned on.
          <a href="https://web.dev/prefers-reduced-motion/" target="_blank">
            Learn more here.
          </a>
        </p>
      </div>
    </div>
    <h1>Modal Animation With AnimXYZ and Vue.js</h1>
    <button
      class="modal-toggle modal-btn-main"
      data-modal-text="Open Modal"
      data-modal-title="Title"
      data-modal-close-text="Close"
      id="label_modal_kdf8e87cga"
      aria-haspopup="dialog"
      ref="openButton"
      @click="open"
      autofocus
    >
      Open Modal
    </button>
    <span
      id="js-modal-overlay"
      class="simple-modal-overlay"
      data-background-click="enabled"
      title="Close this window"
      v-if="isModal"
      @click="close"
    >
      <span class="invisible">Close this window</span>
    </span>
    <div
      role="dialog"
      class="simple-modal__wrapper"
      aria-labelledby="modal-title"
    >
      <XyzTransition duration="auto" xyz="fade out-delay-5">
        <section
          id="modal1"
          aria-labelledby="modal1_label"
          aria-modal="true"
          class="modal xyz-nested"
          xyz="fade small stagger ease-out-back"
          v-if="isModal"
          tabindex="-1"
          ref="modal"
          @keydown.esc="close"
        >
          <div class="modal_top flex xyz-nested" xyz="up-100% in-delay-3">
            <header
              id="modal1_label modal-title"
              class="modal_label xyz-nested"
              xyz="fade right in-delay-7"
            >
              Join our community on Slack
            </header>
            <button
              type="button"
              aria-label="Close"
              xyz="fade small in-delay-7"
              class="xyz-nested"
              @click="close"
              title="Close"
            >
              <svg viewBox="0 0 24 24" focusable="false" aria-hidden="true">
                <path
                  fill="currentColor"
                  d="M.439,21.44a1.5,1.5,0,0,0,2.122,2.121L11.823,14.3a.25.25,0,0,1,.354,0l9.262,9.263a1.5,1.5,0,1,0,2.122-2.121L14.3,12.177a.25.25,0,0,1,0-.354l9.263-9.262A1.5,1.5,0,0,0,21.439.44L12.177,9.7a.25.25,0,0,1-.354,0L2.561.44A1.5,1.5,0,0,0,.439,2.561L9.7,11.823a.25.25,0,0,1,0,.354Z"
                ></path>
              </svg>
            </button>
          </div>
          <div class="modal_body xyz-nested" xyz="up-100% in-delay-3">
            <div class="modal_body--top flex justify_center align_center">
              <img
                src="../assets/slack.png"
                alt="slack logo"
                class="slack_logo"
              />
              <img src="../assets/plus.png" alt="plus" class="plus" />
              <img
                src="../assets/discord.png"
                alt="discord logo"
                class="discord_logo"
              />
            </div>
            <p><span class="bold">929</span> users are registered so far.</p>
          </div>
          <form class="modal_form" autocomplete>
            <label for="email"
              ><span class="sr-only">Enter your email</span></label
            >
            <input
              id="email"
              type="email"
              placeholder="johndoe@email.com"
              autocomplete="email"
              aria-describedby="email"
              class="modal_input"
              required
            />
            <button type="submit" class="modal_invite_btn">
              Get my invite
            </button>
            <p>Already joined?</p>
            <button
              type="button"
              aria-describedby="open_slack"
              class="
                modal_slack_btn
                flex
                align_center
                justify_center
                xyz-nested
              "
              xyz="fade in-right in-delay-7"
              id="open_slack"
            >
              <span
                ><img src="../assets/slack.png" alt="slack logo" role="icon"
              /></span>
              Open Slack
            </button>
          </form>
        </section>
      </XyzTransition>
    </div>
  </section>

Then, in our modal, we would use the v-if="isModal" directive to specify that we want the modal to be hidden from the page by default. Then, when the button is clicked, we open the modal by calling the open() method, which sets the isModal property to true. This will reveal the modal on the page and also apply the animation properties that we specified using AnimXYZ’s built-in utilities.

<script>
export default {
  data() {
    return {
      isModal: false,
    };
  },
  methods: {
    open() {
      if (!this.isModal) {
        this.isModal = true;
        this.$nextTick(() => {
          const modalRef = this.$refs.modal;
          console.log(modalRef);
          modalRef.focus();
        });
      }
    },
    close() {
      if (this.isModal) {
        this.isModal = false;
        this.$nextTick(() => {
          const openButtonRef = this.$refs.openButton;
          openButtonRef.focus();
        });
      }
    },
  },
};
</script>

AnimXYZ’s animations are disabled when the reduced-motion setting in the browser or operating system is turned on. Let’s display a helper message to users who have opted in to reduced motion.

Using the @media screen and (prefers-reduced-motion) media query, we’ll display a message notifying those users that they’ve turned off the animation feature in our modal component. To do this, add the following block of code to your styles:

<style>
@media (prefers-reduced-motion: reduce) {
  .alerts__wrap {
    display: block;
  }
}
</style>

Conclusion

We’ve gone through the basics of AnimXYZ and how to use it with plain HTML and Vue.js. We’ve also implemented some demo projects that give us a glimpse of the range of CSS animations that we can create simply by adding the composable utility classes provided by this toolkit, and all without writing a single line of a CSS keyframe. Hopefully, this tutorial has given you a solid foundation to add some sleek CSS animations to your own projects and to build on them over time for any of your needs.

The final demo is on GitHub. Feel free to clone it and try out the toolkit for yourself.

That’s all for now! Let me know in the comments section below what you think of this article. I am active on Twitter and GitHub. Thank you for reading, and stay tuned.

Resources

• Documentation, AnimXYZ
• AnimXYZ, Chris Coyier, CSS Tricks

Further Reading

• How To Deal With Big Tooling Upgrades In Large Organizations
• Sticky Headers And Full-Height Elements: A Tricky Combination
• An Introduction To CSS Scroll-Driven Animations: Scroll And View Progress Timelines
• The Design Leader Dilemma

(ks, vf, yk, il, al, mrn)

Giving users the ability to quickly search through and navigate our content easily comes with great benefits. This not only improves the user experience, but also increases user retention and boosts conversion as users can now explore beyond what brought them to our site in the first place.

In this tutorial, we’ll be looking at how to integrate this search functionality into our Nuxt app using Algolia. Algolia is a third-party service that we can integrate into our app and provides us with a set of tools that allow us to create a full search experience in our sites and applications.

We’ll be using Nuxt Content, “Git Based Headless CMS” which allows us to create and manage content using Markdown, XML, JSON files, and so on. We’ll build a Nuxt site with Nuxt Content with a search feature using Algolia InstantSearch, for styling, we’ll use TailwindCSS. This tutorial is aimed at Vue.js devs that are familiar with Nuxt.

Prerequisites

To follow along with this tutorial, you’ll need to have the following installed:

• Node,
• A text editor, I recommend VS Code with the Vetur extension (for Vue.js syntax features in VS Code),
• A terminal, you can use VS Code’s integrated terminal or any other of your choice.

You’ll also require a basic understanding of the following in order to follow along smoothly:

• HTML, CSS & JavaScript,
• Vue.js,
• Nuxt.js,
• TailwindCSS.

Setting Up Our Nuxt App

Nuxt.js is a framework built on Vue, it has many capabilities and features including Server-Side Rendering (SSR).

To install it, open our terminal and run:

npx create-nuxt-app <project-name>

“Where <project-name> is the name of our project folder, I’ll be using algolia-nuxt for this project.”

Running the command will ask you some questions (name, Nuxt options, UI framework, TypeScript, etc. ). To find out more about all the options, see the Create Nuxt app.

When asked for Nuxt.js modules, make sure to select Content - Git-based headless CMS to install the nuxt/content module along with our Nuxt app.

After selecting all of your options, installation can begin. My selected options look like this:

After successfully installing the Nuxt app, navigate to the directory by running this command:

cd algolia-nuxt

Install Nuxt Content Separately

If you already have Nuxt set up before now, you can install the content module by running the command.

Skip this if you’ve already selected to install the nuxt/content module along with our Nuxt app.

#install nuxt content

npm install @nuxt/content

Then you can add it to our modules property inside our nuxt.config file.

//nuxt.config.js

export default {
  modules: ['@nuxt/content']
}

Install And Setup TailwindCSS

TailwindCSS is a utility first CSS framework that provides us with custom classes we can use to style our app.

We’ll also be using TailwindCSS Typography, which is “a plugin that provides a set of prose classes you can use to add beautiful typographic defaults to any vanilla HTML you don’t control (like HTML rendered from Markdown, or pulled from a CMS).”

First, we install @nuxtjs/tailwindcss which is a Nuxt module for TailwindCSS integration, as well as TailwindCSS and its peer-dependencies using npm:

npm install -D @nuxtjs/tailwindcss tailwindcss@latest postcss@latest autoprefixer@latest

Add the @nuxtjs/tailwindcss module to the buildModules section of our nuxt.config.js file:

// nuxt.config.js

export default {
  buildModules: ['@nuxtjs/tailwindcss']
}

Create Configuration File

Next, generate our tailwind.config.js file:

npx tailwindcss init

This will create a minimal tailwind.config.js file at the root of our project:

//tailwind.config.js

module.exports = {
  purge: [],
  darkMode: false, // or 'media' or 'class'
  theme: {
    extend: {},
  },
  variants: {
    extend: {},
  },
  plugins: [],
}

Create a tailwind.css file in assets/css/ use the @tailwind directive to inject TailwindCSS’ base, components, and utilities styles:

/*assets/css/tailwind.css*/

@tailwind base;
@tailwind components;
@tailwind utilities;

You can import the CSS file into our components or make it accessible globally by defining the CSS files/modules/libraries you want to set globally (included in every page).

  /* nuxt.config.js*/

  // Global CSS: https://go.nuxtjs.dev/config-css
  css: [
    // CSS file in the project
    '@/assets/css/tailwind.css',
  ],

Here, we have added the path to our tailwind.css file to the list of global CSS files in our nuxt.config.js.

“The @/ tells Nuxt that it’s an absolute path to look for the file from the root directory.”

Install TailwindCSS Typography

# Using npm
npm install @tailwindcss/typography

Then add the plugin to our tailwind.config.js file:

// tailwind.config.js
module.exports = {
  purge: [],
  darkMode: false, // or 'media' or 'class'
  theme: {
    extend: {},
  },
  variants: {
    extend: {},
  },
  plugins: [
    require('@tailwindcss/typography'),
  ],
}

Configure TailwindCSS To Remove Unused Styles In Production

In our tailwind.config.js file, configure the purge option with the paths to all of our pages and components so TailwindCSS can tree-shake unused styles in production builds:

// tailwind.config.js
module.exports = {
  purge: [
    './components/**/*.{vue,js}',
    './layouts/**/*.vue',
    './pages/**/*.vue',
    './plugins/**/*.{js,ts}',
    './nuxt.config.{js,ts}',
  ],
  darkMode: false, // or 'media' or 'class'
  theme: {
    extend: {},
  },
  variants: {
    extend: {},
  },
  plugins: [
    require('@tailwindcss/typography'),
  ],
}

Since we’ve installed the packages, let’s start our app:

npm run dev

This command starts our Nuxt app in development mode.

Nice 🍻

Creating Our Pages And Articles

Now, let’s create our articles and a blog page to list out our articles. But first, let’s create a site header and navigation component for our site.

Creating A Site Header And Navigation

Navigate to our components/folder, and create a new file siteHeader.vue and enter the following code:

<!-- components/siteHeader.vue -->

<template>
  <header class="fixed top-0 w-full bg-white bg-opacity-90 backdrop-filter backdrop-blur-md">
    <div class="wrapper flex items-center justify-between p-4 m-auto max-w-5xl">
      <nuxt-link to="/">
        <Logo />
      </nuxt-link>

      <nav class="site-nav">
        <ul class="links">
          <li>
            <nuxt-link to="/blog">Blog</nuxt-link>
          </li>
        </ul>
      </nav>
    </div>
  </header>
</template>

Here, in our <header> we have a <Logo /> component wrapped in <nuxt-link> which routes to the home page and another <nuxt-link> that routes to /blog (We’ll create the blog page that we will create later on).

This works without us importing the components and configuring routing ourselves because, by default, Nuxt handles importing components and routing for us.

Also, let’s modify the default <Logo /> component. In components/Logo.vue, replace the content with the following code:

<!-- components/Logo.vue -->

<template>
  <figure class="site-logo text-2xl font-black inline-block">
    <h1>Algolia-nuxt</h1>
  </figure>
</template>

We can now add our siteHeader.vue component to our site. In layouts/default.vue, add <site-header /> just above the <Nuxt /> component.

<!-- layouts/default.vue -->

<template>
  <div>
    <site-header />
    <Nuxt />
  </div>
</template>

...

The <Nuxt /> component renders the current Nuxt page depending on the route.

Creating Our First Article

In content/, which is a folder created automatically for the nuxt/content module, create a new folder articles/ and then a new file in the folder first-blog-post.md. Here is the file for our first article in markdown format. Enter the following code:

<!-- content/articles/first-blog-post.md -->

---

title: My first blog post
description: This is my first blog post on algolia nuxt
tags: [first, lorem ipsum, Iusto]

---

## Lorem ipsum

Lorem ipsum dolor sit amet consectetur, adipisicing elit.
Assumenda dolor quisquam consequatur distinctio perferendis.

## Iusto nobis nisi

repellat magni facilis necessitatibus, enim temporibus.

- Quisquam
- assumenda
- sapiente explicabo
- totam nostrum inventore

The area enclosed with --- is the YAML Front Matter which will be used as a custom injected variable that we will access in our template.

Next, we’re going to create a dynamic page which will be used to:

• Fetch the article content using asyncData which runs before the page has been rendered. We have access to our content and custom injected variables through the context by using the variable $content. As we are using a dynamic page, we can know what article file to fetch using the params.slug variable provided by Vue Router to get the name of each article.
• Render the article in the template using <nuxt-content>.

Ok, navigate to pages/ and create a blog/ folder. Create a _slug.vue (our dynamic page) file and insert the following:

<!-- pages/blog/_slug.vue -->

<template>
  <article class="prose prose-lg lg:prose-xl p-4 mt-24 m-auto max-w-4xl">
    <header>
      <h1>{{ article.title }}</h1>
      <p>{{ article.description }}</p>
      <ul class="list-none">
        <li class="inline-block mr-2 font-bold font-monospace" v-for="tag in article.tags" :key="tag" > {{tag}} </li>
      </ul>
    </header>
    <!-- this is where we will render the article contents -->
    <nuxt-content :document="article" />
  </article>
</template>

<script>
export default {
  async asyncData({ $content, params }) {
    //here, we will fetch the article from the articles/ folder using the name provided in the `params.slug`
    const article = await $content('articles', params.slug).fetch()

    //return `article` which contains our custom injected variables and the content of our article
    return { article }
  },
}
</script>

If you go to your browser and navigate to https://localhost:3000/blog/first-blog-post you should see our rendered content:

Now that our dynamic page is working and our article is rendering, let’s create some duplicates for the purpose of this tutorial.

<!-- content/articles/second-blog-post.md -->

---

title: My first blog post
description: This is my first blog post on algolia nuxt
tags: [first, Placeat amet, Iusto]

---

## Lorem ipsum

Lorem ipsum dolor sit amet consectetur, adipisicing elit.
Assumenda dolor quisquam consequatur distinctio perferendis.

## Iusto nobis nisi

repellat magni facilis necessitatibus, enim temporibus.

- Quisquam
- assumenda
- sapiente explicabo
- totam nostrum inventore

Create Blog Page To List Our Articles

Let’s now create a blog page to list our articles. This is also where our search bar will live. Create a new file pages/blog/index.vue.

<!-- pages/blog/index.vue -->

<template>
  <main>
    <section class="p-4 mt-24 m-auto max-w-4xl">
      <header>
        <h1 class="font-black text-2xl">All posts</h1>
          
        <!-- dummy search bar -->
        <div class="search-cont inline-flex gap-2 bg-white p-2 rounded-lg shadow-lg">
          <input class="px-2 outline-none" type="search" name="search" id="search">
          <button class="bg-blue-600 text-white px-2 rounded-md" type="submit">Search</button>
        </div>
      </header>
      <ul class="prose prose-xl">
          <!-- list out all fetched articles --> 
        <li v-for="article in articles" :key="article.slug">
          <nuxt-link :to="{ name: 'blog-slug', params: { slug: article.slug } }">
            <h2 class="mb-0">{{ article.title }}</h2>
            <p class="mt-0">{{ article.description }}</p>
          </nuxt-link>
        </li>
      </ul>
    </section>
  </main>
</template>

<script>
export default {
  async asyncData({ $content }) {
    // fetch all articles in the folder and return the:
    const articles = await $content('articles')
      // title, slug and description
      .only(['title', 'slug', 'description'])
      // sort the list by the `createdAt` time in `ascending order`
      .sortBy('createdAt', 'asc')
      .fetch()

    return { articles }
  },
}
</script>

Here, in our asyncData function, when fetching $content('articles') we chain .only(['title', 'slug', 'updatedAt', 'description']) to fetch only those attributes from the articles, .sortBy('createdAt', 'asc') to sort it and lastly fetch() to fetch the data and assign it to const articles which we then return.

So, in our <template>, we can the list of articles and create links to them using their slug property.

Our page should look something like this:

Great 🍻

Install And Set Up Algolia Search And Vue-instantSearch

Now that we’ve gotten the basic stuff out of the way, we can integrate Algolia Search into our blog site.

First, let’s install all the packages we will be needing:

#install dependencies

npm install vue-instantsearch instantsearch.css algoliasearch nuxt-content-algolia remove-markdown dotenv

• vue-instantsearch
  Algolia InstantSearch UI component/widget library for Vue.
• instantsearch.css
  Custom styling for instantSearch widgets.
• algoliasearch
  A HTTP client to interact with Algolia.
• nuxt-content-algolia
  Package for indexing our content and sending it to Algolia.
• remove-markdown
  This strips all markdown characters from the bodyPlainText of the articles.
• dotenv
  This helps to read environment variables from .env files.

We’ll be using these packages throughout the rest of this tutorial, but first, let’s set up an Algolia account.

Set Up Algolia Account

Sign up for an Algolia account at https://www.algolia.com/. You can do this for free, however, this will give you a trial period of 14days. Since we’re not performing heavy tasks with Algolia, their free tier will do just fine for our project after the trial expires.

You’ll be taken through some onboarding steps. After that, an UNAMED APP will be created for you. On the sidebar, on the left, navigate to the API Keys you’ll be provided with:

• Application ID
  This is your unique application identifier. It’s used to identify you when using Algolia’s API.
• Search Only API Key
  This is the public API key to use in your frontend code. This key is only usable for search queries and sending data to the Insights API.
• Admin API Key
  This key is used to create, update and DELETE your indices. You can also use it to manage your API keys.

Now that we have our API Keys, let’s save them in an .env file for our project. Navigate to the project root folder and create a new file .env and enter your API keys:

.env

ALGOLIA_APP_ID=algolia-app-id
ALGOLIA_API_KEY=algolia-admin-api-key

Replace algolia-app-id and algolia-admin-api-key with your Application ID and Admin API Key respectively.

Create An 'Articles' Index For Our Nuxt Articles In Algolia

On your Algolia account, go to Indices and click on create Index. Then enter the name of your index and we’ll be using articles for this tutorial.

As you can see, our 'article' index has been created.

Set Up nuxt-content-algolia To Send Content Index To Algolia

We’ve successfully created an index property on our account. Now we have to generate an index from our Nuxt articles which is what Algolia will use to provide results for search queries. This is what the nuxt-content-algolia module that we previously installed is for.

We need to configure it in our nuxt.config.js.

First, we will add it to our buildModules:

// nuxt.config.js

...

// Modules for dev and build (recommended): https://go.nuxtjs.dev/config-modules
buildModules: ['@nuxtjs/tailwindcss', 'nuxt-content-algolia'],

...

Then, we create a new nuxtContentAlgolia object and add a few configurations to it:

// nuxt.config.js

export default {
...

nuxtContentAlgolia: {

  // Application ID
  appId: process.env.ALGOLIA_APP_ID,
    
  // Admin API Key
  // !IMPORTANT secret key should always be an environment variable
  // this is not your search only key but the key that grants access to modify the index
  apiKey: process.env.ALGOLIA_ADMIN_API_KEY,

  paths: [
    {
      name: 'articles',
      index: process.env.ALGOLIA_INDEX || 'articles',
      fields: ['title', 'description', 'tags', 'bodyPlainText']
    }
  ]
},


...
}

The nuxtContentAlgolia takes in the following properties:

• appId
  Application ID*.
• apiKey
  Admin API Key.
• paths
  An array of index objects. This is where we define where we want to generate indexes from. Each object takes the following properties:
  • name
    The name of the folder within the content/ folder. In other words, we’ll be using files within content/articles/ since we defined the name as 'articles'.
  • index
    This is the name of the index we created on our Algolia dashboard.
  • fields
    An array of fields to be indexed. This is what Algolia will base its search queries on.

Generate bodyPlainText From Articles

Note that in the fields array, we have bodyPlainText as one of its values. Nuxt Content does not provide such a field for us. Instead, what Nuxt Content provides is body which is a complex object that will be rendered in the DOM.

In order to get our bodyPlainText which is simply all text, stripped of markdown and HTML characters, we have to make use of yet another package, remove-markdown.

To use the remove-markdown function we need to make use of Nuxt hooks. We’ll use the 'content:file:beforeInsert' hook which allows you to add data to a document before it is inserted, to strip off the markdown and add the generated plain text to bodyPlainText.

// nuxt.config.js

export default {
...
    
hooks: {
  'content:file:beforeInsert': (document)=>{
    const removeMd = require('remove-markdown');

    if(document.extension === '.md'){
      document.bodyPlainText = removeMd(document.text);
    }
  }
},

...
}

In the 'content:file:beforeInsert' hook, we get the remove-markdown package. Then we check if the file to be inserted is a markdown file. If it is a markdown file, we generate the plain text by calling removeMd which takes document.text — the text of our content, as an argument, which we assign to a new document.bodyPlainText property. The property will now be available for use through Nuxt Content.

Great! Now that that’s done, we can generate the index and send it over to Algolia.

Confirm Algolia Index

Alright. We’ve set up nuxt-content-algolia and we’ve generated bodyPlainText for our articles. We can now generate this index and send the data over to Algolia by building our project using nuxt generate.

npm run generate

This will start building our project for production and run the nuxtContentAlgolia config. When we look at our terminal after the build we should see that our content has been indexed and sent to Algolia.

To verify, you can go to your Algolia dashboard:

Open Indices, then go to Search API logs, where you will see a log of operations performed with your Search API. You can now open and check the API call sent from your Nuxt project. This should have the content of your article as specified in the fields section of nuxtContentAlgolia config.

Nice! 🍻

Building The Search UI

So far we’ve been able to generate and send index data to Algolia, which means that we are able to query this data to get search results.

To do that within our app, we have to build our search UI.

Vue-InstantSearch provides lots of UI components using Algolia that can be integrated to provide a rich search experience for users. Let’s set it up.

Create And Configure vue-instantSearch Plugin

In order to use the Algolia InstantSearch widgets in our Nuxt app, we will have to create a plugin in our plugins folder.

Go to plugins/ and create a new file vue-instantsearch.js.

// plugins/vue-instantsearch.js

import Vue from 'vue'
import InstantSearch from 'vue-instantsearch'

Vue.use(InstantSearch)

Here, we’re simply importing InstantSearch and using it on the Vue frontend.

Now, we have to add the vue-instantSearch plugin to our plugins and build options in nuxt.config.js in order to transpile it to Vue.js.

So, go over to nuxt.config.js and add the following:

// nuxt.config.js

export default {
...

// Plugins to run before rendering page: https://go.nuxtjs.dev/config-plugins
plugins: ['@/plugins/vue-instantsearch.js'],

// Build Configuration: https://nuxtjs.org/docs/2.x/configuration-glossary/configuration-build#transpile
build: {
  transpile: ['vue-instantsearch', 'instantsearch.js/es']
}

...
}

InstantSearch code uses ES modules, yet it needs to be executed in Node.js. That’s why we need to let Nuxt know that those files should be transpiled during the build. Now that we’ve configured our vue-instantSearch plugin, let’s create a search component.

Create A Search Component

Create a new file components/Search.vue.

Since we’ve installed vue-instantSearch as a plugin, we can use it within our Vue components.

<!-- components/Search.vue -->

...

<script>
import algoliaSearch from 'algoliasearch/lite'
import 'instantsearch.css/themes/satellite-min.css'

// configurations for Algolia search
const searchClient = algoliaSearch(
  // Applictaion ID
  '34IIDW6KKR',
    
  // Search API key
  '3f8d80be6c42bb030d27a7f108eb75f8'
)
export default {
    data(){
        return{
            searchClient
        }
    }
}
</script>

First, in the <script> section, we’re importing algoliaSearch and instantsearch.css.

Next, we provide the credentials for our Algolia search which are:

• Application ID,
• Search API key.

As parameters to algoliaSearch then assign it to searchClient which we will use in our <template> to configure our Algolia search widgets.

ais-instant-search Widget

ais-instant-search is the root Vue InstantSearch component. All other widgets need to be wrapped with the root component to function. The required attributes for this component are:

• index-name
  Name of the index to query, in this case, it would be articles.
• search-client
algoliaSearch object containing Application ID and Search API Key.

<!-- components/Search.vue -->

<template>
  <div class="search-cont inline-flex gap-2 bg-white p-2 rounded-lg shadow-lg">
    <ais-instant-search index-name="articles" :search-client="searchClient">
    </ais-instant-search>
  </div>
</template>

...

ais-configure Widget

The ais-configure widget helps configure the search functionality by sending defined parameters to Algolia.

Any props you add to this widget will be forwarded to Algolia. For more information on the different parameters you can set, have a look at the search parameters API reference.

The parameters we’ll set for now will be:

• attributesToSnippet
  The name of the attribute or field to snippet in, we’ll soon see more on this.
• hits-per-page.camel
  Number of results in one page.
• snippetEllipsisText="…"
  Set ... before and after snipped text.

<!-- components/Search.vue -->

<template>
  <div class="search-cont inline-flex gap-2 bg-white p-2 rounded-lg shadow-lg">
    <ais-instant-search index-name="articles" :search-client="searchClient">
      <ais-configure
        :attributesToSnippet="['bodyPlainText']"
        :hits-per-page.camel="5"
        snippetEllipsisText="…"
      >
      </ais-configure>
    </ais-instant-search>
  </div>
</template>

...

ais-autocomplete Widget

This widget is basically a wrapper that allows us to create a search result that autocompletes the query. Within this widget, we can connect to other widgets to provide a richer UI and access multiple indices.

<!-- components/Search.vue -->

<template>
  <div class="search-cont inline-flex gap-2 bg-white p-2 rounded-lg shadow-lg">
    <ais-instant-search index-name="articles" :search-client="searchClient">
      <ais-configure
        :attributesToSnippet="['bodyPlainText']"
        :hits-per-page.camel="5"
        snippetEllipsisText="…"
      >
        <ais-autocomplete>
          <template v-slot="{ currentRefinement, indices, refine }">
            <input
              type="search"
              :value="currentRefinement"
              placeholder="Search for an article"
              @input="refine($event.currentTarget.value)"
            />
            <ais-stats />
            <template v-if="currentRefinement">
              <ul v-for="index in indices" :key="index.indexId">
                <li>
                  <h3>{{ index.indexName }}</h3>
                  <ul>
                    <li v-for="hit in index.hits" :key="hit.objectID">
                      <h1>
                        <ais-highlight attribute="title" :hit="hit" />
                      </h1>
                      <h2>
                        <ais-highlight attribute="description" :hit="hit" />
                      </h2>
                      <p>
                        <ais-snippet attribute="bodyPlainText" :hit="hit" />
                      </p>
                    </li>
                  </ul>
                </li>
              </ul>
            </template>
            <ais-pagination />
          </template>
        </ais-autocomplete>
      </ais-configure>
    </ais-instant-search>
  </div>
</template>

...

So, within our ais-autocomplete widget, we’re doing a few things:

• Overriding the DOM output of the widget using the default slot. We’re doing this using the scopes:
  • currentRefinement: string: the current value of the query.
  • indices: object[]: the list of indices.
  • refine: (string) => void: the function to change the query.

...
<template v-slot="{ currentRefinement, indices, refine }">
...

• Create a search <input> to hold, change the query and value of the currentRefinement.

...
<input
    type="search"
    :value="currentRefinement"
    placeholder="Search for an article"
    @input="refine($event.currentTarget.value)"
/>
...

• Render the search results for each index. Each index has the following properties:
  • indexName: string: the name of the index.
  • indexId: string: the id of the index.
  • hits: object[]: the resolved hits from the index matching the query.

...
<template v-if="currentRefinement">
    <ul v-for="index in indices" :key="index.indexId">
        <li>
            <h3>{{ index.indexName }}</h3>
            
...

• Then render the results — hits.

...
<ul>
    <li v-for="hit in index.hits" :key="hit.objectID">
      <h1>
        <ais-highlight attribute="title" :hit="hit" />
      </h1>
      <h2>
        <ais-highlight attribute="description" :hit="hit" />
      </h2>
      <p>
        <ais-snippet attribute="bodyPlainText" :hit="hit" />
      </p>
    </li>
</ul>

...

Here’s what we’re using:

• <ais-highlight>
  Widget to highlight the portion of the result which directly matches the query of the field passed to the attribute prop.
• <ais-snippet>
  Widget to display the relevant section of the snippeted attribute and highlight it. We defined the attribute in attributesToSnippet in <ais-configure>.

Let’s run our dev server and see what our New search looks like.

Styling Our Search Component

InstantSearch comes with some default styles that we included in our project using the instantsearch.css package. However, we might need to change or add some styles to our components to suit the site we’re building.

The CSS classes with many widgets can be overwritten using the class-names prop. For example, we can change the highlighted style of <ais-highlight>.

<!-- components/Search.vue -->

...
<h1>
  <ais-highlight
    :class-names="{
      'ais-Highlight-highlighted': 'customHighlighted',
    }"
    attribute="title"
    :hit="hit"
  />
</h1>

...

And in our CSS:

<!-- components/Search.vue -->

...

<style>
    .customHighlighted {
      @apply text-white bg-gray-600;
    }
</style>
...

We see that the class we defined has been applied to the highlight.

So, I’ll go ahead and style it using tailwind till I feel it looks good.

<!-- components/Search.vue -->

<template>
  <div class="search-cont relative inline-flex mt-6 bg-gray-100 border-2 rounded-lg focus-within:border-purple-600">
    <ais-instant-search-ssr index-name="articles" :search-client="searchClient">
      <ais-configure :attributesToSnippet="['bodyPlainText']" :hits-per-page.camel="5">
        <ais-autocomplete class="wrapper relative">
          <div slot-scope="{ currentRefinement, indices, refine }">
            <input class="p-2 bg-white bg-opacity-0 outline-none" type="search" :value="currentRefinement" placeholder="Search for an article" @input="refine($event.currentTarget.value)" />
            <div class="results-cont relative">
              <div
                class=" absolute max-h-96 overflow-y-auto w-96 top-2 left-0 bg-white border-2 rounded-md shadow-lg" v-if="currentRefinement">
                <ais-stats class="p-2" />
                <ul v-for="index in indices" :key="index.indexId">
                  <template v-if="index.hits.length > 0">
                    <li>
                      <h2 class="font-bold text-2xl p-2">
                        {{ index.indexName }}
                      </h2>
                      <ul>
                        <li
                          class="border-gray-300 border-t p-2 hover:bg-gray-100" v-for="hit in index.hits" :key="hit.objectID" >
                          <nuxt-link
                            :to="{
                              name: 'blog-slug',
                              params: { slug: hit.objectID },
                            }"
                          >
                            <h3 class="font-extrabold text-xl">
                              <ais-highlight
                                :class-names="{
                                  'ais-Highlight-highlighted':
                                    'customHighlighted',
                                }"
                                attribute="title"
                                :hit="hit"
                              />
                            </h3>
                            <p class="font-bold">
                              <ais-highlight
                                :class-names="{
                                  'ais-Highlight-highlighted':
                                    'customHighlighted',
                                }"
                                attribute="description"
                                :hit="hit"
                              />
                            </p>
                            <p class="text-gray-500">
                              <ais-snippet
                                :class-names="{
                                  'ais-Snippet-highlighted':
                                    'customHighlighted',
                                }"
                                attribute="bodyPlainText"
                                :hit="hit"
                              />
                            </p>
                          </nuxt-link>
                        </li>
                      </ul>
                    </li>
                  </template>
                </ul>
              </div>
            </div>
          </div>
        </ais-autocomplete>
      </ais-configure>
    </ais-instant-search-ssr>
  </div>
</template>

...

<style>
.customHighlighted {
  @apply text-purple-600 bg-purple-100 rounded p-1;
}
</style>

Alright, the styling is done and I’ve included a <nuxt-link> to route to the article on click.

<nuxt-link :to="{ name: 'blog-slug', params: { slug: hit.objectID }}">

We now have something like this:

Configuring InstantSearch For Server-Side Rendering (SSR)

We now have our search component up and running but it only renders on the client-side and this means we have to wait for the search component to load even after the page loads. We can further improve the performance of our site by rendering it on the server-side.

According to Algolia, the steps for implementing server-side rendering are:

On the server:

• Make a request to Algolia to get search results.
• Render the Vue app with the results of the request.
• Store the search results on the page.
• Return the HTML page as a string.

On the client:

• Read the search results from the page.
• Render (or hydrate) the Vue app with search results.

Using Mixins, serverPreFetch, beforeMount

Following Algolia’s documentation on implementing SSR with Nuxt, we have to make the following changes:

<!-- components/Search.vue -->

...
<script>
// import 'vue-instantsearch';
import { createServerRootMixin } from 'vue-instantsearch'

import algoliaSearch from 'algoliasearch/lite'
import 'instantsearch.css/themes/satellite-min.css'

const searchClient = algoliaSearch(
  '34IIDW6KKR',
  '3f8d80be6c42bb030d27a7f108eb75f8'
)

export default {
  data() {
    return {
      searchClient,
    }
  },

  mixins: [
    createServerRootMixin({
      searchClient,
      indexName: 'articles',
    }),
  ],

  serverPrefetch() {
    return this.instantsearch.findResultsState(this).then((algoliaState) => {
      this.$ssrContext.nuxt.algoliaState = algoliaState
    })
  },

  beforeMount() {
    const results =
      (this.$nuxt.context && this.$nuxt.context.nuxtState.algoliaState) ||
      window.__NUXT__.algoliaState

    this.instantsearch.hydrate(results)

    // Remove the SSR state so it can’t be applied again by mistake
    delete this.$nuxt.context.nuxtState.algoliaState
    delete window.__NUXT__.algoliaState
  },
}
</script>

We’re simply doing the following:

• createServerRootMixin to create a reusable search instance;
• findResultsState in serverPrefetch to perform a search query on the back end;
• hydrate method in beforeMount.

Then in our <template>,

<!-- components/Search.vue -->

...
<ais-instant-search-ssr index-name="articles" :search-client="searchClient">
    ...
</ais-instant-search-ssr>
...

Here, we to replace ais-instant-search with ais-instant-search-ssr.

Conclusion

We’ve successfully built a Nuxt site with some content handled by Nuxt Content and integrated a simple Algolia search into our site. We’ve also managed to optimize it for SSR. I have a link to the source code of the project in this tutorial and a demo site deployed on Netlify, the links are down below.

We have tons of options available to customize and provide a rich search experience now that the basics are out of the way. The Algolia widgets showcase is a great way to explore those options and widgets. You’ll also find more information on the widgets used in this tutorial.

GitHub Source Code

• You can check out the source code here.
• You can play with the demo on https://algolia-nuxtx.netlify.app/.

Other Resources

Here are some links that I think you will find useful:

• Create a Blog with Nuxt Content by Debbie O’Brien
• @nuxt/content Module
• Tailwindcss docs
• Vue InstantSearch

Further Reading

• An Introduction To CSS Scroll-Driven Animations: Scroll And View Progress Timelines
• Uniting Web And Native Apps With 4 Unknown JavaScript APIs
• How To Deal With Big Tooling Upgrades In Large Organizations
• How To Build An Accessible Front-End Application With Chakra UI And Nuxt.js

(ks, vf, yk, il, mrn)

JavaScript frameworks like React, Angular and Vue have a very bad reputation when it comes to web accessibility. But is this due to inherent technical limitations or insurmountable problems of those tools? I think not. During the research phase of my book, “Accessible Vue,” I gained three insights regarding web app accessibility in general and the framework in particular. Considering these, perhaps it’s worth taking another perspective around accessible Vue apps.

Insight 1: JavaScript Framework Features For Accessibility Are Underused

Component-based design, enabled and enforced by modern JavaScript frameworks, does not only provide great developer experiences and project ergonomics when used in a smart way, but it can also offer advantages for accessibility. The first is the factor of reusability, i.e. when your component gets used in several places within your app (perhaps in different forms or shapes) and it only has to be made accessible only once. In this case, an increased developer experience actually helps the user and “baking accessibility into components” (as Hidde de Vries puts it) creates a win-win scenario for everyone.

The second aspect that comes with component based-designs are props — namely in the form that one component can inherit or get context from its parent environment. This forwarding of “environment data” can serve accessibility as well.

Take headlines, for example. A solid and comprehensible headline structure is not only good for SEO but especially for people using screen readers. When they encounter a sound document outline, constructed with headlines that structure a web page or app, screen reader users gain a quick overview of the web page they are on. Just like visually-abled users don’t read every word on a page but scan for interesting things, blind screen reader users don’t make their software read each and every word. Instead, they are checking a document for content and functionality they are interested in. Headlines, for that matter, are keeping pieces of content together and are at the same time providing a structural frame of a document (think timber frame houses).

What makes headlines providing a structure is not only their mere existence. It is also their nesting that creates an image inside a user’s mind. For that, a web developer’s headline toolbox contains six levels (<h1> to <h6>). By applying these levels, both editors and developers can create an outline of content and a reliable functionality that users can expect in the document.

For example, let’s take the (abridged) headline tree from the GOV.UK website:

1 — Welcome to GOV.UK
  2 — Popular on GOV.UK
  2 — Services and information
    3 — Benefits
    3 — Births, deaths, marriages and care
    3 — Business and self-employment
    // …etc
  2 — Departments and policy
    3 — Coronavirus (COVID 19)
    3 — Travel abroad: step by step
…etc

Even without visiting the actual page and without actually perceiving it visually, this headline tree created a table of contents helping you understand what sections can be expected on the front page. The creators used headline elements to herald data following it and didn’t skip headline levels.

So far, so familiar (at least in correlation with search engines, I guess). However, because a component can be used in different places of your app, hardwired headline levels inside them can sometimes create a suboptimal headline tree overall. Relations between headlines possibly aren’t conveyed as clear as in the example above (“Business and self-employment” does not stand on its own but is related to “Services and information”).

For example, imagine a listing of a shop’s newest products that can be placed both in the main content and a sidebar — it’s quite possible that both sections live in different contexts. A headline such as <h1>Our latest arrivals</h1> would make sense above the product list in the main content — given it is the central content of the whole document or view.

The same component sporting the same <h1> but placed in a sidebar of another document, however, would suggest the most important content lives in the sidebar and competes with the <h1> in the main content. While what I described above is a peculiarity of component-based design in general this gives us a perfect opportunity to put both aspects together — the need for a sound headline tree and our knowledge about props:

Context Via props

Let’s progress from theoretical considerations into hands-on code. In the following code block, you see a component listing the newest problems in an online shop. It is extremely simplyified but the emphasis is on line 3, the hardcoded <h1>:

<template>
    <div>
        <h1>Our latest arrivals</h1>
        <ol>
            <li>Product A</li>
            <li>Product B</li>
            <!-- etc -->
        </ol>
  </div>
</template>

To use this component in different places of the app without compromising the document’s headline tree, we want to make the headline level dynamic. To achieve this, we replace the <h1> with Vue’s dynamic component name helper called, well, component:

<component :is="headlineElement">Our latest arrivals</component>

In the script part of our component, we now have to add two things:

• A component prop that receives the exact headline level as a string, headlineLevel;
• A computed property (headlineElement from the code example above) that builds a proper HTML element out of the string h and the value of headlineLevel.

So our simplified script block looks like this:

<script>
export default {
    props: {
      headlineLevel: {
        type: String
    },
    computed: {
        headlineElement() {
          return "h" + this.headlineLevel;
        }
    }
}
</script>

And that’s all!

Of course, adding checks and sensible defaults on the prop level is necessary — for example, we have to make sure that headlineLevel can only be a number between 1 and 6. Both Vue’s native Prop Validation, as well as TypeScript, are tools at your disposal to do just that, but I wanted to keep it out of this example.

If you happen to be interested in learning how to accomplish the exact same concept using React, friend of the show magazine Heydon Pickering wrote about the topic back in 2018 and supplied React/JSX sample code. Tenon UI’s Heading Components, also written for React, take this concept even further and aim to automate headline level creation by using so-called “LevelBoundaries” and a generic <Heading> element. Check it out!

Insight 2: There Are Established Strategies To Tackle Web App Accessibility Problems

While web app accessibility may look daunting the first time you encounter the topic, there’s no need to despair: vested accessibility patterns to tackle typical web app characteristics do exist. In the following Insight, I will introduce you to strategies for supplying accessible notifications, including an easy implementation in Vue.js (Strategy 1), then point you towards recommended patterns and their Vue counterparts (Strategy 2). Lastly, I recommend taking a look at both Vue’s emerging (Strategy 3) and React’s established accessibility community (Strategy 4).

Strategy 1: Announcing Dynamic Updates With Live Regions

While accessibility is more than making things screen reader compatible, improving the screen reader experience plays a big part of web app accessibility. This is rooted in the general working principle of this form of assistive technology: screen reader software transforms content on the screen into either audio or braille output, thus enabling blind people to interact with the web and technology in general.

Like keyboard focus, a screen reader’s output point, the so-called virtual cursor, can only be at one place at once. At the same time, one core aspect of web apps is a dynamic change in parts of the document without page reload. But what happens, for example, when the update in the DOM is actually above the virtual cursor’s position in the document? Users likely would not notice the change because do not tend to traverse the document in reverse — unless they are somehow informed of the dynamic update.

In the following short video, I demonstrate what happens (or rather, what not happens) if an interaction causes a dynamic DOM change nowhere near the virtual cursor — the screen reader just stays silent:

But by using ARIA Live Regions, web developers can trigger accessible announcements, namely screen reader output independent of the virtual cursor’s position. The way live regions work is that a screen reader is instructed to observe certain HTML elements’ textContent. When it changes due to scripting, the screen reader picks up the update, and the new text will be read out.

As an example, imagine a list of products in an online shop. Products are listed in a table and users can add every product to their shopping cart without a page reload by the click of a button. The expected asynchronous update of the DOM, while perceivable for visual users, is a perfect job for live regions.

Let’s write a piece of simplified dream code for this situation. Here’s the HTML:

<button id="addToCartOne">Add to cart</button>

<div id="info" aria-live="polite">
<!-- I’m the live region. For the sake of this example, I'll start empty. 
     But screen readers detect any text changes within me! -->
</div>

Now, both DOM updates and live regions announcements are only possible with JavaScript. So let’s look at the equally simplified script part of our “Add to Cart” button click handler:

<script>
const buttonAddProductOneToCart = document.getElementById('addToCartOne');
const liveRegion = document.getElementById('info');

buttonAddProductOneToCart.addEventListener('click', () => {
        // The actual adding logic magic 🪄

        // Triggering the live region:
        liveRegion.textContent = "Product One has been added to your cart";
});
</script>

You can see in the code above that when the actual adding happens (the actual implementation depends on your data source and tech stack, of course), an accessible announcement gets triggered. The once empty <div> with the ID of info changes its text content to “Product One has been added to your cart”. Because screen readers observe the region for changes like this, a screen reader output regardless of the virtual cursor position is prompted. And because the live region is set to polite, the announcement waits in case there is a current output.

If you really want to convey an important announcement that doesn’t respect the current screen reader message but interrupts it, the aria-live attribute can also be set to assertive. Live regions in themselves are powerful tools that should be used with caution, which is even more valid for this more “aggressive” kind. So please limit their use to urgent error messages the user must know about, for example, “Autosave failed, please save manually”.

Let’s visit our example from above again, this time with implemented live regions: Screen reader users are now informed that their button interaction has worked and that the particular item has been added to (or removed from) their shopping cart:

If you want to use live regions in Vue.js applications, you can, of course, recreate the code examples above. However, an easier way would be to use the library vue-announcer. After installing it with npm install -S @vue-a11y/announcer (or npm install -S @vue-a11y/announcer@next for the Vue 3 version) and registering it a Vue plugin, there are only two steps necessary:

1. The placement of <VueAnnouncer /> in your App.vue’s template. This renders an empty live region (like the one from above that had the ID of info).
   Note: It is recommended only to use one live region instance, and it makes sense to place it in a central place, so that many components can refer to it.
   

<template>
  <div>
    <VueAnnouncer />
    <!-- ... -->
  </div>
</template>

1. The triggering of the live region, for example from within a method or lifecycle hook. The easiest way to accomplish this is using the .set method or this.$announcer. The method’s first parameter is the text the live regions is updated with (equivalent to the text that the screen reader will output). As a second parameter, you can explicitly supply polite and assertive as a setting). But, as you’ll notice it is optional — in case the parameter gets omitted the announcement will be a polite one:
   

methods: {
  addProductToCart(product) {
    // Actual adding logic here

    this.$announcer.set(`${product.title} has been added to your cart.`);
  }
}

This was just a small peek into the amazing world of ARIA live regions. As a matter of fact, more options than polite and assertive are available (such as log, timer and even marquee) but with varying support in screen readers.

If you want to dive deeper into the topic, here are three recommended resources:

• “ARIA Live Regions,” MDN Web Docs
• “The Many Lives Of A Notification,” Sarah Higley (video)
• NerdeRegion, a Chrome extension that lets you roughly emulate live region output in your dev tools without the need to fire up a screen reader. However, this should not replace conscientious testing in real screen readers!

Strategy 2: Using Undisputed WAI-ARIA Authoring Practices

The moment you encounter WAI-ARIA’s authoring practices, you’ll likely feel a great relief. It seems that the web’s standard body, the W3 Consortium, offers some kind of pattern library that you just have to use (or convert to your framework of choice), and boom, all your web app accessibility challenges are solved.

The reality, however, is not so simple. While it is true that the W3C offers a plethora of typical web app patterns like combo boxes, sliders, menus and treeviews, not all authoring practices are in a state that they are recommended for production. The actual idea behind authoring practices was to demonstrate the “pure” use of ARIA states, roles and widget patterns.

But in order to be a truly vetted pattern, its authors have to make sure that every practice has solid support among assistive technologies and also works seamlessly for touch devices. Alas, that’s the place where some patterns listed in the Authoring Practices fall short. Web development is in a state of constant flux, and likely web app evolution even more so. A good place to stay updated with the state of single authoring practices is W3C’s authoring-practices repo on GitHub. In the Issues section, web accessibility experts exchange their current ideas, experiences, and testing research for every pattern.

All that being said does not mean that the practices have no value at all for your web app accessibility ventures, though. While there are widgets that are mere proofs of concept there are solid patterns. In the following, I want to highlight three undisputed Authoring Practices and their counterparts in built-in Vue.js:

• Disclosure Widgets are simple and straightforward concepts that can be used in a variety of ways: as a basis for your accessible accordion, as part of a robust dropdown navigation menu, or to show and hide additional information, like extended image descriptions.
  
  The great thing about the pattern is that it only consists of two elements: A trigger (1) that toggles the visibility of a container (2). In HTML terms, trigger and container must directly follow each other in the DOM. To learn more about the concept and the implementation in Vue, read my blog article about Disclosure Widgets in Vue, or check out the corresponding demo on CodeSandBox.

• Modal dialogs are also considered an established pattern. What makes a dialog “modal” is its property to render the parts of the interface that are not the modal’s content inactive when it’s open.
  
  Furthermore, developers must ensure that the keyboard focus is sent into the modal upon activation, can’t leave an open modal and is being sent back to the triggering control after deactivation. Kitty Giraudel’s A11y Dialog component takes care of all the things I just described. For developers using Vue.js, there is a plugin called vue-a11y-dialog available.

• Tab Components are a common dynamic pattern that works with the metaphor of physical folder tabs and thus, helps authors to pack larger amounts of content into “tab panels”. The authoring practice comes in two variants related to panel activation (automatic or manual).
  
  What is even more important, tab components enjoy good support in assistive technology and can be therefore considered a recommended pattern (as long as you test which activation mode works best for your users). Architecturally speaking, there are multiple ways to build the tab component with the help of Vue.js: In this CodeSandBox, I decided to go for a slot-based approach and automatic activation.

Strategy 3: View And Help Vue’s Accessibility Initiatives Grow

While there is still a way to go, it is true to state that the topic of accessibility in Vue.js is finally on the rise. A milestone for the topic was the addition of an “Accessibility” section in Vue’s official docs, which happened related to the release of Vue 3.

But even apart from official resources, the following people from the Vue community are worth following because they provide either education material, accessible components, or both:

• Maria Lombardo has the status of “Vue community partner”, penned the accessibility documentation linked above, is giving a11y-related workshops at Vue conferences, and has a (paid) Web Accessibility Fundamentals course at vueschool.io.
• An article about accessibility in Vue.js would not be complete without a mention of Alan Ktquez, project lead of vue-a11y.com. He and his community initiative create and maintain plugins like the aforementioned vue-announcer, vue-skipto for creating skip links, vue-axe as a Vue wrapper around Deque’s axe-core testing engine, and especially awesome-vue-a11y, an ever-growing link list of accessibility resources in the Vueniverse.
• Fellow Berliner Oscar Braunert has a special focus on inclusive inputs and shows how to implement them in Vue.js, for example in the form of talks and articles. With the tournant UI library, Oscar and I are aiming to supply accessible components both based on (undisputed) WAI Authoring Practices (see Strategy 2) and Heydon Pickering’s Inclusive Components.
• Moritz Kröger built a Vue wrapper for Kitty Giraudel’s a11y-dialog dubbed vue-a11y-dialog, which provides everything a developer needs in term of semantics and focus management (see above).

Strategy 4: Learn From React Accessibility Leads

If you compare it with the top dog React.js, Vue.js is not a niche product, but you must admit that it has (not yet?) reached its popularity. However, this does not have to be a disadvantage when it comes to accessibility. React — and Angular before it — are in a sense pioneering in accessibility by their proliferation alone.

The more popular frameworks become, the higher the likelihood of good work in terms of inclusivity. Be it due to community initiatives on the subject or simply government authorities with web accessibility obligations doing a “buy-in”. If they also share their findings and accessible code via open-source, it’s a win-win-win situation. Not only for the framework itself and its community but also for “competitors”.

This actually has happened in the case of React (and the government project that I talked about so abstractly is the Australian Government Design System). Teams and developers caring for accessibility and working with React can check out projects like these and use the provided components and best practices.

Teams and developers caring for accessibility but using Vue.js, Angular, Svelte etc. can look into the React code and learn from it. Although there may be natural differences in the syntax of each framework, they have many basic concepts in common. Other React libraries that are considered accessible and are available as a basis for learning:

• Cauldron from Deque
• Tenon UI from Tenon
• BaseWeb Components from Uber

For improving Vue.js accessibility, it’s also worth following accessibility people from the React world:

• Marcy Sutton is a freelance web accessibility expert who worked in the past for Deque and improved accessibility and related documentation at Gatsby.js, which is a static site generator based on React. She is very hands-on, conducts research and conveys important topics regarding web app accessibility in great presentations, blog posts, and workshops. You can find Marcy Sutton on Twitter at @marcysutton, web app-related courses on Egghead.io and TestingAccessibility.com or an overview of all of her projects by visiting her website.
• Lindsey Kopacz is a web developer specializing in inaccessibility. She cares for inclusive experiences on the web, about overcoming ableism and educating her fellow web developers about the importance of accessibility. Apart from writing on her blog a11ywithlindsey.com, she also has courses on Egghead.io and lately published her ebook “The Bootcampers Guide to Web Accessibility”. On Twitter, she is @littlekope.
• Ryan Florence and Michael Jackson created Reach UI, a collection of components and tools that aims “to become the accessible foundation of your React-based design system.” Besides the fact that they have created some accessible standard components, it is especially noteworthy that their “Reach UI Router” (along with its accessibility features) will merge with the “official” React Router in the future.
  
  Although React does not do “first-class plugins” like Vue.js, this is excellent news because they created their router with inbuilt focus management. A feature and accessibility enhancement that will soon benefit everyone using React Router and their users.

Insight 3: Vue’s $refs Are Great For Focus Management

Focus Management?

You encountered a way of sending accessible announcements by the use of ARIA Live Regions in the last Insight. Another way to deal with the problems a highly dynamic document presents to screen-reader and keyboard users is to manage focus programmatically. Before I start explaining focus management any further, please be aware: Usually, it is bad to change focus via scripting, and you should refrain from doing so.

Users don’t want their focus to be messed with. If a focus change does happen and is entirely unexpected, such an intervention is either a nuisance or even becomes a real barrier. On the other hand, changing focus programmatically is sometimes the only sensible option in JavaScript-based widgets or apps to help users who rely on keyboard usage. However, in this case, the focus change has to be predictable. A good way of ensuring this predictability is to ensure that a focus change only happens after an interaction, such as a button or link click.

What are circumstances in which focus management is can improve an app’s accessibility?

1. Focus management is needed when the content that is being affected by an interaction (e.g. <div>) does not follow the trigger (e.g. <button>) directly in the document. For example, the disclosure widget concept assumes the container the button toggles is directly below the button in the DOM tree.
   
   This document structure, this proximity of trigger and reacting container, cannot be ensured in every widget, so the focus has to be managed actively. When a modal dialog opens after a button activation, it can’t be ensured that its HTML nodes directly follow the triggering button in the DOM. Thus, the focus has actively sent into the modal, ensuring that keyboard-only and screen reader users can use the particular widget.
2. When parts of the document have changed without a page reload or parts of the DOM have been updated (again, after an interaction such as a button click), it is appropriate to send focus to the added or changed content.
   
   An example of this is the navigation between routes (“pages”) in Single Page Apps: Since they don’t reload the HTML document (like static websites do), a keyboard-only or screen reader user is not sent to the top of the “new page”. Because what is happening is not a “proper” page load — but a modification of a certain part of the same page.

You can see examples of bad and good focus management in the following demos, provided by Manuel Matuzović. Although the underlying framework (React) and the underlying UI pattern (modal dialog) differs, the problem remains the same:

An example for lack of focus management:

An example for good focus management:

That leaves responsible developers with the task of sending the keyboard focus to particular elements for your template. Luckily, JavaScript frameworks have the concept of DOM node references, or “refs”. In Vue.js, it is sufficient to add the ref attribute in an HTML node. Subsequently, a reference to this node is available in the $this.refs object. Finally, focusing an element programmatically is as easy as calling JavaScript’s native .focus() method on it.

For the next example, let’s assume we have a button somewhere in our component and apply a ref named triggerButton to it. We want to set focus to it once the user hits the ESC key. Our code for this would look as follows:

<template>
    <div @keydown.esc="focusTriggerBtn">
        <button ref="triggerButton">Trigger</button>
    </div>
</template>
<script>
export default {
//...
methods: {
    focusTriggerBtn() {
        this.$refs.triggerButton.focus();
    }
}
//...
}
</script>

Modal Off-Canvas Navigation

Another use of both refs and focus management would be the accessible implementation of an off-canvas navigation.

In this case, you need to establish at least two refs: One for the trigger button that opens the navigation (let’s call it navTrigger), and one for the element that gains focus as soon as the navigation is visible (navContainer in this example, an element which needs tabindex="-1" to be programmatically focusable). So that, when the trigger button is clicked, the focus will be sent into the navigation itself. And vice versa: As soon as the navigation closes, the focus must return to the trigger.

After having read the paragraphs above, I hope one thing becomes clear for you, dear reader: Once you understand the importance of focus management, you realize that all the necessary tools are at your fingertips — namely Vue’s this.$refs and JavaScript’s native .focus()

Conclusion

By highlighting some of my core findings regarding web app accessibility, I hope that I have been able to help reduce any diffuse fear of this topic that may have existed, and you now feel more confident to build accessible apps with the help of Vue.js (if you want to dive deeper into the topic, check out if my little ebook “Accessible Vue” can help you along the journey).

More and more websites are becoming more and more app-like, and it would be sad if these amazing digital products were to remain so barrier-laden only because web developers don’t know exactly where to start with the topic. It’s a genuinely enabling moment once you realize that a vast majority of web app accessibility is actually “good old” web accessibility, and for the rest of it, cowpaths are already paved.

(vf, il)

Throughout this tutorial, we will be looking at practices that should be adopted, things that should be avoided, and have a closer look at some helpful tools to make writing Vue.js easier. I’ll be focusing mostly on Vue 2 as most folks and organizations still use the older version. No reason to worry though, as most things mentioned here still apply to Vue 3 since it’s just a supercharged and faster version. Still, if you already know Vue 2 and just want to learn about what’s new in Vue 3, then you can check out the migration guide to learn more.

Note: This article is aimed at both beginners and seasoned developers who want to better their Vue.js skills. Basic knowledge of JavaScript and Vue.js will be of great benefit as you work your way throughout this tutorial.

Module-Based Vs File-Based Project Structuring

Let’s start by looking at how to structure files by modules, how file-based structuring might not be a good idea when it comes to building projects of scale, and how to structure modules to fit in with business requirements.

As we are newly creating a project with Vue.js CLI, we are getting the default file structure that has been mapped out by the Vue.js team. Using the proposed file structure is not a bad way of structuring your project per se, but as your project grows, you will need a better structure as your code becomes clustered and harder to navigate and access files.

This is where the module-based method of structuring your project comes into play.

A bad way of structuring your project will involve storing different data that is not related to the same folder, such as the notification component and the authentication component in the root component folder:

+-- src/
|   +-- assets/
|       +-- logo.png
|       +-- userprofile.png
|   +-- components
|       +-- NotificationBar.vue
|       +-- LoginForm.vue
|       +-- DashboardInfo.vue
|       +-- AuthenticationModal.vue
|   +-- main.js

So what we want to do is decouple the project based on business logic and concerns so that we have something like authentication module, product module, service module, and so on. This way we can make sure that anything concerning that particular feature is put in the module, making our code neater and navigating not so hard.

+-- modules/
|   +-- AuthModule/
|       +-- assets/
|           +-- userprofile.png
|       +-- Components/
|           +-- Authentication.vue
|           +-- login.vue
|   +-- NotificationModule
|       +-- assets/
|            +-- Alert.png
|       +-- Components/
|            +-- NotificationBar.vue
|   +-- ProductModule/

Organizing Modules

There are two ways you can organize your modules:

1. Vue.js core modules,
2. App feature modules.

The Vue.js core modules are here to facilitate your Vue.js development. Modules like the service module containing all the network requests needed by the company are kept in this core module and all corresponding network requests are made from here.

Modularizing your app according to features is a great way of making a better file structure in your app. This will allow separation of your concern and make sure that you are only working on the feature that you or your team is assigned to. Another advantage of modularizing according to feature is its maintainability and ability to avoid technical debt in the long term where there might need to be a rework on the app.

Now whenever there is a need to add, remove or change the state of a particular feature, all we need to do is to navigate to that feature and make changes without breaking the app. This method of modularization allows for efficient program development and easy debugging and modification in our application.

For example, a payout feature assigned to you and your team is a good time to implement a payout module that encapsulates all functionalities and data for the feature.

+-- modules/
|   +-- payout/
|       +-- index.js
|       +-- assets/
|       +-- Components/
|            +-- PayOut.vue
|            +-- UserInfo.vue
|       +-- store/
|            +-- index.js 
|            +-- actions.js
|            +-- mutations.js          
|       +-- Test/

Based on our payout feature above, we have an index.js file to import and use plugins associated only with the payout module. The asset folder houses all the assets (images and styles) for the module. Our component folder contains components related to the payout feature. The store folder contains our actions, mutations, and getters used to manage the state of this feature. There is also a test folder to carry out testing for this feature.

Using Custom Directives

Directives in Vue.js are a way for us to tell Vue.js to do something or exhibit a certain behavior for us. Examples of directives are v-if, v-model, v-for, etc. In our Vue.js app, when we use something like v-model to tie data to an input in a form, we are giving the Vue.js code some certain instructions that are peculiar to Vue.js. But what if we want a particular action or behavior that our Vue.js provided directive doesn’t allow us to do, what do we do then? We can create what we call custom directives.

Registering Custom Directives And Directives Hooks

We can go about registering directives in two ways:

1. Globally
   In our main.js file.
2. Locally
   In our component.

Hooks in directives are like methods that fire when a certain action happens in our directives. Like the created and mounted hook life cycle hooks, we are provided with hooks to use in our directives.

Let’s say we are building an application and in one of our pages, we want the background color to always change each time we navigate to it. We are going to name this directive colorChange. We can achieve that with the help of a directive.

Our template looks something like this:

<template>
  <div id="app" v-color-change>
    <HelloWorld msg="Hello Vue in CodeSandbox!"/>
  </div>
</template>

We can see the custom directive above, but to make it work, in our main.js file we add:

// custom directive
Vue.directive("color-change", {
  bind: function (el) {
    const random = Math.floor(Math.random() * 900000) + 100000;
    el.style.backgroundColor = `#${random}`
  }
})

The above Vue.js directive takes in the directive name as the first argument then an Object as the second argument that controls the behavior of the directives. bind is one of the hooks we talked about and will be called once the directive is bound to the element. It accepts the following arguments:

• el
  This is the element node we have attached the directive to.
• binding
  It contains helpful properties that change the behavior of the directive.
• vnode
  This is the virtual node of Vue.js.

We have created a random set of 6-digit numbers so that we can use it in changing the hex code of our background color style.

Best Practices When Writing Custom Directives

We have created a custom directive for the above, but we need to take note of a few things. Apart from el, never modify hook arguments and make sure the arguments are read-only because the hook arguments are objects with native methods that can cause side effects if modified. If necessary, use the Vue.js dataset to share information among hooks.

If we are using the CLI build of Vue.js, custom directives should be in the main.js file so that all the .vue files can have access to it. Your directive name should be something that resonates with what that particular directive does, very descriptive about the directive functionality.

You can see and play more with the code in this codesandbox I have created. You can also read more about this in the Vue docs.

Controlling Updates

Vue.js reactivity system is powerful in a way that it detects things that need updating and updates them without you as the developer doing anything. For example, re-rendering a page each time we navigate to it. At times the case can be different as we might find ourselves writing code that requires us to force an update.

Note: If you find yourself needing to force an update, which is a rare occasion, then you may need to really understand Vue’s Reactivity and how to properly use props in communicating dynamic data.

Forcing An Update To Occur

In most cases, when the value in the vue data object changes, the view automatically re-renders, but it’s not always like this. a classic case of our view, not re-rendering is when we are using a v-for in our template to loop over some data in the data object, and we do not add a :key value in the v-for loop.

<div v-for="item in itemsArray" :key="item">

This gives Vue.js a way to track each node’s identity and re-render the view for any change.

A rare situation that can cause us to force an update is if we intentionally or accidentally set an array item with the index.

var app = new Vue({
  data: {
    items: ['1', '2']
  }
})
app.items[1] = '7' //vue does not notice any change

There are different ways to force an update or re-render. Some are very bad practices like the use of v-if to re-render the page when it’s true, and when false, the component disappears and no longer exists. This is bad practice because the template is never destroyed but just hidden till it can be re-used.

<template>
    <div v-if="show">
       <button @click="rerender">re-render</button>
    </div>
</template>

<script>
  export default {
    data() {
      return {
        show: true,
      };
    },
    methods: {
      rerender() {
        this.show= false;
        this.$nextTick(() => {
            this.show = true;
        });
      }
    }
  };
</script>

In the code above, the state of show is initially set to true, meaning our component is initially rendered. Then, when we click on the button, the rerender() function is called and the state of show is set to false, and the component is no longer rendered. On the next tick, which is a single DOM update cycle, show is set to true and our component is rendered again. This is a very hacky way of re-rendering.

I would like to talk about two legit ways this can be done:

1. Vue’s $forceUpdate.
2. Key changing pattern.

Vue’s $forceUpdate: In the use of $forceUpdate, the child components do not render, only the Vue.js instance, the instance, and child components with slots.

Globally we can force the update:

import Vue from 'vue';
Vue.forceUpdate();

And locally too:

export default {
  methods: {
    methodThatForcesUpdate() {
      this.$forceUpdate();
    }
  }
}

Using the key changing pattern which is much better than the $forceUpdate method is another way to go about this. The reason behind the key changing pattern being better is that it allows Vue.js to know which component is tied to a specific data and when the key changes, it destroys the old component to create a new one, according to matthiasg on this Github issue I ran into. You can use a :key attribute to let Vue.js know which component is attached to a specific piece of data. When the key changes, it causes Vue.js to destroy the old component and a new one is created.

<template>
  <Child
    :key="key"
  />
</template>

<script>
  export default {
    data() {
      return {
        key: 0,
      };
    },
    methods: {
      forceRerender() {
        this.key += 1;
      }
    }
  }
</script>

Third Party Libraries And Optimization

It is almost inevitable that we do not use third-party libraries in our apps. Third-party libraries can begin to be a problem if we turn a blind eye to it, increasing bundle size and slowing down our application.

I recently used the Vuetify component library in a project and checked to see that the overall bundle size was a whooping 500kb minified. Things like this can become a bottleneck in our application. You can check the bundle size of your app by using webpack-bundle-analyzer. You can install it by running:

npm install --save-dev webpack-bundle-analyzer

and include it in your webpack config file:

const BundleAnalyzerPlugin = require('webpack-bundle-analyzer').BundleAnalyzerPlugin;

module.exports = {
  plugins: [
    new BundleAnalyzerPlugin()
  ]
}

Good Practices To Optimize Your Vue App

• Our main bundle should only contain dependencies that are critical to our app, like vue, vuex. We should avoid putting libraries that are used in specific routes in our app in the main bundle.
• When using component libraries, you can import individual components from the libraries, instead of importing everything. For example, vuetify:

<template>
  <v-app>
    <v-navigation-drawer app>
    <!-- -->
  </v-navigation-drawer>
  <v-app-bar app>
    <!-- -->
  </v-app-bar>
 </v-app>
</template>
<script>
import { VApp, VNavigationDrawer, VAppBar } from 'vuetify/lib'

export default {
  components: {
    VApp,
    VNavigationDrawer,
    VAppBar,
  }
}
</script>

By doing the above we have reduced the bundle size and redundant code, only using the components we want to use in that particular route.

Making Early Decisions To Use Vuex

Often I have found myself wondering if I should start up a project with Vuex. Sometimes I just want to start a small side project and I start it up without Vuex to manage my state and communication using props begins to get messy.

So when should we use Vuex? To answer this, we need to consider:

• Size of the project,
• The simplicity of the code,
• Routing,
• Dataset involved,
• Components nesting.

If your app begins to grow, it’s only appropriate to include Vuex to manage the state in your application. If you’re ever in doubt if you should use a state manager when starting your project, then just use it. However, there is a talk of the new Vue3 composition API being a replacement for vuex.

How Vuex Should Be Set Up For Large Applications

We have four components in the vuex store:

• State: Store data in our store.
• Getters: Retrieve state data.
• Mutations: Used to mutate state data.
• Action: Used to commit mutations.

When we use the above in Vuex we should keep in mind that actions should always commit mutations no matter what. This allows our devtools to be able to track changes and revert to a particular period in our state and asynchronous operations or business logic should be carried out in the actions.

You can create a separate file for each of the Vuex components to look like this:

├── services
├── main.js
└── store
    ├── index.js          
    ├── actions.js
    ├── mutations.js
    └── Getters.js
├── components

Moduling According To Feature

If our project is a very large project with a team, we can modularize our store according to app features. This is done especially when there are complex and large projects with many files and folders and we just want an organized way of handling the structuring of our app. We have to be careful the way we go about this, if not we can do more harm than good. A simple store modularized according to the feature looks like this:

store/
   ├── index.js 
   └── modules/
       ├── cart
           ├── index.js          
           ├── actions.js
           ├── mutations.js       
       ├── product.js
       ├── login.js

Good Practice When Using Vuex Modules

As the modules we have created become more complicated, it becomes harder to manually import and organize. It is advised that your modules have an index.js file at the root of your module, bringing the files altogether.

Make sure you have a standard naming pattern in your store as this will increase maintainability. You can use camelCase for naming the modules then a .store.js extension. Example: CartData.store.js.

modules/
       ├── cart.js
           ├── index.js   -> auto export module       
           ├── userProduct.store.js
           ├── userData.store.js

Code related to business logic or async code should not run inside mutations because of its blocking behavior, instead, actions should be used. It is considered best practice not to directly access a state object. Instead, use the getter function because it can be mapped into any vue component using the mapGetters behaving like a computed property with the getters result cached based on its dependencies. Also, make sure each module is namespaced and not to access them using the global state scope.

Using The Provide/Inject Method To Pass Data Around

Think of an app that has different components. We have the parent component and the parent component has many child components. From the image below, we see our Child component A, B, and D as top components, then we see Component E nested in component D and component F nested in component E. What if we have app data (like User Address), that we want to use in child Component A, C, and F, and this User address data is in our parent component.

To do this, we need to:

• Provide value in the parent component (Dependency provider).
• Inject the value in component F (dependency consumer).

In our parent component we provide the data:

app.component('parent-component', {
  data() {
    return {
      user: {name:"Uma Victor", address:"No 33 Rumukwurushi"}
    }
  },
  provide() {
    return {
     userAddress: this.user.address
    }
  },
  template: `
    ...
  `
})

We use provide as a function by returning an object to access component instance properties.

In our child-f component, we have the following:

app.component('child-f', {
  inject: ['userAddress'],
  template: `
    <h2>Injected property: {{ this.userAddress }}</h2>
  `
})

However, we noticed that if we change our user.address to another address, the change won’t be reflected in our injected value, this is because the data provided to the provide/inject are not reactive initially. We can fix this by passing a reactive object to provide. We have to assign a computed property to our user object.

app.component('parent-component', {
  data() {
    return {
      user: {name:"Uma Victor", address:"No 33 Rumukwurushi"}
    }
  },
  provide() {
    return {
     userAddress: Vue.computed(() => this.user)

    }
  },
  template: `
    ...
  `
})

This pattern can be very useful and simpler than using Vuex.

However, with Vue3, and the recent upgrade, we can now use context providers, enabling us to share data between multiple components just like vuex.

Proper Use of Props For Form Components

Building forms on the web is one of those things not everyone loves doing. Vue.js makes building excellent forms easy. To achieve this we need to know how to properly use props in our form components. In a traditional app where we have signup, logins, or product page we want to have consistent behavior and design. For example, the sign-in page below.

With the code:

<template>
  <div class="form-group">
  <form>
    <label for="email">Your Name</label>
    <input
      type="text"
      id="name"
      class="form-control"
      placeholder="name"
      v-model="userData.name"
    />
    <label for="email">Your Email Address</label>
    <input
      type="text"
      id="email"
      class="form-control"
      placeholder="Email"
      v-model="userData.email"
    />
    <label for="email">Your Password</label>
    <input
      type="text"
      id="password"
      class="form-control"
      placeholder="password"
      v-model="userData.password"
    />
  </form>
  </div>
</template>
<script>
    export default {
        data() {
            return {
                userData: {
                    name: '',
                    email: '',
                    password: ''
                }
            }
        },
    }
</script>

We will like to have a BaseInput component that we can use for the three form inputs above. Our BaseInput looks like this:

<template>
 <div>
   <label v-if="label">{{ label }}</label>
   <input type="email" @value="value" @input="updateInput" v-bind="$attrs">
 </div>
</template>
<script>
    export default {
      props: {
        label: {
          type: String,
          default: ""
        },
        value: [String, Number]
      },
      methods: {
        updateInput(event) {
          this.$emit('input', event.target.value)
        }
      }
    }
</script>

We want our BaseInput to accept a label prop which is always a string, and if the Input has a label, we show it in our template as we can see above.

When we fill the form, the updateInput method is triggered. The updateInput method takes the input event as an argument and it emits an event with the name of Input, along with the payload event.target.value which is the name (John Doe) in the form:

<BaseInput label="Your Name" v-model="userData.name" placeholder="Name"/>

The v-model will be listening for the input event and then when it gets it, it sets our userData.name to the payload it got.

If we want to set a placeholder for an input, we might experience an error, this is because in vue2 attributes always attach themselves to the parent, so to fix this we set inheritAttrs to false and bind attrs.

<script>
    export default {
      inheritAttrs: false,
      props: {
        label: {
          type: String,
          default: ""
        },
        value: [String, Number]
      },
      methods: {
        updateInput(event) {
          this.$emit('input', event.target.value)
        }
      }
    }
</script>

To where we want the placeholder attribute to be. Our form page code looks like this now:

<template>
  <div class="form-group">
    <form>
      <BaseInput label="Your Name" v-model="userData.name" placeholder="Name"/>
      <BaseInput label="Your Email Address" v-model="userData.email" placeholder="Email"/>
      <BaseInput label="Your Password" v-model="userData.password" placeholder="Password"/>
    </form>
  </div>
</template>

We finally have a standalone reusable form component. You can play with the code in the codesandbox I made.

Note: $Attrs in Vue3 now includes all of your listeners, style bindings, and classes.

Getting Familiar With Vue Devtools

Vue.js Devtools is a very powerful tool as it helps us effectively debug our application in real-time. It is most powerful when we use Vuex and we have to manage mutations and track changes in our app. Most Vue.js developers use devtools as an extension, but we can also install it as a standalone app.

Note: The Vue.js devtools only work in the development mode of your build and won’t work in production so other people can’t use it to inspect your app.

Installing Devtools As a Standalone App

You might be wondering why we would want to install a standalone app for devtools when we can use the browser extension for it? It is because when you install it as a standalone app locally, you can use it from any browser.

We install it:

// Globally
npm install -g @vue/devtools
// or locally
npm install --save-dev @vue/devtools

Once it’s done installing, run:

vue-devtools

Then in our index.html file, located in the public folder in the root of our Vue.js application we add:

<script src="https://localhost:8098"></script>

Once your app is reloaded, it will automatically connect.

Some Operations We Can Do With Vue Devtools

Here are some helpful operations you can do on Vue.js DevTools.

• Dark Theme
  In the new DevTools, there is now an option to set between light, dark, or contrast themes. You can do this by going to your global settings and selecting it.

• Timeline
  The new timeline in the devtools displays information about events that occur and it’s arranged in chronological order. It is located next to the inspector and settings view.

• Format component name
  You can choose to display your component name in either camelCase or kebab-case.

There are many other operations that you can utilize in the vue devtools. You can check out their changelog.

Tools to Make Work In Vue Easier

When working with Vuejs, we might encounter some features we would love to implement, but it might take a lot of time to hard code or just a little bit difficult to implement. As professional developers, we add certain tools and helper libraries to make things easier and we would be looking at some of them.

Testing libraries

Testing can play a crucial role when building large-scale applications. It helps us to avoid unnecessary bugs during development when working with a team. Let’s look at the three types of testing we can carry out in our Vue application and their frameworks.

• Component Testing
  Vue Testing Library, Vue Test Utils.
• Unit testing
  Jest, Mocha.
• End to End Tests
  Nightwatch.js, Cypress.

Component Libraries

A component library is a set of reusable components we can use in our application to make UI development much faster and more consistent in our application. Like React and Angular, Vue has its own set of component libraries. Some of them include:

• Vue Material Kit
  A “Badass” Vue.js UI kit built upon material design. It contains more than 60+ handcrafted components.
• Buefy
  A lightweight component library based on the Bulma CSS framework. If you are comfortable with SASS, you will have no problem using it.
• Vuetify
  This is also a material design component framework with the availability of already made scaffolding for code, with a large community and regular updates
• Quasar
  My personal favorite, when it comes to the component framework. Quasar with its high performant frontend stack allows you to build cross-platform applications for Web, Mobile, and Desktop.

Other Interesting Libraries

Other note worthy libraries are:

• FilePond
  This Vue.js library uploads any image you give it and optimizes those images with a silky-smooth experience.
• Vuelidate
  This library is very important when working with forms and you need a way to validate user inputs on the frontend. It is a simple and lightweight Model-based validation.
• vue-Clickaway
  Vue doesn’t have a native event listener to know when a user has clicked outside an element, for example, a dropdown, that’s why vue-clickaway exists to detect click events.

There are many more libraries out there. You can check out a plethora of them on madewithvuejs.com and vuejsexamples.com.

Helpful Extensions To Help You In Writing Vue

Extensions are really helpful tools, which can make a big difference in your daily productivity when writing vuejs. During the time I have spent writing Vuejs code, I have found the following extensions Very helpful:

• Vetur
  This is the number one extension on my list. Saving me hours when writing Vuejs. It provides specific highlighting, snippets, Intellisense, debugging, and much more for Vue.js.
• Bookmarks
  This extension comes in very handy when working on a large project because you can mark and set a bookmark in places in your code and jump to that specific place when you want to.
• Eslint
  Eslint helps us to easily find coding errors by throwing a warning if we do something wrong in the code. It is advisable to use it in a prettier format.
• Vue.js Extension Pack
  This extension pack contains a collection of other extensions that will help in your Vue.js development like Prettier, Vetur, Night Owl, Etc.

Conclusion

In this tutorial, we have looked at some tips and tools to help you become a better Vue developer. We started with some helpful insights on organizing our projects for scale and other great points to note and we rounded it up with Tools and extensions that make writing Vuejs so much easier.

Keep in mind that most of what is learned in this article is centered on Vue.js 2, to avoid misunderstandings.

Other Resources

Here are some useful links you can check out if you want to dive deeper into some of the things we discussed above.

• “Custom Directives,” Official Docs
• “Vue’s Reactivity,” Official Docs
• “Vue Devtools,” website
• Talk on Composition API vs Vuex
• Useful tools vue javascript development by Timi Omoyeni

Further Reading

• 35 Beautiful Vintage and Retro Photoshop Tutorials
• 60 Rare and Unusual Vintage Signs
• Vintage and Retro Typography Showcase
• Rediscovering The Joy Of Design

(yk, mrn)

Pinpoint accuracy and modularity are among the perks that make geocodes the perfect means of finding a particular location.

In this guide, we’ll build a simple geocoding app from scratch, using Vue.js and Mapbox. We’ll cover the process from building the front-end scaffolding up to building a geocoder to handle forward geocoding and reverse geocoding. To get the most out of this guide, you’ll need a basic understanding of JavaScript and Vue.js and how to make API calls.

What Is Geocoding?

Geocoding is the transformation of text-based locations to geographic coordinates (typically, longitude and latitude) that indicate a location in the world.

Geocoding is of two types: forward and reverse. Forward geocoding converts location texts to geographic coordinates, whereas reverse geocoding converts coordinates to location texts.

In other words, reverse geocoding turns 40.714224, -73.961452 into “277 Bedford Ave, Brooklyn”, and forward geocoding does the opposite, turning “277 Bedford Ave, Brooklyn” into 40.714224, -73.961452.

To give more insight, we will build a mini web app that uses an interactive web map with custom markers to display location coordinates, which we will subsequently decode to location texts.

Our app will have the following basic functions:

• give the user access to an interactive map display with a marker;
• allow the user to move the marker at will, while displaying coordinates;
• return a text-based location or location coordinates upon request by the user.

Set Up Project Using Vue CLI

We’ll make use of the boilerplate found in this repository. It contains a new project with the Vue CLI and yarn as a package manager. You’ll need to clone the repository. Ensure that you’re working from the geocoder/boilerplate branch.

Set Up File Structure Of Application

Next, we will need to set up our project’s file structure. Rename the Helloworld.vue file in the component’s folder to Index.vue, and leave it blank for now. Go ahead and copy the following into the App.vue file:

<template>
  <div id="app">
    <!--Navbar Here -->
    <div>
      <nav>
        <div class="header">
          <h3>Geocoder</h3>
        </div>
      </nav>
    </div>
    <!--Index Page Here -->
    <index />
  </div>
</template>
<script>
import index from "./components/index.vue";
export default {
  name: "App",
  components: {
    index,
  },
};
</script>

Here, we’ve imported and then registered the recently renamed component locally. We’ve also added a navigation bar to lift our app’s aesthetics.

We need an .env file to load the environment variables. Go ahead and add one in the root of your project folder.

Install Required Packages And Libraries

To kickstart the development process, we will need to install the required libraries. Here’s a list of the ones we’ll be using for this project:

1. Mapbox GL JS
   This JavaScript library uses WebGL to render interactive maps from vector tiles and Mapbox.
2. Mapbox-gl-geocoder
   This geocoder control for Mapbox GL will help with our forward geocoding.
3. Dotenv
   We won’t have to install this because it comes preinstalled with the Vue CLI. It helps us to load environment variables from an .env file into process.env. This way, we can keep our configurations separate from our code.
4. Axios
   This library will help us make HTTP requests.

Install the packages in your CLI according to your preferred package manager. If you’re using Yarn, run the command below:

cd geocoder && yarn add mapbox-gl @mapbox/mapbox-gl-geocoder axios

If you’re using npm, run this:

cd geocoder && npm i mapbox-gl @mapbox/mapbox-gl-geocoder axios --save

We first had to enter the geocoder folder before running the installation command.

Scaffolding The Front End With Vue.js

Let’s go ahead and create a layout for our app. We will need an element to house our map, a region to display the coordinates while listening to the marker’s movement on the map, and something to display the location when we call the reverse geocoding API. We can house all of this within a card component.

Copy the following into your Index.vue file:

<template>
  <div class="main">
    <div class="flex">
      <!-- Map Display here -->
      <div class="map-holder">
        <div id="map"></div>
      </div>
      <!-- Coordinates Display here -->
      <div class="dislpay-arena">
        <div class="coordinates-header">
          <h3>Current Coordinates</h3>
          <p>Latitude:</p>
          <p>Longitude:</p>
        </div>
        <div class="coordinates-header">
          <h3>Current Location</h3>
          <div class="form-group">
            <input
              type="text"
              class="location-control"
              :value="location"
              readonly
            />
            <button type="button" class="copy-btn">Copy</button>
          </div>
          <button type="button" class="location-btn">Get Location</button>
        </div>
      </div>
    </div>
  </div>
</template>

To see what we currently have, start your development server. For Yarn:

yarn serve

Or for npm:

npm run serve

Our app should look like this now:

The blank spot to the left looks off. It should house our map display. Let’s add that.

Interactive Map Display With Mapbox

The first thing we need to do is gain access to the Mapbox GL and Geocoder libraries. We’ll start by importing the Mapbox GL and Geocoder libraries in the Index.vue file.

import axios from "axios";
import mapboxgl from "mapbox-gl";
import MapboxGeocoder from "@mapbox/mapbox-gl-geocoder";
import "@mapbox/mapbox-gl-geocoder/dist/mapbox-gl-geocoder.css";

Mapbox requires a unique access token to compute map vector tiles. Get yours, and add it as an environmental variable in your .env file.

.env

VUE_APP_MAP_ACCESS_TOKEN=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

We also need to define properties that will help with putting our map tiles together in our data instance. Add the following below the spot where we imported the libraries:

export default {
  data() {
    return {
      loading: false,
      location: "",
      access_token: process.env.VUE_APP_MAP_ACCESS_TOKEN,
      center: [0, 0],
      map: {},
    };
  },
}

• The location property will be modeled to the input that we have in our scaffolding. We will use this to handle reverse geocoding (i.e. display a location from the coordinates).
• The center property houses our coordinates (longitude and latitude). This is critical to putting our map tiles together, as we will see shortly.
• The access_token property refers to our environmental variable, which we added earlier.
• The map property serves as a constructor for our map component.

Let’s proceed to create a method that plots our interactive map with our forward geocoder embedded in it. This method is our base function, serving as an intermediary between our component and Mapbox GL; we will call this method createMap. Add this below the data object:

mounted() {
  this.createMap()
},

methods: {
  async createMap() {
    try {
      mapboxgl.accessToken = this.access_token;
      this.map = new mapboxgl.Map({
        container: "map",
        style: "mapbox://styles/mapbox/streets-v11",
        center: this.center,
        zoom: 11,
      });

    } catch (err) {
      console.log("map error", err);
    }
  },
},

To create our map, we’ve specified a container that houses the map, a style property for our map’s display format, and a center property to house our coordinates. The center property is an array type and holds the longitude and latitude.

Mapbox GL JS initializes our map based on these parameters on the page and returns a Map object to us. The Map object refers to the map on our page, while exposing methods and properties that enable us to interact with the map. We’ve stored this returned object in our data instance, this.map.

Forward Geocoding With Mapbox Geocoder

Now, we will add the geocoder and custom marker. The geocoder handles forward geocoding by transforming text-based locations to coordinates. This will appear in the form of a search input box appended to our map.

Add the following below the this.map initialization that we have above:

let geocoder =  new MapboxGeocoder({
    accessToken: this.access_token,
    mapboxgl: mapboxgl,
    marker: false,
  });

this.map.addControl(geocoder);

geocoder.on("result", (e) => {
  const marker = new mapboxgl.Marker({
    draggable: true,
    color: "#D80739",
  })
    .setLngLat(e.result.center)
    .addTo(this.map);
  this.center = e.result.center;
  marker.on("dragend", (e) => {
    this.center = Object.values(e.target.getLngLat());
  });
});

Here, we’ve first created a new instance of a geocoder using the MapboxGeocoder constructor. This initializes a geocoder based on the parameters provided and returns an object, exposed to methods and events. The accessToken property refers to our Mapbox access token, and mapboxgl refers to the map library currently used.

Core to our app is the custom marker; the geocoder comes with one by default. This, however, wouldn’t give us all of the customization we need; hence, we’ve disabled it.

Moving along, we’ve passed our newly created geocoder as a parameter to the addControl method, exposed to us by our map object. addControl accepts a control as a parameter.

To create our custom marker, we’ve made use of an event exposed to us by our geocoder object. The on event listener enables us to subscribe to events that happen within the geocoder. It accepts various events as parameters. We’re listening to the result event, which is fired when an input is set.

In a nutshell, on result, our marker constructor creates a marker, based on the parameters we have provided (a draggable attribute and color, in this case). It returns an object, with which we use the setLngLat method to get our coordinates. We append the custom marker to our existing map using the addTo method. Finally, we update the center property in our instance with the new coordinates.

We also have to track the movement of our custom marker. We’ve achieved this by using the dragend event listener, and we updated our center property with the current coordinates.

Let’s update the template to display our interactive map and forward geocoder. Update the coordinates display section in our template with the following:

<div class="coordinates-header">
  <h3>Current Coordinates</h3>
  <p>Latitude: {{ center[0] }}</p>
  <p>Longitude: {{ center[1] }}</p>
</div>

Remember how we always updated our center property following an event? We are displaying the coordinates here based on the current value.

To lift our app’s aesthetics, add the following CSS file in the head section of the index.html file. Put this file in the public folder.

<link href="https://api.tiles.mapbox.com/mapbox-gl-js/v0.53.0/mapbox-gl.css" rel="stylesheet" />

Our app should look like this now:

Reverse Geocode Location With Mapbox API

Now, we will handle reverse geocoding our coordinates to text-based locations. Let’s write a method that handles that and trigger it with the Get Location button in our template.

Reverse geocoding in Mapbox is handled by the reverse geocoding API. This accepts longitude, latitude, and access token as request parameters. This call returns a response payload — typically, with various details. Our concern is the first object in the features array, where the reverse geocoded location is.

We’ll need to create a function that sends the longitude, latitude and access_token of the location we want to get to the Mapbox API. We need to send them in order to get the details of that location.

Finally, we need to update the location property in our instance with the value of the place_name key in the object.

Below the createMap() function, let’s add a new function that handles what we want. This is how it should look:

async getLocation() {
  try {
    this.loading = true;
    const response = await axios.get(
      `https://api.mapbox.com/geocoding/v5/mapbox.places/${this.center[0]},${this.center[1]}.json?access_token=${this.access_token}`
    );
    this.loading = false;
    this.location = response.data.features[0].place_name;
  } catch (err) {
    this.loading = false;
    console.log(err);
  }
},

This function makes a GET request to the Mapbox API. The response contains place_name — the name of the selected location. We get this from the response and then set it as the value of this.location.

With that done, we need to edit and set up the button that will call this function we have created. We’ll make use of a click event listener — which will call the getLocation method when a user clicks on it. Go ahead and edit the button component to this.

<button
  type="button"
  :disabled="loading"
  :class="{ disabled: loading }"
  class="location-btn"
  @click="getLocation"
>
  Get Location
</button>

As icing on the cake, let’s attach a function to copy the displayed location to the clipboard. Add this just below the getLocation function:

copyLocation() {
  if (this.location) {
    navigator.clipboard.writeText(this.location);
    alert("Location Copied")
  }
  return;
},

Update the Copy button component to trigger this:

<button type="button" class="copy-btn" @click="copyLocation">

Conclusion

In this guide, we’ve looked at geocoding using Mapbox. We built a geocoding app that transforms text-based locations to coordinates, displaying the location on an interactive map, and that converts coordinates to text-based locations, according to the user’s request. This guide is just the beginning. A lot more could be achieved with the geocoding APIs, such as changing the presentation of the map using the various map styles provided by Mapbox.

• The source code is available on GitHub.

Resources

• “Geocoding”, Mapbox documentation
• “Styles”, Mapbox documentation
• “Using Env Variables in Client-Side Code”, in “Modes and Environment Variables”, Vue CLI

Further Reading

• Uniting Web And Native Apps With 4 Unknown JavaScript APIs
• How To Build Server-Side Rendered (SSR) Svelte Apps With SvelteKit
• Optimizing A Vue App
• Setting And Persisting Color Scheme Preferences With CSS And A “Touch” Of JavaScript

(ks, vf, yk, il, al, mrn)

State can be hard. When we start a simple Vue project, it can be simple to just keep our working state on a particular component:

setup() {
  let books: Work[] = reactive([]);

  onMounted(async () => {
    // Call the API
    const response = await bookService.getScienceBooks();
    if (response.status === 200) {
      books.splice(0, books.length, ...response.data.works);
    }
  });

  return {
    books
  };
},

When your project is a single page of showing data (perhaps to sort or filter it), this can be compelling. But in this case, this component will get data on every request. What if you want to keep it around? That’s where state management comes into play. As network connections are often expensive and occasionally unreliable, it would be better to keep this state around as you navigate through an application.

Another issue is communicating between components. While you can use events and props to communicate with direct children-parents, handling simple situations like error handling and busy flags can be difficult when each of your views/pages are independent. For example, imagine that you had a top-level control was wired up to show error and loading animation:

// App.vue
<template>
  <div class="container mx-auto bg-gray-100 p-1">
    <router-link to="/"><h1>Bookcase</h1></router-link>
    <div class="alert" v-if="error">{{ error }}</div>
    <div class="alert bg-gray-200 text-gray-900" v-if="isBusy">
      Loading...
    </div>
    <router-view :key="$route.fullPath"></router-view>
  </div>
</template>

Without an effective way to handle this state, it might suggest a publish/subscribe system, but in fact sharing data is more straightforward in many cases. If want to have shared state, how do you go about it? Let’s look at some common ways to do this.

Note: You’ll find the code for this section in the “main” branch of the example project on GitHub.

Shared State In Vue 3

Since moving to Vue 3, I’ve migrated completely to using the Composition API. For the article, I’m also using TypeScript though that’s not required for examples I’m showing you. While you can share state any way you want, I’m going to show you several techniques that I find the most commonly used patterns. Each has it’s own pros and cons, so don’t take anything I talk about here as dogma.

The techniques include:

• Factories,
• Shared Singletons,
• Vuex 4,
• Vuex 5.

Note: Vuex 5, as of the writing of this article, it’s in the RFC (Request for Comments) stage so I want to get you ready for where Vuex is going, but right now there is not a working version of this option.

Let’s dig in…

Factories

Note: The code for this section is in the “Factories” branch of the example project on GitHub.

The factory pattern is just about creating an instance of the state you care about. In this pattern, you return a function that is much like the start function in the Composition API. You’d create a scope and build the components of what you’re looking for. For example:

export default function () {

  const books: Work[] = reactive([]);

  async function loadBooks(val: string) {
      const response = await bookService.getBooks(val, currentPage.value);
      if (response.status === 200) {
        books.splice(0, books.length, ...response.data.works);
      }
  }

  return {
    loadBooks,
    books
  };
}

You could ask for just the parts of the factory created objects you need like so:

// In Home.vue
  const { books, loadBooks } = BookFactory();

If we add an isBusy flag to show when the network request happens, the above code doesn’t change, but you could decide where you are going to show the isBusy:

export default function () {

  const books: Work[] = reactive([]);
  const isBusy = ref(false);

  async function loadBooks(val: string) {
    isBusy.value = true;
    const response = await bookService.getBooks(val, currentPage.value);
    if (response.status === 200) {
      books.splice(0, books.length, ...response.data.works);
    }
  }

  return {
    loadBooks,
    books,
    isBusy
  };
}

In another view (vue?) you could just ask for the isBusy flag without having to know about how the rest of the factory works:

// App.vue
export default defineComponent({
  setup() {
    const { isBusy } = BookFactory();
    return {
      isBusy
    }
  },
})

But you may have noticed an issue; every time we call the factory, we’re getting a new instance of all the objects. There are times when you want to have a factory return new instances, but in our case we’re talking about sharing the state, so we need to move the creation outside the factory:

const books: Work[] = reactive([]);
const isBusy = ref(false);

async function loadBooks(val: string) {
  isBusy.value = true;
  const response = await bookService.getBooks(val, currentPage.value);
  if (response.status === 200) {
    books.splice(0, books.length, ...response.data.works);
  }
}

export default function () {
 return {
    loadBooks,
    books,
    isBusy
  };
}

Now the factory is giving us a shared instance, or a singleton if you prefer. While this pattern works, it can be confusing to return a function that doesn’t create a new instance every time.

Because the underlying objects are marked as const you shouldn’t be able to replace them (and break the singleton nature). So this code should complain:

// In Home.vue
  const { books, loadBooks } = BookFactory();

  books = []; // Error, books is defined as const

So it can be important to make sure mutable state can be updated (e.g. using books.splice() instead of assigning the books).

Another way to handle this is to use shared instances.

Shared Instances

The code for this section is in the “SharedState” branch of the example project on GitHub.

If you’re going to be sharing state, might as well be clear about the fact that the state is a singleton. In this case, it can just be imported as a static object. For example, I like to create an object that can be imported as a reactive object:

export default reactive({

  books: new Array<Work>(),
  isBusy: false,

  async loadBooks() {
    this.isBusy = true;
    const response = await bookService.getBooks(this.currentTopic, this.currentPage);
    if (response.status === 200) {
      this.books.splice(0, this.books.length, ...response.data.works);
    }
    this.isBusy = false;
  }
});

In this case, you just import the object (which I’m calling a store in this example):

// Home.vue
import state from "@/state";

export default defineComponent({
  setup() {

    // ...

    onMounted(async () => {
      if (state.books.length === 0) state.loadBooks();
    });

    return {
      state,
      bookTopics,
    };
  },
});

Then it becomes easy to bind to the state:

<!-- Home.vue -->
<div class="grid grid-cols-4">
  <div
    v-for="book in state.books"
    :key="book.key"
    class="border bg-white border-grey-500 m-1 p-1"
  >
  <router-link :to="{ name: 'book', params: { id: book.key } }">
    <BookInfo :book="book" />
  </router-link>
</div>

Like the other patterns, you get the benefit that you can share this instance between views:

// App.vue
import state from "@/state";

export default defineComponent({
  setup() {
    return {
      state
    };
  },
})

Then this can bind to what is the same object (whether it is a parent of the Home.vue or another page in the router):

<!-- App.vue -->
  <div class="container mx-auto bg-gray-100 p-1">
    <router-link to="/"><h1>Bookcase</h1></router-link>
    <div class="alert bg-gray-200 text-gray-900"   
         v-if="state.isBusy">Loading...</div>
    <router-view :key="$route.fullPath"></router-view>
  </div>

Whether you use the factory pattern or the shared instance, they both have a common issue: mutable state. You can have accidental side effects of bindings or code changing state when you don’t want them to. In a trivial example like I’m using here, it isn’t complex enough to worry about. But as you’re building larger and larger apps, you will want to think about state mutation more carefully. That’s where Vuex can come to the rescue.

Vuex 4

The code for this section is in the “Vuex4” branch of the example project on GitHub.

Vuex is state manager for Vue. It was built by the core team though it is managed as a separate project. The purpose of Vuex is to separate the state from the actions you want to do to the state. All changes of state has to go through Vuex which means it is more complex, but you get protection from accidental state change.

The idea of Vuex is to provide a predictable flow of state management. Views flow to Actions which, in turn, use Mutations to change State which, in turn, updates the View. By limiting the flow of state change, you should have fewer side effects that change the state of your applications; therefore be easier to build larger applications. Vuex has a learning curve, but with that complexity you get predictability.

Additionally, Vuex does support development-time tools (via the Vue Tools) to work with the state management including a feature called time-travel. This allows you to view a history of the state and move back and forward to see how it affects the application.

There are times, too, when Vuex is important too.

To add it to your Vue 3 project, you can either add the package to the project:

> npm i vuex

Or, alternatively you can add it by using the Vue CLI:

> vue add vuex

By using the CLI, it will create a starting point for your Vuex store, otherwise you’ll need to wire it up manually to the project. Let’s walk through how this works.

First, you’ll need a state object that is created with Vuex’s createStore function:

import { createStore } from 'vuex'

export default createStore({
  state: {},
  mutations: {},
  actions: {},
  getters: {}
});

As you can see, the store requires several properties to be defined. State is just a list of the data you want to give your application access to:

import { createStore } from 'vuex'

export default createStore({
  state: {
    books: [],
    isBusy: false
  },
  mutations: {},
  actions: {}
});

Note that the state shouldn’t use ref or reactive wrappers. This data is the same kind of share data that we used with Shared Instances or Factories. This store will be a singleton in your application, therefore the data in state is also going to be shared.

Next, let’s look at actions. Actions are operations that you want to enable that involve the state. For example:

  actions: {
    async loadBooks(store) {
      const response = await bookService.getBooks(store.state.currentTopic,
      if (response.status === 200) {
        // ...
      }
    }
  },

Actions are passed an instance of the store so that you can get at the state and other operations. Normally, we’d destructure just the parts we need:

  actions: {
    async loadBooks({ state }) {
      const response = await bookService.getBooks(state.currentTopic,
      if (response.status === 200) {
        // ...
      }
    }
  },

The last piece of this are Mutations. Mutations are functions that can mutate state. Only mutations can affect state. So, for this example, we need mutations that change change the state:

  mutations: {
    setBusy: (state) => state.isBusy = true,
    clearBusy: (state) => state.isBusy = false,
    setBooks(state, books) {
      state.books.splice(0, state.books.length, ...books);
    }
 },

Mutation functions always pass in the state object so that you can mutate that state. In the first two examples, you can see that we’re explicitly setting the state. But in the third example, we’re passing in the state to set. Mutations always take two parameters: state and the argument when calling the mutation.

To call a mutation, you’d use the commit function on the store. In our case, I’ll just add it to the destructuring:

  actions: {
    async loadBooks({ state, commit }) {
      commit("setBusy");
      const response = await bookService.getBooks(state.currentTopic, 
      if (response.status === 200) {
        commit("setBooks", response.data);
      }
      commit("clearBusy");
    }
  },

What you’ll see here is how commit requires the name of the action. There are tricks to make this not just use magic strings, but I’m going to skip that for now. This use of magic strings is one of the limitations of using Vuex.

While using commit may seem like an unnecessary wrapper, remember that Vuex is not going to let you mutate state except inside the mutation, therefore only calls through commit will.

You can also see that the call to setBooks takes a second argument. This is the second argument that is calling the mutation. If you were to need more information, you’d need to pack it into a single argument (another limitation of Vuex currently). Assuming you needed to insert a book into the books list, you could call it like this:

commit("insertBook", { book, place: 4 }); // object, tuple, etc.

Then you could just destructure into the pieces you need:

mutations: {
  insertBook(state, { book, place }) => // ...    
}

Is this elegant? Not really, but it works.

Now that we have our action working with mutations, we need to be able to use the Vuex store in our code. There are really two ways to get at the store. First, by registering the store with application (e.g. main.ts/js), you’ll have access to a centralized store that you have access to everywhere in your application:

// main.ts
import store from './store'

createApp(App)
  .use(store)
  .use(router)
  .mount('#app')

Note that this isn’t adding Vuex, but your actual store that you’re creating. Once this is added, you can just call useStore to get the store object:

import { useStore } from "vuex";

export default defineComponent({
  components: {
    BookInfo,
  },
  setup() {
    const store = useStore();
    const books = computed(() => store.state.books);
    // ...
  

This works fine, but I prefer to just import the store directly:

import store from "@/store";

export default defineComponent({
  components: {
    BookInfo,
  },
  setup() {
    const books = computed(() => store.state.books);
    // ...
  

Now that you have access to the store object, how do you use it? For state, you’ll need to wrap them with computed functions so that changes will be propagated to your bindings:

export default defineComponent({
  setup() {

    const books = computed(() => store.state.books);

    return {
      books
    };
  },
});

To call actions, you will need to call the dispatch method:

export default defineComponent({
  setup() {

    const books = computed(() => store.state.books);

    onMounted(async () => await store.dispatch("loadBooks"));

    return {
      books
    };
  },
});

Actions can have parameters that you add after the name of the method. Lastly, to change state, you’ll need to call commit just like we did inside the Actions. For example, I have a paging property in the store, and then I can change the state with commit:

const incrementPage = () =>
  store.commit("setPage", store.state.currentPage + 1);
const decrementPage = () =>
  store.commit("setPage", store.state.currentPage - 1);

Note, that calling it like this would throw an error (because you can’t change state manually):

const incrementPage = () => store.state.currentPage++;
  const decrementPage = () => store.state.currentPage--;

This is the real power here, we’d want control where state is changed and not have side effects that produce errors further down the line in development.

You may be overwhelmed with number of moving pieces in Vuex, but it can really help manage state in larger, more complex projects. I would not say you need it in every case, but there will be large projects where it helps you overall.

The big problem with Vuex 4 is that working with it in a TypeScript project leaves a lot to be desired. You can certainly make TypeScript types to help development and builds, but it requires a lot of moving pieces.

That’s where Vuex 5 is meant to simplify how Vuex works in TypeScript (and in JavaScript projects in general). Let’s see how that will work once it’s released next.

Vuex 5

Note: The code for this section is in the “Vuex5” branch of the example project on GitHub.

At the time of this article, Vuex 5 isn’t real. It’s a RFC (Request for Comments). It’s a plan. It’s a starting point for discussion. So a lot of what I may explain here likely will change somewhat. But to prepare you for the change in Vuex, I wanted to give you a view of where it’s going. Because of this the code associated with this example doesn’t build.

The basic concepts of how Vuex works have been somewhat unchanged since it’s inception. With the introduction of Vue 3, Vuex 4 was created to mostly allow Vuex to work in new projects. But the team is trying to look at the real pain-points with Vuex and solve them. To this end they are planning some important changes:

• No more mutations: actions can mutate state (and possibly anyone).
• Better TypeScript support.
• Better multi-store functionality.

So how would this work? Let’s start with creating the store:

export default createStore({
  key: 'bookStore',
  state: () => ({
    isBusy: false,
    books: new Array<Work>()
  }),
  actions: {
    async loadBooks() {
      try {
        this.isBusy = true;
        const response = await bookService.getBooks();
        if (response.status === 200) {
          this.books = response.data.works;
        }
      } finally {
        this.isBusy = false;
      }
    }
  },
  getters: {
    findBook(key: string): Work | undefined {
      return this.books.find(b => b.key === key);
    }
  }
});

First change to see is that every store now needs it own key. This is to allow you to retrieve multiple stores. Next you’ll notice that the state object is now a factory (e.g. returns from a function, not created on parsing). And there is no mutations section any more. Lastly, inside the actions, you can see we’re accessing state as just properties on the this pointer. No more having to pass in state and commit to actions. This helps not only in simplifying development, but also makes it easier to infer types for TypeScript.

To register Vuex into your application, you’ll register Vuex instead of your global store:

import { createVuex } from 'vuex'

createApp(App)
  .use(createVuex())
  .use(router)
  .mount('#app')

Finally, to use the store, you’ll import the store then create an instance of it:

import bookStore from "@/store";

export default defineComponent({
  components: {
    BookInfo,
  },
  setup() {
    const store = bookStore(); // Generate the wrapper
    // ...
  

Notice that what is returned from the store is a factory object that returns thsi instance of the store, no matter how many times you call the factory. The returned object is just an object with the actions, state and getters as first class citizens (with type information):

onMounted(async () => await store.loadBooks());

const incrementPage = () => store.currentPage++;
const decrementPage = () => store.currentPage--;

What you’ll see here is that state (e.g. currentPage) are just simple properties. And actions (e.g. loadBooks) are just functions. The fact that you’re using a store here is a side effect. You can treat the Vuex object as just an object and go about your work. This is a significant improvement in the API.

Another change that’s important to point out is that you could also generate your store using a Composition API-like syntax:

export default defineStore("another", () => {

  // State
  const isBusy = ref(false);
  const books = reactive(new Array≷Work>());

  // Actions
  async function loadBooks() {
    try {
      this.isBusy = true;
      const response = await bookService.getBooks(this.currentTopic, this.currentPage);
      if (response.status === 200) {
        this.books = response.data.works;
      }
    } finally {
      this.isBusy = false;
    }
  }

  findBook(key: string): Work | undefined {
    return this.books.find(b => b.key === key);
  }

  // Getters
  const bookCount = computed(() => this.books.length);

  return {
    isBusy,
    books,
    loadBooks,
    findBook,
    bookCount
  }
});

This allows you to build your Vuex object just like you would your views with the Composition API and arguably it’s simpler.

One main drawback in this new design is that you lose the non-mutability of the state. There are discussions happening around being able to enable this (for development only, just like Vuex 4) but there isn’t consensus how important this is. I personally think it’s a key benefit for Vuex, but we’ll have to see how this plays out.

Where Are We?

Managing shared state in single page applications is a crucial part of development for most apps. Having a game plan on how you want to go about it in Vue is an important step in designing your solution. In this article, I’ve shown you several patterns for managing shared state including what’s coming for Vuex 5. Hopefully you’ll now have the knowledge to make the right decision for you own projects.

Further Reading

• Building Complex Forms In Vue
• How To Deal With Big Tooling Upgrades In Large Organizations
• The Era Of Platform Primitives Is Finally Here
• The Safest Way To Hide Your API Keys When Using React

(vf, yk, il, mrn)

Videos work with streams. This means that instead of sending the entire video at once, a video is sent as a set of smaller chunks that make up the full video. This explains why videos buffer when watching a video on slow broadband because it only plays the chunks it has received and tries to load more.

This article is for developers who are willing to learn a new technology by building an actual project: a video streaming app with Node.js as the backend and Nuxt.js as the client.

• Node.js is a runtime used for building fast and scalable applications. We will use it to handle fetching and streaming videos, generating thumbnails for videos, and serving captions and subtitles for videos.
• Nuxt.js is a Vue.js framework that helps us build server-rendered Vue.js applications easily. We will consume our API for the videos and this application will have two views: a listing of available videos and a player view for each video.

Prerequisities

• An understanding of HTML, CSS, JavaScript, Node/Express, and Vue.
• A text editor (e.g. VS Code).
• A web browser (e.g. Chrome, Firefox).
• FFmpeg installed on your workstation.
• Node.js. nvm.
• You can get the source code on GitHub.

Setting Up Our Application

In this application, we will build the routes to make requests from the frontend:

• videos route to get a list of videos and their data.
• a route to fetch only one video from our list of videos.
• streaming route to stream the videos.
• captions route to add captions to the videos we are streaming.

After our routes have been created, we’ll scaffold our Nuxt frontend, where we’ll create the Home and dynamic player page. Then we request our videos route to fill the home page with the video data, another request to stream the videos on our player page, and finally a request to serve the caption files to be used by the videos.

To set up our application, we create our project directory,

mkdir streaming-app

Setting Up Our Server

In our streaming-app directory, we create a folder named backend.

cd streaming-app
mkdir backend

In our backend folder, we initialize a package.json file to store information about our server project.

cd backend
npm init -y

we need to install the following packages to build our app.

• nodemon automatically restarts our server when we make changes.
• express gives us a nice interface to handle routes.
• cors will allow us to make cross-origin requests since our client and server will be running on different ports.

In our backend directory, we create a folder assets to hold our videos for streaming.

 mkdir assets

Copy a .mp4 file into the assets folder, and name it video1. You can use .mp4 short sample videos that can be found on Github Repo.

Create an app.js file and add the necessary packages for our app.

const express = require('express');
const fs = require('fs');
const cors = require('cors');
const path = require('path');
const app = express();
app.use(cors())

The fs module is used to read and write into files easily on our server, while the path module provides a way of working with directories and file paths.

Now we create a ./video route. When requested, it will send a video file back to the client.

// add after 'const app = express();'

app.get('/video', (req, res) => {
    res.sendFile('assets/video1.mp4', { root: __dirname });
});

This route serves the video1.mp4 video file when requested. We then listen to our server at port 3000.

// add to end of app.js file

app.listen(5000, () => {
    console.log('Listening on port 5000!')
});

A script is added in the package.json file to start our server using nodemon.

"scripts": {
    "start": "nodemon app.js"
  },

Then on your terminal run:

npm run start

If you see the message Listening on port 3000! in the terminal, then the server is working correctly. Navigate to https://localhost:5000/video in your browser and you should see the video playing.

Requests To Be Handled By The Frontend

Below are the requests that we will make to the backend from our frontend that we need the server to handle.

• /videos
  Returns an array of video mockup data that will be used to populate the list of videos on the Home page in our frontend.
• /video/:id/data
  Returns metadata for a single video. Used by the Player page in our frontend.
• /video/:id
  Streams a video with a given ID. Used by the Player page.

Let’s create the routes.

Return Mockup Data For List Of Videos

For this demo application, we’ll create an array of objects that will hold the metadata and send that to the frontend when requested. In a real application, you would probably be reading the data from a database, which would then be used to generate an array like this. For simplicity’s sake, we won’t be doing that in this tutorial.

In our backend folder create a file mockdata.js and populate it with metadata for our list of videos.

const allVideos = [
    {
        id: "tom and jerry",
        poster: 'https://image.tmdb.org/t/p/w500/fev8UFNFFYsD5q7AcYS8LyTzqwl.jpg',
        duration: '3 mins',
        name: 'Tom & Jerry'
    },
    {
        id: "soul",
        poster: 'https://image.tmdb.org/t/p/w500/kf456ZqeC45XTvo6W9pW5clYKfQ.jpg',
        duration: '4 mins',
        name: 'Soul'
    },
    {
        id: "outside the wire",
        poster: 'https://image.tmdb.org/t/p/w500/lOSdUkGQmbAl5JQ3QoHqBZUbZhC.jpg',
        duration: '2 mins',
        name: 'Outside the wire'
    },
];
module.exports = allVideos

We can see from above, each object contains information about the video. Notice the poster attribute which contains the link to a poster image of the video.

Let’s create a videos route since all our request to be made by the frontend is prepended with /videos.

To do this, let’s create a routes folder and add a Video.js file for our /videos route. In this file, we’ll require express and use the express router to create our route.

const express = require('express')
const router = express.Router()

When we go to the /videos route, we want to get our list of videos, so let’s require the mockData.js file into our Video.js file and make our request.

const express = require('express')
const router = express.Router()
const videos = require('../mockData')
// get list of videos
router.get('/', (req,res)=>{
    res.json(videos)
})
module.exports = router;

The /videos route is now declared, save the file and it should automatically restart the server. Once it’s started, navigate to https://localhost:3000/videos and our array is returned in JSON format.

Return Data For A Single Video

We want to be able to make a request for a particular video in our list of videos. We can fetch a particular video data in our array by using the id we gave it. Let’s make a request, still in our Video.js file.

// make request for a particular video
router.get('/:id/data', (req,res)=> {
    const id = parseInt(req.params.id, 10)
    res.json(videos[id])
})

The code above gets the id from the route parameters and converts it to an integer. Then we send the object that matches the id from the videos array back to the client.

Streaming The Videos

In our app.js file, we created a /video route that serves a video to the client. We want this endpoint to send smaller chunks of the video, instead of serving an entire video file on request.

We want to be able to dynamically serve one of the three videos that are in the allVideos array, and stream the videos in chunks, so:

Delete the /video route from app.js.

We need three videos, so copy the example videos from the tutorial’s source code into the assets/ directory of your server project. Make sure the filenames for the videos are corresponding to the id in the videos array:

Back in our Video.js file, create the route for streaming videos.

router.get('/video/:id', (req, res) => {
    const videoPath = `assets/${req.params.id}.mp4`;
    const videoStat = fs.statSync(videoPath);
    const fileSize = videoStat.size;
    const videoRange = req.headers.range;
    if (videoRange) {
        const parts = videoRange.replace(/bytes=/, "").split("-");
        const start = parseInt(parts[0], 10);
        const end = parts[1]
            ? parseInt(parts[1], 10)
            : fileSize-1;
        const chunksize = (end-start) + 1;
        const file = fs.createReadStream(videoPath, {start, end});
        const head = {
            'Content-Range': `bytes ${start}-${end}/${fileSize}`,
            'Accept-Ranges': 'bytes',
            'Content-Length': chunksize,
            'Content-Type': 'video/mp4',
        };
        res.writeHead(206, head);
        file.pipe(res);
    } else {
        const head = {
            'Content-Length': fileSize,
            'Content-Type': 'video/mp4',
        };
        res.writeHead(200, head);
        fs.createReadStream(videoPath).pipe(res);
    }
});

If we navigate to https://localhost:5000/videos/video/outside-the-wire in our browser, we can see the video streaming.

How The Streaming Video Route Works

There is a fair bit of code written in our stream video route, so let’s look at it line by line.

 const videoPath = `assets/${req.params.id}.mp4`;
 const videoStat = fs.statSync(videoPath);
 const fileSize = videoStat.size;
 const videoRange = req.headers.range;

First, from our request, we get the id from the route using req.params.id and use it to generate the videoPath to the video. We then read the fileSize using the file system fs we imported. For videos, a user’s browser will send a range parameter in the request. This lets the server know which chunk of the video to send back to the client.

Some browsers send a range in the initial request, but others don’t. For those that don’t, or if for any other reason the browser doesn’t send a range, we handle that in the else block. This code gets the file size and send the first few chunks of the video:

else {
    const head = {
        'Content-Length': fileSize,
        'Content-Type': 'video/mp4',
    };
    res.writeHead(200, head);
    fs.createReadStream(path).pipe(res);
}

We will handle subsequent requests including the range in an if block.

if (videoRange) {
        const parts = videoRange.replace(/bytes=/, "").split("-");
        const start = parseInt(parts[0], 10);
        const end = parts[1]
            ? parseInt(parts[1], 10)
            : fileSize-1;
        const chunksize = (end-start) + 1;
        const file = fs.createReadStream(videoPath, {start, end});
        const head = {
            'Content-Range': `bytes ${start}-${end}/${fileSize}`,
            'Accept-Ranges': 'bytes',
            'Content-Length': chunksize,
            'Content-Type': 'video/mp4',
        };
        res.writeHead(206, head);
        file.pipe(res);
    }

This code above creates a read stream using the start and end values of the range. Set the Content-Length of the response headers to the chunk size that is calculated from the start and end values. We also use HTTP code 206, signifying that the response contains partial content. This means the browser will keep making requests until it has fetched all chunks of the video.

What Happens On Unstable Connections

If the user is on a slow connection, the network stream will signal it by requesting that the I/O source pauses until the client is ready for more data. This is known as back-pressure. We can take this example one step further and see how easy it is to extend the stream. We can easily add compression, too!

const start = parseInt(parts[0], 10);
        const end = parts[1]
            ? parseInt(parts[1], 10)
            : fileSize-1;
        const chunksize = (end-start) + 1;
        const file = fs.createReadStream(videoPath, {start, end});

We can see above that a ReadStream is created and serves the video chunk by chunk.

const head = {
            'Content-Range': `bytes ${start}-${end}/${fileSize}`,
            'Accept-Ranges': 'bytes',
            'Content-Length': chunksize,
            'Content-Type': 'video/mp4',
        };
res.writeHead(206, head);
        file.pipe(res);

The request header contains the Content-Range, which is the start and end changing to get the next chunk of video to stream to the frontend, the content-length is the chunk of video sent. We also specify the type of content we are streaming which is mp4. The writehead of 206 is set to respond with only newly made streams.

Creating A Caption File For Our Videos

This is what a .vtt caption file looks like.

WEBVTT

00:00:00.200 --> 00:00:01.000
Creating a tutorial can be very

00:00:01.500 --> 00:00:04.300
fun to do.

Captions files contain text for what is said in a video. It also contains time codes for when each line of text should be displayed. We want our videos to have captions, and we won’t be creating our own caption file for this tutorial, so you can head over to the captions folder in the assets directory in the repo and download the captions.

Let’s create a new route that will handle the caption request:

router.get('/video/:id/caption', (req, res) => res.sendFile(`assets/captions/${req.params.id}.vtt`, { root: __dirname }));

Building Our Frontend

To get started on the visual part of our system, we would have to build out our frontend scaffold.

Note: You need vue-cli to create our app. If you don’t have it installed on your computer, you can run npm install -g @vue/cli to install it.

Installation

At the root of our project, let’s create our front-end folder:

mkdir frontend
cd frontend

and in it, we initialize our package.json file, copy and paste the following in it:

{
  "name": "my-app",
  "scripts": {
    "dev": "nuxt",
    "build": "nuxt build",
    "generate": "nuxt generate",
    "start": "nuxt start"
  }
}

then install nuxt:

npm add nuxt

and execute the following command to run Nuxt.js app:

npm run dev

Our Nuxt File Structure

Now that we have Nuxt installed, we can begin laying out our frontend.

First, we need to create a layouts folder at the root of our app. This folder defines the layout of the app, no matter the page we navigate to. Things like our navigation bar and footer are found here. In the frontend folder, we create default.vue for our default layout when we start our frontend app.

mkdir layouts
cd layouts
touch default.vue

Then a components folder to create all our components. We will be needing only two components, NavBar and video component. So in our root folder of frontend we:

mkdir components
cd components
touch NavBar.vue
touch Video.vue

Finally, a pages folder where all our pages like home and about can be created. The two pages we need in this app, are the home page displaying all our videos and video information and a dynamic player page that routes to the video we click on.

mkdir pages
cd pages
touch index.vue
mkdir player
cd player
touch _name.vue

Our frontend directory now looks like this:

|-frontend
  |-components
    |-NavBar.vue
    |-Video.vue
  |-layouts
    |-default.vue
  |-pages
    |-index.vue
    |-player
      |-_name.vue
  |-package.json
  |-yarn.lock

Navbar Component

Our NavBar.vue looks like this:

<template>
    <div class="navbar">
        <h1>Streaming App</h1>
    </div>
</template>
<style scoped>
.navbar {
    display: flex;
    background-color: #161616;
    justify-content: center;
    align-items: center;
}
h1{
    color:#a33327;
}
</style>

The NavBar has a h1 tag that displays Streaming App, with some little styling.

Let’s import the NavBar into our default.vue layout.

// default.vue
<template>
 <div>
   <NavBar />
   <nuxt />
 </div>
</template>
<script>
import NavBar from "@/components/NavBar.vue"
export default {
    components: {
        NavBar,
    }
}
</script>

The default.vue layout now contains our NavBar component and the <nuxt /> tag after it signifies where any page we create will be displayed.

In our index.vue (which is our homepage), let’s make a request to https://localhost:5000/videos to get all the videos from our server. Passing the data as a prop to our video.vue component we will create later. But for now, we have already imported it.

<template>
<div>
  <Video :videoList="videos"/>
</div>
</template>
<script>
import Video from "@/components/Video.vue"
export default {
  components: {
    Video
  },
head: {
    title: "Home"
  },
    data() {
      return {
        videos: []
      }
    },
    async fetch() {
      this.videos = await fetch(
        'https://localhost:5000/videos'
      ).then(res => res.json())
    }
}
</script>

Video Component

Below, we first declare our prop. Since the video data is now available in the component, using Vue’s v-for we iterate on all the data received and for each one, we display the information. We can use the v-for directive to loop through the data and display it as a list. Some basic styling has also been added.

<template>
<div>
  <div class="container">
    <div
    v-for="(video, id) in videoList"
    :key="id"
    class="vid-con"
  >
    <NuxtLink :to="`/player/${video.id}`">
    <div
      :style="{
        backgroundImage: `url(${video.poster})`
      }"
      class="vid"
    ></div>
    <div class="movie-info">
      <div class="details">
      <h2>{{video.name}}</h2>
      <p>{{video.duration}}</p>
      </div>
    </div>
  </NuxtLink>
  </div>
  </div>
</div>
</template>
<script>
export default {
    props:['videoList'],
}
</script>
<style scoped>
.container {
  display: flex;
  justify-content: center;
  align-items: center;
  margin-top: 2rem;
}
.vid-con {
  display: flex;
  flex-direction: column;
  flex-shrink: 0;
  justify-content: center;
  width: 50%;
  max-width: 16rem;
  margin: auto 2em;
  
}
.vid {
  height: 15rem;
  width: 100%;
  background-position: center;
  background-size: cover;
}
.movie-info {
  background: black;
  color: white;
  width: 100%;
}
.details {
  padding: 16px 20px;
}
</style>

We also notice that the NuxtLink has a dynamic route, that is routing to the /player/video.id.

The functionality we want is when a user clicks on any of the videos, it starts streaming. To achieve this, we make use of the dynamic nature of the _name.vue route.

In it, we create a video player and set the source to our endpoint for streaming the video, but we dynamically append which video to play to our endpoint with the help of this.$route.params.name that captures which parameter the link received.

<template>
    <div class="player">
        <video controls muted autoPlay>
            <source :src="`https://localhost:5000/videos/video/${vidName}`" type="video/mp4">
        </video>
    </div>
</template>
<script>
export default {
 data() {
      return {
        vidName: ''
      }
    },
mounted(){
    this.vidName = this.$route.params.name
}
}
</script>
<style scoped>
.player {
    display: flex;
    justify-content: center;
    align-items: center;
    margin-top: 2em;
}
</style>

When we click on any of the video we get:

Adding Our Caption File

To add our track file, we make sure all the .vtt files in the captions folder have the same name as our id. Update our video element with the track, making a request for the captions.

<template>
    <div class="player">
        <video controls muted autoPlay crossOrigin="anonymous">
            <source :src="`https://localhost:5000/videos/video/${vidName}`" type="video/mp4">
            <track label="English" kind="captions" srcLang="en" :src="`https://localhost:5000/videos/video/${vidName}/caption`" default>
        </video>
    </div>
</template>

We’ve added crossOrigin="anonymous" to the video element; otherwise, the request for captions will fail. Now refresh and you’ll see captions have been added successfully.

What To Keep In Mind When Building Resilient Video Streaming.

When building streaming applications like Twitch, Hulu or Netflix, there are a number of things that are put into consideration:

• Video data processing pipeline
  This can be a technical challenge as high-performing servers are needed to serve millions of videos to users. High latency or downtime should be avoided at all costs.
• Caching
  Caching mechanisms should be used when building this type of application example Cassandra, Amazon S3, AWS SimpleDB.
• Users’ geography
  Considering the geography of your users should be thought about for distribution.

Conclusion

In this tutorial, we have seen how to create a server in Node.js that streams videos, generates captions for those videos, and serves metadata of the videos. We’ve also seen how to use Nuxt.js on the frontend to consume the endpoints and the data generated by the server.

Unlike other frameworks, building an application with Nuxt.js and Express.js is quite easy and fast. The cool part about Nuxt.js is the way it manages your routes and makes you structure your apps better.

• You can get more information about Nuxt.js here.
• You can get the source code on Github.

Resources

• “Adding Captions And Subtitles To HTML5 Video,” MDN Web Docs
• “Understanding Captions And Subtitles,” Screenfont.ca

(ks, vf, yk, il)

In this article, we’re going to look at reactivity in Vue, how it works, and how we can create reactive variables using newly created methods and functions. This article is targeted at developers who have a good understanding of how Vue 2.x works and are looking to get familiar with the new Vue 3.

We’re going to build a simple application to better understand this topic. The code for this app can be found on GitHub.

By default, JavaScript isn’t reactive. This means that if we create the variable boy and reference it in part A of our application, then proceed to modify boy in part B, part A will not update with the new value of boy.

let framework = 'Vue';
let sentence = `${framework} is awesome`;
console.log(sentence)
 // logs "Vue is awesome"
framework = 'React';
console.log(sentence)
//should log "React is awesome" if 'sentence' is reactive.

The snippet above is a perfect example of the non-reactive nature of JavaScript — hence, why the change isn’t reflected in the sentence variable.

In Vue 2.x, props, computed, and data() were all reactive by default, with the exception of properties that are not present in data when such components are created. This means that when a component is injected into the DOM, only the existing properties in the component’s data object would cause the component to update if and when such properties change.

Internally, Vue 3 uses the Proxy object (an ECMAScript 6 feature) to ensure that these properties are reactive, but it still provides the option to use Object.defineProperty from Vue 2 for Internet Explorer support (ECMAScript 5). This method defines a new property directly on an object, or modifies an existing property on an object, and returns the object.

At first glance and since most of us already know that reactivity is not new in Vue, it might seem unnecessary to make use of these properties, but the Options API has its limitations when you’re dealing with a large application with reusable functions in several parts of the application. To this end, the new Composition API was introduced to help with abstracting logic in order to make a code base easier to read and maintain. Also, we can now easily make any variable reactive regardless of its data type using any of the new properties and methods.

When we use the setup option, which serves as the entry point for the Composition API, the data object, computed properties, and methods are inaccessible because the component instance has not yet been created when setup is executed. This makes it impossible to take advantage of the built-in reactivity in any of these features in setup. In this tutorial, we’re going to learn about all of the ways we can do this.

The Reactive Method

According to the documentation, the reactive method, which is the equivalent of Vue.observable() in Vue 2.6, can be useful when we’re trying to create an object all of whose properties are reactive (such as the data object in the Options API). Under the hood, the data object in the Options API uses this method to make all of the properties in it reactive.

But we can create our own reactive object like this:

import { reactive } from 'vue'

// reactive state
let user = reactive({
        "id": 1,
        "name": "Leanne Graham",
        "username": "Bret",
        "email": "Sincere@april.biz",
        "address": {
            "street": "Kulas Light",
            "suite": "Apt. 556",
            "city": "Gwenborough",
            "zipcode": "92998-3874",
            "geo": {
                "lat": "-37.3159",
                "lng": "81.1496"
            }
        },
        "phone": "1-770-736-8031 x56442",
        "website": "hildegard.org",
        "company": {
            "name": "Romaguera-Crona",
            "catchPhrase": "Multi-layered client-server neural-net",
            "bs": "harness real-time e-markets"
        },
        "cars": {
            "number": 0
        }
    })

Here, we imported the reactive method from Vue, and then we declared our user variable by passing its value to this function as an argument. In doing so, we’ve made user reactive, and, thus, if we use user in our template and if either the object or a property of this object should change, then this value will get automatically updated in this template.

ref

Just as we have a method for making objects reactive, we also need one to make other standalone primitive values (strings, booleans, undefined values, numbers, etc.) and arrays reactive. During development, we would work with these other data types while also needing them to be reactive. The first approach we might think of would be to use reactive and pass in the value of the variable that we want to make reactive.

import { reactive } from 'vue'

const state = reactive({
  users: [],
});

Because reactive has deep reactive conversion, user as a property would also be reactive, thereby achieving our goal; hence, user would always update anywhere it is used in the template of such an app. But with the ref property, we can make any variable with any data type reactive by passing the value of that variable to ref. This method also works for objects, but it nests the object one level deeper than when the reactive method is used.

let property = {
  rooms: '4 rooms',
  garage: true,
  swimmingPool: false
}
let reactiveProperty = ref(property)
console.log(reactiveProperty)
// prints {
// value: {rooms: "4 rooms", garage: true, swimmingPool: false}
// }

Under the hood, ref takes this argument passed to it and converts it into an object with a key of value. This means, we can access our variable by calling variable.value, and we can also modify its value by calling it in the same way.

import {ref} from 'vue'
let age = ref(1)

console.log(age.value)
//prints 1
age.value++
console.log(age.value)
//prints 2

With this, we can import ref into our component and create a reactive variable:

<template>
  <div class="home">
    <form @click.prevent="">
      <table>
        <tr>
          <th>Name</th>
          <th>Username</th>
          <th>email</th>
          <th>Edit Cars</th>
          <th>Cars</th>
        </tr>
        <tr v-for="user in users" :key="user.id">
          <td>{{ user.name }}</td>
          <td>{{ user.username }}</td>
          <td>{{ user.email }}</td>
          <td>
            <input
              type="number"
              style="width: 20px;"
              name="cars"
              id="cars"
              v-model.number="user.cars.number"
            />
          </td>
          <td>
            <cars-number :cars="user.cars" />
          </td>
        </tr>
      </table>
      <p>Total number of cars: {{ getTotalCars }}</p>
    </form>
  </div>
</template>
<script>
  // @ is an alias to /src
  import carsNumber from "@/components/cars-number.vue";
  import axios from "axios";
  import { ref } from "vue";
  export default {
    name: "Home",
    data() {
      return {};
    },
    setup() {
      let users = ref([]);
      const getUsers = async () => {
        let { data } = await axios({
          url: "data.json",
        });
        users.value = data;
      };
      return {
        users,
        getUsers,
      };
    },
    components: {
      carsNumber,
    },
    created() {
      this.getUsers();
    },
    computed: {
      getTotalCars() {
        let users = this.users;
        let totalCars = users.reduce(function(sum, elem) {
          return sum + elem.cars.number;
        }, 0);
        return totalCars;
    },
  };
</script>

Here, we imported ref in order to create a reactive users variable in our component. We then imported axios to fetch data from a JSON file in the public folder, and we imported our carsNumber component, which we’ll be creating later on. The next thing we did was create a reactive users variable using the ref method, so that users can update whenever the response from our JSON file changes.

We also created a getUser function that fetches the users array from our JSON file using axios, and we assigned the value from this request to the users variable. Finally, we created a computed property that computes the total number of cars that our users have as we have modified it in the template section.

It is important to note that when accessing ref properties that are returned in the template section or outside of setup(), they are automatically shallow unwrapped. This means that refs that are an object would still require a .value in order to be accessed. Because users is an array, we could simply use users and not users.value in getTotalCars.

In the template section, we displayed a table that displays each user’s information, together with a <cars-number /> component. This component accepts a cars prop that is displayed in each user’s row as the number of cars they have. This value updates whenever the value of cars changes in the user object, which is exactly how the data object or computed property would work if we were working with the Options API.

toRefs

When we use the Composition API, the setup function accepts two arguments: props and context. This props is passed from the component to setup(), and it makes it possible to access the props that the component has from inside this new API. This method is particularly useful because it allows for the destructuring of objects without losing its reactivity.

<template>
  <p>{{ cars.number }}</p>
</template>
<script>
  export default {
    props: {
      cars: {
        type: Object,
        required: true,
      },
      gender: {
        type: String,
        required: true,
      },
    },
    setup(props) {
      console.log(props);
   // prints {gender: "female", cars: Proxy}
    },
  };
</script>
<style></style>

To use a value that is an object from props in the Composition API while ensuring it maintains its reactivity, we make use of toRefs. This method takes a reactive object and converts it into a plain object in which each property of the original reactive object becomes a ref. What this means is that the cars prop…

cars: {
  number: 0
}

… would now become this:

{
  value: cars: {
    number: 0
  }

With this, we can make use of cars inside any part of the setup API while still maintaining its reactivity.

 setup(props) {
      let { cars } = toRefs(props);
      console.log(cars.value);
      // prints {number: 0}
    },

We can watch this new variable using the Composition API’s watch and react to this change however we might want to.

setup(props) {
      let { cars } = toRefs(props);
      watch(
        () => cars,
        (cars, prevCars) => {
          console.log("deep ", cars.value, prevCars.value);
        },
        { deep: true }
      );
    }

toRef

Another common use case we could be faced with is passing a value that is not necessarily an object but rather one of the data types that work with ref (array, number, string, boolean, etc.). With toRef, we can create a reactive property (i.e. ref) from a source reactive object. Doing this would ensure that the property remains reactive and would update whenever the parent source changes.

const cars = reactive({
  Toyota: 1,
  Honda: 0
})

const NumberOfHondas = toRef(state, 'Honda')

NumberOfHondas.value++
console.log(state.Honda) // 1

state.Honda++
console.log(NumberOfHondas.value) // 2

Here, we created a reactive object using the reactive method, with the properties Toyota and Honda. We also made use of toRef to create a reactive variable out of Honda. From the example above, we can see that when we update Honda using either the reactive cars object or NumberOfHondas, the value gets updated in both instances.

This method is similar and yet so different from the toRefs method that we covered above in the sense that it maintains its connection to its source and can be used for strings, arrays, and numbers. Unlike with toRefs, we do not need to worry about the existence of the property in its source at the time of creation, because if this property does not exist at the time that this ref is created and instead returns null, it would still be stored as a valid property, with a form of watcher put in place, so that when this value changes, this ref created using toRef would also be updated.

We can also use this method to create a reactive property from props. That would look like this:

<template>
  <p>{{ cars.number }}</p>
</template>
<script>
  import { watch, toRefs, toRef } from "vue";
  export default {
    props: {
      cars: {
        type: Object,
        required: true,
      },
      gender: {
        type: String,
        required: true,
      },
    },
    setup(props) {
      let { cars } = toRefs(props);
      let gender = toRef(props, "gender");
      console.log(gender.value);
      watch(
        () => cars,
        (cars, prevCars) => {
          console.log("deep ", cars.value, prevCars.value);
        },
        { deep: true }
      );
    },
  };
</script>

Here, we created a ref that would be based on the gender property gotten from props. This comes in handy when we want to perform extra operations on the prop of a particular component.

Conclusion

In this article, we have looked at how reactivity in Vue works using some of the newly introduced methods and functions from Vue 3. We started by looking at what reactivity is and how Vue makes use of the Proxy object behind the scenes to achieve this. We also looked at how we can create reactive objects using reactive and how to create reactive properties using ref.

Finally, we looked at how to convert reactive objects to plain objects, each of whose properties are a ref pointing to the corresponding property of the original object, and we saw how to create a ref for a property on a reactive source object.

Other Resources

• “Proxy” (object), MDN Web Docs
• “Reactivity Fundamentals”, Vue.js
• “Refs”, Vue.js
• “Lifecycle Hook Registration Inside setup”, Vue.js

Further Reading

• Building Complex Forms In Vue
• How To Deal With Big Tooling Upgrades In Large Organizations
• Build A Static RSS Reader To Fight Your Inner FOMO
• The Era Of Platform Primitives Is Finally Here

(ks, vf, yk, il, al, mrn)

Vuex is the solution for state management in Vue applications. The next version — Vuex 4 — is making its way through the final steps before officially releasing. This release will bring full compatibility with Vue 3, but doesn’t add new features. While Vuex has always been a powerful solution, and the first choice for many developers for state management in Vue, some developers had hoped to see more workflow issues addressed. However, even as Vuex 4 is just getting out the door, Kia King Ishii (a Vue core team member) is talking about his plans for Vuex 5, and I’m so excited by what I saw that I had to share it with you all. Note that Vuex 5 plans are not finalized, so some things may change before Vuex 5 is released, but if it ends up mostly similar to what you see in this article, it should be a big improvement to the developer experience.

With the advent of Vue 3 and it’s composition API, people have been looking into hand-built simple alternatives. For example, You Might Not Need Vuex demonstrates a relatively simple, yet flexible and robust pattern for using the composition API along with provide/inject to create shared state stores. As Gábor states in his article, though, this (and other alternatives) should only be used in smaller applications because they lack all those things that aren’t directly about the code: community support, documentation, conventions, good Nuxt integrations, and developer tools.

That last one has always been one of the biggest issues for me. The Vue devtools browser extension has always been an amazing tool for debugging and developing Vue apps, and losing the Vuex inspector with “time travel” would be a pretty big loss for debugging any non-trivial applications.

Thankfully, with Vuex 5 we’ll be able to have our cake and eat it too. It will work more like these composition API alternatives but keep all the benefits of using an official state management library. Now let’s take a look at what will be changing.

Defining A Store

Before we can do anything with a Vuex store, we need to define one. In Vuex 4, a store definition will look like this:

import { createStore } from 'vuex'

export const counterStore = createStore({
  state: {
    count: 0
  },
  
  getters: {
    double (state) {
      return state.count * 2
    }
  },
  
  mutations: {
    increment (state) {
      state.count++
    }
  },
  
  actions: {
    increment (context) {
      context.commit('increment')
    }
  }
})

Each store has four parts: state stores the data, getters give you computed state, mutations are used to mutate the state, and actions are the methods that are called from outside the store to accomplish anything related to the store. Usually, actions don’t just commit a mutation as this example shows. Instead, they are used to do asynchronous tasks because mutations must be synchronous or they just implement more complicated or multi-step functionality. Actions also cannot mutate the state on their own; they must use a mutator. So what does Vuex 5 look like?

import { defineStore } from 'vuex'

export const counterStore = defineStore({
  name: 'counter',
  
  state() {
    return { count: 0 }
  },
  
  getters: {
    double () {
      return this.count * 2
    }
  },
  
  actions: {
    increment () {
      this.count++
    }
  }
})

There are a few changes to note here. First, instead of createStore, we use defineStore. This difference is negligible, but it’s there for semantic reasons, which we’ll go over later. Next, we need to provide a name for the store, which we didn’t need before. In the past, modules got their own name, but they weren’t provided by the module itself; they were just the property name they were assigned to by the parent store that added them. Now, there are no modules. Instead, each module will be a separate store and have a name. This name is used by the Vuex registry, which we’ll talk about later.

After that, we need to make state a function that returns the initial state instead of just setting it to the initial state. This is similar to the data option on components. We write getters very similar to the way we did in Vuex 4, but instead of using the state as a parameter for each getter, you can just use this to get to the state. In the same way, actions don’t need to worry about a context object being passed in: they can just use this to access everything. Finally, there are no mutations. Instead, mutations are combined with actions. Kia noted that too often, mutations just became simple setters, making them pointlessly verbose, so they removed them. He didn’t mention whether it was “ok” to mutate the state directly from outside the store, but we are definitely allowed and encouraged to mutate state directly from an action and the Flux pattern frowns on the direct mutation of state.

Note: For those who prefer the composition API over the options API for creating components, you’ll be happy to learn there is also a way to create stores in a similar fashion to using the composition API.

import { ref, computed } from 'vue'
import { defineStore } from 'vuex'

export const counterStore = defineStore('counter', {
  const count = ref(0)

  const double = computed(() => count.value * 2)
  
  function increment () {
    count.value++
  }

  return { count, double, increment }  
})

As shown above, the name gets passed in as the first argument for defineStore. The rest looks just like a composition function for components. This will yield exactly the same result as the previous example that used the options API.

Getting The Store Instantiated

In Vuex 4, things have changed from Vuex 3, but I’ll just look at v4 to keep things from getting out of hand. In v4, when you called createStore, you already instantiated it. You can then just use it in your app, either via app.use or directly:

import { createApp } from 'vue'
import App from './App.vue' // Your root component
import store from './store' // The store definition from earlier

const app = createApp(App)

app.use(store)
app.mount('#app')

// Now all your components can access it via `this.$store`
// Or you can use in composition components with `useStore()`

// -----------------------------------------------

// Or use directly... this is generally discouraged
import store from './store'

store.state.count // -> 0
store.commit('increment')
store.dispatch('increment')
store.getters.double // -> 4

This is one thing that Vuex 5 makes a bit more complicated than in v4. Each app now can get a separate instance of Vuex, which makes sure that each app can have separate instances of the same stores without sharing data between them. You can share an instance of Vuex if you want to share instances of stores between apps.

import { createApp } from 'vue'
import { createVuex } from 'vuex'
import App from './App.vue' // Your root component

const app = createApp(App)
const vuex = createVuex() // create instance of Vuex

app.use(vuex) // use the instance
app.mount('#app')

Now all of your components have access to the Vuex instance. Instead of giving your store(s) definition directly, you then import them into the components you want to use them in and use the Vuex instance to instantiate and register them:

import { defineComponent } from 'vue'
import store from './store'

export default defineComponent({
  name: 'App',

  computed: {
    counter () {
      return this.$vuex.store(store)
    }
  }
})

Calling $vuex.store, instantiates and registers the store in the Vuex instance. From that point on, any time you use $vuex.store on that store, it’ll give you back the already instantiated store instead of instantiating it again. You can call the store method straight on an instance of Vuex created by createVuex().

Now your store is accessible on that component via this.counter. If you’re using the composition API for your component, you can use useStore instead of this.$vuex.store:

import { defineComponent } from 'vue'
import { useStore } from 'vuex' // import useStore
import store from './store'

export default defineComponent({
  setup () {
    const counter = useStore(store)

    return { counter }
  }
})

There are pros and cons to importing the store directly into the component and instantiating it there. It allows you to code split and lazily loads the store only where it’s needed, but now it’s a direct dependency instead of being injected by a parent (not to mention you need to import it every time you want to use it). If you want to use dependency injection to provide it throughout the app, especially if you know it’ll be used at the root of the app where code splitting won’t help, then you can just use provide:

import { createApp } from 'vue'
import { createVuex } from 'vuex'
import App from './App.vue'
import store from './store'

const app = createApp(App)
const vuex = createVuex()

app.use(vuex)
app.provide('store', store) // provide the store to all components
app.mount('#app')

And you can just inject it in any component where you’re going to use it:

import { defineComponent } from 'vue'

export default defineComponent({
  name: 'App',
  inject: ['store']
})

// Or with Composition API

import { defineComponent, inject } from 'vue'

export default defineComponent({
  setup () {
    const store = inject('store')

    return { store }
  }
})

I’m not excited about this extra verbosity, but it is more explicit and more flexible, which I am a fan of. This type of code is generally written once right away at the beginning of the project and then it doesn’t bother you again, though now you’ll either need to provide each new store or import it every time you wish to use it, but importing or injecting code modules is how we generally have to work with anything else, so it’s just making Vuex work more along the lines of how people already tend to work.

Using A Store

Apart from being a fan of the flexibility and the new way of defining stores the same way as a component using the composition API, there’s one more thing that makes me more excited than everything else: how stores are used. Here’s what it looks like to use a store in Vuex 4.

store.state.count            // Access State
store.getters.double         // Access Getters
store.commit('increment')    // Mutate State
store.dispatch('increment')  // Run Actions

State, getters, mutations, and actions are all handled in different ways via different properties or methods. This has the advantage of explicitness, which I praised earlier, but this explicitness doesn’t really gain us anything. And this API only gets more difficult to use when you are using namespaced modules. By comparison, Vuex 5 looks to work exactly how you would normally hope:

store.count        // Access State
store.double       // Access Getters (transparent)
store.increment()  // Run actions
// No Mutators

Everything — the state, getters and actions — is available directly at the root of the store, making it simple to use with a lot less verbosity and practically removes all need for using mapState, mapGetters, mapActions and mapMutations for the options API or for writing extra computed statements or simple functions for composition API. This simply makes a Vuex store look and act just like a normal store that you would build yourself, but it gets all the benefits of plugins, debugging tools, official documentation, etc.

Composing Stores

The final aspect of Vuex 5 we’ll look at today is composability. Vuex 5 doesn’t have namespaced modules that are all accessible from the single store. Each of those modules would be split into a completely separate store. That’s simple enough to deal with for components: they just import whichever stores they need and fire them up and use them. But what if one store wants to interact with another store? In v4, the namespacing convolutes the whole thing, so you need to use the namespace in your commit and dispatch calls, use rootGetters and rootState and then work your way up into the namespaces you want to access getters and state from. Here’s how it works in Vuex 5:

// store/greeter.js
import { defineStore } from 'vuex'

export default defineStore({
  name: 'greeter',
  state () {
    return { greeting: 'Hello' }
  }
})

// store/counter.js
import { defineStore } from 'vuex'
import greeterStore from './greeter' // Import the store you want to interact with

export default defineStore({
  name: 'counter',

  // Then `use` the store
  use () {
    return { greeter: greeterStore }
  },
  
  state () {
    return { count: 0 }
  },
  
  getters: {
    greetingCount () {
      return `${this.greeter.greeting} ${this.count}' // access it from this.greeter
    }
  }
})

With v5, we import the store we wish to use, then register it with use and now it’s accessible all over the store at whatever property name you gave it. Things are even simpler if you’re using the composition API variation of the store definition:

// store/counter.js
import { ref, computed } from 'vue'
import { defineStore } from 'vuex'
import greeterStore from './greeter' // Import the store you want to interact with

export default defineStore('counter', ({use}) => { // `use` is passed in to function
  const greeter = use(greeterStore) // use `use` and now you have full access
  const count = 0

  const greetingCount = computed(() => {
    return  `${greeter.greeting} ${this.count}` // access it like any other variable
  })

  return { count, greetingCount }
})

No more namespaced modules. Each store is separate and is used separately. You can use use to make a store available inside another store to compose them. In both examples, use is basically just the same mechanism as vuex.store from earlier and they ensure that we instantiating the stores with the correct instance of Vuex.

TypeScript Support

For TypeScript users, one of the greatest aspects of Vuex 5 is that the simplification made it simpler to add types to everything. The layers of abstraction that older versions of Vuex had made it nearly impossible and right now, with Vuex 4, they increased our ability to use types, but there is still too much manual work to get a decent amount of type support, whereas in v5, you can put your types inline, just as you would hope and expect.

Conclusion

Vuex 5 looks to be almost exactly what I — and likely many others — hoped it would be, and I feel it can’t come soon enough. It simplifies most of Vuex, removing some of the mental overhead involved, and only gets more complicated or verbose where it adds flexibility. Leave comments below about what you think of these changes and what changes you might make instead or in addition. Or go straight to the source and add an RFC (Request for Comments) to the list to see what the core team thinks.

Further Reading

• Building Complex Forms In Vue
• How To Deal With Big Tooling Upgrades In Large Organizations
• Build A Static RSS Reader To Fight Your Inner FOMO
• How Marketing Changed OOP In JavaScript

(ra, yk, il, mrn)