DEV Community: Maximilien Monteil

Firebase + Algolia: How to set up transform functions

Maximilien Monteil — Tue, 07 Sep 2021 05:55:47 +0000

Firebase is an incredible service, especially their Firestore database which I use to handle data in Mylo.

Recently I updated the website with a page to show all public workouts. Implementing that is just a read operation but then I thought to add search capability and things quickly got more involved.

Firestore has no native full-text search support and trying to make your own on top of Firebase is:

expensive
impractical
not what I set out to do
leaves me with more software to maintain

Luckily Firebase is aware that this is a common use case, so their own docs recommend using a dedicated third-party search service. I decided to go with Algolia because they were the service I had heard of the most.

The official guides do a great job of walking you through the setup process so I won't parrot them here. Instead this article goes over transform function and how to set them up. I ran into a few pitfalls doing this and decided to write the guide I wish I had.

Heads up: you can access nested fields with dot notation "data.book.name".

What is a transform function

When you install the Algolia extension and point it to a collection to search through, all the documents there and the fields you listed get used to create a search index. A search index is essentially a list that Algolia formats and organizes in a way that is better for searching.

Each uploaded document is referred to as a record and a good practice is keep these small. The record data is also what is returned with search results.

This leads to a balancing act, you want small records that are faster to search through but you also want records to have all the data you need to display results (otherwise you have to request each document again for the rest of the data).

As a concrete example, I wanted to show the total number of exercises within each workout. To do this with the Firestore documents I do something like this:

const numberOfExercises = (workout) => {
  return Object.keys(workout.exercises).length;
}

This is fine since I've already requested and received the whole document. But the exercises object is actually quite large and I definitely don't want to have it in a record.

That's where the transform function comes in. Before sending a document to be indexed, it will go through the transform function where I can do what I need to reduce the size or shape of the object.

const transformWorkout = (workout) => ({
  // ...
  exercises: Object.keys(workout.exercises),
  // ...
});

How to add a transform function to Algolia Firebase

After (or during) the setup of the Algolia extension, you can add the name of your transform function (same as the actual function) in the Transform Function Name (Experimental) (Optional) configuration field.

Firestore Algolia Search extension - Github

Note that you can access nested fields with dot notation "data.exercise.name". That's also the key you have to use to access the data in your transform function and your search results (records). You can rename them by returning an object with the key name you want instead (name: req.body.data["data.exercise.name"]).

Creating

First, set up Firebase functions and the tools needed as per Google's own guide:
Get Started - Firebase Functions Docs

Then create your function in the functions/index.js folder that was made during the init process.

Now, contrary to what the extension docs say (at the time of writing), you should make your function callable via HTTP as described here and not one callable from your app.

This means using functions.https.onRequest instead of functions.https.onCall. This is because the extension calls your function by its URL and not with the Firebase SDK.

Another important thing is the geographical location of your function. It needs to be in the same region as the extension to work. So if your extension is located in europe-west1 make sure your function is too.

Cloud Functions Location - Google Cloud

// index.js

const functions = require("firebase-functions");

exports.transformPayloadForSearch = functions
  // this needs to be the same location as the extension
  .region("europe-west1")
  .https.onRequest((req, res) => {
  try {
    // extract the actual data payload
    const payload = req.body.data;

    // the returned object MUST be wrapped within "result"
    res.send({
      result: {
        // the `objectID` property is required, don't forget it!
        objectID: payload.objectID,

        // the object keys are the ones you put in the comma separated list when setting up the extension
        name: payload["data.exercise.name"],

        ...transformPayload(payload),
      },
    });
  } catch (e) {
    // You can send logs this way but be aware of quotas or you'll get a surprise in your bill
    functions.logger.log("There was an error", { message: e.message });

    // Make sure to call `.send()`, `.end()`, or `.redirect()` on `res`
    // so that your function doesn't run longer than needed
    res.status(500).end();
  }
})

About nested fields

When configuring the extension, you can optionally pass a comma separated list of Indexable Fields. This is the key the extension will use to access the fields of your Firestore documents and is also the name under which they will appear within your Algolia index.

You can access nested fields by using dot notation, for example "data.exercise.name". The annoying thing is this name will also trickle down to the front-end as you get your search results. You will have to access everything with these long String keys.

Luckily, the keys you return in your transform function is what Algolia will use. So a transform function can also be used to avoid the key hassle.

Re-indexing

Now you can deploy your function with this command (replace transformPayloadForSearch with the name of your function):

firebase deploy --only functions:transformPayloadForSearch

To make Algolia update its index, run the script with the proper env variables set, you can find it in your Firebase console for the project where you installed Algolia.

Extensions > Search with Algolia > How this extension works

Note that you might need to create a service account and generate a key. Make sure to place that key in a safe place but not in version control (git).

