DEV Community: Alex Chiu

Easy React data fetching with the new `use()` hook

Alex Chiu — Sat, 27 May 2023 15:38:21 +0000

React.use() is still an unstable API. For more information check out the support for promises React RFC . At the time of writing this, you can only test this API in Next.js 13.

OK with that disclaimer out the way, lets talk about how use() works .

In short, this new hook will let you you run asynchronous code in your client-side react components. You can think of it as the React version of async / await.

To appreciate why it's going to be a game changer for client side data-fetching, lets compare the old-way of doing a client-side data fetch using useEffect() with use().

// returns an array of user objects e.g:
// [ {id:1 name: "Leanne Graham"}, {id:1 name: "Ervin Howell"}] 

export const fetchUsers = async () => {
  const resp = await 
  fetch("https://jsonplaceholder.typicode.com/users");
  const json = await resp.json();
  return json; 
};

'use client'

import { useState, useEffect } from "react";
import { fetchUsers } from "@/fetch-users";


export const OldDataFetchData = () => {

const [usersData, setUsersData] = useState(null);


useEffect(() => {
    if (!usersData) {
        const startFetchingData = async () => {
            const users = await fetchUsers();
            setUsersData(users);
        };
           startFetchingData();
    }

    }, [usersData]);



    if (!usersData) {
        return <>Loading...</>;
    }

    return (
        <>
            {usersData.map((u) => (
                <div key={u.id}>{u.name} </div>
            ))}

        </>
    );

};

This is idiomatic code for most React developers. But for those less familiar with React and useEffect you may ask all sort of questions like:

Why cant the function you pass into useEffect be async?
Why cant the whole React component be async?
Why do you need to check userData before calling startFetchingData()?

There are technical answers to all of these,but this is not a useEffect tutorial so a quick response would be - because, React. 😅

My point is, this is not intuitive code to read but we React developers have become accustomed to the rules and quirks of useEffect.

Now lets see how can re-write this with use() .

'use client'

import { use } from "react";
import { fetchUsers } from "@/fetch-users";

export const NewDataFetchData = () => {

const usersData = use(fetchUsers());

return (
    <>
        {usersData.map((u) => (
            <div key={u.id}>{u.name} </div>
        ))}
    </>
);

};

Thats's it!

Ok I lied.

A little bit more code is required If you want to handle a loading state. In the parent server component that uses this client component, you can wrap it in Suspense which can accept a React component in its fallback prop.

// ./app/page.jsx

import { Suspense } from "react";
import { NewDataFetchData } from "@/components/NewDataFetch";  

export default function Home() {
    return (
        <main>
            <Suspense fallback={<>Loading...</>}>
                <NewDataFetchData />
            </Suspense>
        </main>
    );
}

Overall, much more elegant to read and write.

An interesting property of the use hook is that it can be called conditionally 🤯.

This is a big deal because we've traditionally never been able to usehooks conditionally.

Here is an example of how this could look taken from the rfc.

function Note({id, shouldIncludeAuthor}) {
  const note = use(fetchNote(id));

  let byline = null;
  if (shouldIncludeAuthor) {
    const author = use(fetchNoteAuthor(note.authorId));
    byline = <h2>{author.displayName}</h2>;
  }

  return (
    <div>
      <h1>{note.title}</h1>
      {byline}
      <section>{note.body}</section>
    </div>
  );
}

I'm excited for this hook to become stable but I have mixed emotions.

On one hand, the ergonomics of data fetching will be so much better and we may no longer need to rely of a third party libraries like TanStack query.

On the other hand, our mental model of hooks needs to adjust when using use(), maybe this is not a big deal, but I can see this being a point of confusion for beginner React devs.

If you want to test out the use() for yourself, feel free to fork this codesandbox which is running the code examples above.

How to use npm modules client-side in Astro.js `.astro` files

Alex Chiu — Wed, 13 Oct 2021 18:43:59 +0000

I've been playing with Astro some more and finally got my head around how to use npm modules client side in a .astro file. It's not that obvious...

First thing I tried was something like this:

<!-- Test.astro -->
<canvas class="webgl"></canvas>

<script type="module"> 
 import * as THREE from 'three'

 console.log(THREE) //undefined :(
</script>

This returns Uncaught TypeError: Failed to resolve module specifier "three". Relative references must start with either "/", "./", or "../". in the console.

Astro doesnt let you import npm modules in inline script tags within .astro unfortunatley. However we can import in an external .js/.ts file, then make use of Astro.resolve like so:

<!-- Test.astro -->
<canvas class="webgl"></canvas>

<script src={Astro.resolve('./myScript.js')} type="module"/>

Inside myScript.js we can import things as expected.

// myScript.js
import * as THREE from 'three';

console.log(THREE) // Three.js module!

Working demo here.

What Inspired You To Learn To Code?

Alex Chiu — Thu, 11 Mar 2021 16:10:32 +0000

I hacked together something special to me yesterday. I've been keeping it running in the background and found that It's extremely relaxing.

A week off work with nothing to do. So I made a thing.

🎶 Musical OSM Edits...https://t.co/07ZeNrjYWf

🔊 Sound on and relax... pic.twitter.com/2pA8AIslNP
— 𝘈𝘭𝘦𝘹 𝘊𝘩𝘪𝘶☁ (@chiubaca) March 10, 2021

