Forem: Michael Hoffmann

Create a Table of Contents With Active States in Nuxt 3

Michael Hoffmann — Wed, 07 Dec 2022 00:00:00 +0000

I'm a big fan of a table of contents (ToC) on the side of a blog post page, especially if it is a long article. It helps me gauge the article's length and allows me to navigate between the sections quickly.

In this article, I will show you how to create a sticky table of contents sidebar with an active state based on the current scroll position using Nuxt 3, Nuxt Content and Intersection Observer.

Demo

The following StackBlitz contains the source code that is used in the following chapters:

Setup

For this demo, we need to initialize a Nuxt 3 project and install the Nuxt Content and Nuxt Tailwind (optional) modules.

We need to add these modules to nuxt.config.ts:

export default defineNuxtConfig({
  modules: ['@nuxt/content', '@nuxtjs/tailwindcss'],
})

Of course, we need some content to show the table of contents. For this demo, I will reference the index.md file from my StackBlitz demo.

To render this content, let's create a catch-all route in the pages directory:

<template>
  <main class="p-4 flex flex-col gap-4">
    <ContentDoc>
      <template #default="{ doc }">
        <div class="grid grid-cols-12 gap-8">
          <div class="nuxt-content col-span-8">
            <ContentRenderer ref="nuxtContent" :value="doc" />
          </div>
        </div>
      </template>
    </ContentDoc>
  </main>
</template>

The <ContentDoc> component fetches and renders a single document, and the <ContentRenderer> component renders the body of a Markdown document.

Check the official docs for more information about these Nuxt Content components.

Now let's add a TableOfContents.vue component to this template:

<script setup lang="ts">
const activeTocId = ref(null)
</script>

<template>
  <main class="p-4 flex flex-col gap-4">
    <ContentDoc>
      <template #default="{ doc }">
        <div class="grid grid-cols-12 gap-8">
          <div class="nuxt-content col-span-8">
            <ContentRenderer ref="nuxtContent" :value="doc" />
          </div>
          <div class="col-span-4 border rounded-md p-4">
            <div class="sticky top-0 flex flex-col items-center">
              <TableOfContents :activeTocId="activeTocId" />
            </div>
          </div>
        </div>
      </template>
    </ContentDoc>
  </main>
</template>

I'll explain the activeTocId prop in the following "Intersection Observer" chapter.

Let's take a look at the component's code:

<script setup lang="ts">
import { Ref } from 'vue'

const props = withDefaults(defineProps<{ activeTocId: string }>(), {})

const router = useRouter()

const { data: blogPost } = await useAsyncData(`blogToc`, () => queryContent(`/`).findOne())
const tocLinks = computed(() => blogPost.value?.body.toc.links ?? [])

const onClick = (id: string) => {
  const el = document.getElementById(id)
  if (el) {
    router.push({ hash: `#${id}` })
    el.scrollIntoView({ behavior: 'smooth', block: 'center' })
  }
}
</script>

<template>
  <div class="max-h-82 overflow-auto">
    <h4>Table of Contents</h4>
    <nav class="flex mt-4">
      <ul class="ml-0 pl-4">
        <li
          v-for="{ id, text, children } in tocLinks"
          :id="`toc-${id}`"
          :key="id"
          class="cursor-pointer text-sm list-none ml-0 mb-2 last:mb-0"
          @click="onClick(id)"
        >
          {{ text }}
          <ul v-if="children" class="ml-3 my-2">
            <li
              v-for="{ id: childId, text: childText } in children"
              :id="`toc-${childId}`"
              :key="childId"
              class="cursor-pointer text-xs list-none ml-0 mb-2 last:mb-0"
              @click.stop="onClick(childId)"
            >
              {{ childText }}
            </li>
          </ul>
        </li>
      </ul>
    </nav>
  </div>
</template>

Let's analyze this code:

To get a list of all available headlines, we use the queryContent composable and access them via body.toc.links:

const { data: blogPost } = await useAsyncData(`blogToc`, () => queryContent(`/`).findOne())
const tocLinks = computed(() => blogPost.value?.body.toc.links ?? [])

If someone clicks on a link in the ToC, we query the HTML element from the DOM, push the hash route and smoothly scroll the element into the viewport:

const onClick = (id: string) => {
  const el = document.getElementById(id)
  if (el) {
    router.push({ hash: `#${id}` })
    el.scrollIntoView({ behavior: 'smooth', block: 'center' })
  }
}

At this point, we can show a list of all the headlines of our content in the sidebar, but our ToC does not indicate which headline is currently visible.

Intersection Observer

We use the Intersection Observer to handle detecting when an element scrolls into our viewport. It's supported by almost every browser.

Nuxt Content automatically adds an id to each heading of our content files. Using document.querySelectorAll, we query all h2 and h3 elements associated with an id and use the Intersection Observer API to get informed when they scroll into view.

Let's go ahead and implement that logic:

<script setup lang="ts">
import { watchDebounced } from '@vueuse/core'

const activeTocId = ref(null)
const nuxtContent = ref(null)

const observer: Ref<IntersectionObserver | null | undefined> = ref(null)
const observerOptions = reactive({
  root: nuxtContent.value,
  threshold: 0.5,
})

onMounted(() => {
  observer.value = new IntersectionObserver((entries) => {
    entries.forEach((entry) => {
      const id = entry.target.getAttribute('id')
      if (entry.isIntersecting) {
        activeTocId.value = id
      }
    })
  }, observerOptions)

  document.querySelectorAll('.nuxt-content h2[id], .nuxt-content h3[id]').forEach((section) => {
    observer.value?.observe(section)
  })
})

onUnmounted(() => {
  observer.value?.disconnect()
})
</script>

Let's break down the single steps that are happening in this code.

First, we define some reactive variables:

activeTocId is used to track the currently active DOM element to be able to add some CSS styles to it.
nuxtContent is a Template Ref to access the DOM element of the ContentRenderer component.
observer is used to track the h2 and h3 HTML elements that scroll into the viewport.
observerOptions contains a set of options that define when the observer callback is invoked. It contains the nuxtContent ref as root for the observer and a threshold of 0.5, which means that if 50% of the way through the viewport is visible, the callback will fire. You can also set it to 0; it will fire the callback if one element pixel is visible.

In the onMounted lifecycle hook, we are initializing the observer. We iterate over each article heading and set the activeTocId value if the entry intersects with the viewport. We also use document.querySelectorAll to target our .nuxt-content article and get the DOM elements that are either h2 or h3 elements with IDs and observe those using our previously initialized IntersectionObserver.

Finally, we are disconnecting our observer in the onUnmounted lifecycle hook to inform the observer to no longer track these headings when we navigate away.

Style Active Link

Let's improve the code by applying styles to the activeTocId element in our table of contents component. It should be highlighted and show an indicator:

<script setup lang="ts">
import { watchDebounced } from '@vueuse/core'
import { Ref } from 'vue'

const props = withDefaults(defineProps<{ activeTocId: string }>(), {})

const router = useRouter()

const sliderHeight = useState('sliderHeight', () => 0)
const sliderTop = useState('sliderTop', () => 0)
const tocLinksH2: Ref<Array<HTMLElement>> = ref([])
const tocLinksH3: Ref<Array<HTMLElement>> = ref([])

const { data: blogPost } = await useAsyncData(`blogToc`, () => queryContent(`/`).findOne())
const tocLinks = computed(() => blogPost.value?.body.toc.links ?? [])

const onClick = (id: string) => {
  const el = document.getElementById(id)
  if (el) {
    router.push({ hash: `#${id}` })
    el.scrollIntoView({ behavior: 'smooth', block: 'center' })
  }
}

watchDebounced(
  () => props.activeTocId,
  (newActiveTocId) => {
    const h2Link = tocLinksH2.value.find((el: HTMLElement) => el.id === `toc-${newActiveTocId}`)
    const h3Link = tocLinksH3.value.find((el: HTMLElement) => el.id === `toc-${newActiveTocId}`)

    if (h2Link) {
      sliderHeight.value = h2Link.offsetHeight
      sliderTop.value = h2Link.offsetTop - 100
    } else if (h3Link) {
      sliderHeight.value = h3Link.offsetHeight
      sliderTop.value = h3Link.offsetTop - 100
    }
  },
  { debounce: 200, immediate: true }
)
</script>

<template>
  <div class="max-h-82 overflow-auto">
    <h4>Table of Contents</h4>
    <nav class="flex mt-4">
      <div class="relative bg-secondary w-0.5 overflow-hidden rounded">
        <div
          class="
            absolute
            left-0
            w-full
            transition-all
            duration-200
            rounded
            bg-red-500
          "
          :style="{ height: `${sliderHeight}px`, top: `${sliderTop}px` }"
        ></div>
      </div>
      <ul class="ml-0 pl-4">
        <li
          v-for="{ id, text, children } in tocLinks"
          :id="`toc-${id}`"
          :key="id"
          ref="tocLinksH2"
          class="cursor-pointer text-sm list-none ml-0 mb-2 last:mb-0"
          :class="{ 'font-bold': id === activeTocId }"
          @click="onClick(id)"
        >
          {{ text }}
          <ul v-if="children" class="ml-3 my-2">
            <li
              v-for="{ id: childId, text: childText } in children"
              :id="`toc-${childId}`"
              :key="childId"
              ref="tocLinksH3"
              class="cursor-pointer text-xs list-none ml-0 mb-2 last:mb-0"
              :class="{ 'font-bold': childId === activeTocId }"
              @click.stop="onClick(childId)"
            >
              {{ childText }}
            </li>
          </ul>
        </li>
      </ul>
    </nav>
  </div>
</template>

We use the VueUse's watchDebounced composable to debounced watch changes of the active ToC element ID:

watchDebounced(
  () => props.activeTocId,
  (newActiveTocId) => {
    const h2Link = tocLinksH2.value.find((el: HTMLElement) => el.id === `toc-${newActiveTocId}`)
    const h3Link = tocLinksH3.value.find((el: HTMLElement) => el.id === `toc-${newActiveTocId}`)

    if (h2Link) {
      sliderHeight.value = h2Link.offsetHeight
      sliderTop.value = h2Link.offsetTop - 100
    } else if (h3Link) {
      sliderHeight.value = h3Link.offsetHeight
      sliderTop.value = h3Link.offsetTop - 100
    }
  },
  { debounce: 200, immediate: true }
)

Based on the current active ToC element ID, we find the HTML element from the list of available links and set the slider height & top values accordingly.

Check the StackBlitz demo for the full source code and to play around with this implementation. A similar ToC is also available on my blog.

Conclusion

I'm pleased with my table of contents implementation using Nuxt 3, Nuxt Content, and Intersection Observer.