You can paste the script into your terminal to run it but if you end up running it a lot (like I did), create a bash script to help you out (also keep it out of git).

#!/bin/bash
# Re-index the Algolia index
# ----------------------------
export LOCATION=<add-yours>
export PROJECT_ID=<add-yours>
export ALGOLIA_APP_ID=<add-yours>
export ALGOLIA_API_KEY=<add-yours>
export ALGOLIA_INDEX_NAME=<add-yours>
export COLLECTION_PATH=<add-yours>
export FIELDS=<add-yours>
export TRANSFORM_FUNCTION=<add-yours>
export GOOGLE_APPLICATION_CREDENTIALS=<add-yours>

npx firestore-algolia-search

Then run this command to make your script executable:

chmod +x reindexAlgolia.sh

And finally use this while in the same directory to run it

./reindexAlgolia.sh

Conclusion

That about covers the process. I myself ran into quite a few roadblocks trying to set it up and couldn't find more information on the topic. I hope this can help you out and save you some headaches!

Feel free to share any feedback or ask any questions 😁

You can reach me on Twitter @MaxMonteil

Add Typescript to your JS project in 1 line

Maximilien Monteil — Sat, 06 Mar 2021 10:16:22 +0000

If you've been spending any time in the JS world, you might have noticed Typescript becoming all the rage. But if you didn't start off with it, adding Typescript can be a pain.

Well it doesn't have to be, in 5 lines you can have your cake and eat it too!

Why Typescript in the first place?

The argument is that your Javascript code is bound to start getting errors that Typescript's typing could have avoided, especially as your project gets bigger.

According to Kent C. Dodds, adding a type system is also the first step to getting into testing if you don't already have it.

How to add testing to an existing project

Everyone wants to catch bugs that are obvious like passing a string where a number is expected, getting that sweet IDE auto-completion, and all around being more confident when you make changes.

Maybe you're convinced, but you're already knee deep in your pure JS project and adding Typescript seems like a huge hassle. Well there exists a beautiful solution that requires literally 1 line.

/** @param {number} value */
function onlyGiveMeNumbers (value) {
    return Math.round(value)
}

Boom! Full on typing thanks to special JSDoc comments. You just need to make sure to use 2 * to start the multi-line comment.

If it doesn't work right away you have three options:

add // @ts-check to the top of each file
If you use VS Code there's a checkJs option
create tsconfig.json or jsconfig.json in your project root

// jsconfig.json
// if you make a tsconfig.json make sure to add "checkJs": true

{
  "include": ["src/**/*"],
  "exclude": ["node_modules", "dist"],
  "compilerOptions": {
    "module": "es2020",
    "moduleResolution": "node",
    "target": "es2020",
    "lib": ["dom", "es2019"],
    "checkJs": true,
    "noEmit": true,
    "strict": false,
    "baseUrl": ".",
  }
}

This works because a lot of IDEs use the TS language server to check your code even if it is in Javascript.

Setting checkJs to true takes advantage of what's already there, but instead of getting types as any everywhere, JSDoc lets you give your editor the information it needs.

This has some advantages over TS:

No compilation step
Hyper simple setup
No impact on final bundle size
Self documenting
Almost as complete as full on TS

That last point is where you might have some second thoughts about going in on JSDoc. Standard JSDoc is not at feature parity with Typescript.

If you follow the official JSDoc documentation (JSDoc Docs if you will), there are some things that you either can't do or are a huge hassle to set up (compared to TS), but this might not even affect you.

You see, I think there are 2 kinds of typing worlds:

Application logic
Library land

In application logic, typing is generally pretty straight forward (compared to 2), you mainly need to make sure you are consistent and thorough.

For example, say you have an application that deals managing quests, you would first define the type for your core domains and then make sure every function and method expecting these domains is typed as such.

Define all your domains.

/**
 * @typedef Quest
 * @prop {string} target What you should hunt
 * @prop {boolean} completed Whether the quest is completed or not
 */

/**
 * @typedef QuestBoard
 * @prop {string} name The board's name
 * @prop {Quest[]} quests All the quests on this board
 */

Type all the places that would expect these items.

/**
 * @param {string} task
 * @return {Quest}
 */
function createQuest (target) {
    return { target, completed: false }
}

/**
 * Given a name and list of quests, create a new Quest Board.
 *
 * @param {string} name Name for the quest board.
 * @param {Quest[]=} quests optional list of quests.
 * @return {QuestBoard}
 */
function createQuestBoard (name, quests=[]) {
    return { name, quests }
}

If most of your typing is going to be in the Application realm then JSDoc will serve you admirably. But when you enter Library Land things can get a little murkier, mainly because of Generics.

As a quick explanation, Generics, are a placeholder type. You tell your code that it will receive a "something", but whatever it is, here is how you should handle it. Without Generics you might have to duplicate functions for each kind of type you expect it to receive.