It's special because it was directly inspired by a CodePen I saw a few years ago called Trams of Helsinki. I promised myself that I would create something similar once I learnt how to code.

Coming from a background in GIS (Geographical Information Systems) I've always been drawn to map oriented data visualisations. You can get pretty far with desktop applications such as QGIS and ArcMap. But I was always impressed with those who could create these data visualisations using code.

2017 was when I decided I was going to transition my career from a GIS consultant to web-developer. During this time I self-taught myself with texts books, Free Code Camp and lots of YouTube!

Somewhere along this journey, I forgot about what originally inspired me to start this journey in the first place. It was to create Whimsy and interesting data visualisations!

It kind of felt like I brought my coding journey full circle by creating this. It's interesting and constructive to look back on how far you've come sometimes.

Tell me about what inspired you to start your coding journey!

Building My New Blog | Nuxt Vs Gridsome

Alex Chiu — Sun, 17 Jan 2021 10:11:24 +0000

🥅 The Goal

I had three criteria's for my new blog :

I wanted to use DEV.to as a CMS for my blog.
I wanted my blog to be statically rendered for performance, SEO and to keep the cost of hosting free by hosting it on Netlify.
I had legacy blogs in markdown files which I wanted to host along with the rest of the blog.

To achieve this, I experimented with both Nuxt and Gridsome. This is my experience with both frameworks.

🎬 Take 1 - Nuxt

First, addressing my old markdown blogs. Nuxt recently released the content module which was perfect for rendering my old markdown files into individual pages.

To build the rest of the blog, Nuxt has a new Full Static mode which was released in version 2.14.0.

This mode used in conjunction with Nuxt's asyncData hook means it is possible to fetch all DEV.to blogs post via the DEV.to API at build time. When we run npm run generate to build the blog, Nuxt auto-magically pre-renders each page of your Nuxt site into static HTML pages.

How this works at high level. In my .src/pages/index.vue file, the home page of the blog, I fetch a list of all published posts from the DEV.to API using the /articles/me endpoint. This data fetching is done within the asyncData hook and this endpoint returns an array of your published posts. With the data retrieved, I list each of the posts, and link to a new page by making use of the <nuxt-link> router component. I re-use the DEV.to post slug for the sub-paths of each of the blogs, like so:

<div v-for="(post, index) in posts" :key="index">
    <nuxt-link :to="`/${post.slug}`">{{ post.title}}</nuxt-link>
</div>

Nuxt handles routing based on the file structure of your pages directory, so by creating a _slug.vue file relative to where the index.vue file is. Nuxt knows that this will be the template for any sub paths off that page.

Within _slug.vue, we make use of asyncData lifecycle hook again to make another call to the DEV.to API, which will retrieve the specific blog based on the slug using the /articles/{username}/{slug} endpoint. This returns an object of the specific post and one of the properties is body_markdown. This is the raw markdown of your Dev.to post. Converting this to HTML and making it look nice is another challenge within itself, but once done you can render this directly in the Vue template using Vue's v-html directive. You can see how I did it here (warning very messy code!!).

What's key here is that when building this application in static mode, Nuxt will perform all the actions in the asyncData hook at build time!

Although I was happy with the end result. I realised there is a lot of logic in the asyncData lifecycle hook. Data fetching, markdown parsing and potentially extra data cleaning logic which I would need to implement later. I also had plans to extend the data fetching to alternative sources such as other Forem sites, Medium and GitHub. I felt like this could get pretty unwieldy if I didn't adopt a nice pattern. This is what lead me to Gridsome.

🎬 Take 2 - Gridsome

The main selling point of Gridsome is the GraphQL data layer. Gridsome provides a simple API to import data from any external source into a data layer. This normalises all your content into a user-friendly GraphQL API.

Also, Gridsome has a growing number of source plug-ins which are helpers to pull data from an external source and import it into the GraphQL data layer.

To read in my old markdown blogs I was able to make use of the filesystem source plug-in. This allows me to create pages for each of my old markdown blog with minimal effort.

Next was to connect Gridsome to DEV.to. There were already plug-ins for this but I decided to hand roll my own as a learning exercise 🤓.

I was able to copy most of my data fetching logic from the Nuxt version of my blog, but I had to write some additional code to import the DEV.to posts into GraphQL using Gridsome's Data Store API. You can see how I did this here.

Once all my DEV.to blogs are loaded in the data layer we can work with this data in any .vue file in the Gridsome project via the <page-query> or <static-query> blocks. Within this block, you can write a GraphQL query and the result is exposed in your <template> via the $page object. The Gridsome docs explain this a lot better!

Similar to Nuxt, Gridsome also has a ./src/pages/ directory and also it's own router component, g-link. This is how you list the titles of all your DEV.to posts and link to them:

<template>
    <div v-for="blog in $page.articles.edges":key="blog.node.id">
     <g-link :to="blog.node.slug">{{ blog.node.title }}</g-link>
    </div>
</template>

<page-query>
  query {
    articles: allDevToArticles{
      edges {
        node{
          title
          slug
        }
      }
    }
  }
</page-query>

Whereas Nuxt crawls your entire application to figure which pages it needs to generate. Gridsome is smart enough to generate a page for each node in for all your GraphQL collections*.

*The aggregation of all Dev.to blogs in the Gridsome data layer, is referred to as a "collection" each blog is referred to as a "node".

To work with these pages we create a .vue file in the ./templates directory in the Gridsome project. This is the equivalent of the _slug.vue file in the Nuxt version of the blog.