Of course, you can use the Intersection Observer in a traditional Vue application without Nuxt. The Intersection Observer API is mighty and can also be used to implement features like lazy-loading images.

Leave a comment if you have a better solution to implement such a ToC.

If you liked this article, follow me on Twitter to get notified about new blog posts and more content from me.

Alternatively (or additionally), you can also subscribe to my newsletter.

Building a Polite Newsletter Popup With Nuxt 3

Michael Hoffmann — Tue, 18 Oct 2022 00:00:00 +0000

This year I launched a free eBook with 27 helpful tips for Vue developers for subscribers of my weekly Vue newsletter. For marketing purposes, I showed a popup on the landing page of my portfolio page each time a user visited my site. I was aware that users probably could get annoyed by that popup. Thus I added a "Don't show again" button to that popup. I thought I solved the problem!

But soon, I realized that many other sites solved that problem more elegantly. If you visit their website, stay for some time, and scroll through the content, a small notification appears at the bottom of the screen. It asks if you are interested in a specific product, and if you agree, it redirects to a page with information about this product.

In this article, I'll explain how I built a polite popup to ask people if they would like to subscribe to my newsletter using Nuxt 3.

What is a polite popup?

The goal of a so-called polite popup is to only ask for visitors emails if it detects that visitors are engaged with your content. This means they’ll be more likely to sign up by the time we ask them because it’ll be after they’ve decided they liked our content.

In the following sections, we'll build a popup that

waits for a visitor to browse the website
makes sure visitors are interested in the website
appears off to the side in a non-intrusive way
is easy to dismiss or ignore
asks for permission first
waits a bit before it appears again

Implementation

Now that we know the criteria of a polite popup let's start implementing it using Nuxt 3.

I use Nuxt.js in this example, but the concepts and solutions are not tied to any framework.

The demo code is interactively available at StackBlitz:

Implement the composable

The most exciting challenge of the polite popup is only showing it if visitors are interested in the website and content we want to promote.

Technically, we'll solve it this way:

The visitor must be visiting a page with Vue-related content as my newsletter targets Vue developers.
The visitor must be actively scrolling the current page for 6 seconds or more.
The visitor must scroll through at least 35% of the current page during their visit.

If these numbers aren’t generating the amount of engagement you want to see from visitors, you can enable a more aggressive mode that will lower the threshold by about 20-30%.

Let's start by writing a Vue composable for our polite popup:

import { useWindowScroll, useWindowSize, useTimeoutFn } from '@vueuse/core'

const config = {
  timeoutInMs: 3000,
  contentScrollThresholdInPercentage: 300,
}

export const usePolitePopup = () => {
  const visible = useState('visible', () => false)
  const readTimeElapsed = useState('read-time-elapsed', () => false)

  const { start } = useTimeoutFn(
    () => {
      readTimeElapsed.value = true
    },
    config.timeoutInMs,
    { immediate: false }
  )
  const { y: scrollYInPx } = useWindowScroll()
  const { height: windowHeight } = useWindowSize()

  // Returns percentage scrolled (ie: 80 or NaN if trackLength == 0)
  const amountScrolledInPercentage = computed(() => {
    const documentScrollHeight = document.documentElement.scrollHeight
    const trackLength = documentScrollHeight - windowHeight.value
    const percentageScrolled = Math.floor((scrollYInPx.value / trackLength) * 100)
    return percentageScrolled
  })

  const scrolledContent = computed(() => amountScrolledInPercentage.value >= config.contentScrollThresholdInPercentage)

  const trigger = () => {
    readTimeElapsed.value = false
    start()
  }

  watch([readTimeElapsed, scrolledContent], ([newReadTimeElapsed, newScrolledContent]) => {
    if (newReadTimeElapsed && newScrolledContent) {
      visible.value = true
    }
  })

  return {
    visible,
    trigger,
  }
}

We defined two state variables:

visible: a boolean indicating if the popup should be visible or not.
readTimeElapsed: a boolean indicating if the user has spent the defined time on the page.

The trigger method is exposed and triggers the a timer which is used to check if the visitor has spent a predefined amount of time on the page. A Vue watcher is used to set visible to true if the timer has expired and the scroll threshold is exceeded.
For the timer, we use VueUse's useTimeoutFn composable which runs a setTimeout function and sets the readTimeElapsed state variable to true after the timer has expired.

Let's take a detailed look at the amountScrolledInPercentage computed property:

import { useWindowSize } from '@vueuse/core'

const { height: windowHeight } = useWindowSize()

// Returns percentage scrolled (ie: 80 or NaN if trackLength == 0)
const amountScrolledInPercentage = computed(() => {
  const documentScrollHeight = document.documentElement.scrollHeight
  const trackLength = documentScrollHeight - windowHeight.value
  const percentageScrolled = Math.floor((scrollYInPx.value / trackLength) * 100)
  return percentageScrolled
})

To get the total scrollable area of a document, we need to retrieve the following two measurements of the page:

The height of the browser window: We use VueUse's useWindowSize composable to get reactive variable of the browser window height.
The height of the entire document: We use document.documentElement.scrollHeight to get the height of the document, including content not visible on the screen due to overflow.

By subtracting 2 from 1, we get the total scrollable area of the document. VueUse's useWindowScroll composable is used to access the number of pixels the document is currently scrolled along the vertical axis.

Move your eyes down to the trackLength variable, which gets the total available scroll length of the document. The variable will contain 0 if the page is not scrollable. The percentageScrolled variable then divides the scrollYInPx variable (amount the user has scrolled) with trackLength to derive how much the user has scrolled percentage wise.

Finally, we need to trigger the popup on certain pages. In our case, we only want to trigger it on the Vue route path:

<template>
  <main>
    <ContentDoc />
  </main>
</template>

<script setup lang="ts">
const route = useRoute()

const { trigger } = usePolitePopup()

if (route.path === '/vue') {
  trigger()
}
</script>

Write the popup component

Now it's time to write the Vue component that renders the popup:

<template>
  <div v-if="visible" class="fixed z-50 right-0 bottom-0 md:right-5 md:bottom-5 p-4 rounded-md bg-white shadow-lg">
    <span>May I show you something cool?</span>
    <div class="flex gap-4 mt-4">
      <button @click="onClickOk">OK</button>
      <button @click="onClickClose">Nah, thanks</button>
    </div>
  </div>
</template>

<script setup lang="ts">
const { setClosed, visible } = usePolitePopup()

const onClickOk = async () => {
  setClosed()
  navigateTo('/newsletter')
}

const onClickClose = () => {
  setClosed()
}
</script>

In this example, I'm using Nuxt Tailwind to style the component.

PolitePopup.vue is rendered at a fixed position of the viewport if the visible reactive variable value is true. It offers two buttons, one to accept the offer and one to decline it.

As you can see, we are using setClosed from our useShowPopup composable, which we haven't defined yet. Let's define it:

export const usePolitePopup = () => {
  const visible = useState('visible', () => false)
  ...

  const setClosed = () => {
    visible.value = false
  }

  return {
    ...
    setClosed
  }
}

The last step is to add our new PolitePopup.vue component to the template of app.vue:

<template>
  <div>
    <NuxtLayout>
      <NuxtPage />
    </NuxtLayout>
    <PolitePopup />
  </div>
</template>

At this point, we finished the basic implementation of the polite popup. If we navigate to /vue, spend 3 seconds on the page, and scroll down more than 300 pixel the polite popup appears:

Add logic to wait a bit before the popup appears again

One problem with the current implementation: each time we reload the page and scroll down, the popup is triggered. But our popup should wait a bit before it appears again. So let's implement that logic.

First, we need a way to store the status of the polite popup in LocalStorage. For this, we use the following data model:

interface PolitePopupStorageDTO {
  status: 'unsubscribed' | 'subscribed'
  seenCount: number
  lastSeenAt: number
}

status is per default unsubscribed and is set to subscribed if a visitor subscribes to the newsletter.
seenCount tracks how often the user has seen the popup.
lastSeenAt tracks the timestamp when the visitor has seen the popup.

Let's add that interface to our usePolitePopup composable:

interface PolitePopupStorageDTO {
  status: 'unsubscribed' | 'subscribed'
  seenCount: number
  lastSeenAt: number
}

export const usePolitePopup = () => {
  ...
  const storedData: Ref<PolitePopupStorageDTO> = useLocalStorage('polite-popup', {
    status: 'unsubscribed',
    seenCount: 0,
    lastSeenAt: 0,
  })
  ...
  watch(
    [readTimeElapsed, scrolledContent],
    ([newReadTimeElapsed, newScrolledContent]) => {
      if (newReadTimeElapsed && newScrolledContent) {
        visible.value = true;
        storedData.value.seenCount += 1;
        storedData.value.lastSeenAt = new Date().getTime();
      }
    }
  );
  ...

  return {
    ...
  }
}

We use VueUse's useLocalStorage composable to get a reactive variable of a LocalStorage entry. Each time our watcher is fired and set the popup visible, we increment seenCount and set the current timestamp at lastSeenAt in our LocalStorage object.

Let's store the information that the visitor has subscribed to the newsletter. Let's add that logic to newsletter.vue:

<template>
  <main class="flex flex-col gap-8">
    <NuxtLink to="/">Back home</NuxtLink>
    <button @click="setSubscribed">Subscribe</button>
  </main>
</template>

<script setup lang="ts">
const { setSubscribed } = usePolitePopup()
</script>

and in

export const usePolitePopup = () => {
  ...

  const setSubscribed = () => {
    storedData.value.status = 'subscribed'
  }

  return {
    ...
    setSubscribed
  }
}

Extend visibility logic

The next step is only to show the popup if the current visitor

hasn't subscribed yet
has seen the popup more than three times
has already seen the popup today

Let's implement that logic:

const isToday = (date: Date): boolean => {
  const today = new Date();
  return (
    date.getDate() === today.getDate() &&
    date.getMonth() === today.getMonth() &&
    date.getFullYear() === today.getFullYear()
  );
};

const config = {
  timeoutInMs: 3000,
  maxSeenCount: 5,
  scrollYInPxThreshold: 300,
};

export const usePolitePopup = () => {
  ...
  watch(
    [readTimeElapsed, scrolledContent],
    ([newReadTimeElapsed, newScrolledContent]) => {
      if (storedData.value.status === 'subscribed') {
        return;
      }

      if (storedData.value.seenCount >= config.maxSeenCount) {
        return;
      }

      if (
        storedData.value.lastSeenAt &&
        isToday(new Date(storedData.value.lastSeenAt))
      ) {
        return;
      }

      if (newReadTimeElapsed && newScrolledContent) {
        visible.value = true;
        storedData.value.seenCount += 1;
        storedData.value.lastSeenAt = new Date().getTime();
      }
    }
  };
  ...

  return {
    ...
  }
}