When making libraries that will be used by others, you can't predict what people will send so you need to be ready for anything, I'm not a typing expert but I've seen some frightening Library Land typing that JSDoc might not be able to handle (or maybe it might?).

// Detect dark theme var iframe = document.getElementById('tweet-1363992092498747392-288'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=1363992092498747392&theme=dark" }

Unless you have such requirements, JSDoc still handles itself pretty well.

/**
 * @template SomeGenericType
 *
 * @typedef WrappedData
 * @prop {SomeGenericType} data
 * @prop {Object} meta
 * @prop {number} meta.createdAt
 */

/** @template DataType */
class DataWrapper {
    /** @param {DataType} data */
    constructor (data) {
        this.wrapped = this.wrap(data)
    }

    get data () {
        return this.unwrap()
    }

    /**
     * @private
     * @param {DataType} data
     * @return {WrappedData<DataType>}
     */
    wrap (data) {
        return {
            data,
            meta: {
                createdAt: +(new Date()),
            },
        }
    }

    /** @private */
    unwrap () {
        return this.wrapped.data
    }
}

// A generic wrapper that will work with any random thing
const messageWrapper = new DataWrapper('Hello, World!')

/** @extends {DataWrapper<Quest>} */
class QuestWrapper extends DataWrapper {}

const quest = createQuest('Capture a Shogun Ceanator!')
// This wrapper will only accept Quest type things
const questWrapper = new QuestWrapper(quest)

As with most examples dealing with Generics, this is a little contrived and not all that useful, but even then, JSDoc manages to get through.

But what can you do about the things JSDoc just can't doc?

Well there are 2 tricks that can get you almost all the way to complete feature parity with Typescript:

Your editor's sneaky little secret
Good old *.d.ts files

Your editor's sneaky little secret

I said earlier that your editor (probably VS Code) uses a Typescript language server to parse and understand your code. Even in Vim I'm using the same language server to check my code (Neovim ftw).

That's the secret!

What do I mean? It is a Typescript Language Server, not a JSDoc Language Server (if that makes sense).

When your editor goes through your code trying to understand it, it does so with a Typescript manual, this means it understands all the JSDoc stuff but also all the Typescript stuff. Here's an example:

import { Quest } from 'quest'

class QuestMap {
    /** @param {ReturnType<QuestMap.toPersistence>} raw */
    static toDomain = (raw) => Quest.create(raw)

    /** @param {Quest} quest */
    static toPersistence = (quest) => ({ target: quest.target, completed: quest.completed })
}

If you look at this line:

/** @param {ReturnType<QuestMap.toPersistence>} raw */

You'll see a Typescript only feature ReturnType that still works because your editor is checking things through a Typescript lens.

I haven't done extensive tests with this but it should generally work for any Typescript feature that you're able to write out in JSDoc syntax.

It does have it's limits, for example, I wasn't able to get this to work:

// some function that returns an arbitrary number of Promise<boolean>
const getBools = () => [Promise.resolve(false), Promise.resolve(true)]
const getString = async => 'Hello'

async function tryToTypeThis () {
    await Promise.all([
        ...getBools(),
        getString(),
    ])
}

async function jsDocPlease () {
    const promises = [...getBools(), getString()]

    // ???
    await /** @type {PromiseConstructor['all']<boolean | string>} */ (Promise.all(promises))
}

const getBools: () => Promise<boolean>[] = () => [Promise.resolve(false), Promise.resolve(true)]
const getString: () => Promise<string> = async => 'Hello'

async function canTypeThis () {
    await Promise.all<boolean | string>([
        ...getBools(),
        getString(),
    ])
}

This is another set of contrived examples and I don't think you should write code like this, but it serves the purpose of showing where JSDoc reaches it's limits.

But there's a solution even to that.

Good old `*.d.ts` files

In our config earlier we had to set checkJs to true, that's because your editor type checks .ts files by default which your definition files fall under.

You might think what's the point of writing definition files, might as well go full Typescript.

To that I say, even in Typescript you'd end up writing some definition files, and using them still gives you all the advantages of only using JSDoc.

With definition files, you get the full feature set of Typescript, but once again you won't need a compile step and during build they get ignored since your project is a JS one (not 100% sure on this, please correct me if I'm wrong).

/** @typedef {import('./types.d.ts').ComplexType} ComplexType */

/** @type {ComplexType} */
const complexVariable = {}

So should you use JSDoc?

If you are in a situation where your project is almost all JS and you're tempted to switch TS but the cost is just too high, this could be an option to consider.

It even has the advantage that if you do make the switch to TS, things will already be typed and documented.

Now of course JSDoc isn't perfect, it's quite a lot more verbose than the equivalent TS and it can sometimes be difficult to find answers to some problems.