The name of this template file should be the same as the collection name. Though this can be configured to your liking in gridsome.config.js.

With that setup, I now had parity between both Nuxt and Gridsome implementations of my blog.

Closing Thoughts

Why I Chose Gridsome Over Nuxt

Overall I felt like the architecture for Gridsome was much better suited for my blog. I liked that there is a separation of concerns with data fetching. All of this logic was contained in my Dev.to source plug-in. This meant I only needed to focus on the organisation of pages and design in the Gridsome codebase.

Nuxt Is Still Great

I think Nuxt is perfect for more complex Vue applications.
There was nothing wrong with having too much logic in the asyncData hook. This was just a personal opinion.
If you are only working with markdown files for your blog, the content module is perfect!

Cons of Gridsome

It's still not at a 1.0 release.
Development doesn't seem to be as active as Nuxt.
Developer experience improvements on the <page-query> and <static-query> blocks. Is it possible to have GraphQL autocompletion somehow?
More documentation for plug-ins. Creating a source plug-in was a good experience, but I had difficulty understanding how to use transformer plug-ins

This was a quick comparison between two great Vue.js meta frameworks. Are you planning to work with Nuxt or Gridsome any time soon? Let me know.

If you're reading this on DEV.to, you check out my new blog site here 👇

✨ chiubaca.com ✨

Free Web Tools & Utils

Alex Chiu — Fri, 25 Dec 2020 21:54:48 +0000

The web is amazing. There are so many handy free web tools out there. Every time I come across something useful I bookmark it. Recently these bookmarks are starting to get out of hand. Therefore, I've organised and open sourced my list so that others can benefit from it too. If you've stumbled across this, I hope you find it useful.

chiubaca / free-web-tools-and-utils

My list of free web tools & utils from around the internet.

Free Web Tools & Utils 🙌

A list of free web tools & utils from around the internet which I have found useful. Yes there are probably other similar repos but this is mine ☺.

Searchable and sortable Notion version

Design

Colorsinspo - All in one resource for finding everything about colors | Colorsinspo

Seamless Pattern Maker - Create Unlimited Seamless Patterns For Free

Create a palette - Coolors

Avataaars Generator - A free online avatar generator for anyone to make their beautiful personal avatar easily!

Colors UI - Colors UI is color tool website.

Diagrams

Coggle- Flow Diagrams

Flowcharts | Diagrams Software

Excalidraw | Hand-drawn look & feel • Collaborative • Secure

Graphics

Figma

Squoosh

Shrink Me - Compress JPG, PNG, WEBP, and SVG Images

Photopea | Online Photo Editor

gifski — highest-quality GIF converter

SvgPathEditor

Free Favicon Maker — Create…

View on GitHub

Is there something you think should be on the list? Please let me know or feel free to submit a pull request.

Using JavaScript to write PostgreSQL functions

Alex Chiu — Sat, 12 Dec 2020 21:20:51 +0000

If you're new to PostgreSQL, just understand you can write functions or stored procedures to conveniently capture and reuse processes.

PostgreSQL includes it's own lanaguge called PL/pgSQL which is an extension of the SQL language. It makes it more powerful by enabling things like variables and loops to write more versatile logic.

Here is a very primitive calculator function written in PL/pgSQL.

create or replace function calc_plpgsql(x int, y int, func text)
returns int
as
$$
declare
 result int = null;
begin
    if func = '+' then
        result =  x + y;
    elsif  func = '-' then
        result = x - y;
    elsif  func = '*' then
    result = x * y;
    elsif  func = '/' then
    result = x / y;
    else
        raise exception 'Invalid function provided';
    end if;

    return result;
end
$$
language plpgsql;

select calc_plpgsql(5,5,'+') -- returns 10

To break this down. First we're creating a new function called calc_plpgsql. This takes three arguments x, y and func. x and y are both integers, and func will be a string which will signify the calculation function to perform e.g '+', '-' , '*' or /.

Note, we wrap our logic for the function in $$. This is known as dollar-quoted strings and is equivalent to template literals in JavaScript. It is a very common pattern when writing functions and stored procedures in PostgreSQL. It allows us to write any code between the $$'s without needing to escape single quotes and backslashes which can produce un-readable code.

Next, we can make use of if, elsif and else for conditional logic to detect what was passed into the func argument.

The last line is interesting. We state the language we want PostgreSQL to parse in the dollar quoted string. In this example we are using language plpgsql.

When I first saw this it got me thinking. "Does this mean we can use other languages too!?". Turns out you can. PostgreSQL also supports other procedural languages such as Python, C and my favourite, JavaScript!

To be able to write JavaScript for your PostgreSQL function, you have to ensure that PL/v8 has been installed on your database server. If not, then there are a couple of additional steps required.

Once installed you can run:

CREATE EXTENSION plv8;

To test Pl/v8 ready, we can run:

SELECT plv8_version(); -- shoud show something similar to `3.0alpha`

Now lets rewrite our calculator function in JavaScript.

create or replace function calc_plv8(x int, y int, func text)
returns int
as
$$
if (func === '+'){
    return x + y
}
else if (func === '-'){
    return x - y
}
else if (func === '*'){
    return x * y
}
else if (func === '/'){
    return x - y
} else {
    plv8.elog(ERROR, 'invaid function');
}
$$
language plv8;