We are done!

You will probably also have seen this polite popup on this page if you read it on my portfolio website.

Conclusion

In my opinion, polite popups are the best way to convert visitors to my newsletter. This way, I can ensure that they are interested in my content and do not get annoyed by modals.

If you liked this article, follow me on Twitter to get notified about new blog posts and more content from me.

Alternatively (or additionally), you can also subscribe to my newsletter.

Weekly Vue News

Michael Hoffmann — Wed, 12 Oct 2022 09:59:10 +0000

A weekly Vue newsletter that provides high-quality tips and curated content that help you to become a Vue.js expert.

https://weekly-vue.news

Create an RSS Feed With Nuxt 3 and Nuxt Content v2

Michael Hoffmann — Mon, 15 Aug 2022 00:00:00 +0000

My portfolio website is built with Nuxt 3 and Nuxt Content v2. An RSS feed with my latest five blog posts is available here. In this article, you'll learn how to add an RSS feed to your Nuxt website.

Setup

First, let's create a new Nuxt 3 project. As the next step, we need to add the Nuxt Content v2 module to our application.

Finally, let's add some content that will be included in the RSS feed:

├── content
|  └── blog
|  └── blog
|  |   ├── article-1.md
|  |   ├── article-2.md
|  |   ├── article-3.md
|  |   ├── article-4.md
|  |   ├── article-5.md

Each .md file has this simple structure:

---
title: 'Article 1'
description: 'Article 1 description'
date: '2022-01-01'
---

Article 5 Content

The source code for this demo is available at GitHub and in this StackBlitz playground:

Add Server Route

We will be utilizing the server routes available within Nuxt, and to do so, we'll need to create the server/ directory within our app root directly.

Once this is done, we create a routes/ directory inside this and add a rss.xml.ts file. It will translate to /rss.xml:

export default defineEventHandler(async (event) => {
  const feedString = ''
  event.res.setHeader('content-type', 'text/xml')
  event.res.end(feedString)
})

The next step is to query our blog posts:

import { serverQueryContent } from '#content/server'

export default defineEventHandler(async (event) => {
  const docs = await serverQueryContent(event).sort({ date: -1 }).where({ _partial: false }).find()
  const blogPosts = docs.filter((doc) => doc?._path?.includes('/blog'))

  const feedString = ''
  event.res.setHeader('content-type', 'text/xml')
  event.res.end(feedString)
})

Now let's add the rss library to generate the RSS XML string based on our content:

import { serverQueryContent } from '#content/server'
import RSS from 'rss'

const feed = new RSS({
  title: 'Michael Hoffmann',
  site_url: 'https://mokkapps.de',
  feed_url: `https://mokkapps.de/rss.xml`,
})

const docs = await serverQueryContent(event).sort({ date: -1 }).where({ _partial: false }).find()
const blogPosts = docs.filter((doc) => doc?._path?.includes('/blog'))

for (const doc of blogPosts) {
  feed.item({
    title: doc.title ?? '-',
    url: `https://mokkapps.de${doc._path}`,
    date: doc.date,
    description: doc.description,
  })
}

const feedString = feed.xml({ indent: true })
event.res.setHeader('content-type', 'text/xml')
event.res.end(feedString)

When using nuxt generate, you may want to pre-render the feed since the server route won't be able to run on a static hosting.

We can do this by using the nitro.prerender option in nuxt.config:

import { defineNuxtConfig } from 'nuxt'

// https://v3.nuxtjs.org/api/configuration/nuxt.config
export default defineNuxtConfig({
  modules: ['@nuxt/content'],
  nitro: {
    prerender: {
      routes: ['/rss.xml'],
    },
  },
  content: {
    // https://content.nuxtjs.org/api/configuration
  },
})

If we now navigate to /rss.xml, we get our generated RSS feed:

<rss xmlns:dc="http://purl.org/dc/elements/1.1/"
  xmlns:content="http://purl.org/rss/1.0/modules/content/"
  xmlns:atom="http://www.w3.org/2005/Atom" version="2.0">
  <channel>
    <title>
      <![CDATA[ Michael Hoffmann ]]>
    </title>
    <description>
      <![CDATA[ Michael Hoffmann ]]>
    </description>
    <link>https://mokkapps.de</link>
    <generator>RSS for Node</generator>
    <lastBuildDate>Sun, 14 Aug 2022 18:14:16 GMT</lastBuildDate>
    <atom:link href="https://mokkapps.de/rss.xml" rel="self" type="application/rss+xml"/>
    <item>
      <title>
        <![CDATA[ Article 5 ]]>
      </title>
      <description>
        <![CDATA[ Article 5 description ]]>
      </description>
      <link>https://mokkapps.de/blog/article-5</link>
      <guid isPermaLink="true">https://mokkapps.de/blog/article-5</guid>
      <pubDate>Thu, 05 May 2022 00:00:00 GMT</pubDate>
    </item>
    <item>
      <title>
        <![CDATA[ Article 4 ]]>
      </title>
      <description>
        <![CDATA[ Article 4 description ]]>
      </description>
      <link>https://mokkapps.de/blog/article-4</link>
      <guid isPermaLink="true">https://mokkapps.de/blog/article-4</guid>
      <pubDate>Mon, 04 Apr 2022 00:00:00 GMT</pubDate>
    </item>
    <item>
      <title>
        <![CDATA[ Article 3 ]]>
      </title>
      <description>
        <![CDATA[ Article 3 description ]]>
      </description>
      <link>https://mokkapps.de/blog/article-3</link>
      <guid isPermaLink="true">https://mokkapps.de/blog/article-3</guid>
      <pubDate>Thu, 03 Mar 2022 00:00:00 GMT</pubDate>
    </item>
    <item>
      <title>
        <![CDATA[ Article 2 ]]>
      </title>
      <description>
        <![CDATA[ Article 2 description ]]>
      </description>
      <link>https://mokkapps.de/blog/article-2</link>
      <guid isPermaLink="true">https://mokkapps.de/blog/article-2</guid>
      <pubDate>Wed, 02 Feb 2022 00:00:00 GMT</pubDate>
    </item>
    <item>
      <title>
        <![CDATA[ Article 1 ]]>
      </title>
      <description>
        <![CDATA[ Article 1 description ]]>
      </description>
      <link>https://mokkapps.de/blog/article-1</link>
      <guid isPermaLink="true">https://mokkapps.de/blog/article-1</guid>
      <pubDate>Sat, 01 Jan 2022 00:00:00 GMT</pubDate>
    </item>
  </channel>
</rss>

If you liked this article, follow me on Twitter to get notified about new blog posts and more content from me.

Alternatively (or additionally), you can also subscribe to my newsletter.

How to Create a Custom Code Block With Nuxt Content v2

Michael Hoffmann — Wed, 15 Jun 2022 09:01:01 +0000

Code blocks are essential for blogs about software development. In this article, I want to show you how can define a custom code block component in Nuxt Content v2 with the following features:

Custom styling for code blocks inside Markdown files
Show language name (if available)
Show file name (if available)
Show a “Copy Code” button

Nuxt Content v2

Nuxt Content v2 is a Nuxt 3 module that reads local files from the /content directory in your project. It supports .md, .yml, .csv and .json files. Additionally, it’s possible to use Vue components in Markdown with the MDC Syntax.

Setup Nuxt App

First, let’s start a new Nuxt Content project with:

npx nuxi init nuxt-custom-code-blocks -t content

Then we need to install the dependencies in the nuxt-custom-code-blocks folder:

yarn install

Now we can start the Nuxt content app in development mode:

yarn dev

A browser window should automatically open for http://localhost:3000. Alternatively, you can start playing with Nuxt Content in your browser using StackBlitz or CodeSandbox.

The following StackBlitz sandbox demonstrates the application we create in this article:

Custom Prose Component

Prose represents the HTML tags output from the Markdown syntax in Nuxt Content. Nuxt Content provides a Vue component for each HTML tag like links, title levels, etc.

It’s possible to override these Vue components, which is precisely what we’ll do to create a custom code block component.

To customize a Prose component, we have to perform these steps:

Check out the original component sources.
Use the same props.
Name it the same in our components/content/ directory.

In our example, we want to override ProseCode, which is Nuxt Content’s default Vue component to render code blocks in Markdown files.

This component accepts the following props:

code: the provided code as a string
language: the provided language name
filename: the provided filename
highlights: a list of highlighted line numbers

Let’s take a look at how we can set these values in a Markdown file:

js [src/index.js] {1, 2-3}
  const a = 4;
  const b = a + 3;
  const c = a * b;

In the above example:

js is the value passed to the language prop
src/index.js is the value passed to the filename prop
[1, 2, 3] is the value passed to the highlights prop

To override the component, we create ProseCode.vue in the components/content directory and use the exact same props that are defined in the default component:

<template>
  <slot />
</template>

<script setup lang="ts">
const props = withDefaults(
  defineProps<{
    code?: string;
    language?: string | null;
    filename?: string | null;
    highlights?: Array<number>;
  }>(),
  { code: '', language: null, filename: null, highlights: [] }
);
</script>

Now we can customize this component however we want.

Style Container

First, we want to style the container that includes the code. Therefore, we wrap the <slot /> in a div and style it:

<template>
  <div class="container">
    <slot />
  </div>
</template>

<style scoped>
.container {
  background: #1e1e1e;
  position: relative;
  margin-top: 1rem;
  margin-bottom: 1rem;
  overflow: hidden;
  border-radius: 0.5rem;
}
</style>

Let’s take a look at our custom code block:

Styled Code Block Container

Show Language

Next, we want to show the name of the language on the top right, if it is available.

<template>
  <div class="container">
    <span v-if="languageText" :style="{ background: languageBackground, color: languageColor }" class="language-text" > {{ languageText }} </span> <slot />
  </div>
</template>

<script setup lang="ts">
const props = withDefaults(
  defineProps<{
    code?: string;
    language?: string | null;
    filename?: string | null;
    highlights?: Array<number>;
  }>(),
  { code: '', language: null, filename: null, highlights: [] }
);

const languageMap: Record<
  string,
  { text: string; color: string; background: string }
> = {
  vue: {
    text: 'vue',
    background: '#42b883',
    color: 'white',
  },
  js: {
    text: 'js',
    background: '#f7df1e',
    color: 'black',
  },
};

const languageText = computed(() =>
  props.language ? languageMap[props.language]?.text : null
);
const languageBackground = computed(() =>
  props.language ? languageMap[props.language]?.background : null
);
const languageColor = computed(() =>
  props.language ? languageMap[props.language]?.color : null
);
</script>