In the end it's up to you to evaluate your options and make the choice that's best for you.

Some Helpful resources

When writing JSDoc there are actually 2 syntaxes that you can use, the one described on the official JSDoc site and the Closure Compiler Syntax.

CCS has a few extra features that might only be understood by the Closure Compiler but I have used some of them in JSDoc so your mileage may vary.

Closure Compiler Syntax

Since we're relying on the TS language server to check our JSDoc comments, it's helpful to look at Typescript's own JSDoc reference for what's supported.

Is your app online? Here's how to reliably know in just 10 lines of JS [Guide]

Maximilien Monteil — Sun, 06 Sep 2020 12:34:21 +0000

We usually expect our web apps to be online but that ignores reality.

People go on planes, enter tunnels, have bad internet, or just decide to go offline. Depending on your user's expectations, should your app stop working?

If not, you'll need a reliable way to detect if your app is offline in order to offer the proper experience.

Here's how in just 10 lines of JS.

TL;DR Code is at the bottom for your copy/pasting pleasure!

Browser Navigator

Before coding, let's look at the lay of the land.

Browsers come with the navigator.onLine property. This straight up returns true or false based on the browser state.

function isOnline () {
    return window.navigator.onLine
}

So are we done? Well, because of how it works, you can only trust false to mean offline. true could be more varied.

MDN - Navigator.onLine

So how to tell if you also have access to the internet?

Because of the way navigator works, we know when we're offline but online is a little murky.

Navigator returns true when the device is connected to a network but that doesn't mean you are also connected to the internet which are 2 very different things.

Your first instinct might be to make a request to some random site and seeing if you get a success or an error.

But what kind of request? And to which resource? 🤔

Sending the perfect request ✨

Checking the network status might happen often so ideally our request response should be as small as possible. This will make it faster and it will consume less bandwidth.