select calc_plv8(5,5,'+') -- returns 10

How fun is that?

Note, we're using the V8 JavaScript engine inside the context on a database engine so this is not node.js or a browser. This means we don't have access to all the APIs you may expect, such as console.log, instead you'll need to use plv8.elog. Also don't expect to be able to import libraries from NPM or anything! Nonetheless, I thought it was interesting to know this is possible.

If you want an easy way to test this out, I recommend spinning up a PostgreSQL database via https://supabase.io. It's free!

Shiba Every Hour - A Twitter bot powered by GitHub Actions

Alex Chiu — Wed, 19 Aug 2020 20:00:02 +0000

My Workflow

My GitHub action posts a new picture of a Shiba to ShibaEveryHour every hour. The bot was previously working off an Azure serverless function. But for this hackathon, I have moved it into a GitHub Action.

Submission Category:

If it's not obvious already, this is one for the Wacky Wildcards 😂.

Yaml File or Link to Code

chiubaca / shiba-every-hour

GitHub Action to post a Shiba to Twitter every hour. Because why not? 🐕

Shiba Every Hour

posting shibas around the the inter-webs hourly

wow

site	status
x.com/ShibaEveryHour
mas.to/@ShibaEveryHour
shibaeveryhour.bsky.social

View on GitHub

Additional Resources / Info

ShibaEveryHour the Twitter bot
https://shibe.online/ for the Shiba pics

TypeScript and Netlify Functions

Alex Chiu — Sat, 18 Jul 2020 13:25:17 +0000

Did you know that Netlify Functions are just using AWS Lambdas behind the scenes?

This means you can use the same type definitions available for aws-lambda for your Netlify functions too. Install the aws-lamda types by running the following.

npm install @types/aws-lambda --save-dev

You only need to import the APIGatewayProxyEvent, APIGatewayProxyCallback types like so.

import { APIGatewayProxyEvent, APIGatewayProxyCallback } from "aws-lambda";

export const handler = async function (
  event: APIGatewayProxyEvent,
  context: any,
  callback: APIGatewayProxyCallback
) {
  // Do some stuff here 
};

Note, there are no type declarations available for context as this includes properties and methods specific to Netlify such as Netlify Identity .

However, having auto completion for event alone makes this hugely useful!

I'm putting together some TypeScript Netlify Functions examples over at this repo. Feel free to give it a star if you find it helpful.

Managing your self-learning

Alex Chiu — Wed, 22 Apr 2020 10:25:18 +0000

It feels like there is endless content for a developer to learn. It can sometimes feel a bit overwhelming.

I find it is important to have some sort of system in place to help manage and reduce the cognitive overload of remembering what you want to learn.

I personally like to use Notion and the board feature. Its very similar to Trello.

It's great way to see the big picture of everything you're doing and track your progress. Also its nice to look back on it at the end of the year and see all the things you have completed.

I'd like to share some things I have learnt which have helped make using this board more effective for myself to keep on track of my goals.

1) Prioritise

It's so easy to be seduced by the next new shiny framework and you know what, that's ok! I put it on the list and make sure I prioritise it. For example, want to learn React? Well you best make sure you have your JavaScript fundamentals in place first! Make sure your "learn JS fundmentals" card is above your "Learn React" card.

2) Break down the task

I've got some quite broad tasks on my board such as "Learn TypeScript Fundamentals". To help stay focused on completing the card. I've broken down what the fundamentals are so I can clearly see what I need to cover.

3) Be specific

This leads me on to my next point. Be specific with that you want to learn. I find I struggle if my card is too broad. For example if I had a card like "Learn CSS", there is just too much to cover. Try to hone in on something specific like "Learn the basics of CSS animation". Then follow step 2 and break it down further.

My system is not perfect and I'm trying to always evolve it. I'm curious how others manage their self learning. Do you do something similar?

Build a serverless CRUD app with authentication using Vue.js Netlify and FaunaDB

Alex Chiu — Mon, 20 Apr 2020 15:05:09 +0000

Building web apps has never been easier. It's not necessary to build a whole backend system and configure your database from scratch. We are in the age of serverless which means we don't need to think about managing servers anymore. All the hard problems around scaling your app can be offloaded to third party services and there so many great ones to choose from now. This means you have more time to think about the thing that is important, the product you want to build.

How to start building serverless web apps today?

Well one way is to use some starter code which I've put together here:

https://github.com/chiubaca/vue-netlify-fauna-starter-kit.

Follow the steps and you will have spun up your own serverless app in just a few clicks.

...

OK done?

You have now deployed a serverless app which has authentication and a persistent data store ready go. All hosted and managed for free thanks to Fauna and Netlify! And you didn't even need to whip out your credit card.

If you're like me and learn by poking around the source code. The rest of this blog will be a companion guide to explain how this app works and has been put together. Try running the app local on your machine, follow along and don't be afraid to break things.

App Structure

.
├── functions // Netlify serverless functions
├── src/
  ├── components // Vue components
  ├── pages  // Wrapper components to construct the "pages" of the app
  ├── store
    ├── modules/
      ├── auth/ // Vuex store for everything related to user auth
      ├── app/  // Vuex Store for generic app metadata
  ├── helpers   // Helper modules
  ├── models    // Wrapper functions for FuanaDB processes
  ├── router.js // Vue Router settings
  ├── main.js   // App entry point and also where initialisation scripts get called