<style scoped>
.container {
  background: #1e1e1e;
  padding-top: 1em;
}

.language-text {
  position: absolute;
  top: 0;
  right: 1em;
  padding: 0.25em 0.5em;
  font-size: 14px;
  text-transform: uppercase;
  border-bottom-right-radius: 0.25em;
  border-bottom-left-radius: 0.25em;
}
</style>

We define a map called languageMap that contains the displayed text, the CSS background, and text color for each programming language. We style the span tag that renders the language inside our template based on this map and the provided language prop:

Code block with language name

Show File Name

Next, we want to show the file’s name on the top left, if it is available:

<template>
  <div class="container">
    <span v-if="filename" class="filename-text">
      {{ filename }}
    </span>
    <slot />
  </div>
</template>

<style scoped>
.filename-text {
  position: absolute;
  top: 0;
  left: 1em;
  padding: 0.25em 0.5em;
  color: white;
  font-size: 14px;
}
</style>

The result looks like this:

Code block with file name

Add Copy Code Button

Finally, we want to show a button that copies the code to the clipboard. Therefore, we use the useClipboard composable from VueUse:

<template>
  <div class="container">
    <slot />
    <div class="bottom-container">
      <div class="copy-container">
        <span class="copied-text" v-if="copied">Copied code!</span>
        <button @click="copy(code)">Copy Code</button>
      </div>
    </div>
  </div>
</template>

<script setup lang="ts">
import { useClipboard } from '@vueuse/core';

const { copy, copied, text } = useClipboard();
</script>

<style scoped>
.bottom-container {
  display: flex;
  justify-content: flex-end;
}

.copy-container {
  display: flex;
}

.copied-text {
  margin-right: 1em;
}
</style>

Let’s take a look at the final result with language & file name, copy code button, and line highlighting:

Final custom code block

Conclusion

Custom code blocks are essential for my blog as my blog posts contain a lot of code snippets. Features like copy code or line highlighting provide excellent value to my readers, and it is straightforward to add such features by creating a custom code block component in Nuxt Content v2.

The source code of this demo is available at GitHub or as StackBlitz sandbox.

You can expect more Nuxt 3 posts in the following months as I plan to blog about interesting topics that I discover while rewriting my portfolio website.

If you liked this article, follow me on Twitter to get notified about new blog posts and more content from me.

Alternatively (or additionally), you can also subscribe to my newsletter.

Create a Blog With Nuxt Content v2

Michael Hoffmann — Thu, 02 Jun 2022 15:15:35 +0000

I prefer simple Markdown files as the content source for my blog posts. In this article, I want to show you how can set up a simple blog using Nuxt Content v2.

Nuxt Content v2

Setup Nuxt App

First, let’s start a new Nuxt Content project with:

npx nuxi init nuxt-demo-blog -t content

Then we need to install the dependencies in the nuxt-demo-blog folder:

yarn install

Now we can start the Nuxt content app in development mode:

yarn dev

A browser window should automatically open for http://localhost:3000. Alternatively, you can start playing with Nuxt Content in your browser using StackBlitz or CodeSandbox.

The following StackBlitz sandbox demonstrates the simple blog application we create in this article:

Blog Content Structure

Our demo blog will have this structure inside the /content directory:

├── blog
│ ├── _index.md
│ ├── a-great-article
│ └── cover.jpg
│ │ └── index.md
│ └── another-great-article
│ └── cover.jpg
│ └── index.md

blog/_index.md is a Partial content that will show a list of all available blog posts.

Each blog post has its directory, including an index.md and a cover.jpg file.

The index.md files include Front-matter at the top of the file to provide meta-data to pages, like title, date, and the cover image URL:

---
title: A Great Article
date: 2018-05-11
cover: /content/blog/a-great-article/cover.jpg
---

This is a great article body!

Simple Navigation

First, we need simple navigation in our application to be able to navigate to our blog page.

Let’s start by adding a default layout in layouts:

<template>
  <div>
    <nav>
      <NuxtLink to="/" class="link">Home</NuxtLink>
      <NuxtLink to="/blog" class="link">Blog</NuxtLink>
    </nav>
    <main>
      <slot />
    </main>
  </div>
</template>

<style>
.link {
  margin-right: 1rem;
}
</style>

In our app.vue we need to wrap the NuxtPage component with the NuxtLayout component:

<template>
  <div>
    <NuxtLayout>
      <NuxtPage />
    </NuxtLayout>
  </div>
</template>

Finally, we create a index.vue in pages directory:

<template>
  <h1>Home</h1>
</template>

Home Page

Blog List

Let’s look at how we can implement a list of all available blog posts.

First, we need to create a BlogPosts.vue Vue component in components/content/ that queries and renders all available blog posts:

<template>
  <h1>Blog</h1>
  <ul>
    <li v-for="{ _path: slug, title } in blogPosts" :key="slug">
      <NuxtLink :to="slug">{{ title }}</NuxtLink>
    </li>
  </ul>
</template>

<script setup lang="ts">
const blogPosts = await queryContent('/blog')
  .sort({ date: -1 }) // show latest articles first
  .where({ _partial: false }) // exclude the Partial files
  .find();
</script>

We use the queryContent function from Nuxt to query a list of our blog posts.

Now we can reference this Vue component inside our content/blog/_index.md file:

---
title: Blog
---

::blog-posts

We can use any component in the components/content/ directory or any component made available globally in your application in Markdown files.

If we now click on the “Blog” navigation link in our application, we can see a list of all available blog posts:

Blog Post List

I reported a Nuxt content bug that you need to reload some routes; otherwise, their content is not visible.

Blog Post Page

Finally, we need to create a dynamic route for the blog posts. Thus, we create a [...slug].vue file in pages/blog:

<template>
  <ContentDoc
    :path="$route.params.slug ? `/blog/${$route.params.slug[0]}` : '/blog'"
  >
    <template #not-found>
      <h2>Blog slug ({{ $route.params.slug }}) not found</h2>
    </template>
  </ContentDoc>
</template>

We use the current slug in the route parameters ($route.params.slug) to determine whether we want to render the blog post list or an individual blog post.

We can now see the content of the corresponding blog post:

Blog Post

Conclusion

It’s effortless to create a Markdown file-based blog using Nuxt Content v2. This article demonstrates the basic steps to set up such a blog.

You can expect more Nuxt 3 posts in the following months as I plan to blog about interesting topics that I discover while rewriting my portfolio website.

If you liked this article, follow me on Twitter to get notified about new blog posts and more content from me.

Alternatively (or additionally), you can also subscribe to my newsletter.

Chrome Recorder: Record, Replay and Measure User Flows

Michael Hoffmann — Thu, 28 Apr 2022 09:01:52 +0000

Typically, a user needs to process multiple pages or steps to finish his journey, such as submitting an order or completing a registration. If we as developers need to develop one of the last pages of this user flow, we need to manually process all the previous pages/steps every time we refresh the page or need to restart the flow.

If multiple team members (also tester) have to do the same steps repeatedly, this costs a lot of time and, therefore, money. In previous projects, we often developed custom tools to proceed to certain pages/steps in the application automatically.

But now, the Chrome browser provides this functionality as a preview feature.

What is Chrome Recorder?

Chrome Recorder is a preview feature in the Chrome browser designed to record, replay and measure user flows of an application.

You can start a recording, execute the steps you’d like to record in the app (such as typing or clicking), and export the recording as JSON file, Puppeteer script or @puppeteer/replay script.

It’s then possible to replay the recorded user flow and measure the performance of the run.

Open Recorder

To find the Recorder, you first open up the Chrome DevTools.

Command+Option+C (Mac) or Control+Shift+C (Windows, Linux, ChromeOS).

You can open the Recorder from the options menu:

Open Chrome Recorder from options menu

Alternatively, you can open it from Command Menu:

Open Chrome Recorder from Command Menu

Record

I’ll be using Vue 3 Form Wizard to demonstrate the recording & replaying of a simple user flow.

The demo page provides a simple wizard with multiple steps containing common input types like text & select inputs.

Let’s start the recording:

Start Recording

The selector attribute textbox is optional. See Customize the recording’s selector.

Once you hit the record button, you can enter all data in the wizard. If you are done, hit the “End recording” button at the bottom of the recorder panel.

Recorded User Flow

The following GIF visualizes this process:

It’s also possible to manually edit the recorded steps. For example, you can manually change selectors:

Change Selector

Additionally, you can manually add or remove steps:

Add/Remove Steps

Replay

After recording a user flow, you can replay it by clicking on the “Replay” button.

When replaying a user flow recording, the Recorder waits until the element is visible or clickable in the viewport or tries to automatically scroll the element into the viewport before replaying the corresponding step.

It’s also possible to simulate a slow network connection in the “Replay” settings:

Simulate Slow Network

Measure performance

You can also measure the performance of your recording by clicking the “Measure performance” button. This way, you can regularly measure the performance of critical user flows.

Performance Panel

Conclusion

The Chrome Recorder is valuable tool that will boost my productivity during development. It’s still a preview feature, but I think it will become a must-have tool for web developers.

I recommend reading the official Chrome blog post.

If you liked this article, follow me on Twitter to get notified about new blog posts and more content from me.

Alternatively (or additionally), you can also subscribe to my newsletter.

Dark Mode Switch With Tailwind CSS & Nuxt 3

Michael Hoffmann — Mon, 21 Feb 2022 09:04:45 +0000

I am currently rewriting my portfolio website with Nuxt 3 which is still in beta. In this article, I want to show you how I implemented a dark mode switch in Nuxt 3 using Tailwind CSS that I will use in my new portfolio website.

Create Nuxt 3 project

To create a new Nuxt 3 project, we need to run this command in our terminal:

npx nuxi init nuxt3-app

Add Tailwind CSS 3

Next, we add the nuxt/tailwind module, which provides a prerelease version that supports Nuxt 3 and Tailwind CSS v3:

npm install --save-dev @nuxtjs/tailwindcss@5.0.0-4

Then we need to add this module to the buildModules section in nuxt.config.js:

import { defineNuxtConfig } from 'nuxt3';

// https://v3.nuxtjs.org/docs/directory-structure/nuxt.config
export default defineNuxtConfig({
  buildModules: ['@nuxtjs/tailwindcss'],});

Now, we can create the Tailwind configuration file tailwind.config.js by running the following command:

npx tailwindcss init

Let’s add a basic CSS file at ./assets/css/tailwind.css (see official docs for further configuration options):

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

.theme-light {
  --background: #f8f8f8;
  --text: #313131;
}

.theme-dark {
  --background: #313131;
  --text: #f8f8f8;
}