To figure what kind of requests are available, we can look at the different HTTP methods and the HEAD method stands out as the best (TRACE might actually be better but isn't supported by fetch).

A HEAD request is almost exactly like a GET request except we get no response data, only the HEADers. This works out great since our goal is to check if the request was successful or not, we don't actually care about any data returned.

Where should you send the request?

We have the perfect request but where should it go?

Your first instinct might be to send it to some service or site that is always active. Maybe google.com? But try that and you will be greeted by CORS errors.

This makes sense, Google (and every other site by default) won't accept requests from random sites.
The next option is to make your own server or cloud function that would accept requests exclusively from your application!

But that's far too much work for a simple network check and a good developer is a lazy developer.

So back to square one, CORS errors.

Their goal is prevent security issues on requests coming from a different origin. Then wouldn't it be possible send the request to your own origin?

The answer is yes! And you can automatically get your origin with window.location.origin.

async function isOnline () {
  if (!window.navigator.onLine) return false

  const response = await fetch(
    window.location.origin,
    { method: 'HEAD' },
  )

  return response.ok
}

Now you can ping your own site and wait for a response, but the problem is since we always send the same request to the same URL, your browser will waste no time caching the result making our function useless.

So the final trick is to send our request with a randomized query parameter!
This will have no impact on the result and will prevent your browser from caching the response since it goes to a different URL each time.

And thanks to the built-in URL class, we don't even need to manually manipulate strings.

Here is the final code along with some extra error handling.

getRandomString () {
  return Math.random().toString(36).substring(2, 15)
}

async function isOnline () {
  if (!window.navigator.onLine) return false

  // avoid CORS errors with a request to your own origin
  const url = new URL(window.location.origin)

  // random value to prevent cached responses
  url.searchParams.set('rand', getRandomString())

  try {
    const response = await fetch(
      url.toString(),
      { method: 'HEAD' },
    )

    return response.ok
  } catch {
    return false
  }
}

This gives us a more reliable check on the network's status but it is missing some configuration options.

Notably we always check with the same URL. This could be fine but what if you would prefer to ping your own server or just something closer to reduce latency?

Additionally this runs only on call, it might be useful to be able to pass a callback, or have some kind of observer.

You do get event listeners when the network status changes...

window.addEventListener('online', () => console.log('online'))
window.addEventListener('offline', () => console.log('offline'))

The final result here is very simple and I leave it up to you to expand this to fit your needs!

Thanks for reading this article! Let me know what you think in a comment or message me directly on twitter @MaxMonteil

Quickly build a performant Landing page with Nuxt

Maximilien Monteil — Wed, 15 Jul 2020 06:48:36 +0000

I've been building Mylo (a more intelligent workout assistant) but contrary to popular advice, I started building the app and completely ignored making a landing page. I should have taken that advice 😔

There are all the usual reasons like letting you build hype and gather email addresses, but the biggest impact I've noticed is how 'real' it makes the project. It's no longer an idea in your head but a landmark that others can see giving them the chance to understand you.

Determined to make a landing page, I decided to learn Nuxt, let me share what I learned to help you make your own page and get amazing scores in Lighthouse.

Setup

Setting up your nuxt project is pretty straightforward, as per nuxt's getting started guide, run this command:



$ npx create-nuxt-app <project-name>

When you go through the setup cli make sure to select 'static' as the target, it's a brand new option in Nuxt that will let you generate a fully static version of your site. This will make it load much faster, and you can benefit from free hosting on most CDNs, like Netlify.

Add the generate command to your package.json:



{
    // ...
    "scripts": {
        // ...
        "generate": "nuxt build && nuxt export",
    }
    // ...
}



$ cd <project-name>
$ npm run dev

After that you're pretty much dealing with standard Vue. I won't go into all the details of Nuxt because you won't need most of them for a simple landing page like this one, but here is a brief primer of what you do need:

Directory structure

Unlike Vue, which essentially dumps you in the desert with nothing but a src folder, Nuxt leaves you by the oasis 🌴
You're given a few folders to help you get started, here are the ones you will definitely need:

assets - static assets that you want Nuxt to bundle/transform for you (images, SVG, CSS)
components - your usual components like buttons, modals, forms, etc.
layouts - these are also components but they handle full page elements like a header, footer, sidebar, etc.
pages - each file/folder here will get mapped to a URL of your site
- index.vue -> yoursite.com/
- about.vue -> yoursite.com/about
- blog/welcome.vue -> yoursite.com/blog/welcome

Generally a landing page is rather light in interactivity so you might find yourself writing very little JS, and might not use the other Nuxt features like asyncData.

If you want to check out the code behind Mylo's homepage, I've open-sourced it here: Github - MyloWebsite

Improving Lighthouse

Making the site itself is only the first step though, we need to make sure performance is great, a slow site doesn't make for a great first impression of your product or service.

So first, go ahead and run a Lighthouse audit to get an idea of where things stand.

Before optimizing 😰

These scores aren't all that great, the performance one is downright horrible. But here's where a few changes get me 😎

Performance

The biggest issue I was running into were caused by SVGs.

When it comes to icons I generally prefer to use SVGs over images, they often result in smaller file sizes, can be modified with CSS, and can be resized without any loss of quality.

Now there are many ways to embed them into your site depending on what you need. I needed to be able to modify their color with CSS so I inlined them.



<template functional>
  <svg
    xmlns="http://www.w3.org/2000/svg"
    :width="props.size"
    :height="props.size"
    viewBox="0 0 16 16"
    :aria-labelledby="props.labelledby"
    role="presentation"
  >
    <title lang="en">logo icon</title>
    ...
  </svg>
</template>

This works great for simpler SVGs like the logo. But when I inlined a more complex one (multiple times) it made the DOM huge, filling it with giant SVG tags that the browser had to parse through, giving me that performance score of 13.

The solution then was to embed them in an <img /> tag. This way you avoid adding thousands of DOM elements while still benefiting from caching, but you lose the ability to color them with CSS...



<img :src="require('~/assets/images/sports_icons.svg')" />

Or do you?

Turns out there are a couple of ways to change the color of an SVG even if embedded this way. They involve using combinations of CSS filters to get the color you want.

You can find more information on how to do that in this post:
CSS Tricks - Change SVG fill on hover

But these filters aren't very intuitive to combine into the color you want, luckily I found this codepen which can convert a HEX value into the matching set of CSS filters:
Generate filters for a hex



<img

    :src="require('~/assets/images/sports_icons.svg')"

    class="fill-green"

/>



.fill-green {

  filter: invert(91%) sepia(10%) saturate(1436%) hue-rotate(90deg) brightness(94%) contrast(93%);

}

Accessibility - color contrast

Another issue I had was poor color contrast.
In most design tools you start off by creating a nice color palette which you then tweak to get proper contrast.

What if you could do things the other way around? That's what Leonardo Color does. You set your base color(s) and from there generate additional colors that achieve the contrast ratios you need to pass the WCAG's criteria.

And here is another tool you can use to check contrast between colors: WebAIM Contrast Checker

Conclusion

Making a landing page really is a good first step, it seemed like such a daunting task to me but ended up being much easier to create than my actual project.

Turns out I was just scared of how concrete it would make Mylo feel, because now the whole world can see and criticize it, but in the end, what better way is there to improve?

Let me know what you thought of this post and if you check out Mylo I'd love to hear your feedback!😁

P.S. Here's one more tip

Making the landing page is cool and all but you're likely going to need a way to contact those who sign up, and it looks more professional to have an email address on at a custom domain.

contact@<your-project>.com

Some hosting services offer emails but I use Netlify which doesn't offer this and getting such an address is usually a paid service but I found this guide to set you up for free!

How to setup a custom email address for free

How to start Coding up your Design System in Vue

Maximilien Monteil — Fri, 31 Jan 2020 19:23:24 +0000

Imagine this, you create your web app for this new epic idea and you implement the core functionality. The design can come later you think.

Well later is now, you're gaining traction and getting feedback, the time has come to overhaul or completely recreate your design!

In this article I'll go over the tools and methods you can use to achieve just that.

I personally fell into this situation with my web app Mylo, a workout management application. As it grew and came into contact with users, issues arose with color contrast, inconsistencies, and more.

Fixing these issues can be described in two pillars:

Design System (how everything will look)
Implementation (how to apply the look)

(I focus on look here but understand that design is only about 20% look, the rest must be considerations about the user experience)

Going through this has taught me a lot but also made obvious how much more there is to learn. If you find any mistakes or have some tips please let me know :D

I'll be using TailwindCSS in this article but everything applies just as well without.

Directory Structure
Colors
Icons
Buttons
Text Inputs
Radio Buttons
Select Input
Conclusion

Pillar 1: Design System

The first step, which is all the rage these days, is having a design system. A design system is essentially a visual codebase of your software, and just like a codebase, it is a complete and specific description of what the application should look like under almost any circumstance.

And so, the more you look into what makes up a design system, the more it feels like an impossible task. A complete design system involves the colors, spacing rules, text styles, buttons, containers, branding, accessibility, and so much more.

The best and most exhaustive resource I've found is the Design System Checklist.

Therefore I feel more comfortable referring to what I have as a design library with loose guidelines. It works out because I can just refer to myself for any design questions ;)