└── package.json

I leaned heavily on the pattern outlined by Divya in this Netlify blog with some amendments. We will be making use of Vuex and Vue Router . If you're following along it is assumed you are familiar with how these libraries work.

App Initialisation

The deploy to Netlify button makes forking and deploying the app really straight forward, but you might be wondering what is going on behind the scenes.

Firstly, the script bootstrap-db.js is run before the Vue app is built and deployed to Netlify. This script checks the FaunaDB instance for the necessary collections and indexes which is required by the app and creates them if they are missing. It will build the following :

A collection for the users
A collection for the journals
A collection for the posts
An index for the posts
An index for the journals

If you want to extend this app to include more collections and create additional indexes, this is where you can do it.

If this all a bit confusing already, you might to spend a bit of time in the Fauna docs to familiarise your self with some of their concepts. Their CRUD tutorial is great.

Authentication

With the app bootstrapped and ready to go, lets get into the weeds of how authentication works. This app utilises Netlify’s open source GoTrue JS library There is no user interface that comes shipped with GoTrue-js, so we will go though the steps of how you can assemble these various components into a coherent login and signup experience.

Start the GoTrue client

in main.js The first step is to initialise GoTrue. We do this by dispatching a Vuex action.

store.dispatch("auth/initAuth");

/src/main.js

This is a simplified version of the "auth/initAuth" the Vuex action.

const hostName = document.location.hostname; // returns "vue-netlify-fauna.netlify.com"
const APIUrl = `https://${hostName}/.netlify/identity`; // construct the netlify identity endpoint
...
const initNewGoTrue = APIUrl => {
    return new GoTrue({
        APIUrl: APIUrl,
        audience: "",
        setCookie: true
    });
};
...
commit("SET_GOTRUE", initNewGoTrue(APIUrl));

/src/store/modules/auth.js

The important part is instantiating the GoTrue client and making a mutation to the Vuex state to store the GoTrue instance. This gives us access to all the GoTrue methods which we can then use throughout the auth.js Vuex module.

Signups and Logins

The GoTrue-js library has a straight forward and intuitive API which you read here.

Signups and logins is good way to see it in action. As noted in Divya's Netlify blog, we need to wrap the GoTrue methods in a promise which makes it possible to chain on additional error checks.

    attemptSignup({ state }, credentials) {
      return new Promise((resolve, reject) => {
        state.GoTrueAuth.signup(credentials.email, credentials.password, {
          full_name: credentials.name
        })
          .then(response => resolve(response);
          )
          .catch(error => reject(error));
      });
    },

/src/store/modules/auth.js

Notice how we're using GoTrue with state.GoTrueAuth.signup. This is important otherwise Vuex will throw a warning that we're mutating state outside of Vuex. The whole purpose of a state management library like Vuex is that we're trying to contain the state in one place to make it easier manage. You will see the attemptLogin action follows pretty much the exact same pattern.

    attemptLogin({ commit, state }, credentials) {
      return new Promise((resolve, reject) => {
        state.GoTrueAuth.login(credentials.email, credentials.password, true) // the third enable the client store the login token, useful for remember me functionality.
          .then(response => {
            resolve(response);
            commit("SET_CURRENT_USER", response); // This stores the user credentials into state
          })
          .catch(error => reject(error));
      });
    },

The key part, is that we pass the successful sign in response to SET_CURRENT_USER which mutates thestate.currentUser object with useful user-metadata including a database access token.

Before we take a deeper look into how the user metadata is created. Let's loop back to what happens after the user has successfully signed up.

Confirming the user

GoTrue still needs to verify the user via a one time confirmation token. Netlify will generate this token behind the scenes for you. The user simply has to check a confirmation email they received when they signed up. Within that email, there is a link which will redirect you back to your app.

On returning back to the app, you will be prompted that the account has been confirmed!

Wait, what? How did that happen?

Take note of the URL at the top. You can see that there is a hash or fragment identifier. This is the token which is used to confirm the user.

The magic happens in src/main.js . Whenever the app initialises, it always checks for a hash in the URL via attemptToAuthoriseTokens() . There are various tokens we need to look out for and parse such password resets and external login tokens, so all of this logic is in src/helpers/authorise-token.js. No matter what the token is, we make use of the document.location browser API to access contents of the URL, then extract the bit that we need, like so.

const token = decodeURIComponent(document.location.hash).split("confirmation_token=")[1];

function confirmEmailToken(token) {
  store.dispatch("auth/attemptConfirmation", token)
    .then(resp => alert(`${resp.email} has been confirmed, please login`))
    .catch(error => {
      alert(`Can't authorise your account right now. Please try again`);
      console.error(error, "Somethings gone wrong logging in");
    });
}

As you can see, once we have the token we pass this over to the "auth/attemptConfirmation" Vuex action.

    attemptConfirmation({ state }, token) {
      console.log("Attempting to verify token", token);
      return new Promise((resolve, reject) => {
        state.GoTrueAuth.confirm(token)
          .then(response => {
            console.log("User has been confirmed");
            resolve(response);
          })
          .catch(error => {
            console.log("An error occurred trying to confirm the user", error);
            reject(error);
          });
      });
    },

src/store/modules/auth.js

GoTrue-js will do the rest. Once again, a similar pattern to the login and signups actions.

To wire this up in the front end, here is a simplified version of what the login component looks like