We define two CSS classes for the dark and light theme. CSS variables (indicated by --) are used to change CSS values based on the selected theme dynamically.

Therefore, we need to define these colors in our tailwind.conf.js:

module.exports = {
  content: [
    `components/**/*.{vue,js,ts}`,
    `layouts/**/*.vue`,
    `pages/**/*.vue`,
    `app.vue`,
    `plugins/**/*.{js,ts}`,
    `nuxt.config.{js,ts}`,
  ],
  theme: {
    extend: {
      colors: { themeBackground: 'var(--background)', themeText: 'var(--text)', }, },
  },
  plugins: [],
};

Implement Theme Switch

Let’s start to implement a theme switch by adding this simple template to our app.vue component:

<template>
  <div
    :class="{
      'theme-light': !darkMode,
      'theme-dark': darkMode,
    }"
    class="h-screen bg-themeBackground p-5"
  >
    <h1 class="text-themeText">Nuxt 3 Tailwind Dark Mode Demo</h1>
    <Toggle v-model="darkMode" off-label="Light" on-label="Dark" />
  </div>
</template>

On the div container element, we dynamically set theme-light or theme-dark CSS class based on the reactive darkMode variable value, which we will implement later in the script part of the component.

The h1 and container div elements use our Tailwind CSS classes bg-themeBackground and text-themeText to use theme-specific colors for the background and text color.

Additionally, we use the Vue 3 Toggle library to switch between our themes.

Let’s take a look at the script part of app.vue:

<script setup lang="ts">
import Toggle from '@vueform/toggle';
import { useState } from '#app';
import { onMounted, watch } from '@vue/runtime-core';

type Theme = 'light' | 'dark';

const LOCAL_STORAGE_THEME_KEY = 'theme';

const darkMode = useState('theme', () => false);

const setTheme = (newTheme: Theme) => {
  localStorage.setItem(LOCAL_STORAGE_THEME_KEY, newTheme);
  darkMode.value = newTheme === 'dark';
};

onMounted(() => {
  const isDarkModePreferred = window.matchMedia(
    '(prefers-color-scheme: dark)'
  ).matches;

  const themeFromLocalStorage = localStorage.getItem(
    LOCAL_STORAGE_THEME_KEY
  ) as Theme;

  if (themeFromLocalStorage) {
    setTheme(themeFromLocalStorage);
  } else {
    setTheme(isDarkModePreferred ? 'dark' : 'light');
  }
});

watch(darkMode, selected => {
  setTheme(selected ? 'dark' : 'light');
});
</script>

We store the selected theme value in Local Storage and use useState to define a reactive variable called darkMode:

const darkMode = useState('theme', () => false);

If the component is mounted, we first detect if the user has requested light or dark color theme by using the CSS media feature “prefers-color-scheme”:

const isDarkModePreferred = window.matchMedia(
  '(prefers-color-scheme: dark)'
).matches;

Then we set the theme value based on the local storage value:

const setTheme = (newTheme: Theme) => {
  localStorage.setItem(LOCAL_STORAGE_THEME_KEY, newTheme);
  darkMode.value = newTheme === 'dark';
};

onMounted(() => {
  const isDarkModePreferred = window.matchMedia(
    '(prefers-color-scheme: dark)'
  ).matches;

  const themeFromLocalStorage = localStorage.getItem( LOCAL_STORAGE_THEME_KEY ) as Theme; if (themeFromLocalStorage) { setTheme(themeFromLocalStorage); } else { setTheme(isDarkModePreferred ? 'dark' : 'light'); }});

This the complete app.vue component code:

<template>
  <div
    :class="{
      'theme-light': !darkMode,
      'theme-dark': darkMode,
    }"
    class="h-screen bg-themeBackground p-5"
  >
    <h1 class="text-themeText">Nuxt 3 Tailwind Dark Mode Demo</h1>
    <Toggle v-model="darkMode" off-label="Light" on-label="Dark" />
  </div>
</template>

<script setup lang="ts">
import Toggle from '@vueform/toggle';
import { useState } from '#app';
import { onMounted, watch } from '@vue/runtime-core';

type Theme = 'light' | 'dark';

const LOCAL_STORAGE_THEME_KEY = 'theme';

const darkMode = useState('theme', () => false);

const setTheme = (newTheme: Theme) => {
  localStorage.setItem(LOCAL_STORAGE_THEME_KEY, newTheme);
  darkMode.value = newTheme === 'dark';
};

onMounted(() => {
  const isDarkModePreferred = window.matchMedia(
    '(prefers-color-scheme: dark)'
  ).matches;

  const themeFromLocalStorage = localStorage.getItem(
    LOCAL_STORAGE_THEME_KEY
  ) as Theme;

  if (themeFromLocalStorage) {
    setTheme(themeFromLocalStorage);
  } else {
    setTheme(isDarkModePreferred ? 'dark' : 'light');
  }
});

watch(darkMode, selected => {
  setTheme(selected ? 'dark' : 'light');
});
</script>

<style src="@vueform/toggle/themes/default.css"></style>

Now we can use run the following command to start our Nuxt app in development mode:

npm run dev

Finally, we can test our dark mode theme switch at http://localhost:3000:

StackBlitz Demo

My simple demo is available as interactive StackBlitz demo:

Alternatively, you could also use the color-mode module that supports Nuxt Bridge and Nuxt 3.

Conclusion

This article showed you how to create a simple dark mode switch in Nuxt 3 with Tailwind CSS v3. You can expect more Nuxt 3 posts in the following months as I plan to blog about interesting topics that I discover while I rewrite my portfolio website.

If you liked this article, follow me on Twitter to get notified about new blog posts and more content from me.

Alternatively (or additionally), you can also subscribe to my weekly Vue.js newsletter.

Building a Vue 3 Desktop App With Pinia, Electron and Quasar

Michael Hoffmann — Mon, 14 Feb 2022 18:48:04 +0000

Recently, I planned to rewrite my “Scrum Daily Standup Picker” Electron application in Vue 3. I wrote the initial release in Angular, but I wanted to refactor the code base and rewrite it in Vue 3.

Why? Because I love Vue and want to have a public showcase that I can reference to potential customers.

Why Quasar?

Quasar is an MIT licensed open-source Vue.js based framework that targets SPA, SSR, PWA, mobile app, desktop app, and browser extension all using one codebase. It handles the build setup and provides a complete collection of Material Design compliant UI components.

Quasar’s motto is:

Write code once and simultaneously deploy it as a website, a Mobile App and/or an Electron App.

Using Quasar drastically saves development time due to these reasons:

It’s based on Vue.js.
It provides many UI components that follow Material Design guidelines.
It has a regular release cycle inclusive of new features.
It provides support for each build mode (SPA, SSR, PWA, Mobile app, Desktop app & Browser Extension).
It has its own CLI that provides a pleasant developer experience. For example, we can build our application as SPA, mobile, or desktop app within the same project folder.

Read more about why Quasar might be a good choice for your next project.

Install Quasar CLI

The source code for the following demo is available at GitHub

# Node.js >=12.22.1 is required.

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

Let’s start by creating a new project using the Quasar CLI:

▶ quasar create vue3-electron-demo

  ___
 / _ \ _ _ ______  ___ ___