So we'll be going over how to implement elements like buttons, icons, colors and a few input types.

Pillar 2: Implementation

Directory Structure

Coding up design elements is amazing for reusability and consistency but it isn't very useful if components are all across the app in random, hard to access locations. We want them organized.

I recommend putting the smallest/atomic elements into the src/components folder and then into their own subfolders (icons, inputs, buttons, etc.)
Compound components, built out of the smaller ones, can be placed into the src/layouts folder, again with their own subfolders.

Colors

Defining and enforcing colors is a good first step.

You generally have a clear discrete set of colors that your app allows, to bring them in you can either modify the TailwindCSS config file or add them as CSS variables.

Here is how it looks in TailwindCSS, I overwrote the default colors to enforce the use of the system colors but you can also extend the default theme and add your own colors.

// tailwind.config.js

module.exports = {
  theme: {
    colors: {
      white: '#FFFFFF',
      black: '#000000',
      gray: {
        default: '#EEEEEE',
        dark: '#5D5D5C',
        darker: '#414040'
      },
      green: {
        default: '#83E8BC',
        dark: '#56806C',
        darker: '#445F51'
      },
      red: {
        default: '#F25F5C',
        dark: '#C15450',
        darker: '#8B4440'
      }
    }
  }
}

TailwindCSS Docs - Theme Configuration

If you're not using tailwind this can also be achieved using css variables like so:

/* src/App.vue */
:root {
  --white: '#FFFFFF';
  --black: '#000000';
  --gray: '#EEEEEE';
  --gray-dark: '#5D5D5C';
  --gray-darker: '#414040';
  ...
}

Icons

First off I recommend using SVG icons because of how configurable they are. You can change their size without any quality loss, dynamically change their color, and their file size is generally smaller than an equivalent png/jpg.

Getting the actual SVGs can be done through the export options of design tools like Figma, Sketch, or Illustrator.

Once you have the files you can further optimize them with SVGO, there is a command line tool and a web based one.

svg / svgo

⚙️ Node.js tool for optimizing SVG files

jakearchibald / svgomg

Web GUI for SVGO

Both work automatically by pointing them to the file though the web version makes the available options more accessible. Make sure to have a look at the final result to make sure your icons still look fine.

Then we bring the icons into our Vue app, I used a method recommended in the Vue Cookbook. It's a system made by Sarah Drasner, the SVG queen, and you can find the link for it here.

To make it work with TailwindCSS, you'll need to make a couple of changes:

<template functional>
  <svg xmlns="http://www.w3.org/2000/svg"
    :width="props.size"
    :height="props.size"
    viewBox="0 0 16 16"
    :aria-labelledby="props.iconName"
    role="presentation"
    class="fill-current inline-block align-baseline"
    :class="[
      data.class,
      data.staticClass
    ]"
    style="margin-bottom: -2px;"
  >
    <title lang="en">{{ props.icon.replace(/-/g, ' ') }} icon</title>
    <component :is="injections.components[props.iconName]" />
  </svg>
</template>

Since SVGs themselves are rather light, it felt like a lot of overhead to use full components, so I made some further changes to make use of functional components, you can check out my fork here:

MaxMonteil / vue-sample-svg-icons

An opinionated example of how to use SVG icons in a Vue.js application as functional components

Buttons

Initially I wanted to bring in buttons the same way as with icons, using Vue components but that ended up being deceptively complicated. The component had to work with buttons, links, or a router-link (using vue-router).

Supporting links was important for accessibility and semantics as links are meant to take you to another page whereas buttons should not.

As a solution I extracted the common classes into their own utilities in TailwindCSS, which in pure css is just a normal class rule.

Some examples:

@tailwind base;
@tailwind components;

.btn {
    @apply font-medium rounded align-bottom;
}

.btn-primary {
    @apply px-8 py-2;
}

.btn-secondary {
    @apply px-5 py-1;
}

.btn-white {
    @apply text-green-darker bg-white;
}

.btn-green {
    @apply text-white bg-green-dark;
}

@tailwind utilities;

Text Inputs

For inputs we can use Vue components but there are a few things to take into consideration.

Our wrapper components need to be lightweight and transparent, we can do that by using functional components and attaching all attributes and event listeners.

I also took the chance to include the label into the component. It fits the design, is more accessible, and ensures I never forget them.

Start off with a BaseInput.vue component:

<!-- src/components/inputs/BaseInput.vue -->
<template functional>
  <label
    :ref="data.ref"
    class="text-sm leading-none font-medium"
    :class="props.makeGray ? 'text-gray-darker' : 'text-green-darker'"
  >
    {{ props.label }}
    <input
      type="text"
      :ref="data.ref"
      class="block mt-2 bg-white rounded w-full outline-none focus:shadow"
      :class="[
        data.class,
        data.staticClass,
      ]"
      :style="[
        data.style,
        data.staticStyle,
      ]"
      v-bind="data.attrs"
      v-on="{ ...listeners, input: e => listeners.input(e.target.value) }"
    >
  </label>
</template>

And here is an example use of BaseInput.vue:

<!-- src/components/inputs/InputLarge.vue -->

<template functional>
  <component
    :is="injections.components.BaseInput"
    :label="props.label"
    :makeGray="props.makeGray"
    class="font-medium text-3xl text-black pl-4 py-px"
    :class="props.makeGray ? 'bg-gray' : 'bg-white'"
    v-bind="data.attrs"
    v-on="listeners"
  />
</template>

<script>
import BaseInput from '@/components/inputs/BaseInput'

export default {
  name: 'inputLarge',
  inject: {
    components: {
      default: {
        BaseInput
      }
    }
  }
}
</script>

Notice how we call the BaseInput.vue component. Surprisingly, imported components are not exposed in functional components when using the template format. So instead we place the imported components into injections. They could also placed into props if you prefer.

This method was brought up in this github issue:

Functional single file component with components option. #7492

terrierscript posted on Jan 21, 2018

Version

2.5.13

Reproduction link

NG pattern (functional) https://codesandbox.io/s/004vv2onw0

OK pattern (no functional) https://codesandbox.io/s/q9k5q8qq56

Steps to reproduce

I found can't use components option when functional single file component.

<template functional>
  <div>
    <some-children />
  </div>
</template>

<script>
import SomeChildren from "./SomeChildren"

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

It's occure Unknown custom element.

What is expected?

Not occure Unknown custom element and use child component

What is actually happening?

It's occure Unknown custom element

In workaround, it not occure when use Vue.component.

import Vue from "vue"
import SomeChildren from "./SomeChildren"
Vue.component("some-children", SomeChildren);

export default {}

// can use  <some-children />

View on GitHub

Radio Buttons

After all the elements we've done so far, Radio Buttons are not too different. The difference is that styling them can be more involved. While it is possible to use standard buttons instead, I wanted to use the default radio buttons, again for semantics and accessibility.

The trick I found was to use the behavior of labels wrapping radio buttons.
The buttons by themselves are small and hard to touch/click but if you wrap them in a label, clicking anywhere on the label box will also select the radio button.
Using this, I styled radio buttons by actually making the label look as I wanted and hiding the radio buttons inside the label.

<template functional>
  <div
    :ref="data.ref"
    :class="[
      data.class,
      data.staticClass,
    ]"
    :style="[
      data.style,
      data.staticStyle,
    ]"
  >
    <label
      v-for="label in props.labels"
      :key="label.value || label"
      class="relative px-3 py-1 rounded"
      :class="(label.value || label) === props.modelValue ? '...' : '...'"
    >
      <slot :label="label">
        {{ label.text || label }}
      </slot>
      <input
        :ref="data.ref"
        type="radio"
        class="sr-only"
        :value="label.value || label"
        v-on="{ ...listeners, input: e => listeners.input(e.target.value) }"
        :checked="(label.value || label) === props.modelValue"
      >
    </label>
  </div>
</template>

