DEV Community: Bryant Gillespie

How I shipped an event registration site in just 1 week with Nuxt, Directus, OpenAI, and TailwindCSS

Bryant Gillespie — Fri, 07 Jun 2024 16:47:03 +0000

I recently shipped a event registration site in 1 week that would take some companies 1 year. And I'm definitely not a 10x developer.

When I was first learning to code, I always appreciated behind-the-curtain looks at how projects were made, soooo… here’s the story and how it’s built.

The TLDR;

Adding this here, just to get the “What’s your stack?” questions out of the way 🤣

frontend - Nuxt / Vue
backend / CMS - Directus
styling - Nuxt UI and Tailwind CSS
hosting - Netlify
avatar generation - OpenAI Dall•E 3

All the gory details are below.

The Story 🐰

Meet Leapweek

LeapWeek.dev is our week long launch celebration for developers at Directus. There are product announcements, workshops, giveaways, and more.

The live events are typically hosted via the Directus TV website (https://directus.io/tv) but the registration has typically been powered by other tools like Lu.ma and a few others.

Using third-party tools obviously meant additional costs which add up, but that wasn’t the main concern.

The big headaches to solve were:

a very disconnected experience for users
an in-efficient (pronounced “💩-y”) workflow for our team.

So with this third Leap Week, we made the call to build our own “platform” that is tightly integrated with our existing stack and could be re-used for future Leap Week events.

Goals 🥅

Aside from supporting registration for the event, there were a few important boxes to check.

“Own” our own event property.
Build a growth loop to incentivize shares.
Leverage AI for something “different” to get attention.

The Concept 👨‍🚀🚀

Our previous Leap Week events were spaced themed. We knew we wanted to carry that same theme so we didn’t have to whip up a ton of brand new supporting creative.

Aside from that though, the event registration site was mostly a blank canvas.

We took some inspiration from Vercel Ship and their user registration badge concept. I’d also seen other companies do similar things in the past.

I really loved the personalization, but I definitely wanted to take the concept “up a notch”.

Mission Patch

The sharing loop was critical for the project and our first idea for it was a mission patch.

It looked nice, dynamically added a name when you filled out the form, and included a parallax effect to make it feel "3D". It would be fine, but it just didn’t feel right.

We kept iterating though. At some point fairly early in the process, I had snuck in a rabbit astronaut on the landing page as an accent piece.

My next thought was “ok, let’s use that to make the patch concept even more interesting”. So I added the ability to upload an avatar and drop it into the astronaut suit and that appeared behind the custom patch. This felt a little more interesting.

And then….I wanted to customize the astronaut even further by adding custom patches for the person’s country and company.

A few GPT-fueled jam sessions later and quick demo that left the whole team smiling, the astronaut became the focal point.

And Rabbitars were born.

So basically “Rabbitars” are personalized rabbit astronauts. It’s our version of the registration badge and it’s definitely over the top. They include:

AI generated rabbit headshot
Company logo patch
Name patch
Country patch

And when you share your unique referral link – we use that avatar to create a personalized social sharing image as well.

The Backend 🧱

The backend is powered by Directus - a data platform that is a hybrid of BaaS and CMS. It pairs up with most SQL databases.

It provides:

instantly ready-to-go REST APIs (or GraphQL if that’s your thing)
asset / file storage
authentication and permissions
admin interface where you can manage and edit data, build or adjust your data model without writing code
no-code dashboards
low code automation tool to build simple or complex flows

Directus runs the whole backend from ticketing and registration to serving data for the landing page.

Data Model

I created the data model via the UI inside Directus.

This means it was easy to see what the editing experience would look like for my team.

I also put together a nice dashboard for the team to track sign ups and view all the different countries users were from. This is baked into Directus and took me all of like 5 minutes.

The Frontend 🧱

The frontend runs on Nuxt - the popular full stack meta-framework on top of Vue.js. I’m a fan of Nuxt and I’ve been using it for several years in various projects.

Routes

Nuxt’s file based routing is a helpful pattern to speed along projects. Chuck a Vue component into the /pages directory and you get a route.

And there’s really only a handful of routes for this project.

/ - the landing page
/tickets - the registration page
/tickets/customize - the (logged in only)
/ticket/[ticket] - the personalized rabbitar page
/auth/login - login if you switch devices or logout
/auth/reset - if you somehow misplace the initial email with a confirmation code
/terms - terms and conditions for the giveaway

Nuxt Route Rules keep the site speedy by allowing different rendering modes based on specific routes – an uncommon feature for other frameworks.

For example, the landing page data is fetched from the Directus backend, but uses a stale while revalidate caching pattern for performance.

I also setup a proxy for the Clearbit Logo API to prevent hounding their server all the time. The site uses their API to fetch the logos for companies based on the website you enter.

Landing Page

The event landing page uses a “page builder” concept where anyone on our marketing team can update the layout on the page and add new components like card groups or faqs.

On the backend, this is setup using Directus’ Many-to-Any (M2A) relationships. Each block can has different schema.

It all comes together on the Nuxt side. The data is fetched from the Directus backend, and then passed to a PageBuilder component that is responsible for looping through an array of blocks and rendering the components dynamically.

UI

The site uses the Nuxt UI library for a lot of the basic components like buttons and form inputs. Nuxt UI in turn uses libraries like TailwindCSS and Headless UI. It’s pretty easy to theme and uses tailwind-merge to manage class conflicts.

It really saved me a lot of time by not to re-create some of the more “rich” components like comboboxes or dropdown menus.

Generating AI Rabbitars 🧱

The actual rabbitar images are generated using OpenAI’s Dall•E 3. Currently, the average user generates ~1.52 avatars costing us a total of ~$0.0608 per registrant. We have set a hard limit of 3 generations to prevent any crazy scary OpenAI bills.

There is a Nuxt server route that calls the OpenAI API, saves the generated image to the Directus instance, and updates the avatars generated by the user.

The Challenges 🪨

There were more than a few challenges I faced with this thing. 😅

Referral Tracking

We wanted to offer more chances in the giveaway for referrals so we needed to build a mechanism to control that.

Once you generate your personalized rabbitar - you can share it to increase your odds of winning. Each person your refer earns you another entry in the giveaway.

To track this, we tag the visitor with a referral_ticket_id cookie whenever they visit a registrant personal url. Whenever a visitor registers for the event, we check for the cookie, and update a referred_by field inside our Directus backend.

This is surfaced to the registrant as a “Swag-O-Meter” on their personalized ticket page.

Function Timeouts

Leapweek.dev is hosted on Netlify. We’ve got a number of our other projects hosted there and I’m pretty familiar with the workflow. With Nuxt, there’s not really much configuration to be done, aside from connecting your repo and adding your ENV variables.

But Dall•E 3 currently takes roughly between ~15-21 seconds to generate a rabbitar for the site. In local development this wasn’t a problem, but once deployed to Netlify, we were getting timeouts on the serverless functions because the default timeout is 10 secs.

The Netlify support team was right there to help us out. They increased our limit to 26 secs and we’ve not had anymore issues.

Long URLs

Originally we wanted to run this off a subdomain of the site. But https://leapweek.directus.io/tickets/bryant-gillespie eats up a lot of characters and shorter urls are better for sharing. We’re really digging Dub.co for sharing our content on socials, but it just wasn’t a fit here for generating links.

So we chose the leapweek.dev domain over leapweek.directus.io.

But we could do better.

Nuxt Alias

The alias property within Nuxt’s definePageMeta makes it super easy to generate aliases for a specific route. So the page at /tickets/bryant-gillespie can also be rendered at /t/bryant-gillespie.

Which gives us a final url like:

https://leapweek.dev/t/bryant-gillespie

Dynamic OG Images and Caching

Dynamically generated OG images are really freaking cool, but it’s hard to ensure they render perfectly on different social media platforms. Each platform tends to have it’s own cache for OG images, making it harder to figure out than the Water Temple in Ocarina of Time.

For actually generating the dynamic social share images and caching them, we use the Nuxt OG-Image module by Harlan Wilton. It abstracts away a lot of the complexities of serving up dynamic social images.

Under the hood, it uses Satori by Vercel to render the images from a Vue component. But because of that there are some caveats about component structure and how you can style your images.

When someone updates their avatar, we also need to purge the cached image so we don’t show the previous one. That’s handled inside a Nuxt server route as well.

The Results

I'm pretty happy with the results so far.

The site just launched on Monday this week and we already have over 300+ registrants and 475 rabbitars generated.

There's been 0 promotion aside from a few tweets from our team and a single LinkedIn post.

And as far as I know, we now have the world's largest collection of rabbit avatars.

So if you ever need 100s or 1000s of rabbit headshots, consider me your guy 🤣.

If you're interested and want to poke around the site and generate your rabbitar - go for it. You can check out the site at https://leapweek.dev

Directus and SEO: Tips & Tricks

Bryant Gillespie — Thu, 02 Nov 2023 04:01:00 +0000

Search engine optimization (SEO) is an ever-changing but super important part of getting your website in front of visitors.

When using Directus as a Headless CMS, it is incredibly un-opinionated about what you do with your data and content on the frontend, leaving how you build your website up to you.

But if you’re just starting out, being so open-ended can leave you wondering about the best way to handle things like SEO.

In this post, I’ll share a few tips for managing SEO with Directus. I’ll also share some links and resources for some of the most popular frontend frameworks.

Important Assumptions

You understand basic SEO strategy and terminology.
You’re familiar with collections, fields, and fetching data from Directus.

Create a Separate Collection for SEO Data

At the end of the day, page titles and meta tags are just data. And you have to store that SEO data for your pages and blog posts somewhere.

For simple sites, you could easily manage all your meta tag data by duplicating fields like title and meta_description from one collection to another.

But beyond a couple collections, this approach becomes cumbersome and potentially dangerous. What if you forget to copy one field? What if there’s a typo and the names become inconsistent? These oversights could break your SEO practices and ,at worst, your whole site.

One better option would be creating a single collection to standardize all the SEO data for your content collections:

Create an seo collection

seo

- id (Type: uuid)
- title (Type: String, Interface: Input, Note: This item's title, defaults to item.title. Max 70 characters including the site name.)
- meta_description (Type: Text, Interface: Textarea, Note: This item's meta description. Max 160 characters.)
- canonical_url (Type: String, Interface: Input, Note: Where should the canonical URL for this entry point to.)
- no_index (Type: Boolean, Interface: Toggle, Note: Instruct crawlers not to index this item.)
- no_follow (Type: Boolean, Interface: Toggle, Note: Instruct crawlers not to follow links on this item.)
- og_image (Type: Image, Note: This item's OG image. Defaults to global site OG image. The recommended size is 1200px x 630px. The image will be focal cropped to this dimension.)
- sitemap_change_frequency (Type: String, Interface: Input, Note: How often to instruct search engines to crawl.)
- sitemap_priority (Type: Decimal, Interface: Input, Note: Valid values range from 0.0 to 1.0. This value does not affect how your pages are compared to pages on other sites, it only lets the search engines know which pages you deem most important for the crawlers.)

Beyond the basic title and meta_description , the other fields you add to your SEO collection are totally up to you.

Adding the fields within Directus is only one half of the work - you need to use these fields in your frontend within your <head> tags and sitemap.

For each of your content collections that have a route on your frontend, inside Directus – create a many-to-one (M2O) relationship with the SEO collection.

When fetching your content on the frontend, use the fields parameter to expand the SEO data within a single API call.

import { createDirectus, rest, readItem } from '@directus/sdk';
const client = createDirectus('directus_project_url').with(rest());

const postId = '234ee-3fdsafa-dfadfa-dfada';

const post = await client.request(
    readItem('posts', postId, {
        fields: [
            'title',
            'summary',
            'content',
            'image',
            {
                seo: [
                    'title',
                    'meta_description',
                    'canonical_url',
                    'no_index',
                    'no_follow',
                    'og_image',
                    'sitemap_change_frequency',
                    'sitemap_priority',
                ],
            },
        ],
    }),
);

Then pass that to your frameworks specific method of add SEO metadata within your
tags.

Frontend Framework Metadata Documentation

Don’t Use Slugs as a Primary Key

The actual url for a page on your website is a key factor for search engine rankings. Because of that, your content editors will want to experiment and adjust urls and slugs for items as needed.

When adding a new collection Directus lets you choose from several types of primary keys for your collection.

Auto-incremented integer
Auto-incremented big integer
Generated UUID
Manually entered string

I’ve seen lots of folks name the primary key field slug and use the Manually entered string . It’s easy to understand. It makes fetching that item easier because you can get the item by its id (the slug) directly instead of constructing a query to match the slug.

But an item’s p*rimary key value can not be changed after they are created, while t*his protects your database and all of your relationships, it makes it hard to experiment or change URLs if, for example, a product name changes.

To avoid this, use the auto-incremented ids or UUIDs for the primary key id and create a separate field input for the slug . You can require uniqueness which means only one item in a collection can have a given slug.

You can no longer use API endpoints or SDK functions for reading a single item, as this relies on using the primary key. Instead, query the whole collection and use Filter Rules to get the single item that has the slug:

import { createDirectus, rest, readItems } from '@directus/sdk';
const client = createDirectus('directus_project_url').with(rest());

const slugFromYourFrontEndFramework = params.slug || router.query.slug // whatever your convention your framework follows;

const posts = await client.request(
  readItems('posts', {
    filter: {
      slug: {
        _eq: 'slugFromYourFrontEndFramework',
      },
    },
    limit: 1,
  })
);

const post = posts.data[0];

Use Relationships for Internal Linking

When building a website, you’ll need both links for internal content and links for external content.

One common pattern I’ve noticed is creating string inputs for internal links to other content.

But this can be surprisingly brittle. As soon as the slug for the Contact page changes from /contact-us to /contact-directus-team , the link will break and this can really crash your search engine rankings.

Luckily Directus makes a more dynamic approach possible with relationships.

When creating your data model for links to other items from the same or different collections, try using the conditional fields and many to one relationships to build a powerful, resilient way to link items.

Within your content collection, add the following fields for linking. (Note: This example is extremely simplified so you can learn the logic involved. - name these depending on what makes the most sense to you and your use case.)

your_content_collection

- link_type (Type: String, Interface: Dropdown, Note: Choices: [
    {
        "text": "Internal - Page",
        "value": "pages"
    },
    {
        "text": "Internal - Post",
        "value": "posts"
    },
    {
        "text": "External - URL",
        "value": "external"
    }
])
- link_label (Type: String, Interface: Input, Note: What label or title is displayed for this link?)
- link_page (Type: M20 Relationship, Related Collection: pages, Hidden On Detail, Conditions: [
    {
        "name": "IF link_type === page",
        "rule": {
            "_and": [
                {
                    "link_type": {
                        "_eq": "pages"
                    }
                }
            ]
        },
        "hidden": false,
    }
])
- link_post (Type: M20 Relationship, Related Collection: post, Hidden On Detail, Conditions: [
    {
        "name": "IF link_type === post",
        "rule": {
            "_and": [
                {
                    "link_type": {
                        "_eq": "post"
                    }
                }
            ]
        },
        "hidden": false,
    }
])
- link_external_url (Type: String, Interface: Input, Conditions: [
    {
        "name": "IF link_type === external",
        "rule": {
            "_and": [
                {
                    "link_type": {
                        "_eq": "external"
                    }
                }
            ]
        },
        "hidden": false,
    }
])

Fields for page, post, and external url are only visible when the related type is selected so there is no confusion about which fields to enter data for. And it also allows you to use that relationship to fetch the proper slug or permalink for posts and pages.

On the frontend, when you are fetching data via the API, use the [fields parameter](https://docs.directus.io/reference/query.html#fields) to get the related posts and pages in a single API call.

Then make sure you’re getting the proper url based on the link_type:

```tsx
const post = await client.request(
    readItem('your_content_collection', 'your_content_item_id', {
        fields: [
            // Fetch all the other root level fields for your collection **In production, you should only fetch the fields you need**
            '*',
            'link_type',
            'link_label',
            'external_url',
            // Use object syntax to fetch fields from a relation
            {
                page: ['id', 'title', 'permalink'],
                post: ['id', 'title', 'slug'],
            },
        ],
    }),
)

function getUrl(item) {
    if (item.link_type === 'pages') {
        return item.page.permalink ?? ''
    } else if (item.link_type === 'posts') {
        return `/blog/${item.post.slug}` ?? ''
    } else if (item.link_type === 'external') {
        return item.external_url ?? ''
    }
    return undefined
}

// ~~~ //
// Inside your template
// Make sure to use the correct syntax for your framework
<a href={getUrl(item)}>{item.link_label}</a>
// ~~~ //
```

Frontend Framework Link Documentation

Add Fields to Control Semantic Elements When Using Dynamic Page Builder

The structure of your content matters a lot for SEO. Crawlers like well structured pages with a clear hierarchy.

For educational items like blog posts or documentation, semantic hierarchy and design usually align well. Most of these items also have a well defined “template” or “layout” on the frontend.

The <h1> tag contains the title of the article and is the visually the largest header on the page. Other header tags like <h2> or <h3> get smaller visually and have less priority for SEO.

But for other items like that are more dynamic like landing pages or homepages, the Builder (Many To Any Relationships) really shine inside Directus. You can let your marketing or content teams build pages on their own with predefined collections or blocks without involving a developer at all. It also pairs beautifully with the Live Preview feature to allow them to see exactly what the site will look like before publishing.

However, handling the semantic markup you need for proper SEO versus the fact that blocks could be placed anywhere on a page can be a real challenge when developing your site.

Let’s take header tags for example. You need proper semantic hierarchy for SEO. But our hierarchy for SEO doesn’t always equal our visual hierarchy required for good design.

Having the keyword optimized <h1> tag be the largest visually - is not always ideal.

But in other cases, the <h1> tag should be the largest visually.

A great solution to this problem can be to create separate fields within the collection that allow the content editor to choose both the proper header tag and the visual size.

Here’s an example.

This provides a ton of flexibility. And with just a little training, editors can create pages that look great on screen and also perform well for SEO.

To render this on the frontend, you’d use dynamic components. Most frontend tools support the concept of dynamic components. The syntax will vary though so consult your frontend framework’s documentation.

Frontend Framework Component Documentation

Next.js - Dynamic Imports for Components
Nuxt - Dynamic Components
Astro - Components - Astro is a bit unique in that you can use components from other frameworks
[Svelte - svelte:component](https://svelte.dev/docs/special-elements#svelte-component)
Remix - I couldn’t find anything on dynamic components within Remix’s documentation.
Angular - Dynamic component loader

Implement a Sitemap

Sitemaps are important tools for crawlers like Googlebot to index your site properly. It’s easy to skip over this step when launching a new site, but it’s an important step that makes sure all the pages on your site can be found in search engines.

There’s not much to really manage inside Directus for a sitemap beyond properly creating your content collections. The heavy lifting for a sitemap is on the frontend.

Some frontend frameworks have an official or community-supported sitemap module / plugin. Others have instructions on how to generate a sitemap without the need to another package.

The exact implementation details will vary based on your selected framework but the general approach looks like this.

Create a function that fetches the items for each collection that has a route on your frontend.
Loop through those items formatting each as proper xml (or as the specific syntax your plugin requires).
Create a route like /sitemap.xml that returns the XML file.

Here’s an example that’s specific to Nuxt but the logic could be extracted to other frameworks.

```jsx
// This example is based on Nuxt and uses a third party package. 
// Consult your own frontend framework's documentation for how to properly generate a sitemap in their ecosystem.
// /server/routes/sitemap.xml.ts

import { SitemapStream, streamToPromise } from 'sitemap'
import { createDirectus, readItems, rest } from '@directus/sdk'

const directus = createDirectus(directusUrl).with(rest())

export default defineEventHandler(async (event) => {
    // Fetch all the collections you want to include in your sitemap
    const pages = await directus.request(
        readItems('pages', {
            fields: ['permalink'],
            limit: -1, // Be careful using -1, it will fetch all the items in the collection and could cause performance issues if you have a lot of items
        }),
    )

    const posts = await directus.request(
        readItems('posts', { fields: ['slug', { type: ['slug'] }], limit: -1 }),
    )

    // Create an array of objects with the url you want to include in your sitemap
    const urls = []

    urls.push(...pages.data.map((page) => ({ url: page.permalink })))

    urls.push(
        ...posts.data.map((post) => ({
            url: `/blog/${post.slug}`,
        })),
    )

    const sitemap = new SitemapStream({
        hostname: 'https://example.com',
    })

    // Add each url to the sitemap
    for (const item of urls) {
        sitemap.write({
            url: item.url,
            changefreq: 'monthly',
        })
    }

    sitemap.end()
    return streamToPromise(sitemap)
})
```

Frontend Framework Sitemap Resources

Next.js - XML Sitemap Documentation
Nuxt - Nuxt Simple Sitemap Module
Astro - @astro/sitemap Integration
Svelte - Sitemap Package
Remix - Remix SEO Package
Angular - I struggled to find a helpful tutorial or sitemap package for Angular.

Give Your Team Control of Redirects

It sucks having to pull yourself away from a fun (or important) project to manually add some redirects for a page. Do yourself a favor and let your content team add and manage redirects within the CMS.

Create a redirects collection

redirects

- id (Type: uuid)
- url_old (Type: String, Interface: Input)
- url_new (Type: Integer, Interface: Slider)
- response_code (Type: String, Interface: Dropdown, Choices: [
    {
        "text": "Permanent (301)",
        "value": "301"
    },
    {
        "text": "Temporary (302)",
        "value": "302"
    }
])

Add redirects dynamically when building your frontend. This is often done by creating a function to fetch the redirects from your Directus API and then passing those redirects to your frontend framework using a specific syntax inside a config file, plugin, or module.

// Though it depends on your specific framework, this logic would probably be called during build time
import { createDirectus, readItems, rest } from '@directus/sdk'

const directus = createDirectus(directusUrl).with(rest())

const redirects = await directus.request(readItems('redirects'))

for (const redirect of redirects) {
    let responseCode = redirect.response_code
        ? parseInt(redirect.response_code)
        : 301

    // If response code doesn't match what we expect, use 301
    if (responseCode !== 301 && responseCode !== 302) {
        responseCode = 301
    }

    // Add Logic here to add the redirects to a config file or tell your frontend framework how to handle them
    // ** Your Logic **
}

Frontend Framework Redirect Documentation

Don’t Forget Image Alt Text

Often overlooked, image alt text is important for SEO and critical for proper accessibility.

<img src="https://example.com/image.png" alt="An example image of how alt text works" width="500" height="500" />

A good way to manage image alt tags is on the files themselves as you upload them within Directus.

I prefer using the description field on files to store alt text. This way you don’t have to input alt text every single time you use this same image in different contexts.

For items like blog posts or articles you might have an image or featured_image field so you can have a nice hero image or a thumbnail if shown inside a card.

If you store alt text inside of the image item, you will want to fetch these nested title and description fields within the same API call:

const posts = await client.request(
  readItems('posts', {
    filter: {
      slug: {
        _eq: slugFromYourFrontEndFramework,
      },
    },
        fields: ['title', 'date_published', 'summary', 'content', { image: ['id', 'title', 'description']}]
    limit: 1,
  })
);

// ~~~ //
// Inside your template
<img src={post.image.id} alt={post.image.description ?? ""} />

Remember that the position of the image id will change from item.image to [item.image.id](http://item.image.id) when you fetch nested fields.

And remember – the actual alt text itself is just as important as rendering it on the page. I won’t dive into details because Moz has a great tutorial on how to write proper alt text here.

And if you’ve got 100s of images without alt text and you’re dreading doing all that work manually, try a boost from this extension - Directus Media AI Bundle - a winner in a recent AI Hackathon submitted by community member Arood. It uses several different AI tools to write image alt text or descriptions for you.

Frontend Framework Image Documentation

Next.js Images
Nuxt Images
Astro Images
Svelte Images
Remix - I couldn’t locate any documentation about images on the Remix site.
Angular Images

Summary

In this post, we’ve covered some SEO best practices when using Directus as a Headless CMS. Hopefully you’ve learnt something new, and can build more robust data models that serve both your users and search engine crawlers.

If these tips were helpful or if you have some of your own you’d like to share, let us know inside our Discord community.

Building a User Feedback Widget with Vue.js and Directus

Bryant Gillespie — Fri, 22 Sep 2023 04:25:28 +0000

One of our DevRel initiatives at Directus is constantly improving our documentation. As a small team with finite time and resources, we rely a lot on user feedback to help guide our writing efforts. But we were missing the most important bit there – your feedback.

What We’re Building

At the time of this post, the Directus Docs runs on VitePress (which in turn is based on Vue.js and Vite). Vitepress is a nice bit of kit for quickly generating a static documentation site, but sadly there’s no built-in feature for gathering user feedback.

So I decided to build my own so our team could make better decisions on where to spend our precious time and attention.

While this project was built in the context of Vitepress, this post will show you how to do it with Vue generally. Here’s what our finished product will look like.

Prerequisites

Before we hop 🐰 in , here’s what you’ll need to follow along:

Knowledge

Beginner knowledge of Javascript, Typescript, and Vue.js (Composition API)

Tooling

A Directus instance up and running (either self-hosted or on Directus Cloud)
A Vue.js project set up (Using Vite is recommended)

Preparing Directus Collection

First off, we're going to need a place to store all this valuable feedback we'll be gathering.

Create a docs_feedback collection with the following data model:

docs_feedback

- id (Type: uuid)
- date_created (Type: Timestamp, Interface: Date/Time)
- url (Type: String, Interface: Input)
- rating (Type: Integer, Interface: Slider)
- title (Type: String, Interface: Input)
- comments (Type: Text, Interface: Textarea)

Creating Vue Component for Article Feedback

Just as if it were the lone dev on a cross-functional team – we’re going to place a lot of different responsibilities on our hard-working little Vue component.

Rating System: We’ll use a 1 to 4 scale, with each value associated with a different message. These messages will help engage users and guide them through the feedback process.
Open Ended Feedback: We provide a text area for users to write their thoughts. This is where the gold is. We want users to share their ideas, suggestions, and insights – positive or constructive 😭.
Posting Data to Directus: The component handles the submission of the feedback to Directus. It constructs the feedback object and makes a POST request to the feedback API endpoint.

Scaffolding the Feedback Component

Create a new file in our components directory named ArticleFeedback.vue . Then copy and paste the following code.

<script setup lang="ts">
</script>

<template>
    <div class="wrapper">
        <div class="step">
            <!-- Step 1. Show Rating Buttons -->
            <div>
                <p class="desc">How can we improve?</p>
                <p class="heading">How helpful was this article?</p>
            </div>
        </div>
        <div class="step">
            <!-- Step 2. Ask for Comments -->
        </div>
        <div class="step">
            <!-- Step 3. Show Success Message -->
        </div>
    </div>
</template>

<style scoped>
</style>

We’ve got three different states (or steps as I’m calling them) we’ll need to build.

An initial state that shows the feedback prompt and rating buttons.
Once a rating has been selected, a state which asks for comments and feedback.
A success state once form submission is complete.

Adding Props and Reactive Logic

Now let’s start adding our logic to control these three steps.

<script setup lang="ts">
+ import { ref, reactive } from 'vue';
+
+ const props = defineProps<{
+   title: string;
+   url: string
+ }>();
+
+ const feedback = reactive<{
+   id?: string;
+   rating?: number;
+   comments?: string;
+ }>({});
+
+ const success = ref(false);
</script>

<template>
    <div class="wrapper">
-       <div class="step">
+       <div v-if="!feedback.rating" class="step">
            <!-- Step 1. Show Rating Buttons -->
            <div>
                <p class="desc">How can we improve?</p>
                <p class="heading">How helpful was this article?</p>
            </div>
        </div>
-       <div class="step">
+       <div v-else-if="feedback.rating && !success" class="step">
            <!-- Step 2. Ask for Comments -->
        </div>
-       <div class="step">
+       <div v-else class="step">
            <!-- Step 3. Show Success Message -->
        </div>
    </div>
</template>

<style scoped>
</style>

Import the ref and reactive functions from Vue.
We’ll pass the url and page title as props from the parent component that contains this widget.
Create a reactive object feedback to manage our form submission data.
Create a reactive success variable to hold the success state.
Use v-if, v-else-if, and v-else to control what step of the feedback process is shown.

With the logic roughed in, let’s add our rating buttons.

Adding the Rating Options

<script setup lang="ts">
import { ref, reactive } from 'vue';

const props = defineProps<{ title: string; url: string }>();

const feedback = reactive<{
    id?: string;
    rating?: number;
    comments?: string;
}>({});

+ const ratingOptions = [
+   { label: 'Worst Doc Ever 🗑️', value: 1, message: 'Woof! 🤦‍♂️ Sorry about that. How do we fix it?' },
+   { label: 'Not Helpful 😡', value: 2, message: '🧐 Help us do better. How can we improve this article?' },
+   { label: 'Helpful 😃', value: 3, message: 'Nice! 👍 Anything we can improve upon?' },
+   { label: 'Super Helpful 🤩', value: 4, message: `Awesome! The whole team is rejoicing in celebration! 🥳🎉🎊 Anything you'd like to say to them?` },
+ ];
+
+ function getRatingOption(rating: number) {
+   return ratingOptions.find((option) => option.value === rating);
+ }
</script>

<template>
    <div class="wrapper">
        <div v-if="!feedback.rating" class="step">
            <!-- Step 1. Show Rating Buttons -->
            <div>
                <p class="desc">How can we improve?</p>
                <p class="heading">How helpful was this article?</p>
            </div>
+           <div class="button-container">
+                   <!-- We'll add a function for handling button clicks while adding our submission logic -->
+                   <button v-for="item in ratingOptions" :key="item.value" class="btn">
+                       <span>{{ item.label }}</span>
+                   </button>
+           </div>
        </div>
        <div v-else-if="feedback.rating && !success" class="step">
            <!-- Step 2. Ask for Comments -->
        </div>
        <div v-else class="step">
            <!-- Step 3. Show Success Message -->
        </div>
    </div>
</template>

The rating options will be an array of objects that have a visible label, a corresponding value of 1-4, and a dynamicmessage that we’ll display to encourage the user to leave comments after selecting a rating.

We’ll also create a small helper function to return the rating object based when passing a number value. This will come in handy in the second step because we’re going to display the rating the user chose.

Add a new div to Step 1 below the feedback prompt that will contain our rating options. Inside that, we’ll use v-for to loop through the ratingOptions array and render the individual buttons.

Asking for Comments

<template>
    <div class="wrapper">
        <div v-if="!feedback.rating" class="step">
            <!-- Step 1. Show Rating Buttons -->
            <div>
                <p class="desc">How can we improve?</p>
                <p class="heading">How helpful was this article?</p>
            </div>
            <div class="button-container">
                <button v-for="item in ratingOptions" :key="item.value" class="btn">
                    <span>{{ item.label }}</span>
                </button>
            </div>
        </div>
        <div v-else-if="feedback.rating && !success" class="step">
            <!-- Step 2. Ask for Comments -->
+               <div>
+                   <p class="desc">This article is</p>
+                   <div>
+                       <span>{{ getRatingOption(feedback.rating)?.label }}</span>
+                       <button class="btn" @click="feedback.rating = undefined">
+                           ❌
+                       </button>
+                   </div>
+               </div>
+               <p class="heading">{{ getRatingOption(feedback.rating)?.message }}</p>
+               <textarea v-model="feedback.comments" autofocus class="input" />
+               <button class="btn btn-primary" :disabled="!feedback.comments">
+                   Send Us Your Feedback
+               </button>
        </div>
        <div v-else class="step">
            <!-- Step 3. Show Success Message -->
+           <p class="heading">Thanks for your feedback!</p>
        </div>
    </div>
</template>

In Step 2 of the process, we’re showing the user the rating they chose using our getRatingOption helper function we created.

To improve the user experience, we’ll also let users go back and choose a different rating in case they picked the wrong one by mistake. Whenever they click the close button we’ll set the feedback.rating property to undefined which will take the user back to Step 1 based on the v-if logic we created.

Below that, we’ll show the proper message for the option they chose to encourage them to leave helpful comments in short form with a textarea input and a submit button.

We’ll also prevent them from submitting from Step 2 when the comments are empty, so we pass the :disabled="!feedback.comments" prop to the button element.

Adding Styling

Next, let’s add some basic styling.

// ^^ Rest of ArticleFeedback.vue Component ^^
<style scoped>

.wrapper {
    margin: 2rem 0;
    padding: 1.5rem;
    border: 1px solid rgba(60, 60, 67, .12);
    border-radius: 8px;
    background: #f6f6f7;
}

.step > * + * {
    margin-top: 1rem;
}

.desc {
    display: block;
    line-height: 20px;
    font-size: 12px;
    font-weight: 500;
    color: rgba(60, 60, 67, .75);
}

.heading {
    font-size: 1.2rem;
    font-weight: 700;
}

.button-container {
    display: grid;
    grid-gap: 0.5rem;
}

.btn {
    border: 1px solid solid rgba(60, 60, 67, .12);
    background-color: #ffffff;
    border-radius: 8px;
    transition: border-color 0.25s, background-color 0.25s;
    display: inline-block;
    font-size: 14px;
    font-weight: 500;
    line-height: 1.5;
    margin: 0;
    padding: 0.375rem 0.75rem;
    text-align: center;
    vertical-align: middle;
    white-space: nowrap;
}

.btn:disabled {
    opacity: 0.5;
}

.btn:hover {
    border-color: #6644ff;
}

.btn-primary {
    color: #fff;
    background-color: #6644ff;
    border-color: #6644ff;
}

.btn-primary:hover {
    background-color: #4422dd;
    border-color: #4422dd;
}

.input {
    width: 100%;
    height: 100px;
    border: 1px solid #ccc;
    border-radius: 4px;
    padding: 0.375rem 0.75rem;
}

@media screen and (min-width: 768px) {
    .button-container {
        grid-template-columns: repeat(4, 1fr);
    }
}
</style>

Adding Submission Logic Inside The Vue Component

We’re going to write a handler function to actually submit our data to our Directus docs_feedback collection.

At the end of our <script> tag, let’s add our submission handler.

async function handleSubmission(rating?: number) {
    loading.value = true;
    if (rating) feedback.rating = rating;

    const body = {
        id: feedback.id,
        rating: feedback.rating,
        comments: feedback.comments,
        title: props.title,
        url: props.url,
    };

    // Replace this with your own Directus URL
    const directusBaseUrl = 'https://yourdirectusurl.directus.app';

    try {
        let response;

        // If we've already created a feedback record, we'll update it with the new rating or comments.
        if (feedback.id) {
            response = await fetch(`${directusBaseUrl}/items/docs_feedback/${feedback.id}`, {
                method: 'PUT',
                body: JSON.stringify(body),
            });
        } else {
            response = await fetch(`${directusBaseUrl}/items/docs_feedback/${feedback.id}`, {
                method: 'POST',
                body: JSON.stringify(body),
            });
        }

        const data = await response.json();
        feedback.id = data.id;

        // If the reponse has comments, we can assume they've completed the second step. So we'll show the success message.
        if (data.comments) {
            success.value = true;
        }
    } catch (err) {
        error.value = err;
    } finally {
        loading.value = false;
    }
}

This function handleSubmission accepts an optional rating and then conditionally creates a new feedback item or updates depending on which step the user completed.

We also need to update our template to call our handler using the @click directive.

<template>
    <div class="wrapper">
        <Transition name="fade" mode="out-in">
            <div v-if="!feedback.rating" class="step">
                <div>
                    <div>
                        <p class="desc">How can we improve?</p>
                        <p class="heading">How helpful was this article?</p>
                    </div>
                </div>
                <div class="button-container">
                    <button v-for="item in ratingOptions"
                        :key="item.value"
                        class="btn"
+                       @click="handleSubmission(item.value)">
                        <span>{{ item.label }}</span>
                    </button>
                </div>
            </div>
            <div v-else-if="feedback.rating && !success" class="step">
                <div>
                    <p class="desc">This article is</p>
                    <div>
                        <span>{{ getRatingOption(feedback.rating)?.label }}</span>
                        <button style="margin-left: 0.5rem" class="btn" @click="feedback.rating = undefined">
                            <span mi icon>close</span>
                        </button>
                    </div>
                </div>
                <p class="heading">{{ getRatingOption(feedback.rating)?.message }}</p>
                <textarea v-model="feedback.comments" autofocus class="input" />
                <button
                    class="btn btn-primary"
                    :disabled="!feedback.comments"
+                   @click="handleSubmission()">
                    Send Us Your Feedback
                </button>
            </div>
            <div v-else class="step">
                <p class="heading">Thanks for your feedback!</p>
            </div>
        </Transition>
    </div>
</template>

Sweet! Now there’s just one last step before we have a working component.

Updating Permissions inside Directus

Right now, if we try to submit some feedback, we’re probably to going receive an Permission denied error from Directus.

This is because all collections have zero public permissions by default. While this is great for security, it’s not so great if we want to store our feedback data.

Open up the Public role with the Roles & Permission settings. Then scroll to find the docs_feedback collection.

Create and Update Operations

Click the block button inside each column and choose check All Access.

Read Operation

We might not want any prying eyes to be able to read the actual feedback ratings and content, so we’ll use some custom permissions to restrict the fields that anyone can ‘read’.

Click the button for the Read column, and choose Custom Permissions.

On the Field Permissions tab, check only the id field.

When you’re all done, it should look like this screenshot.

Awesome! Now on to testing.

Testing the Feedback Widget

Let’s open this up our Vue app and our Directus instance to test that everything is working as intended.

Make sure you check that the form submissions are correct inside Directus.

Next Steps

Here’s a few of the next steps you may want to explore beyond this tutorial.

Analyze the Data Using Directus Insights

Collecting feedback is just one half of the equation. Analyzing and taking action on the data you receive is the more important part.

Our module for creating no-code dashboards - Directus Insights - can help you understand the data you collect much easier and faster than browsing through a list of feedback.

Secure form submissions

To post our form submissions, we just enabled Public create and update access for the docs_feedback collection inside Directus.

There’s not a lot to gain by spamming documentation feedback submissions but you never know with folks these days.

Security wise - we could do better.

Here’s a few options:

Create a Flow with using an incoming webhook trigger that processes the incoming requests.
Obscure our Directus instance URL by using a proxy or serverless function to make the call to the Directus API. Netlify, Vercel, and other hosting static site hosting platforms simplify this process.

Add a session identifier to track feedback from the same user

It could be very handy to know if feedback across different articles is coming from the same user. We don’t really need full blown user sessions stored in the database for this. We could implement it client-side by:

adding a field to for session_id or visitor_id to our collection inside Directus
generating a random ID on a first visit or feedback submission inside the Vue app
storing the ID within the browser using localStorage or sessionStorage
grabbing that ID and passing it in the API call to Directus

I hope you find this post useful - if you have any questions feel free to join our Directus Discord server.