| | | | | | |/ _` / __|/ _` | '__ |
| |_| | |_| | (_| \__ \ (_| | |
 \ __\_\\__ ,_|\ __,_|___ /\__,_|_|

? Project name (internal usage for dev) vue3-electron-demo
? Project product name (must start with letter if building mobile apps) Quasar App
? Project description A Quasar Framework app
? Author Michael Hoffmann <michael.hoffmann@mokkapps.de>
? Pick your CSS preprocessor: SCSS
? Check the features needed for your project: ESLint (recommended), TypeScript
? Pick a component style: Composition
? Pick an ESLint preset: Prettier
? Continue to install project dependencies after the project has been created? (recommended) NPM

We chose SCSS as our CSS preprocessor, ESLint & Typescript as additional features, Vue 3’s Composition API and Prettier for code formatting.

Do not choose Vuex as we will add another state library in the next chapter. If you accidentally added Vuex, remove it manually from your package.json.

Read the official docs for additional information about the Quasar CLI.

Add Pinia as Vue store library

We’ll use Pinia as Vue store library, which is now the recommended state library for Vue.

First, we need to install Pinia:

yarn add pinia
# or with npm
npm install pinia

To be able to register Pinia at our Vue application instance we need to create a Quasar Boot File:

A common use case for Quasar applications is to run code before the root Vue app instance is instantiated, like injecting and initializing your own dependencies (examples: Vue components, libraries…) or simply configuring some startup code of your app.

Our boot file is called pinia.ts and is located at src/boot:

import { boot } from 'quasar/wrappers';
import { createPinia } from 'pinia';

export default boot(({ app }) => {
  app.use(createPinia());
});

We also need to add this new file to quasar.conf.js:

module.exports = configure(function (ctx) {
  return {
    ...
    // app boot file (/src/boot)
    // --> boot files are part of "main.js"
    // https://quasar.dev/quasar-cli/boot-files
    boot: ['pinia'], ...
  }
}

Now, we can create a new folder called pinia in src.

We cannot name this folder store as this name is reserved for the official Vuex integration.

A basic store could look like this:

import { defineStore } from 'pinia';

// useStore could be anything like useUser, useCart
// the first argument is a unique id of the store across your application
const useStore = defineStore('storeId', {
  state: () => {
    return {
      counter: 0,
      lastName: 'Michael',
      firstName: 'Michael',
    };
  },
  getters: {
    fullName: state => `${state.firstName} ${state.lastName}`,
  },
  actions: {
    increment() {
      this.counter++;
    },
  },
});

export default useStore;

We can use this store in any Vue component:

<template>Counter: {{ store.counter }}</template>

<script setup lang="ts">
import { useStore } from '@/stores/counter';

const store = useStore();
</script>

Now we can run the Vue application using the Quasar CLI:

quasar dev

The Vue application is served at http://localhost:8080:

Quasar Dev Mode

Setup Electron

Read this introduction if you are new to Electron.

To develop/build a Quasar Electron app, we need to add the Electron mode to our Quasar project:

$ quasar mode add electron

Every Electron app has two threads: the main thread (deals with the window and initialization code – from the newly created folder /src-electron) and the renderer thread (which deals with the actual content of your app from /src).

The new folder has the following structure:

.
└── src-electron/
├── icons/ # Icons of your app for all platforms
| ├── icon.icns # Icon file for Darwin (MacOS) platform
| ├── icon.ico # Icon file for win32 (Windows) platform
| └── icon.png # Tray icon file for all platforms
├── electron-preload.js # (or .ts) Electron preload script (injects Node.js stuff into renderer thread)
└── electron-main.js # (or .ts) Main thread code

Now we are ready to start our Electron application:

$ quasar dev -m electron

This command will open up an Electron window which will render your app along with Developer Tools opened side by side:

Quasar Electron Dev

Read the official docs for additional and detailed information about developing Electron apps with Quasar.

Control Electron from Vue code

If we want to use Electron features like opening a file dialog, we need to write some code to be able to access Electron’s API.

For example, if we want to show a dialog to open files, Electron provides the dialog API to display native system dialogs for opening and saving files, alerting, etc.

First, we need to install @electron/remote:

npm install -D @electron/remote

Then we need to modify src-electron/electron-main.js and initialize @electron/remote:

import { app, BrowserWindow, nativeTheme } from 'electron'
import { initialize, enable } from '@electron/remote/main'import path from 'path'
import os from 'os'

initialize();
let mainWindow;

function createWindow () {
  /**
   * Initial window options
   */
  mainWindow = new BrowserWindow({
    icon: path.resolve(__dirname, 'icons/icon.png'), // tray icon
    width: 1000,
    height: 600,
    useContentSize: true,
    webPreferences: {
      contextIsolation: true,
      // More info: /quasar-cli/developing-electron-apps/electron-preload-script
      preload: path.resolve(__dirname, process.env.QUASAR_ELECTRON_PRELOAD)
    }
  })

  // ....

  enable(mainWindow.webContents);}

If we want to use Electron API from our Vue code we need to add some code to src-electron/electron-preload.js:

import { contextBridge } from 'electron';
import { dialog } from '@electron/remote';
// 'electronApi' will be available on the global window context
contextBridge.exposeInMainWorld('electronApi', {
  openFileDialog: async (title, folder, filters) => {
    // calling showOpenDialog from Electron API: https://www.electronjs.org/docs/latest/api/dialog/
    const response = await dialog.showOpenDialog({ title, filters, properties: ['openFile', 'multiSelections'], }); return response.filePaths;
  }
});

Next we create src/api/electron-api.ts to access this code from within our Vue application:

export interface ElectronFileFilter {
  name: string;
  extensions: string[];
}

export interface ElectronApi {
  openFileDialog: (
    title: string,
    folder: string,
    filters: ElectronFileFilter
  ) => Promise<string[]>;
}

// eslint-disable-next-line @typescript-eslint/ban-ts-comment
// @ts-ignore
export const electronApi: ElectronApi = (window as { electronApi: ElectronApi })
  .electronApi;

Now we can use this API anywhere in our Vue component:

<template>
  <q-btn @click="openElectronFileDialog">Open Electron File Dialog</q-btn>
</template>

<script lang="ts">
import { defineComponent } from 'vue';
import { electronApi } from 'src/api/electron-api';

export default defineComponent({
  name: 'PageIndex',
  components: { },
  setup() {
    const openElectronFileDialog = async () => {
      return electronApi.openFileDialog('Test', 'folder', { name: 'images', extensions: ['jpg'] });
    };

    return { openElectronFileDialog };
  },
});
</script>

Clicking on the button should now open the native OS file dialog:

Electron File Dialog

Conclusion

Quasar allows us to quickly develop Electron desktop applications in Vue with high-quality UI components that follow Material Design guidelines.

The most significant advantage against a custom Electron + Vue boilerplate project from GitHub is that Quasar has a regular release cycle and provides upgrade guides for older versions.

Take a look at my “Scrum Daily Standup Picker” GitHub repository to see a more complex “Quasar-Electron-Vue3-Typescript-Pinia” project. The demo source code for the following demo is available at GitHub.

If you liked this article, follow me on Twitter to get notified about new blog posts and more content from me.

Alternatively (or additionally), you can also subscribe to my newsletter.

The 10 Favorite Features of My Developer Portfolio Website

Michael Hoffmann — Tue, 04 Jan 2022 10:44:10 +0000

Inspired by Braydon Coyer’s new blogfolio, I’ve added some excellent new features to my portfolio website.

In this article, I want to demonstrate the ten favorite features of my blogfolio.

1. Stats page
2. Article Reactions
3. Automated Open Graph Images
4. Mark Article as Read
5. Intelligent Article Suggestions
6. Article Search Options
7. Prism Code Highlighting
8. MDX
9. Generate Scripts
10. Open Source Analytics
Conclusion

1. Stats page

Inspired by SLD and Braydon Coyer, I’ve added a Stats page on my site.

It shows statistics about the site itself, for example, how many active visitors are currently on the site and how many have visited it in total.

Additionally, it shows some information about my social media channels like the follower count of GitHub, Twitter, Dev.to, and more.

I use AWS Amplify Serverless Functions to access a variety of APIs to provide the necessary data for this site.

2. Article Reactions

Built with Supabase and AWS Amplify Serverless Functions, readers of my articles can now react to the article with the clap emoji.

Additionally, I use the same database table to store the number of page views.

3. Automated Open Graph Images

I use Braydon’s approach to automatically generate Open Graph images for certain pages using the Cloudinary API.

The code grabs the site’s title and generates an Open Graph image using Cloudinary API.

The following image shows such an automatically generated image that I use on my website:

4. Mark Article as Read

Visitors of my website can see at a glimpse which articles they’ve already read. It’s a nice little feature for recurring readers of my blog.

5. Intelligent Article Suggestions

If a reader of a blog article reaches the end of the article, he will see four similar articles. They are selected by checking how many categories match between the articles.

6. Article Search Options

I provide multiple ways to search for blog articles:

All articles are available on the blog page, and you can scroll or use the browser search to find an article.
Use the minimal list, which shows all blog posts grouped in years by title.
Use Google.

7. Prism Code Highlighting

I invested some time to create beautiful code snippets on my blog posts, as they are an essential part of my articles.

I use Prism with the Gatsby Prism Remark plugin to show code blocks in my markdown files:

export const getCategoryDisplayText = category => {
  if (category === 'aws') { return category.toUpperCase(); }
  if (category.includes('-js')) {
    const name = category.split('-')[0];
    return `${capitalize(name)}.js`;
  }

  return capitalize(category);
};

I can highlight certain lines of code, and I show the programming language as a nice badge on the top right.

8. MDX

MDX is very powerful, and I use it for my tips page, where I inject the following React component into my Markdown files to create a beautiful comparison of two code blocks:

9. Generate Scripts

Inspired by Kent C. Dodds, I use multiple JS scripts to generate boilerplate files for new blog posts and tips.

For example, the blogpost.js script will generate a similar output in the console:

? Title this is a test to see if my script is awesome
? Categories development, career, tools
? Release Date (format: yyyy-mm-dd) 2022-01-08
? Dry run without creating files? (default: false) Yes

Date:
2022-01-08

Slug:
this-is-a-test-to-see-if-my-script-is-awesome

Markdown data:
---
title: "This Is a Test to See if My Script Is Awesome"
categories:
  - "development"
  - "career"
  - "tools"
cover: "images/cover.jpg"
---

## Conclusion

If you liked this article, follow me on [Twitter](https://twitter.com/mokkapps) to get notified about new blog posts and more content from me.

Alternatively (or additionally), you can also [subscribe to my newsletter](https://mokkapps.de/newsletter).

The script asks for some mandatory information, converts the entered title to title caps, and finally generates the markdown file with the slug name at the correct directory.

Additionally, I have a script to generate a Table of Content (ToC) for a finished article and an image optimization script.

10. Open Source Analytics

I use Umami with a database hosted on Digital Ocean. I send custom events if a visitor, for example, clicks a social link, subscribes to the newsletter or, edits an article on GitHub. These events provide some valuable insights into how many visitors are using the features on my portfolio website.

Conclusion

My portfolio website is my favorite digital playground. I love to experiment with different new features and try to provide the best possible experience for visitors.

The source code of my website is available on GitHub, so feel free to take a closer look if you are interested in implementation details. Leave a comment if you want more information about a specific topic.

If you liked this article, follow me on Twitter to get notified about new blog posts and more content from me.

Alternatively (or additionally), you can also subscribe to my newsletter.

How I Built a Twitter Keyword Monitoring Using a Serverless Node.js Function With AWS Amplify

Michael Hoffmann — Wed, 15 Dec 2021 09:32:19 +0000

In this article, I will demonstrate to you how I built a simple serverless Node.js function on AWS that sends me a daily email with a list of tweets that mention me on Twitter.

Recently, I used Twilert and Birdspotter for that purpose, which are specialized tools for Twitter keyword monitoring. But their free plans/trials don’t fulfill my simple requirements, so I decided to implement them independently.

Prerequisites

I chose again AWS Amplify to deploy the serverless function to AWS.

If you don’t already have an AWS account, you’ll need to create one to follow the steps outlined in this article. Please follow this tutorial to create an account.

Next, you need to install and configure the Amplify Command Line Interface (CLI).

The serverless function will need access to secrets stored in the AWS Secret Manager. My article “How to Use Environment Variables to Store Secrets in AWS Amplify Backend” will guide you through this process.

Add Serverless Function to AWS

The first step is to add a new Lambda (serverless) function with the Node.js runtime to the Amplify application.

The function gets invoked on a recurring schedule. In my case, it will be invoked every day at 08:00 PM.

Let’s add the serverless function using the Amplify CLI:

▶ amplify add function
? Select which capability you want to add: Lambda function (serverless function)
? Provide an AWS Lambda function name: twittersearchfunction
? Choose the runtime that you want to use: NodeJS
? Choose the function template that you want to use: Hello World
? Do you want to configure advanced settings? Yes
? Do you want to access other resources in this project from your Lambda function? No
? Do you want to invoke this function on a recurring schedule? Yes
? At which interval should the function be invoked: Daily
? Select the start time (use arrow keys): 08:00 PM
? Do you want to enable Lambda layers for this function? No
? Do you want to configure environment variables for this function? No
? Do you want to configure secret values this function can access? No
? Do you want to edit the local lambda function now? No

Get a list of tweets for a specific Twitter keyword

Now it’s time to write the JavaScript code that returns a list of tweets for a given keyword.

Let’s start by writing the twitter-client.js module. This module uses FeedHive’s Twitter Client to access the Twitter API. The first step is to initialize the Twitter API client and trigger the request:

const mokkappsTwitterId = 481186762;
const searchQuery = 'mokkapps';
const searchResultCount = 100;

const fetchRecentTweets = async secretValues => {
  // Configure Twitter API Client
  const twitterClient = new twitterApiClient.TwitterClient({
    apiKey: secretValues.TWITTER_API_KEY,
    apiSecret: secretValues.TWITTER_API_KEY_SECRET,
    accessToken: secretValues.TWITTER_ACCESS_TOKEN,
    accessTokenSecret: secretValues.TWITTER_ACCESS_TOKEN_SECRET,
  });

  // Trigger search endpoint: https://github.com/FeedHive/twitter-api-client/blob/main/REFERENCES.md#twitterclienttweetssearchparameters
  const searchResponse = await twitterClient.tweets.search({
    q: searchQuery,
    count: searchResultCount,
    result_type: 'recent',
  });

  // Access statuses from response
  const statuses = searchResponse.statuses;
};

Next, we want to filter the response into three groups:

Tweets: Tweets from the last 24 hours that were not published by my Twitter account and are no replies or retweets
Replies: Tweets from the last 24 hours that were not published by my Twitter account and are replies
Retweets: Tweets from the last 24 hours that were not published by my Twitter account and are retweets

Let’s start by the filtering the statuses response for “normal” tweets that are no replies or retweets:

const isTweetedInLast24Hours = status => {
  const tweetDate = new Date(status.created_at);
  const now = new Date();
  const timeDifference = now.getTime() - tweetDate.getTime();
  const daysDifference = timeDifference / (1000 * 60 * 60 * 24);
  return daysDifference <= 1;
};

const fetchRecentTweets = async secretValues => {
  // ...
  const statuses = searchResponse.statuses;

  const tweets = statuses.filter(status => { const isNotOwnAccount = status.user.id !== mokkappsTwitterId; const isNoReply = status.in_reply_to_status_id === null; const isNoRetweet = status.retweeted_status === null; return ( isNotOwnAccount && isNoReply && isNoRetweet && isTweetedInLast24Hours(status) ); });};

Now we can filter for retweets and replies in a similar way:

const retweets = statuses.filter(status => {
  const isNotOwnAccount = status.user.id !== mokkappsTwitterId;
  const isRetweet = status.retweeted_status;
  return isNotOwnAccount && isRetweet && isTweetedInLast24Hours(status);
});

const replies = statuses.filter(status => {
  const isNotOwnAccount = status.user.id !== mokkappsTwitterId;
  const isReply = status.in_reply_to_status_id !== null;
  return isNotOwnAccount && isReply && isTweetedInLast24Hours(status);
});

The last step is to map the results to a very simple HTML structure that will be rendered inside the email body:

const { formatDistance } = require('date-fns');

const mapStatus = status => {
  const {
    id_str: id,
    created_at,
    in_reply_to_screen_name,
    in_reply_to_status_id_str,
    text,
    retweet_count,
    favorite_count,
    user: {
      screen_name: user_screen_name,
      followers_count,
      created_at: userCreatedAt,
      friends_count,
    },
  } = status;
  const createdAtLocaleString = new Date(created_at).toLocaleString();
  const url = `https://twitter.com/${user_screen_name}/status/${id}`;
  const userUrl = `https://twitter.com/${user_screen_name}`;
  const originalUrl = in_reply_to_screen_name
    ? `https://twitter.com/${in_reply_to_screen_name}/status/${in_reply_to_status_id_str}`
    : null;
  const userCreatedDateDistance = formatDistance(
    new Date(),
    new Date(userCreatedAt)
  );

  return `
    <div style="margin-bottom: 20px; padding: 10px; border: 1px solid gray; border-radius: 5px;">
      <h2>From <a href=${userUrl}>${user_screen_name}</a> at ${createdAtLocaleString}</h2>
      <small><strong>Followers:</strong> ${followers_count}, <strong>Following:</strong> ${friends_count}, <strong>Account Created:</strong> ${userCreatedDateDistance} ago</small>
      <h3>${text}</h3>
      <a href=${url} style="margin-top: 10px">Tweet</a>
      <small style="margin-top: 5px">(<strong>Likes:</strong> ${favorite_count}, <strong>Retweets: ${retweet_count})</strong></small>
      ${
        originalUrl
          ? `<div style="margin-top: 10px"></br><a href=${originalUrl}>Original Tweet</a></div>`
          : ''
      }
    </div>
    `;
};

const fetchRecentTweets = async secretValues => {
  // ...
  const retweets = statuses
    .filter(status => {
      const isNotOwnAccount = status.user.id !== mokkappsTwitterId;
      const isRetweet = status.retweeted_status;
      return isNotOwnAccount && isRetweet && isTweetedInLast24Hours(status);
    })
    .map(status => mapStatus(status));};

This is the code for the whole twitter-client.js module:

const twitterApiClient = require('twitter-api-client');
const { formatDistance } = require('date-fns');

const mokkappsTwitterId = 481186762;
const searchQuery = 'mokkapps';
const searchResultCount = 100;

const mapStatus = status => {
  const {
    id_str: id,
    created_at,
    in_reply_to_screen_name,
    in_reply_to_status_id_str,
    text,
    retweet_count,
    favorite_count,
    user: {
      screen_name: user_screen_name,
      followers_count,
      created_at: userCreatedAt,
      friends_count,
    },
  } = status;
  const createdAtLocaleString = new Date(created_at).toLocaleString();
  const url = `https://twitter.com/${user_screen_name}/status/${id}`;
  const userUrl = `https://twitter.com/${user_screen_name}`;
  const originalUrl = in_reply_to_screen_name
    ? `https://twitter.com/${in_reply_to_screen_name}/status/${in_reply_to_status_id_str}`
    : null;
  const userCreatedDateDistance = formatDistance(
    new Date(),
    new Date(userCreatedAt)
  );

  return `
    <div style="margin-bottom: 20px; padding: 10px; border: 1px solid gray; border-radius: 5px;">
      <h2>From <a href=${userUrl}>${user_screen_name}</a> at ${createdAtLocaleString}</h2>
      <small><strong>Followers:</strong> ${followers_count}, <strong>Following:</strong> ${friends_count}, <strong>Account Created:</strong> ${userCreatedDateDistance} ago</small>
      <h3>${text}</h3>
      <a href=${url} style="margin-top: 10px">Tweet</a>
      <small style="margin-top: 5px">(<strong>Likes:</strong> ${favorite_count}, <strong>Retweets: ${retweet_count})</strong></small>
      ${
        originalUrl
          ? `<div style="margin-top: 10px"></br><a href=${originalUrl}>Original Tweet</a></div>`
          : ''
      }
    </div>
    `;
};

const isTweetedInLast24Hours = status => {
  const tweetDate = new Date(status.created_at);
  const now = new Date();
  const timeDifference = now.getTime() - tweetDate.getTime();
  const daysDifference = timeDifference / (1000 * 60 * 60 * 24);
  return daysDifference <= 1;
};

const fetchRecentTweets = async secretValues => {
  const twitterClient = new twitterApiClient.TwitterClient({
    apiKey: secretValues.TWITTER_API_KEY,
    apiSecret: secretValues.TWITTER_API_KEY_SECRET,
    accessToken: secretValues.TWITTER_ACCESS_TOKEN,
    accessTokenSecret: secretValues.TWITTER_ACCESS_TOKEN_SECRET,
  });

  const searchResponse = await twitterClient.tweets.search({
    q: searchQuery,
    count: searchResultCount,
    result_type: 'recent',
  });

  const statuses = searchResponse.statuses;

  const tweets = statuses
    .filter(status => {
      const isNotOwnAccount = status.user.id !== mokkappsTwitterId;
      const isNoReply = status.in_reply_to_status_id === null;
      const isNoRetweet = status.retweeted_status === null;
      return (
        isNotOwnAccount &&
        isNoReply &&
        isNoRetweet &&
        isTweetedInLast24Hours(status)
      );
    })
    .map(status => mapStatus(status));

  const retweets = statuses
    .filter(status => {
      const isNotOwnAccount = status.user.id !== mokkappsTwitterId;
      const isRetweet = status.retweeted_status;
      return isNotOwnAccount && isRetweet && isTweetedInLast24Hours(status);
    })
    .map(status => mapStatus(status));

  const replies = statuses
    .filter(status => {
      const isNotOwnAccount = status.user.id !== mokkappsTwitterId;
      const isReply = status.in_reply_to_status_id !== null;
      return isNotOwnAccount && isReply && isTweetedInLast24Hours(status);
    })
    .map(status => mapStatus(status));

  return {
    tweets,
    retweets,
    replies,
  };
};

module.exports = fetchRecentTweets;

Serverless function code

We can now use the twitter-client.js in our serverless function:

const AWS = require('aws-sdk');
const nodemailer = require('nodemailer');
const fetchRecentTweets = require('./twitter-client');

const secretsManager = new AWS.SecretsManager();
const responseHeaders = {
  'Content-Type': 'application/json'
};

exports.handler = async event => {
  console.log(`👷 Function is ready to search for tweets`);

  const secretData = await secretsManager
    .getSecretValue({ SecretId: 'YOUR_SECRET_ID' })
    .promise();
  const secretValues = JSON.parse(secretData.SecretString);

  const transporter = nodemailer.createTransport({
    service: secretValues.MAIL_HOST,
    auth: {
      user: secretValues.MAIL_USER,
      pass: secretValues.MAIL_PW,
    },
  });

  const defaultMailOptions = {
    from: secretValues.MAIL_USER,
    to: secretValues.MAIL_SUCCESS,
    subject: `[Mokkapps API] Twitter Search Results`,
  };

  try {
    // Fetch recent tweets
    const { tweets, replies, retweets } = await fetchRecentTweets(secretValues);

    // Skip sending email if we have no results
    if (tweets.length === 0 && replies.length === 0 && retweets.length === 0) {
      return {
        statusCode: 200,
        headers: responseHeaders,
        body: [],
      };
    }

    // Send email
    await transporter.sendMail({
      ...defaultMailOptions,
      html: `
        <h1>Tweets that mentioned "mokkapps" in the last 24 hours</h1>
        ${tweets.length === 0 ? '<p>No results</p>' : tweets.join('')}
        <h1>Replies that mentioned "mokkapps" in the last 24 hours</h1>
        ${replies.length === 0 ? '<p>No results</p>' : replies.join('')}
        <h1>Retweets that mentioned "mokkapps" in the last 24 hours</h1>
        ${retweets.length === 0 ? '<p>No results</p>' : retweets.join('')}
      `,
    });

    return {
      statusCode: 200,
      headers: responseHeaders,
      body: JSON.stringify({ tweets, replies, retweets }),
    };
  } catch (e) {
    console.error('☠ Twitter Search Function Error:', e);
    return {
      statusCode: 500,
      headers: responseHeaders,
      body: e.message ? e.message : JSON.stringify(e),
    };
  }
};

At this point, we can publish our function by running:

amplify push

If we successfully pushed the function to AWS, we can manually invoke the function in AWS Lamba by clicking the “Test” button:

AWS Lambda Function Test

The serverless function should then send an email with a list of tweets if someone mentioned the monitored keyword in the last 24 hours:

Email sent from serverless Node.js function

Conclusion

I had a lot of fun building this simple serverless function to monitor keywords on Twitter.

Serverless functions are a perfect choice for such a monitoring tool, as we only have to pay for the execution time of the serverless function.

What do you think about my solution? Leave a comment and tell me how you monitor your Twitter keywords.

If you liked this article, follow me on Twitter to get notified about new blog posts and more content from me.

Alternatively (or additionally), you can also subscribe to my newsletter.

Document & Test Vue 3 Components With Storybook

Michael Hoffmann — Mon, 15 Nov 2021 12:36:55 +0000

Storybook is my tool of choice for UI component documentation. Vue.js is very well supported in the Storybook ecosystem and has first-class integrations with Vuetify and NuxtJS. It also has official support for Vue 3, the latest major installment of Vue.js.

This article will demonstrate how you can set up Storybook with zero-config and built-in TypeScript support, auto-generate controls & documentation, and perform automated snapshot tests for your Vue components.

Why Storybook?

We have components that can have many props, states, slots, etc., which influences its visual representation and more.

This circumstance causes some typical problems for any front-end developer:

How can I create documentation for my component that doesn’t get outdated?
How can I get an overview of all different states and kinds of my component?
How can I guarantee that my changes don’t influence other states and kinds?
How can I show the current implementation to non-developer team members?

Storybook will help us here.

Storybook Setup

First, we need to create a Vue 3 application. We’ll use Vite, a new build tool from Evan You, the creator of Vue.js:

npm init vite@latest

Setting up Storybook in an existing Vue 3 project can be done with zero configuration:

npx sb init

This command installs Storybook with its dependencies, configures the Storybook instance, and generates some demo components and stories which are located at src/stories:

Storybook Vue 3 Generated Files

We can now run the following command, which starts a local development server for Storybook and automatically opens it in a new browser tab:

npm run storybook

Storybook Vue 3 Demo

These generated Vue components and stories are good examples of how to write Vue 3 stories. I want to show you some advanced documentation examples using a custom component.

Custom Component Demo

I created a Counter.vue demo component to demonstrate the Storybook integration for this article. The source code is available at GitHub.

The component provides basic counter functionality, has two different visual variants and two slots for custom content.

Let’s take a look at the component’s code:

<template>
  <p>{{ label }}</p>
  <!-- @slot Slot to show content below label --> <slot name="sub-label" />
  <div class="container" :class="variant">
    <button @click="increment()">+</button>
    <p class="value">{{ count }}</p>
    <button @click="decrement()">-</button>
  </div>
  <!-- @slot Default slot to show any content below the counter --> <slot />
</template>

<script lang="ts">
import { ref, watch, PropType } from 'vue';
import { Variant } from './types';

/** * This is my amazing counter component * * It can increment and decrement! */export default {
  props: {
    /** * The initial value for the counter */ initialValue: {
      type: Number,
      default: 0,
    },
    /** * Text shown above the counter */ label: {
      type: String,
      default: 'Counter',
    },
    /** * If true, the counter can show negative numbers */ allowNegativeValues: {
      type: Boolean,
      default: false,
    },
    /** * Defines the visual appearance of the counter */ variant: {
      type: String as PropType<Variant>,
      default: Variant.Default,
    },
  },
  emits: ['counter-update'],
  setup(props, context) {
    const count = ref(props.initialValue);

    const increment = () => {
      count.value += 1;
    };

    const decrement = () => {
      const newValue = count.value - 1;
      if (newValue < 0 && !props.allowNegativeValues) {
        count.value = 0;
      } else {
        count.value -= 1;
      }
    };

    watch(count, value => {
      context.emit('counter-update', value);
    });

    return {
      count,
      increment,
      decrement,
    };
  },
};
</script>
<style scoped></style>

In the above code, you can see that I’ve annotated the Vue component with JSDoc comments. Storybook converts them into living documentation alongside our stories.

Unfortunately, I found no way to add JSDoc comments to the counter-update event. I think it is currently not supported in vue-docgen-api, which Storybook uses under the hood to extract code comments into descriptions. Leave a comment if you know a way how to document events in Vue 3.

Storybook uses so-called stories:

A story captures the rendered state of a UI component. Developers write multiple stories per component that describe all the “interesting” states a component can support.

A component’s stories are defined in a story file that lives alongside the component file. The story file is for development-only, it won’t be included in your production bundle.

Now, let’s take a look at the code of our Counter.stories.ts:

import Counter from './Counter.vue';
import { Variant } from './types';

//👇 This default export determines where your story goes in the story list
export default {
  title: 'Counter',
  component: Counter,
  //👇 Creates specific argTypes with options
  argTypes: {
    variant: {
      options: Variant,
    },
  },
};

//👇 We create a “template” of how args map to rendering
const Template = args => ({
  components: { Counter },
  setup() {
    //👇 The args will now be passed down to the template
    return { args };
  },
  template: '<Counter v-bind="args">{{ args.slotContent }}</Counter>',
});

//👇 Each story then reuses that template
export const Default = Template.bind({});
Default.args = {
  label: 'Default',
};

export const Colored = Template.bind({});
Colored.args = {
  label: 'Colored',
  variant: Variant.Colored,
};

export const NegativeValues = Template.bind({});
NegativeValues.args = {
  allowNegativeValues: true,
  initialValue: -1,
};

export const Slot = Template.bind({});
Slot.args = {
  slotContent: 'SLOT CONTENT',
};

This code is written in Component Story Format and generates four stories:

Default: The counter component in its default state
Colored: The counter component in the colored variation
NegativeValue: The counter component that allows negative values
Slot: The counter component with a slot content

Let’s take a look at our living documentation in Storybook:

As already mentioned, Storybook converts the JSDoc comments from our code snippet above into documentation, shown in the following picture:

Storybook Generated Docs

Testing

Now that we have our living documentation in Storybook run tests against them.

Jest Setup

I chose Jest as the test runner. It has a fast & straightforward setup process and includes a test runner, an assertion library, and a DOM implementation to mount our Vue components.

To install Jest in our existing Vue 3 + Vite project, we need to run the following command:

npm install jest @types/jest ts-jest vue-jest@next @vue/test-utils@next --save-dev

Then we need to create a jest.config.js config file in the root directory:

module.exports = {
  moduleFileExtensions: ['js', 'ts', 'json', 'vue'],
  transform: {
    '^.+\\.ts$': 'ts-jest',
    '^.+\\.vue$': 'vue-jest',
  },
  collectCoverage: true,
  collectCoverageFrom: ['/src/**/*.vue'],
};

The next step is to add a script that executes the tests in our package.json:

"scripts": {
  "test": "jest src"
}

Unit testing with Storybook

Unit tests help verify functional aspects of components. They prove that the output of a component remains the same given a fixed input.

Let’s take a look at a simple unit test for our Storybook story:

import { mount } from '@vue/test-utils';

import Counter from './Counter.vue';

//👇 Imports a specific story for the test
import { Colored, Default } from './Counter.stories';

it('renders default button', () => {
  const wrapper = mount(Counter, {
    propsData: Default.args,
  });
  expect(wrapper.find('.container').classes()).toContain('default');
});

it('renders colored button', () => {
  const wrapper = mount(Counter, {
    propsData: Colored.args,
  });
  expect(wrapper.find('.container').classes()).toContain('colored');
});

We wrote two exemplary unit tests Jest executes against our Storybook story Counter.stories.ts:

renders default button: asserts that the component container contains the CSS class default
renders colored button: asserts that the component container contains the CSS class colored

The test result looks like this:

 PASS src/components/Counter.test.ts
  ✓ renders default button (25 ms)
  ✓ renders colored button (4 ms)

----------|---------|----------|---------|---------|-------------------
File | % Stmts | % Branch | % Funcs | % Lines | Uncovered Line #s
----------|---------|----------|---------|---------|-------------------
All files | 0 | 0 | 0 | 0 |
----------|---------|----------|---------|---------|-------------------
Test Suites: 1 passed, 1 total
Tests: 2 passed, 2 total
Snapshots: 0 total
Time: 3.674 s, estimated 4 s

Snapshot Testing

Snapshot tests compare the rendered markup of every story against known baselines. It’s an easy way to identify markup changes that trigger rendering errors and warnings.

A snapshot test renders the markup of our story, takes a snapshot, and compares it to a reference snapshot file stored alongside the test.

The test case will fail if the two snapshots do not match. There are two typical causes why a snapshot test fails:

The change is expected
The reference snapshot needs to be updated

We can use Jest Snapshot Testing as Jest library for snapshot tests.

Let’s install it by running the following command:

npm install --save-dev jest-serializer-vue

Next, we need to add it as snapshotSerializers to our jest.config.js config file:

module.exports = {
  moduleFileExtensions: ['js', 'ts', 'json', 'vue'],
  transform: {
    '^.+\\.ts$': 'ts-jest',
    '^.+\\.vue$': 'vue-jest',
  },
  collectCoverage: true,
  collectCoverageFrom: ['/src/**/*.vue'],
  snapshotSerializers: ['jest-serializer-vue'],};

Finally, we can write a snapshot test for Storybook story:

it('renders snapshot', () => {
  const wrapper = mount(Counter, {
    propsData: Colored.args,
  });
  expect(wrapper.element).toMatchSnapshot();
});

If we now run our tests, we get the following result:

> vite-vue-typescript-starter@0.0.0 test
> jest src

 PASS src/components/Counter.test.ts
  ✓ renders default button (27 ms)
  ✓ renders colored button (4 ms)
  ✓ renders snapshot (6 ms)

----------|---------|----------|---------|---------|-------------------
File | % Stmts | % Branch | % Funcs | % Lines | Uncovered Line #s
----------|---------|----------|---------|---------|-------------------
All files | 0 | 0 | 0 | 0 |
----------|---------|----------|---------|---------|-------------------
Test Suites: 1 passed, 1 total
Tests: 3 passed, 3 total
Snapshots: 1 passed, 1 total
Time: 1.399 s, estimated 2 s

The test run generates snapshot reference files that are located at src/components/ __snapshots__.

Conclusion

Storybook is a fantastic tool to create living documentation for components. If you keep the story files next to your component’s source code, the chances are high that the story gets updated if you modify the component.

Storybook has first-class support for Vue 3, and it works very well. If you want more information about Vue and Storybook, you should look at the official Storybook documentation.

If you liked this article, follow me on Twitter to get notified about new blog posts and more content from me.

Alternatively (or additionally), you can also subscribe to my newsletter.