Be careful when hiding the radio button as it still needs to be visible to screen readers, tailwind offers a class for this, in standard css that looks like this:

.sr-only {
  position: absolute;
  width: 1px;
  height: 1px;
  padding: 0;
  margin: -1px;
  overflow: hidden;
  clip: rect(0, 0, 0, 0);
  white-space: nowrap;
  border-width: 0;
}

As for the v-slot and all the ORs (||), I explain those in the next section about select inputs.

A really helpful resource that also goes over checkboxes:

Smashing Magazine - Creating Custom Inputs in VueJS

Select Input

The select component is a fun one to wrap both in terms of design and functionality.

Design wise it was surprising to discover how "hacky" it is to change the default downward arrow. There are a few ways to do it but the trick I went with is to remove the default style by setting appearance: none; and then bringing in my SVG of choice with the URL function of CSS.

To do something similar you will need to encode your SVG tag into a URL compatible string, I found this site to do just that:

URL Encoder for SVG

Then there are a few more positioning and spacing styles to place the icon where you want.

For functionality, the end user should retain control over how the drop-down values are displayed, the go to solution is to use scoped slots. With this method our component can support any array of values.

This is because the official Vue doc shows examples using a String Array and an Object Array to populate the select.

<template functional>
  <label
    class="text-sm font-medium text-green-darker"
  >
    {{ props.label }}
    <select
      :ref="data.ref"
      class="custom-arrow bg-no-repeat block mt-2 pl-2 pr-6 bg-white rounded text-black text-lg outline-none focus:shadow"
      :class="[
        data.class,
        data.staticClass,
      ]"
      :style="[
        data.style,
        data.staticStyle,
      ]"
      v-bind="data.attrs"
      v-on="{ ...listeners, input: e => listeners.input(e.target.value) }"
    >
      <option disabled value="">-</option>
      <option
        v-for="option in props.values"
        :value="option.value || option"
        :key="option.value || option"
      >
        <slot :option="option" />
      </option>
    </select>
  </label>
</template>

<script>
export default {
  name: 'inputSelect',
  props: {
    label: {
      type: String,
      require: true
    },
    values: {
      type: [Array, Object],
      require: true
    }
  }
}
</script>

<style scoped>
.custom-arrow {
  -moz-appearance: none;
  -webkit-appearance: none;
  appearance: none;
  background-image: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='12' height='10'%3E%3Cpath fill='%23000000' d='M7.443 9.057L5.229 6.843a.666.666 0 01.943-.942l2.214 2.214 2.199-2.199a.666.666 0 11.942.942l-3.142 3.143-.942-.944z'/%3E%3C/svg%3E");
  background-origin: border-box;
  background-position: top 35% right 0.5rem;
}
</style>

These wrapper components also offer the chance to enforce best practices like a label for an input and an empty disabled first option for better iOS support.

Conclusion

Well you've reached the end, this covers all the components I brought in from my design library. It really just scratches the surface of what is possible and I couldn't hope to be fully exhaustive. Nonetheless, I hope this helped you out and encouraged you to tackle that redesign or even just start to design!

The next step after wrapping all these input fields would be to compose them into a form or other layout for reuse, these are some of the components you'd place into the src/layouts folder. You can expect a follow up article once I finish it up myself :D

Feel free to leave any comments below and if you have questions or want to follow up, you can find me on twitter @MaxMonteil

DEV Community: Maximilien Monteil

Firebase + Algolia: How to set up transform functions

What is a transform function

How to add a transform function to Algolia Firebase

Creating

About nested fields

Re-indexing

Conclusion

Add Typescript to your JS project in 1 line

Why Typescript in the first place?

Define all your domains.

Your editor's sneaky little secret

Good old *.d.ts files

So should you use JSDoc?

Some Helpful resources

Other Links

Is your app online? Here's how to reliably know in just 10 lines of JS [Guide]

Browser Navigator

So how to tell if you also have access to the internet?

Sending the perfect request ✨

Where should you send the request?

Quickly build a performant Landing page with Nuxt

Setup

Directory structure

Improving Lighthouse

Performance

Or do you?

Accessibility - color contrast

Conclusion

P.S. Here's one more tip

How to start Coding up your Design System in Vue

Table Of Contents

Pillar 1: Design System

Pillar 2: Implementation

Directory Structure

Colors

Icons

svg / svgo

⚙️ Node.js tool for optimizing SVG files

jakearchibald / svgomg

Web GUI for SVGO

MaxMonteil / vue-sample-svg-icons

An opinionated example of how to use SVG icons in a Vue.js application as functional components

Buttons

Text Inputs

Functional single file component with components option. #7492

Version

Reproduction link

Steps to reproduce

What is expected?

What is actually happening?

Radio Buttons

Select Input

Conclusion

Good old `*.d.ts` files