<template>
  <div class="login-page">
    ...
      <form
        @keyup.enter="login()"
      >
        <h2>🔐 Login Here</h2>
        <label for="email">Email</label>
        <input
          v-model="crendentials.email"
          placeholder="hey@email.com"
        />
        <label for="password">Password</label>
        <input
          v-model="crendentials.password"
          placeholder="******"
         />  
        ...
      </form>
      <button type="button" @click="login()">Login</button>
  </div>
</template>

<script>
import { mapActions, mapGetters } from "vuex";
export default {
  name: "LoginSignup",
  data() {
    return {
      crendentials: {
        name: "",
        password: "",
        email: ""
      }
    };
  },
  methods: {
    ...mapActions("auth", [
      "attemptLogin",
    ]),
    login() {
      this.attemptLogin({ ...this.crendentials })
        .then(() => {
          alert(`You have signed in!`);
        })
        .catch(err => console.error("There was an error:" err));
    },
      ...
};
</script>

src/components/LoginSignup.vue

There are still remains an important question. Once we're authenticated via Netlify, how is this connected to Fauna?

What needs to happen next, is a new user has to be created in the FaunaDB instance once a user account has been successfully signed up on Netlify. Additionally, this user requires a unique access token with read and write permissions to only the resources it has created. The problem is that we can only create a new Fauna user account and access token via our administrator server key which is the same one used to setup the initial collections. We absolutely can not use this key in the frontend, otherwise anyone would have administrative access to our database!

These types of operations are usually done on secure backend servers, but the whole point of serverless is that we don't need to manage backends! So the answer is...

Netlify Functions!

Lets talk about really exciting aspect of serverless app architecture. Serverless functions! This is the ability to write any arbitrary backend code which is charged only for its execution time.

Netlify Functions lets you run your "backend" logic via this service. My favourite thing about them, is it allows for your backend and frontend code to effortless come together in the same repo. All you need to do is have a folder named functions in the root directory on your project and then you can write any code which you would normally run in Node.js. The only boiler plate code which we need to use is the following:

exports.handler = function(event, context, callback) {
    // your server-side functionality
}

Connecting your Netlify user to FaunaDB

Netlify Functions can be triggered on demand by hitting an endpoint which Netlify will create for you based on the file name of your function. However, Netlify can also trigger your serverless function on certain events. One of these events is identity-signup which is triggered when a new user has signed up. This is the perfect place for us to write our logic to connect our Netlify user to Fauna. A full list of all the available triggers can be found here. All we need to do is name the file"identity-signup.js" in the ./functions folder and Netlify will know to trigger this code whenever a new sign-up event happens.

Lets break down what happens inside identity-signup.js

Firstly we need to import the libraries we need .

const faunadb = require("faunadb");
const generator = require('generate-password');

We're using the FaunaDB JS driver, which lets perform administrative database actions with JavaScript. We also want to generate a random passwords for the newly created Fauna user account and for that we can use the Generate Password library.

Next, we set up our function which creates a new Fauna DB user.

/* configure faunaDB Client with our secret */
const q = faunadb.query
const client = new faunadb.Client({
  secret: process.env.FAUNADB_SERVER_SECRET
})

function createDbUser(userData, password) {
    return client.query(
        q.Create(
            q.Collection("users"), {
                credentials : {
                password : password
            },
            data : {
                id : userData.id,
                user_metadata : userData.user_metadata
            }
        }))
} //resolves a promise with the user object

Looks kind of weird right? That's what I thought at first. What you're looking at is the JavaScript version of FQL (Fauna Query Language). FQL is functional in its programming style, which means you will see functions, within another function. You should feel at home if you like using JavaScript array methods like map and reduce.

Also notice we're using process.env.FAUNADB_SERVER_SECRET. When this function is run by Netlify, it has access to any environment variables which have been set in the Build & Deploy section of your Netlify site settings. When you first deployed the app and supplied the Fauna server key, this was applying the FAUNADB_SERVER_SECRET environment variable for the site. Now we are reusing that key again.

To break down what the createDbUser() function is doing;

We let the new Fauna client instance client.query() method know we want to create a new "thing" by using the q.Create() method.
The q.Create method takes two arguments.

The "thing" we want to create, in this instance , we are inserting some new data in the users collection.
- The second argument is what is the param_object as noted in the Fuana docs. This param_object can take all sorts of configuration which we wont go into details of. What's important to note, is we will be supplying it a password property in the credentials object and a data object which is ,you guessed it, the actual data we Fauna to save. In our instance we supply the unique ID which was generated by Netlify along with the Netlify user-metadata.

Once that FaunaDB user account has been created, we then need a function which creates an access token which can be used to write back to the database. This will secure any read and write operations to that user. To do this we can run the FQL function q.Login() . This will create an authentication token for the provided identity object.

function obtainToken(user, password) {
  console.log("Generating new DB token")
  return client.query(
    q.Login(q.Select("ref", user), { password }))
} // Resolves a promise with the access token in an object

functions/identity-signup.js

We are ready to to put these functions altogether in the main handler function. The handler Netlify function has some useful properties and functions scoped within its context when it is run by Netlify. For example we can extract the Netlify user-metadata by pulling it out of the event object like so.

function handler(event, context, callback) {
      const payload = JSON.parse(event.body);
      const userData = payload.user; // Netlify user object 
      const password = generatePassword(); // Returns a randomised string
      ...
}

The event.body contains the Netlify user-metadata that we need. We need to de-serialise the the payload using JSON.parse as it is a string. Once de-serialised, we can store userData which we will use along with a uniquely generated password.

We can use the createDbUser() function we created earlier and pass in the userData object and password like so.

function handler(event, context, callback) {
    const payload = JSON.parse(event.body);
    const userData = payload.user; // Netlify user object 
    const password = generatePassword(); // Returns a randomised string

    createDbUser(userData, password)
}

Once the DB user is created, we can chain on the obtainToken() function which takes the resolved Fauna user object and also the password for that account which we can reuse.

function handler(event, context, callback) {
    ...
    createDbUser(userData, password)
        .then((user) => obtainToken(user, password))
}

This will return a DB access token which we can save back to the Netlify user account.

We do this by using using the callback function which the Netlify handler function provides.

function handler(event, context, callback) {
    ...
    createDbUser(userData, password)
        .then((user) => obtainToken(user, password))
        .then((key) => {
        callback(null, {
            statusCode: 200,
            body: JSON.stringify({ app_metadata: { db_token : key.secret} })
        })
    })
}

The first argument in the callback function is for handling an error response. The second argument is the response object which you can read about here. If you want to use serverless functions to create a REST APIs, this is where you can return back some data.

What is key here, is that this particular serverless function is run by a Netlify event trigger. This means that if you return an object with "app_metadata", Netlify knows to handle this, and it will write this data back to the Netlify Identity user which invoked this trigger.

Yes that's correct, Netlify user accounts can persist a small amount of data, so this is an ideal place to store the Fauna DB token associated with the account. When we then login via GoTrue, the success response of logging in will return this same user-metadata which can then use in the front-end.

To try and summarise what has happened;

We've registered a new user on the front-end which will invokes identity-signup.js via a Netlify event trigger.
identity-signup.js creates a unique user on Fauna and access token
identity-signup.js then saves this access back to the Netlify users account.
When the user successfully signs into the app, it returns all the useful user-metadata including the DB access token into Vuex so it is readily available for other components in the Vue app.

A good component to see how we can make use of the user-metadata in Vuex for some conditional rendering is the Home.vue component. The Home.vue component is a wrapper for the landing page of the app, but also renders the Login.vue component if there is no logged in user. We can implement this logic by checking the Vuex currentUser getter.

<template>
  <main>
    <h1>Vue - Netlify - Fauna</h1>
    <h2>A serverless stack with authentication ready to go!</h2>
    ...
    <Login v-if="currentUser === null" />
    <div v-else >
      <h2>🖐️ Welcome Back {{ currentUser.user_metadata.full_name }}!</h2>
      ... 
    </div>
  </main>
</template>

<script>
import { mapGetters } from "vuex";
import Login from "../components/Login.vue";
export default {
  name: "Home",
  components: {
    Login
  },
  computed: {
    ...mapGetters("auth", ["currentUser"])
  }
};
</script>

I'm conscious I've covered quite a lot regarding authentication. Its important to note, I've only covered the workflow for email signups. Unfortunately the identity-signup Netlify trigger does not get triggered by external providers such as Google. This means me we need to a little more heavy lifting to create this same workflow for email signups. If you're curious you can see how it all works in ./functions/identity-external-signup.js.

Secured Pages

With the signup and login workflow in place, we now have an app which is "aware" of what user is authenticated. We are now ready to create secured pages where an authenticated user can access and see content which only belongs to them. We do this using client side routing via Vue Router.

Setting up the routes

import Vue from "vue";
import VueRouter from "vue-router";
import store from "./store";

Vue.use(VueRouter);

const routes = [
  { path: "/", redirect: "/home" },
  {
    path: "/home",
    name: "home",
    component: () => import("./pages/Home.vue")
  },
  {
    path: "/journals",
    name: "journals",
    component: () => import("./pages/AllJournals.vue"),
    meta: { authRequired: true }
  },
  {
    path: "/journals/:id/posts",
    name: "posts",
    component: () => import("./pages/AllPosts.vue"),
    meta: { authRequired: true }
  },
  {
    path: "/profile",
    name: "profile",
    component: () => import("./pages/Profile.vue"),
    meta: { authRequired: true }
  },
];

const router = new VueRouter({
  routes,
  mode: "history"
});

export default router

src/router.js

Notice how the /home path is the only router without meta: { authRequired: true }. This is because the /home path is an unrestricted page and will be publicly available regardless of if you are authenticated or not.

All the other routes include meta: { authRequired: true } as we will use this property along with checking the Vuex store to see if there is a currentUser. If so, the user is allowed to proceed to one of these pages. To implement this logic we can do it in the router.beforeEach method.

import Vue from "vue";
import VueRouter from "vue-router";
import store from "./store";
...
router.beforeEach((to, from, next) => {
  // For every route, check if there is `meta.authRequired` property
  const authRequired = to.matched.some(route => route.meta.authRequired);
  // If the route doesnt have a `meta.authRequired` property go on ahead!
  if (!authRequired) {
    return next();
  }
  // If we go this far then it must have the `meta.authRequired`. But is there is a user logged in? If so, then go right on ahead! 
  if (store.getters["auth/loggedIn"]) {
    return next();
  }
  // The page requested is both secured and there is no logged in user detected. Sorry mate. No entry!
  console.warn("Page restricted, you need to login");
  next({ name: "home", query: { redirectFrom: to.fullPath } });
});

export default router

We've seen how components can access the Vuex store for conditional rendering, but notice how we can also read the Vuex store in the router file which is super handy!

Nested Routes

The posts route is bit different as it is a nested route. However it still honours the same route guard logic.

  {
    path: "/journals/:id/posts",
    name: "posts",
    component: () => import("./pages/AllPosts.vue"),
    meta: { authRequired: true }
  }

But by specifying :id this route will dependant on the specific journal ID which will be generated by FaunaDB. We only know what this is at the run time of the app and it is dependant of who is logged in. This leads us nicely to the final part of this blog.

Reading and Writing to FaunaDB

In the app, a user can have any number of journals and within those journals there can be any number of posts. Once the user has logged in and navigate to the /journals route, this will render the AllJournals.vue component. Here the user can create, read, update and delete any journals. The logic for these database operations are in ./src/models/JournalsModel.js. Lets explore how each of these database operations works.

Creating a new journal

export function createJournal(journalData) {
  const me = q.Identity();
  return client
    .query(
      q.Create(q.Collection("journals"), {
        data: {
          ...journalData,
          owner: me
        },
        permissions: {
          read: me,
          write: me
        }
      })
    )
    .then(resp => resp)
    .catch(error => error);
}

src/models/JournalsModel.js

We've seen how to add data into a collection before, and we're doing the same thing here. The difference is as part of the param_object we are also specifying the read and write permission for this document, this where we can supply the Identity object stored in the me const. The Identity function returns the Fauna user object which is associated with the current authentication token that is current being used.

Reading Journals

import { q, client } from "../helpers/init-db";
...
export function getJournals() {
  return client
    .query(
      q.Map(q.Paginate(q.Match(q.Ref("indexes/all_journals"))), ref =>
        q.Get(ref)
      )
    )
    .then(resp => resp);
}

In this query, we're making use of the all_journals FaunaDB index. Fauna indexes are required when you don't know the specific refs for a document you're interested in, more info in the Fauna docs. The other thing you may have noticed is that permissions are applied on a per document level. This means when this query is run, Fauna knows to return the journal documents which belong to the current user.

Deleting Journals

/**
 * @param {object} journal - Fauna journal ref object 
 */
export function deleteJournal(journal) {
  return client
    .query(
      q.Map(
        q.Paginate(
          q.Match(
            // get all the posts within a given journal ref
            q.Index("posts_by_journal"),
            q.Ref(q.Collection("journals"), journal.ref.value.id)
          )
        ),
        // then delete all of the posts within that given journal ref
        q.Lambda("X", q.Delete(q.Select("ref", q.Get(q.Var("X")))))
      )
    )
    .then(() => {
      // Once all of the posts in that given journals have been removed we delete the journal itself
      return client.query(q.Delete(journal.ref));
    })
    .catch(err => err);
}

Remember that a journal can contain any number of posts. This means that every post is associated with the same journal ID, so we need to identify these posts and delete them to.

To break down what this query is doing;

It loops over all posts in the posts_by_journalindex and returns all the posts with the given journal ID. This is done by combing the Paginate and Match FQL functions.
All the posts that are returned are then deleted. This is performed by the Lambda FQL function which is sort of like an inline function which can run any other FQL function.
Once all the posts are deleted, we then run the final query which deletes the Journal itself.

Updating journals

export function updateJournalTitle(journalRefID, newTitle) {
  return client
    .query(
      q.Update(q.Ref(q.Collection("journals"), journalRefID), {
        data: { title: newTitle }
      })
    )
    .then(resp => resp)
    .catch(err => err);
}

The FQL Update function is quite self explanatory. Provide the reference of the of the document in the specified collection you want to update. Then provide the new value in the data property of the param_object.

Using these functions in Vue components

Now we have the core CRUD operations in place, we can we now utilise them in our Vue components.

This is as straight forward as importing them in from "/src/models/JournalsModel". Then we need to wrap the function in a Vue method which lets us use it in the template block.

<template>
  <main>
      <h1>📔 Your Journals</h1>
        <form>
          <input
            v-model="journal.title"
            required
            type="text"
            placeholder="Name of new journal"
            @keyup.enter="submit()"
          />
          <input
            name="create journal"
            value="Create Journal"
            type="button"
            @click="submit()"
          />
        </form>
  </main>
</template>

<script>
import {
  createJournal,
  getJournals,
  deleteJournal,
  updateJournalTitle
} from "../models/JournalsModel";
import JournalCard from "../components/JournalCard.vue";
export default {
  components: {
    JournalCard
  },
  data: function() {
    return {
      journal: {
        title: ""
      },
      allJournals: []
    };
  }
  methods: {
    submit() {
      createJournal(this.journal)
        .then(resp => {
          alert("New journal created");
          this.allJournals.push(resp);
        })
        .catch(err => console.error(err));
    },
    ...     
   }
   ...
};
</script>

src/pages/AllJournals.vue

This example show we're using the createJournal function by wrapping it in the the Vue submit method. This lets us pass the name of the new Journal via a reactive Vue data property.AllPosts.vue and PostsModel.js follow the exact same pattern, check them out.

Wrap up

This blog could on much longer! But for brevity, I've covered the important parts of how everything works. I cobbled this together by learning how each of these components worked individually, but I wished that there was something that explained how they all fitted together. If you have made it this far, I hope you found it useful!