DEV Community: Antonio

Easily send emails in Strapi with any provider

Antonio — Tue, 01 Dec 2020 10:22:22 +0000

Sending emails is a fundamental feature in most projects. From welcoming new users to sending notifications and reminders, it's something that I find myself doing in every project.

I've been using Strapi for a few months now as it allows me to create APIs easily and fast and, even though it includes a default plugin to send emails out the box, it's not the best option to use in Production. There are multiple plugins for different email providers but in this article, I'll show you how to use a plugin that works with any provider.

Why you shouldn't use Strapi's default email plugin

Why do we need to install a new plugin if Strapi has one out of the box? As they mention in the documentation, Strapi uses sendmail as a default provider, which basically means that the emails are sent directly from the local server running Strapi.

You might use this during development but in Production it can cause you some issues:

It's not 100% reliable
Common mail servers, like Gmail, Outlook and Yahoo will block your emails if they are not being sent from a trusted server.
Your server might not have sendmail installed
Sendmail won't probably work if you are deploying your Strapi application with Docker

To avoid these issues, it's better to use an external provider. In the Strapi documentation they have an example using Sendgrid with its own specific plugin. Although it's a great platform, Sendgrid's free tier is very limited (only 100 emails/day) so I prefer to use SendinBlue (free 300 emails/day) or for more email demanding projects, ElasticEmail ($0.09 per 1000 emails).

Although there is a specific plugin for SendinBlue, I don't like the idea of my application depending on one specific third party like that and I'm not sure if I'll be using the same provider forever, so I prefer to use a plugin that is provider agnostic. And what do most email providers have in common? They all support the SMTP protocol, so that's what we'll use.

For this article, I'd assume we'll be using SendinBlue so go ahead and create a free account. You can find the SMTP details in your account settings > SMTP & API.

Plugin install and setup

The first thing you'll need is a scaffolded Strapi project. You can check how to create one in this article.

The plugin we're going to use is strapi-provider-email-nodemailer and, as I mentioned I choose this one for multiple reasons:

It's provider agnostic
Uses SMTP protocol
Super easy to configure and use
Migrating to a different provider is super simple

To install it, run npm i strapi-provider-email-nodemailer. To configure it I recommend to use an .env file as your server details will probably be different in DEV and PROD. To checkout how to use .env files in Strapi, check this section of the docs.

In our .env file we'll add the following variables:

EMAIL_PROVIDER=nodemailer
EMAIL_SMTP_HOST=smtp.zzzz.zzzzz
EMAIL_SMTP_PORT=587
EMAIL_SMTP_USER=xxXXXXxxxxXXX
EMAIL_SMTP_PASS=yyyYYYYYyyyYYYY
EMAIL_ADDRESS_FROM=aaaaaa@bbbbbb.com
EMAIL_ADDRESS_REPLY=ccccccc@dddddd.com

Sendinblue's SMTP host is smtp-relay.sendinblue.com and port is 587.

Next step is to configure the plugin in the config/plugins.js file:

// File: config/plugins.js

module.exports = ({ env }) => ({
  // ...
  email: {
    provider: env('EMAIL_PROVIDER'),
    providerOptions: {
      host: env('EMAIL_SMTP_HOST', 'smtp.example.com'),
      port: env('EMAIL_SMTP_PORT', 587),
      auth: {
        user: env('EMAIL_SMTP_USER'),
        pass: env('EMAIL_SMTP_PASS'),
      },
    },
    settings: {
      defaultFrom: env('EMAIL_ADDRESS_FROM'),
      defaultReplyTo: env('EMAIL_ADDRESS_REPLY'),
    },
  },
  // ...
})

As you can see, the configuration is pretty straight forward and we just have to assign the server and authentication details that we included in the env before.

If you don't want to use an env file, you can populate these variables using process.env.YOUR_ENV_VARIABLE instead of env('YOUR_ENV_VARIABLE') or, if you're testing locally, directly assigning the values but remember not to commit these to your repository for security reasons.

Sending emails

To make this example as simple as possible, I'll create an endpoint in our API that automatically sends an email. We'll create the following files inside api folder:

/api/email/config/routes.json

// /api/email/config/routes.json
{
  "routes": [
    {
      "method": "POST",
      "path": "/emails",
      "handler": "Email.send",
      "config": {}
    }
  ]
}

This will create a new POST endpoint /emails in our API, and the requests will be handled by the send method inside the Email controller, which we will create next:

/api/email/controllers/Email.js

// File /api/email/controllers/Email.js
'use strict'

/**
 * Read the documentation () to implement custom controller functions
 */

module.exports = {
  /**
   * Sends an email to the recipient in the body of the request
   */
  send: async (ctx) => {
    const body = ctx.request.body
    const sendTo = body.email
    strapi.log.debug(`Trying to send an email to ${sendTo}`)

    try {
      const emailOptions = {
        to: sendTo,
        subject: 'This is a test',
        html: `<h1>Welcome!</h1><p>This is a test HTML email.</p>`,
      }
      await strapi.plugins['email'].services.email.send(emailOptions)
      strapi.log.debug(`Email sent to ${sendTo}`)
      ctx.send({ message: 'Email sent' })
    } catch (err) {
      strapi.log.error(`Error sending email to ${sendTo}`, err)
      ctx.send({ error: 'Error sending email' })
    }
  },
}

The send method receives a POST request with the email in the body. We create an emailOptions object that contains the properties for destination address (to), subject and html as the body of the email. Then we just have to use the the strapi.plugins['email'].services.email.send method and pass it the emailOptions object.

If you need to add attachements, bcc or other email options, you can check the nodemailer message configuration here. You'd just need to add the options you need in the emailOptions object 😉

Now if we start our Strapi application with npm run develop and send a POST request to /emails with Postman or cURL, our email will be sent 📬

# Send POST request to /emails via cURL

curl --location --request POST 'localhost:1337/emails' \
--header 'Content-Type: application/json' \
--data-raw '{"email": "example@email.com"}'

Conclusion

This is a very basic example to show you how to programmatically send emails with Strapi via SMTP. In my case I normally trigger emails in cron jobs or in an authentication protected endpoints after users do a certain action.

Important: You shouldn't have a public endpoint in your API that triggers emails as it can be easily exploited and you could be charged by your email provider.

I like using nodemailer because it's provider agnostic and it allows me to easily change providers by just changing the server and credential details in my env file. In addition, it supports Amazon SES transport so you can use that option. You can find more info about how to use nodemailer with SES here.

If you liked this article, you can follow me on Twitter where I share dev tips, interesting articles and updates about the progress of my projects 🤙

Happy coding!

This article was originally posted in my blog where you can find other articles about web development focused on Node.js, Vue, Laravel and anything related with product development.

Use Vuexfire to simplify your application state management

Antonio — Wed, 18 Nov 2020 13:09:27 +0000

The problem tackled by VuexFire is pretty simple: keeping you state data in sync with the data in Firebase Firestore or RTDB. If you're familiar with Vue and Vuex, I'm sure you've faced this problem before. Let's think on a simple app like a to-do list.

Every time a user creates a new to-do, a Vuex action sends a request to the backend and commits a mutation to update the application state.
When the user completes a to-do, a Vuex action sends a request to the backend and then commits another mutation to update that particular to-do in the state.
When a user deletes a to-do, a Vuex action sends another request to the backend and then commits another mutation to delete that particular to-do from the state.

As you can see, every user interaction requires a Vuex action and a mutation to keep the application in sync with the data in the backend. VuexFire simplies this for us a lot, by binding our application state to Firestore or RTDB and updating the state automatically without the need to write or commit any mutation. It archieves this by providing its own set of mutations that take care of common things like adding or deleting items from an array or updating an object.

Let me walk you through a basic example.

I'm assuming we already have a Vue CLI project scaffolded with Vuex installed. You can find more info on how to do that here.

Retrieving data with Vuexfire

Let's say we want to build an app to manage books. The first thing I'd need to do is to install the Firebase and Vuexfire dependencies in the Vue project running npm i firebase vuexfire.

Then I created a firebase.js file in which I'll configure the Firebase SDK with the project keys and, assuming that our books will be stored in a Firebase collection named books, create a reference to it. It'll look like this:

// File src/firebase.js

import firebase from 'firebase/app'
import 'firebase/firestore'

const firebaseApp = firebase.initializeApp({
  apiKey: process.env.VUE_APP_APIKEY,
  authDomain: process.env.VUE_APP_AUTHDOMAIN,
  databaseURL: process.env.VUE_APP_DATABASEURL,
  projectId: process.env.VUE_APP_PROJECTID,
  storageBucket: process.env.VUE_APP_STORAGEBUCKET,
  messagingSenderId: process.env.VUE_APP_MESSAGINGSENDERID,
  appId: process.env.VUE_APP_APPID,
})

const db = firebaseApp.firestore()
// collection reference
const booksCollection = db.collection('books')

// exports collection reference to use it in the Vuex Store
export { booksCollection }

Note: In this example I'm loading the Firebase keys from environment variables but you can load the values directly 😉

In the application store, I'd want to keep all the books in a property named allBooks inside the state, so I''ll just have to create it and initialise it to an empty array:

// File src/store/index.js

import Vue from 'vue'
import Vuex from 'vuex'
Vue.use(Vuex)

export default new Vuex.Store({
  state: {
    // list of all books initialized empty
    allBooks: [],
  },
  actions: {},
  mutations: {},
  getters: {}
}

The next thing I'd need to do is to create a Vuex action that binds the allBooks property from the state with a Firestore query that returns the data from the books collection:

// File src/store/index.js
import Vue from 'vue'
import Vuex from 'vuex'

// imports collection reference from firebase.js file
import { booksCollection } from '@/firebase'
// imports required to bind the state to Firebase using Vuexfire
import { firestoreAction, vuexfireMutations } from 'vuexfire'
Vue.use(Vuex)

export default new Vuex.Store({
  state: {
    allBooks: [],
  },
  actions: {
    /**
     * @param context deconstructed to get only the method to create the ref
     */
    bindBooks: firestoreAction(({ bindFirestoreRef }) => {
      // return the promise returned by `bindFirestoreRef`
      return bindFirestoreRef(
        'allBooks',
        booksCollection.orderBy('author', 'asc')
      )
    }),
  },
  mutations: {
    // adds Vuexfire built-in mutations
    ...vuexfireMutations,
  },
  getters: {
    allBooks: (state) => {
      return state.allBooks
    },
  },
})

As you can see, the action bindBooks is a firestoreAction, which I've imported from vuexfire. This action returns a promise resolved by bindFirestoreRef(), which receives two parameters: the attribute in our state where we want to bind the data (in our case allBooks), and the query that will return the data (in our case, all books ordered by the author).

I also imported vuexfireMutations and added them inside our mutations using the destructuring operator .... Finally, I created a simple getter that returns the allBooks list from the state, which I'll use in a component.

The next step is to create a component to display all the books. A very simple one would be like this:

// App.vue file

<template>
  <div id="app">
    <h1>My Book List app</h1>
    <div class="book" v-for="book in allBooks" :key="book.id">
      <h2>{{ book.title }}</h2>
      <p>Written by {{ book.author }}</p>
      <p>{{ book.summary }}</p>
    </div>
  </div>
</template>

<script>
import { mapGetters } from 'vuex'

export default {
  name: 'App',
  mounted() {
    this.$store.dispatch('bindBooks')
  },
  computed: {
    ...mapGetters(['allBooks']),
  },
}
</script>

<style>
#app {
  font-family: Avenir, Helvetica, Arial, sans-serif;
  -webkit-font-smoothing: antialiased;
  -moz-osx-font-smoothing: grayscale;
  text-align: center;
  color: #2c3e50;
  margin-top: 60px;
}
.book {
  margin: 2rem;
  border-bottom: 1px solid gray;
}
</style>

As you can see, on the mounted lifecycle hook, I dispatch the action I created in the store, which will get the list of data from the Firestore books collection and then all books will be displayed. That awesome because it didn't took too much code to build this, but the best part is that if we add, delete or update books directly from the Firebase console, our app will refresh its store automatically.

Writting to Firestore with Vuexfire

Up until now, I've shown you how to use Vuexfire read and automatically keep the application state on sync with Firestore but in a real world app, we'd need to create, update or delete documents from our database. For that scenario, Vuexfire does not provide any methods or helpers and, as mentioned in the documentation, it recommends you to use the Firebase JS SDK.

Two simple Vuex actions to add and delete books in the collection would look like this:

// File: src/store/index.js

// .....
export default new Vuex.Store({
  state: {
    allBooks: [],
  },
  actions: {
    /**
     * @param context deconstructed to get only the method to create the ref
     */
    bindBooks: firestoreAction(({ bindFirestoreRef }) => {
      // return the promise returned by `bindFirestoreRef`
      return bindFirestoreRef(
        'allBooks',
        booksCollection.orderBy('author', 'asc')
      )
    }),
    addBook: firestoreAction((context, payload) => {
      console.log('Adding a new book!')
      return booksCollection.add(payload.newBook)
    }),
    deleteBook: firestoreAction((context, payload) => {
      console.log(`Deleting book ${payload.bookId}`)
      return booksCollection.doc(payload.bookId).delete()
    }),
  },
})

Note: we'd need to pass the payload for each action from the component. You can see the detailed code in this file of the repo

Notice that in these actions, we're not commiting any mutations as we usually do in Vuex.That's because the first action bindBooks will take care of keeping the application state in sync with Firestore. So even though we have to actually trigger the add() or delete() functions, with Vuexfire we don't have to worry about refreshing our state.

You can find all the code of this article in the following repo in GitHub.

Conclusion

As you can see, Vuexfire is a pretty nice tool you can use to simplify the state management of your Vue app. I've integrated it in one of my latest projects and it has helped me to get rid of a ton of code and, the less code you have, the less bugs you'll probably find 😅

Of course, it has its limitations, like for example, pagination. However thanks to some guidance I found on StackOverflow, I've been able to code a simple pagination that works for me. I'll share it with you in the next article.

If you liked this article, you can follow me on Twitter where I share dev tips an interesting articles and updates about the progress of my projects 🤙

Happy coding!

This article was originally posted in my blog where you can find other articles about web development focused on Node.js, Vue, Laravel and anything related with product development.

Leassons learned using Firebase for the first time

Antonio — Mon, 09 Nov 2020 10:54:10 +0000

A couple of weeks ago I decided that I wanted to build and launch a new project in a few days. To achieve that, I'd need to simplify as much as possible my tasks so I thought it was the perfect moment to learn Firebase and use it in a project for the first time. The project is still under development but so far I've learnt a few lessons I'd like to share.

Why should you use Firebase?

The main reason I had to use Firebase was curiosity. I've been wanting to try it for a while now and with the launch of AWS Amplify (which is pretty similar) my curiosity kicked in again. But other factors can make you decide to choose Firebase. For example:

Free plan: The free tier is good enough to build and run a small side project. It will give you 50k document reads, 20k document writes 20k document deletes, 1GB of stored data and 10GB of network. See free plan details
Fast developing experience: writing an app from scratch requires a lot of time if you're writing every single piece of code. Just all the authentication workflows can take you a week or more so having all that built out of the box is a huge plus. With Firebase I just had to install a dependency in my front end, and forget about any back end code for authentication, APIs or data storage etc. The only thing I've had to write is Firestore rules (the ones used to control who can do what in your database) and those are super simple to use.
Documentation: the official docs are great and even include some Youtube video series like this one for Firestore. Also, there are tons of articles and videos on Youtube. My favourite is probably the Fireship.io channel.
Super simple deployments: With the Firebase CLI, deploying a Firebase project is as simple as running firebase deploy. No need to set up webhooks, clone your repo or anything like that. Just running a script and seeing your project live on a .web.app domain, even with SSL enabled is awesome.

My 8 tips when working with Firebase

I hope you find the reasons above enough compelling to try Firebase but before that, let me tell you a few tips that I think would make your project development event better:

Use the Firebase CLI and VSCode extensions

You can install the CLI running npm i firebase-tools -g and then authenticate running firebase login with your Google credentials (did I mentioned Firebase is owned by Google?). In addition, the two VSCode extensions I installed are Firebase Explorer and Firestore Rules.

Create two Firebase projects

In order to keep your develop and production environments completely isolated, I'd create two different projects in Firebase (for example myAwesomeApp and myAwesomeApp-dev). Each project will have its own database, hosting and, more important, its own quotas so all the tests you'll do will not affect your live environment. You can create the project using the Firebase CLI or, better, create them manually in the Firebase Console website.

Vuejs + Firebase project scaffold

As mentioned earlier, the project I'm creating is a web built with Vuejs so to start I ran vue create my-project-name. Then inside the project folder, run firebase init and selected the features you want, like Hosting or Firestore . Next, choose the development project you created in the previous step and finally, the CLI will ask you for the files where it'll define the Firestore rules and indexes. Once your project is scaffolded, you can do your first deployment!

Setup deployment scripts for each environment/project

Once your Firebase project is initialized, you can deploy it running firebase deploy. This is ok to deploy to the Firebase project you chose when you initialized the project, but as we want to target different projects (remember we have develop and production), I suggest to create different scripts in your package.json file. Here are the ones I have:

  "scripts": {
    "serve": "vue-cli-service serve",
    "build": "vue-cli-service build",
    "lint": "vue-cli-service lint",
    "deploy-rules-dev": "firebase deploy --project myAwesomeApp-dev --only firestore:rules",
    "deploy-rules-production": "firebase deploy --project myAwesomeApp --only firestore:rules",
    "deploy-functions-dev": "firebase deploy --project myAwesomeApp-dev --only functions",
    "deploy-functions-production": "firebase deploy --project myAwesomeApp --only functions",
    "deploy-dev": "vue-cli-service build --mode development && firebase deploy --project myAwesomeApp-dev",
    "deploy-production": "vue-cli-service build --mode production && firebase deploy --project myAwesomeApp"
  },

As you can see the firebase CLI has different flags we can use:

--project is used to select our target project
--only is used to select which part of our project we want to deploy.

Use environment variables

This is very obvious but you should use environment variables to load you Firebase project keys or other variables that would be different in each environment. For example, initialise your app like this:

// ⛔️ DONT
const firebaseApp = firebase.initializeApp({
  apiKey: 'xxxXXXXXxxXXXXxxXXXXxxxx',
  authDomain: 'xxxXXXXXxxXXXXxxXXXXxxxx',
  databaseURL: 'xxxXXXXXxxXXXXxxXXXXxxxx',
  projectId: 'xxxXXXXXxxXXXXxxXXXXxxxx',
  storageBucket: 'xxxXXXXXxxXXXXxxXXXXxxxx',
  messagingSenderId: 'xxxXXXXXxxXXXXxxXXXXxxxx',
  appId: 'xxxXXXXXxxXXXXxxXXXXxxxx',
  measurementId: 'xxxXXXXXxxXXXXxxXXXXxxxx',
})
// ✅ DO 
const firebaseApp = firebase.initializeApp({
  apiKey: process.env.VUE_APP_APIKEY,
  authDomain: process.env.VUE_APP_AUTHDOMAIN,
  databaseURL: process.env.VUE_APP_DATABASEURL,
  projectId: process.env.VUE_APP_PROJECTID,
  storageBucket: process.env.VUE_APP_STORAGEBUCKET,
  messagingSenderId: process.env.VUE_APP_MESSAGINGSENDERID,
  appId: process.env.VUE_APP_APPID,
  measurementId: process.env.VUE_APP_,
})

In my case, I'm using Vuejs so I just need to create two files named .env.development and .env.production locally and whenever I run npm run build, it will automatically replace the environment variables with the values from the correspondent file. You can read more about Vuejs environment variables here.

Think twice your data model and don't be afraid to duplicate

Before you start coding, think about how your app is going to look like, which data you are going to need in each page and which pages are going to be more used. This is pretty important because it will affect the way you'll store your data in Firestore (the noSQL database used in Firebase) or the Real Time Database.

As one of the limitations of the free tier is the number of documents your app reads and writes, consider doing it just when you need it.

One of the things that have made me save a ton of document reads is duplication of some fields. This is something not very common in relational databases (I'd say it's even forbidden 😅) where we use foreign keys and join queries but it's pretty normal in noSQL databases. You can read more about data modelling and view some videos in this section of the docs.

Create functions for your Firestore rules

Once you start defining Firestore rules, there are two functions that you'll use all the time:

validate if the request comes from a logged user
validate if the user accessing a document is the one who created it

For that, you can create the following functions in your firestore.rules file:

//**** Functions   ****//
function isLoggedIn(){
  return request.auth != null;
}
function isOwner(){
  return request.auth.id ==resource.data.uid;
}

You can find more info about security rules here.

Paginate and limit your queries

This comes back to the limitations of the free tier. Just remember to add a limit(x) to your collection queries whenever you are going to access your data. You don't want to return 150 documents when on your page you can only display 20.
Pagination is super simple to build thanks to the startAfter() method. Find below an example of how I'm doing pagination in my Vuejs app:

// part of store/index.js file

// global variable to store last paginated element
let paginationLast = null

// Vuex store action
getUpcomingTalks({ commit }, payload) {
  return new Promise((resolve, reject) => {
    talksCollection
      .orderBy('date', 'asc')
      .limit(payload.limit || 12)
      .startAfter(paginationLast)
      .get()
      .then((res) => {
        if (res.docs.length > 0) {
          // save last item for pagination
          paginationLast = res.docs[res.docs.length - 1]

          commit('GET_UPCOMING_TALKS', res.docs)
          return resolve()
        } else {
          reject({ hasMore: false })
        }
      })
      .catch((err) => {
        console.log('err in action :>> ', err)
        return reject()
      })
  })
},

Just remember:

limit will limit the number of documents returned, pretty straight forward
startAfter will tell Firestore what is the latest document you queried before. In my case, the first time I'll send it null, so it will start at the beginning of the collection. Then after each successful query, I update it with the last item so the following queries will start from it. Note that this has to be a document reference, not an id.

Conclusion

I still have a ton of things to learn about Firebase but I'd say these are the more important things I've learnt so far. Hope you find them useful.

If you liked this article, you can follow me on Twitter where I share dev tips an insteresting articles and updates about the progress of my projects 🤙

Oh! and in case you're wondering, the project I'm building with Firebase is QuickTalks.io a place to organise and find talks for small audiences.

This article was originally posted in my blog where you can find other articles about web development focused on Laravel, Node.js Vue and more.

Improve page performance lazy loading reCaptcha

Antonio — Wed, 01 Jul 2020 10:52:08 +0000

A few days ago I ran Lighthouse in a couple of my websites and the performance score wasn't very good (around ~50). Most of the recommendations provided to improve the score were server-side, like caching and compressing assets but the score gains when I applied them were not that good. I realized that one the things that what was impacting the website performance the most was reCaptcha.

I use reCaptcha in every page that contains a form to avoid spam so getting rid of it was not an option. After searching online for some ways to improve the situation, I found this article which explained how to solve all my issues. The solution is awesome by its simplicity: do not load reCaptcha on the initial page load but lazy load it when the user actually interacts with one of the website forms.

Let's say we have a page with a simple subscription form and we load reCaptcha as it's detailed in their docs:



<html>
<head>
  <title>My page</title>
</head>

<body>
  <header>
    <h1>My awesome website</h1>
  </header>
  <main>
    <form id="contactForm" action="#" method="POST">
      <input aria-label="Name" id="sub_name" type="text" required placeholder="Johnny Mnemonic" />
      <input aria-label="Email address" id="subEmail" type="email" required placeholder="eightgigs@memory.com" />

      <input id="submitBtn" value="Subscribe" type="submit" data-sitekey="GOOGLE_RECAPTCHA_KEY"
        data-callback="sendForm">
    </form>
  </main>

  <!-- reCaptcha API JS -->
  <script src="https://www.google.com/recaptcha/api.js" defer></script>

  <script>
    function sendForm() {
      document.getElementById('contactForm').submit();
    }
  </script>

</body>

</html>

The reCaptcha API library is loaded with the page, just 1.2KB, but it automatically triggers a request to https://www.gstatic.com/recaptcha/releases/ which adds another extra 127KB to our page. And what happens if the user never interacts with the form? We've loaded a JavaScript file for no reason at all.

The solution is pretty simple and easy to implement:



<html>
<head>
  <title>My page</title>
</head>

<body>
  <header>
    <h1>My awesome website</h1>
  </header>
  <main>
    <form id="contactForm" action="#" method="POST">
      <input aria-label="Name" id="subName" type="text" required placeholder="Johnny Mnemonic" />
      <input aria-label="Email address" id="subEmail" type="email" required placeholder="eightgigs@memory.com" />

      <input id="submitBtn" value="Subscribe" type="submit" data-sitekey="GOOGLE_RECAPTCHA_KEY"
        data-callback="sendForm">
    </form>
  </main>

  <script>

    function sendForm() {
      document.getElementById('contactForm').submit();
    }

    // Function that loads recaptcha on form input focus
    function reCaptchaOnFocus() {
      var head = document.getElementsByTagName('head')[0]
      var script = document.createElement('script')
      script.type = 'text/javascript';
      script.src = 'https://www.google.com/recaptcha/api.js'
      head.appendChild(script);

      // remove focus to avoid js error:
      document.getElementById('subName').removeEventListener('focus', reCaptchaOnFocus)
      document.getElementById('subEmail').removeEventListener('focus', reCaptchaOnFocus)
    };
    // add initial event listener to the form inputs
    document.getElementById('subName').addEventListener('focus', reCaptchaOnFocus, false);
    document.getElementById('subEmail').addEventListener('focus', reCaptchaOnFocus, false);

  </script>

</body>
</html>

Let me explain what's happening here:

We're no longer loading the reCaptcha API JS library by default.
We've declared a function recaptchaOnFocus that adds the script tag with the reCaptcha API JS library to our page header when it's invoked.
We've added event listeners in our form inputs to invoke the recaptchaOnFocus function.

This way, our initial page load has 2 less requests and we've saved 128KB. For me this was the difference between these two results:

I hope this helps you improve your page load times but don't apply this just to reCaptcha. Think about other libraries you might be loading by default in your pages that can be lazy loaded in a similar way. I'm sure you'll be able to find some of them that are only necessary in edge cases.

If you liked this article, you can follow me on Twitter where I share dev tips like this one, updates about my projects and insteresting articles I find online 😎

This article was originally posted in my blog where you can find other articles about web development focused on Laravel, Node.js Vue and more.

Happy coding!

Building APIs FAST with Strapi, an overview

Antonio — Mon, 15 Jun 2020 15:31:40 +0000

I've been using Strapi for a few months in different scenarios, from quick prototypes and small test to more serious projects like the web application I'm working on (theLifeBoard.app). Although I've been using it for months, I haven't written an article about it yet and since a few days ago, the Strapi team announced the release of the v3 stable version, what a better time to write one (or maybe more) than now?

So what is Strapi? If you're not familiar with it, this is how they define it in their FAQ

Strapi is an open-source, Node.js based, headless CMS to manage content and make it available through a fully customizable API. It is designed to build practical, production-ready Node.js APIs in hours instead of weeks.

A Content Management System that provides an API in hours. Sounds good, doesn't it? Let's create a simple project to get a taste of it.

A quick example

Let's say we want to build an API to manage books. Only authenticated users can create, edit or delete them but anyone can query them. Our endpoints would be:

Public
- GET /books -> Returns all books
- GET /books/:id -> Returns a specific book by id
- GET /books/count -> Returns the number of books
Auth protected
- POST /books -> Create a new book
- PUT /books/:id -> Edit a book by id
- DELETE /books/:id -> Delete a book by id

Database setup

The first thing we need is a database to store our data. Strapi supports SQLite, MySQL, PostgreSQL and MongoDB so you can use any of them. For this example, I'm going to use MongoDB running on Docker, which, for me, it's the easiest way to manage database services in a local development environment. You can check this article in which I explain how to install Docker among other things.

Once you have Docker running, follow these steps:

Run docker pull mongo to download the latest MongoDB image
Run docker volume create mongoData to create persistent volume in which we'll store the data so it doesn't get lost when we stop/delete our container
Run sudo docker run --rm -d -p 27017:27017/tcp -v mongoData:/data/db mongo:latest to start the MongoDB container. The -p option will map the local port 27017 to the container's port and the -v option will map the local volume mongoData we just created, to the data/db folder in the container.

Scaffold the Strapi project

To initialize and generate the project we need to run npx create-strapi-app your_project_name. For example npx create-strapi-app demo-strapi. This will start a guided installation. Choose Custom type and select the options as detailed below:

Choose your installation type: Custom (manual settings)
Choose your default database client: mongo
Database name: demo-strapi
Host: 127.0.0.1
srv connection: false
Port (It will be ignored if you enable srv): 27017
Username: (your database user, default is empty)
Password: (your database password, default is empty)
Authentication database: admin
Enable SSL connection: No

The installation will take a few minutes. Once finished you can start your app running npm run develop from the project folder and the application will start in port 1337 by default.

The first time we start a Strapi application, it will ask you to create an administrator user. This will be the user we'll use to create content types, manage permissions, install plugins etc.

Once the user is created, we'll be in the administration UI and we can start creating our Book model in the Content-Types Builder section. Select Create new collection type and enter the name of the model, in singular. In our case, it would be Book.

Next you'll have to select the different attributes and types for our Book model. I selected the following ones:

title
- Type: text (short).
- Advanced settings: Required field, Unique field
pages
- Type: number (integer)
- Advanced settings: Private field
publishDate
- Type: date (date)
summary:
- Type: Rich text
- Advanced settings: Required field

As you can see, in the advanced settings we're adding some validations for required and unique fields. We can event include more detailed validations by using a RegExp pattern if we want.

Once our model is defined, click save and the application will restart.

Managing Content within the UI

Now that we have created our Book Content Type we can start adding books directly from the administration UI. Go to the Book Collection Type and you'll see an "Add New Book" button, which will show a form like the one below:

As you can see, the input fields match with the data types of the attributes we selected while creating the content type. From this section of the UI you'll be able to create, edit or delete items for all the content types, which is great but the best part is that Strapi has also generated a REST API we can use to interact with the content types. Let's review how it looks like.

Strapi project structure

Once you've created the first model, if you open the project folder, you'll see that it has generated two folders: config and an api.

Inside the config folder you'll find the application server specific configuration, like the database details (the ones you entered during the installation wizard), the host, port and even a cron.js file in which you can specify scheduled functions to run.

Inside the api folder you'll see one folder for each content type created, in this case one named book. Each one will have the following folders inside: config, controllers, models and services. Inside these folders we have the files we can modify to extend and customize our API:

In book/config/routes.json we have all our endpoint definitions. Each route has a method, path and handler, which by default points to methods in the controller.
In book/controllers/book.js we can create the methods that will handle the request to our routes By default, this file is empty as it extends the default Strapi controller which has the following methods: find(), count(), findOne(), create(), update() and delete(). You can extend the functionality of these methods by creating them in this file and adding your own logic (more info here)
Inside book/models/ we have the books.settings.json which contains the model attributes we defined earlier (title, pages, summary and publishDate) and the book.js model file in which we can add lifecycle hooks, like sending an email every time a book is created for example (more info here)
Similar as with the controller, in the book/services folder you'll find an empty file book.js, as it extends the default Strapi core service which contains all the following methods: find(), findOne(), count(), create(),update(), delete(), search(), countSearch() (more info here).

By default, the generated REST API will manage basic CRUD operations (Create, Read, Update and Delete) so if this is all you need, you're ready to go 😉.

Setting up the permissions

Permission management is Strapi is a pretty straight forward in the Roles & Permissions section of the UI.
We have two different roles available by default: Authenticated and Public, although we can create as many roles as we want.
To allow actions in each role, select the role and in the Permissions section, you'll see all the Content Types available and all its available routes. You'll just need to select the permitted routes for each role and click save. In my example, I'm allowing all actions for the Authenticated role:

And just the count, find and find one actions for the Public role:

Once permissions are configured, our API is ready to test. But how do we create the users for the Authenticated role? Let's see check that out.

Registering and login users

Strapi provides default endpoints to manage API users. These are:

Method: POST
Endpoint: /auth/local/register
Required body:

{   
    "username": "",
    "email": "",
    "password": ""
}

Method: POST
Endpoint: /auth/local
Required body:

{   
    "identifier": "",
    "password": ""
}

Note: the identifier could be the username or the email.

Both return a similar response, including the user details, role and a JWT:

{
    "jwt": "eyJhbGciOiJIUzI1NiIsCI6IkpXVCJ9.....",
    "user": {
        "confirmed": true,
        "blocked": false,
        "username": "user_one",
        "email": "one@a.com",
        "provider": "local",
        "id": "5ee0cafb6ec1410fda381181",
        "role": {
            "name": "Authenticated",
            "description": "Default role given to authenticated user.",
            "type": "authenticated",       
            "id": "5ee0c6f136637b0e7426a2a5"
        },
    }
}

Note: Strapi also provides endpoints to for the forget and reset password functionalities. You can find more info here.

We'd need to send the JWT in the Authorization header in order to access the authenticated protected routes. If we send a request with no JWT (or with an invalid one) to a route only allowed to the authorized role, we'll receive a 403 Forbidden error.

Now we should be able to register a new user, login and with the JWT recived, send a POST request to create a Book.

To query the API we just need to send a GET request to /books, no Authentication required.

Conclusion

This was just a quick overview of what Strapi offers. A quick summary would be that Strapi allows you to generate a Node.js REST API with authentication in a matter of minutes. That's the main sell point for me but it offers a lot more. The administration UI allows you to manage the content without the need to create a front end yourself. It has model relationships out of the box, plugins to manage permissions, send emails, manage media files, use OAuth authentication from different providers, GraphQL, Cron jobs and more. These means that you can basically build and entire back-end for your service or application with Strapi.

Other Pros

It's built in Node.js (for me, it's a pro 😀)
It's easy to extend the logic of your models or create new endpoints
File structure is very simple, mainly: api/model_name/* and /config
Support for .env files, which makes it super easy to deploy to different environments
Model relationships built within the UI
The community in Slack is active and super helpful

The not-so-good

Strapi is great, but it's not perfect. Here are a few of the downsides I've faced while using it:

It's not built in TypeScript
Model relationship management from the UI is not perfect and sometimes requires you to manually modify the model JSON files. Check the model relationships section of the documentation if you have any issues.
It may be difficult to find answers online when you face weird errors. Luckily you can go to the Slack channel and ask for help.
Documentation is good but not perfect although the team keeps polishing it and adding more guides and examples very often. Sometimes I find myself looking at older versions of the docs because they appear first on Google 😐
API permissions are stored in the DB which means that when we want to deploy a new version of your API which includes permission changes we'll have to manually apply them using the UI in Production or via a database migration.

I hope this article helps you decide if Strapi is a good choice for your next project. I really recommend it as it could help you save time developing APIs (I can't remember how many times I've scaffolded an Express app...). However if you're new to back-end development, you might get lost if you try to add custom functionalities so make sure you get familiar with concepts like routing, controllers, services etc by reading the docs first. And if you have any questions, you can ping me on Twitter or ask the community in the Slack help channel.

If you liked this article, you can follow me on Twitter where I share dev tips an insteresting articles I find online 😎

This article was originally posted in my blog where you can find other articles about web development focused on Laravel, Node.js Vue and more.

Happy coding!

Public demo of our side project (no signup required)

Antonio — Tue, 21 Apr 2020 14:58:52 +0000

We've been working in our side project called theLifeBoard for a few months, just doing little bits whenever we can. It's a web application to help people identify their goals and help them achieve them by providing a dashboard to organize their weeks and curated resources.

We have a version of the web app that we've been using for a few weeks, but it still has a lot of missing features and some nasty bugs.

A couple of days ago I had an idea. As the application is not ready to be shared with real users we thought about building a public demo, one that doesn't require users to sign up but that allows them to play around with the dashboard and maybe give us some feedback.

It just took me a couple of days to remove all the API integrations and add it to our landing page. You can find it here:

https://thelifeboard.app/demo

Feel free to play with it and let us know what you think.

The data will not be sent to our back end and will be lost if you refresh the page.

Tech stack

If you're interested in the technical side, the front end it's built with Vue.js + Vuetify and the back end is composed of multiple APIs some of them built with Strapi and others are simple Lambda functions.

Happy coding!

Create a markdown blog with Laravel 7

Antonio — Mon, 13 Apr 2020 09:19:15 +0000

For the last three years, my blog was built using a javascript rich text editor that generated all the HTML code for my posts. I've never been 100% happy with it as the editor generated a lot of unnecessary HTML and the styling of code blocks was not pretty good. In addition, I share my posts here in Dev.to and even though sometimes I can copy/paste my HTML articles, some parts were not styled properly.

I've always enjoyed taking notes in Markdown so I decided to give it a try for my blog. I created a quick demo with a Markdown editor and then parsed the articles to HTML using GitHub's public API. I gotta say the writing experience is way better than what I had before. Cross posting to Dev.to is a lot easier now and I can use GitHub's code highlighting and styling. See below how I did it.

Bootstraping a Laravel blog (model, controller and routes)

First thing we need is a bootstrapped Laravel app. You can check this previous article in which I create a Laravel + Tailwind CSS project.
Once we have our bootstrapped project, lets focus in the blog. First we'd need to create a migration to create the articles table . You can generate one with the running php artisan make:migration create_articles_table .
This will create a new file in the database/migrations folder. Edit it to include all the fields we're going to need:

// database/migrations/2020_xx_xx_xxxxxx_create_articles_table.php 

<?php

use Illuminate\Database\Migrations\Migration;
use Illuminate\Database\Schema\Blueprint;
use Illuminate\Support\Facades\Schema;

class CreateArticlesTable extends Migration
{
    /**
     * Run the migrations.
     *
     * @return void
     */
    public function up()
    {
        Schema::create('articles', function (Blueprint $table) {
            $table->id();
            $table->string('title');
            $table->string('slug')->index();  //to generate seo friendly urls
            $table->text('body_md');  // the article body in mardkdown
            $table->text('summary_md'); // the summary in markdown
                        $table->text('body_html')->nullable();  //the article body in html
            $table->text('summary_html')->nullable();  //the summary in html
            $table->char('online', 1);  // we'll use this to have articles published or in draft mode
            $table->timestamps();
        });
    }

    /**
     * Reverse the migrations.
     *
     * @return void
     */
    public function down()
    {
        Schema::dropIfExists('articles');
    }
}

Make sure your database connection details are correctly configured in your .env file and then run php artisan:migrate to create the table in the database.
Next step is to create the Model and Controller with php artisan make:model Article --resource. This will generate a model in /app/Article.php folder and the controller in /app/Http/Controllers/ArticleController.php .
Now we need to create the routes that we'll need to:

Return the page the contains the form to create a new article
Endpoint to store the article
Return the page to display the list of articles
Return the page to display a single article

Add them in the /routes/web.php file as follows:

<?php

use Illuminate\Support\Facades\Route;

Route::get('/articles/create', 'ArticleController@create')->name('articles.create');
Route::post('/articles', 'ArticleController@store')->name('articles.store');
Route::get('/articles', 'ArticleController@index')->name('articles.index');
Route::get('/articles/{param}', 'ArticleController@show')->name('articles.show');

The blog index page

As we've detailed in the routes file (/routes/web.php), to retrieve the articles index page we'll call the index method in the ArticleController. The controller would have to query the database and retrieve all the published articles (articles with the online field to true) and pass them to the view:

<?php

namespace App\Http\Controllers;
use Illuminate\Http\Request;
use App\Article;

    public function index()
    {
        //query the database
        $articles = Article::orderByDesc('updated_at')->where('online', true)->get();
                //return the view passing the list of articles
        return view ('articles.index', ['articles' => $articles]);
    }

In the blog index page, we'll display the title, summary_html and the date of all the articles. Let's create the view file in /resources/views/articles/index.blade.php with the following content:

// resources/views/articles/index.blade.php

@extends('layouts.app')

@section('content')
<main class="text-gray-800 px-8 md:w-2/3 lg:w-3/5 xl:w-1/2 sm:w-full mx-auto">

    <div class="text-center">
            <h1 class="text-center text-3xl my-8">Articles</h1>
            <a class="my-3 hover:underline" href="{{route('articles.create')}}">New article</a>
        </div>

    @foreach ($articles as $article)
      <section class="border-b">
        <h2 class="text-3xl font-bold text-center mt-4 hover:underline"><a href="{{Route('articles.show', $article->slug)}}">{{$article->title}}</a></h2>
        <p class="text-sm text-center leading-5 text-gray-700 mt-3">Posted {{\Carbon\Carbon::parse($article->updated_at)->format('d/m/Y')}}</p>
        <article class="markdown-body">
        {!! $article->summary_html!!}
          <div class="text-right mt-8">
            <a href="{{Route('articles.show', $article->slug)}}" role="button" class="px-4 py-2 border border-gray-300 rounded bg-white text-sm font-medium text-gray-700 hover:border-gray-500 focus:z-10 focus:outline-none focus:border-gray-300 focus:shadow-outline-gray active:bg-gray-100 active:text-gray-700 transition ease-in-out duration-150">
              Read more
            </a>
          </div>
        </article>
      </section>
    @endforeach
@endsection

Note: I'm using a lot of css classes from TailwindCSS. You can ignore them if you're using another CSS library (like Bootstrap or Bulma).

The important part in this view is the foreach loop that will will print the section inside it for every article we pass to the view.

The blog article page

The blog article page will be very similar to the index one, although in this case controller would have to filter for a specific article using the parameter we'll pass in the URL (note the route is /articles/{param}). This parameter could be the article id or the slug so we can access the articles with /articles/1 or /articles/this-is-the-title 😉

    public function show($param)
    {
        //seach by id or the slug
        $articleFound = Article::where('id', $param)
                        ->orWhere('slug', $param)
                        ->firstOrFail();
            if ($articleFound->online){
            //if article is published, go to article page
            return view('articles.show', ['article' => $articleFound]);
        }

        //if article not published, redirect to articles.index page
        return redirect()->route('articles.index');
        }

In the view (show.blade.php file), we'll display the article's title, the date (using the updated_at) and the body_html fields:

// resources/views/articles/show.blade.php

@extends('layouts.app')

@section('content')
<main class="text-gray-800 md:w-2/3 lg:w-3/5 xl:w-1/2 sm:w-full mx-auto">

    <div class="text-left pb-4 mt-4">
      <a class="text-sm leading-5 text-gray-700 hover:underline" href="{{ url()->previous() }}">Back to blog</a>
    </div>

    <h1 class="text-5xl text-center ">{{$article->title}}</h1>
    <p class="text-sm text-center leading-5 text-gray-700 mt-3">Posted {{\Carbon\Carbon::parse($article->updated_at)->format('d/m/Y')}}</p>
    <article class="markdown-body">
      {!! $article->body_html !!}
    </article>
</main>
@endsection

With this, we have 2 out of 4 routes done, the next one will be the one that returns the page that contains the form to create a new article

The new article page with markdown editor

At the controller level, this is pretty straight forward as we don't need to query the database. We just have to return a page that will contain the form to create the new article:

    public function create()
    {
        return view('articles.create');
    }

The view we'll include a form which action would be the articles.store route. The form will have inputs for all the fields we want: title, summary, body and the online indicator.

For the summary and body fields we'll use textarea inputs and we'll include a mardown editor in them. I've chosen SimpleMDE as (as the name indicates) it's super simple to integrate, has a toolbar with shortcuts to most of the things I'd need and it can be customized to your needs (see documentation in GitHub).


@extends('layouts.app')

@section('content')
<section class="w-full">

  <h3 class="text-center text-3xl font-semibold">New Article</h3>

  <form class="w-full px-6"  action="{{route('articles.store')}}" method="post" enctype="multipart/form-data">
    @csrf
    <div class="flex flex-wrap -mx-3 mb-6">
      <div class="w-full md:w-4/5 px-3 mb-6 md:mb-0">
        <label class="label" for="title">
          Title
        </label>
        <input class="input" id="title" name="title" type="text" >
        <p class="text-red-500 text-xs italic">Please fill out this field.</p>
      </div>
      <div class="w-full md:w-1/5 px-3 mb-6 md:mb-0">
        <label class="label" for="online">
          Online?
        </label>
        <div class="relative">
          <select class="block appearance-none w-full bg-gray-200 border border-gray-200 text-gray-700 py-3 px-4 pr-8 rounded leading-tight " id="online" name="online">
            <option value="0">No</option>
            <option value="1">Yes</option>
          </select>
          <div class="pointer-events-none absolute inset-y-0 right-0 flex items-center px-2 text-gray-700">
            <svg class="fill-current h-4 w-4" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 20 20"><path d="M9.293 12.95l.707.707L15.657 8l-1.414-1.414L10 10.828 5.757 6.586 4.343 8z"/></svg>
          </div>
        </div>
      </div>
    </div>
    <div class="flex flex-wrap -mx-3 mb-6">
      <div class="w-full px-3">
        <label class="label" for="grid-password">
          Article body
        </label>
        <p class="text-gray-600 text-xs italic mb-2">This is actual article body</p>
        <textarea class="input " name="body" id="body">{{ old('body') }}</textarea>
      </div>
    </div>

    <div class="flex flex-wrap -mx-3 mb-6">
      <div class="w-full px-3">
        <label class="label" for="grid-password">
          Summary
        </label>
        <p class="text-gray-600 text-xs italic mb-2">This is the text that will appear in the blog index page</p>
        <textarea class="input " name="summary" id="summary">{{ old('summary') }}</textarea>
      </div>
    </div>

    <div class="w-full text-right pa-3 mb-6">
      <input class="btn btn-green my-4" type="submit" value="Save article">
    </div>
  </form>

</section>

  {{-- Import CSS and JS for SimpleMDE editor --}}
  <link rel="stylesheet" href="https://cdn.jsdelivr.net/simplemde/latest/simplemde.min.css">
  <script src="https://cdn.jsdelivr.net/simplemde/latest/simplemde.min.js"></script>

  <script>
        // Initialise editors
    var bodyEditor = new SimpleMDE({ element: document.getElementById("body") });
    var summaryEditor = new SimpleMDE({ element: document.getElementById("summary") });
  </script>

@endsection

Note: At the end of the file you can see I import the CSS and JS files required for the editor and create new instances of them targeting the textarea elements using their id's

Now, if you open this page (localhost:8000/articles/create) you should see the form with the mardown editors in the body and summary fields.

Storing articles and parsing Markdown to HTML

In the editors of the form we just created we'll write Mardown but, in the index and show views we're going to display the html fids (remember we're displaying the sumary_html and body_html fields from the database). So how can we parse the markdown to HTML 🤔? and when do we parse it? For both questions I found different options.

How to parse it?

Create our own parser
Use an existing library (like Parsedown)
Use GitHub's API via GitDown

When to parse it?

Parse the markdown to HTML every time we display the index or show pages
Parse the markdown to HTML before storing it in the database

At the end I opted to use GitHub's API and parse it before storing the articles in the database. There is package called GitDown that will simplify it a lot, so we'd have to install it via compose with composer require calebporzio/gitdown . Once installed, we can go ahead and create the store method of the ArticleController, the action of the form we just created:

// app/Http/Controllers/ArticleController.php

// import GitDown dependency
use GitDown;

use App\Article;

 public function store(Request $request)
    {
        //I'm just validating the presence of the title, but you can validate more fields
        $request->validate([
            'title'=> 'required',
          ]);

        //create new Article instance and assign values
        $article = new Article;
        $article->title = $request->title;
        $article->body_md = $request->body;
        $article->summary_md = $request->summary;
        $article->online = $request->online;
        //generate article slug for nice URLs
        $article->slug = str_slug($article->title, '-') . '-' . $article->id;

        //parse body and summary to HTML via GitHub API
        $article->body_html = GitDown::parseAndCache($request->body) ;
        $article->summary_html = GitDown::parseAndCache($request->summary); 

        //save article
        $article->save();

        return redirect()->route('articles.index');
    }

Note: we're using the parseAndCache method exposed by the GitDown class and pass it the body and summary fields of the request we received.

In order to use the str_slug() function, we'd need to install the laravel/herlpers dependency via composer: composer require laravel/helpers.

What about code highlighting? Luckily for us, GitDown ships with the helper @gitdown that we can include in the header of our views to add all the CSS classes we need (see docs).
Have you noticed that the divs that contain the body and summary or the articles have a class markdown-body? This is the class targeted by the GitDown CSS.

Of couse, you can use a different class and style everything as you want, or override just some of the classes as you wish, that's up to you 😉.

Conclusion

There are a few things I havent covered in this article, like authentication so only logged users can create new articles or edit/delete articles, but there are plenty of articles out there that explain those concepts. I wanted to focus in the Markdown/HTML part. You can find the whole code of this article in this repo in GitHub. Feel free to clone/download it and use it a base for your projects. Hope you found this useful.

Happy coding!

This article was originally posted in my website. For dev tips and interesting articles follow me on Twitter 😎.

Bootstrap a Laravel 7 + Tailwind CSS project

Antonio — Thu, 19 Mar 2020 19:08:11 +0000

I've decided to redesign and upgrade my website with Tailwind CSS and Laravel 7 so here is a quick guide of how to bootstrap a project that uses both of them.

Install Laravel 7

The first thing to do is to make sure your system meets the requirements, mainly having PHP 7.2, composer and some extensions. Then as detailed in the Laravel official docs run composer global require laravel/installer and then use laravel new my-project to generate the project scaffold.

Additionally, you can run composer create-project --prefer-dist laravel/laravel my-project.

Once your project is created, you can run php artisan serve from the project folder to start a local server and open localhost:8000 in your browser to see the default Laravel welcome page.

Add Tailwind CSS to your Laravel 7 project

The next step is to add Tailwind to the project. I found plugin by Jeffrey Way that makes this super easy. Install it with npm install laravel-mix-tailwind --save-dev and then modify the file webpack.mix.js so it's like the next one:

const mix = require('laravel-mix');

// for Tailwind: https://github.com/JeffreyWay/laravel-mix-tailwind
require('laravel-mix-tailwind');

mix.js('resources/js/app.js', 'public/js')
    .sass('resources/sass/app.scss', 'public/css')
    .tailwind();

But what is this for? If you check the package.json file of your project, you can see that there is a dev/development script. These scripts run Webpack which is a module bundler that will take care of compiling our css or scss and js files in the resources folder and put the results in the public directory. It's normally used for javascript but we're going to use it for our css for now.

As detailed in the Tailwind docs, we need to import the Tailwind base and components to our css or scss file. Inside the resources folder, create a folder named "scss" and inside it, create a file named app.scss. In this file copy the following imports:

/* 
* resources/sass/app.scss
*/

// Imports Tailwind CSS
@tailwind base;

@tailwind components;

@tailwind utilities;

The next step is to generate a Tailwind config file. We can create it manually or we can generate it with the command npx tailwindcss init. This will generate an empty file but Tailwind allows you to customize your fonts, colours and a lot of other things in this file so check the corresponding page of their official docs for more info.

Now if you run npm run dev , Webpack should start to compile and generate the files in your public folder.

NOTE: The current version of laravel-mix-tailwind contains a bug as it expects the file tailwind.config.js to be named tailwind.js. The error in the console is:

_Error: Specified Tailwind config file "/Projects/my-project/tailwind.js" doesn't exist._

You can rename the file to match what it expects or you can change the line where it's hardcoded in the file /node_modules/laravel-mix-tailwind/index.js (line 14).

After Webpack finishes compiling, if you check the file public/app.css you can see there are a lot of classes in it (it will have more than 65k lines!). That's Tailwind being added to your project. Now if you include the app.css file in your views, you'll be able to use all the Tailwind classes 💪 .

Adding PurgeCSS to your Laravel 7 project

One of the inconveniences of Tailwind CSS is its size. As it has so many classes the size of the whole library is very big but we can use purgeCSS to remove all classes we are not using in our project. Similar to what we did to install Tailwind, we need to install a Laravel Mix plugin, in this case with the command npm i laravel-mix-purgecss --save-dev. Once installed, we need to add a few lines to our webpack.mix.js file:

const mix = require('laravel-mix');

// for Tailwind: https://github.com/JeffreyWay/laravel-mix-tailwind
require('laravel-mix-tailwind');

// for PurgeCSS
require('laravel-mix-purgecss');

mix.js('resources/js/app.js', 'public/js')
    .sass('resources/sass/app.scss', 'public/css')
    // .less('resources/less/app.less', 'public/css')
    .tailwind()
    .purgeCss({
        enabled: mix.inProduction(),
        folders: ['src', 'templates'],
        extensions: ['twig', 'html', 'js', 'php', 'vue'],
    })
    .setPublicPath('public');

With this configuration, we'll only run purgeCSS when we generate our production build with npm run prod. Go ahead and run it and compare the file sizes with the ones generated with npm run dev . In my case, the difference in the app.css file is 3.59Kb in production and 1.23Mb in development. That'll make a huge difference in the loading time of our web!

NOTE: if you want to add a more specific config to purgeCSS, you can create a file named postcss.config.js as detailed in this link.

Hope you find this useful. I've uploaded a scaffolded project to this public repo in GitHub so you can just clone it and start using it as the base for your next project. Just remember to follow the instructions in the Readme to install all dependencies!

Happy coding!

This article was originally posted in my website. If you like it, you may find interesting previous articles in my blog

How I built a new year resolutions exercise with Vue, Node and AWS

Antonio — Mon, 06 Jan 2020 17:20:22 +0000

I've been working in a side project called the LifeBoard for a few weeks now. Its main purpose is to help people identify and achieve their goals by creating habits. We know this seems like a very wide and difficult to tackle problem but we think it's just a matter of creating a service focused on few key principles we've been following in our life for the last couple of years:

Asking the right questions
Organisation & motivation
Sharing your success and the failures
Reward consistency

Our service is still far from being ready for users but we wanted to launch something that users could benefit from before the end of the year and also check if it triggered some interest so, being almost at the end of the year, we decided we could create a new year resolutions exercise.

This is something that we do every year and we really like to reflect back and review the things that we did, which ones we completely forgot or couldn't do, how our preferences have changed and analyse why and in general, see how we as persons have changed in the last 365 days. So we thought that including this exercise as part of our project would be a very good introduction letter to potential users.

When working in a big project, I usually do a detailed technical architecture but when I'm building something small I jump straight to my code editor and improvise the architecture as I progress. My main goal with this article is to explain all the different options I explored while I was coding, taking into account pros and cons of each, like if the time invested to implement a more robust design is worth the received return.

If you just want to see the exercise, you can find it in this link but if you're interested in how I built it and the different options I explored during the process, just keep reading 😉

What is the exercise about?

The idea was pretty basic:

Anyone can visit the exercise page, no login required
The exercise is a step-by-step questionnaire and it's meant to be completed in one go
At the end of the exercise, we ask for the user's name and email before storing the responses in our database
Send a confirmation email right after the exercise is completed
One year after completion, user's will receive an email with their details

With these things in mind I jumped to code. We already had a website with a landing page built in Vue.js (bootstrapped with Vue CLI) which includes Vue Router, so adding a new page is as simple as creating a new file in the views folder named NewYear.vue and include a new route in the router.js file pointing to it:

    // router.js file
    import Vue from 'vue'
    import Router from 'vue-router'

    // import views
    import Home from './views/Home.vue'
    const NewYear = () => import('@/views/NewYear.vue')

    Vue.use(Router)

    export default new Router({
    mode: 'history',
      base: process.env.BASE_URL,
      routes: [
        {
          path: '/',
          name: 'home',
          component: Home,
        },
        {
          path: '/newyear',
          name: 'year review and planning',
          component: NewYear,
        },
    ]
    })

That's all needed to add new pages to a Vue.js project. Now I just had to build the exercise in the NewYear.vue file

Building the exercise view

I wanted to divide the exercise in multiple steps so users are aware of how many remaining questions they have left. I could have built something from scratch but, I was already using Vuetify in the landing page and luckily for me, it contains a stepper component which does exactly what I wanted. After going through the documentation, it looked like the template and inner components was different depending if the stepper was horizontal or vertical:

For horizontal steppers, the components to use are:

v-stepper to wrap everything.
v-stepper-header which has to contain multiple v-stepper-step components (one for each step) and v-dividers.
v-stepper-items which has to contain one v-stepper-content for each step.

For vertical steppers, the components are:

v-stepper: to wrap everything.
v-stepper-step and v-stepper-content directly as childs of the v-stepper, one per step.

So the vertical one requires less components in general and, thinking mobile-first, I decided to go for the vertical one. Next was to review the required variables to make it work.

The v-stepper component requires a v-model with a numeric variable (I named it stepper) to track which content to display and the vertical property.
Each v-stepper-step requires a step property with a numeric value (first one has 1, second has 2....). The complete property marks the step as complete so I'll bind it to the result of checking if the variable used in the v-stepper is bigger than its own step property:
Each v-step-content just requires a step property, similar to the one in v-stepper-step.

You can find a full code example in the Vuetify docs.

In order to move back and forward between the steps I included buttons inside each v-step-content component that will call a function named moveToStep(n) . This function receives the number of the destination step and updates the stepper variable used by the v-stepper component. In addition, this function takes care of focusing on the inputs and reseting the forms that appear in multiple steps:

    moveToStep(stepNumber) {
        // actually moves to the step
        this.stepper = stepNumber
        // other controls of forms
        switch (stepNumber) {
            case 1:
              // Welcome step
              // reset form so it does not appear with error alert when going back to step 2
              this.$refs.formTaskDone.reset()
              break

            case 2:
              // Review the Goods
              this.$refs.taskDoneName.focus()

              break
            case 3:
              // Review, the Bads
              this.$refs.formTaskDone.reset()
              this.$refs.taskUndoneName.focus()

              break
            case 4:
              // New year Plans
              this.$refs.formTaskUndone.reset()
              this.$refs.newTaskTodo.focus()

              break
            case 5:
              // NewYear, the word
              this.$refs.formTaskNewYear.reset()
              this.$refs.inputYearWord.focus()

              break
            case 6:
              // Review step
              this.$refs.detailsName.focus()

            default:
              console.log('In default')
              break
          }
        }

Most of the v-step-content components contain forms with questions like the good and bad things from last year. All the questionnaire fields are bounded to variables so at the end of all the steps, I have all the user's answers stored inside the component's data object of the view. I though about saving the answers in localStorage between steps but that's wasn't really adding any value to the exercise so I discarded it at the end. The only downside is that if a user refreshes the page halfway though the exercise, he/she will lose all the answers 😞

Storing the responses

To store the user's responses I opted for a Lambda function that will receive a POST request and store the data in a Mongo database running in Mongo Atlas. This is the same approach I used to build the subscription form for our project's landing page so if you want to see a step by step guide on how to do it, you can check this article I wrote a few weeks ago. In summary, the required pieces are:

Mongo database (you can get one free with Mongo Atlas)
Lambda function in Node.js that receives an object with the responses, does some validations and saves it in the database using the mongodb package
An AWS API that exposes the endpoint the Vue.js application will send the request to

One of the tricky things when dealing with APIs is CORS as if the API is not returning the proper headers to the front end, the browser will block the requests. If you're not familiar with CORS I really recommend checking this article as it explains what it is very well. In AWS API Gateway you can enable CORS using the following option:

Once CORS is enabled, the API will expose an OPTIONS endpoint which will return the required headers and should be reachable from our front end.

To make the request to the API, I created a file named NewYearService.js which uses axios to create the object with the API details, like the URL. It also exports the function postResolutions(resolutions) that receives an object with all the user's responses and makes the POST request to the API:

    // NewYearService.js file
    import axios from 'axios'

    const apiClient = new axios.create({
      baseURL: `https://my-base-url.aws.lambda.com`,
      withCredentials: false,
      headers: {
        Accept: 'application/json',
        'Content-Type': 'application/json'
      }
    })

    export default {
      async postResolutions(resolutions) {
        try {
          const res = await apiClient.post('/resolutions', resolutions)
          console.log(`Posted ok! ${res.data}`)
          return res
        } catch (err) {
          console.error(err)
          throw err
        }
      }
    }

Then in the NewYear.vue view file I just have to import the NewYearService.js file and create a method that calls the postResolutions() function:

    // part of NewYear.vue file
    ........
      methods: {
        submitYear() {
          console.log('sending resolutions...')

          this.isLoading = true
          if (this.$refs.submitYearForm.validate()) {
            NewYearService.postResolutions({
              done2019: this.listDone,
              undone2019: this.listUndone,
              resolutions2020: this.listNewYear,
              word2020: this.yearWord,
              name: this.userName,
              email: this.userMail,

            })
              .then(res => {
                this.isLoading = false
                // move to next page
                this.stepper++
              })
              .catch(err => {
                this.isLoading = false
                this.alertMessage =
                  '🤕 There was an error saving your data. Please try again'
                this.showAlert = true
              })
          } else {
            this.isLoading = false
          }
        },
        ......

Sending the confirmation email

I thought about using an event system (like AWS SNS) that triggers a message every time the user's resolutions are stored in the database and then capture the events to send the emails asynchronly but that was adding a lot of complexity and I wanted to finish the exercise as soon as possible so I opted again for using a Lambda function which I'd call right after the one to store the data finished.

I've done emails in previous projects and the easiest way I know to send them with Node.js is using the nodemailer package. With nodemailer you just need your email SMTP server and account details to create an email transport and send it. Find below a small example that sends an HTML email:

    const nodemailer = require('nodemailer')
    const fs = require('fs')

    let transport = nodemailer.createTransport({
      host: 'YOUR_SMTP_SERVER',
      port: 'YOUR_SMTP_PORT',
      auth: {
        user: 'YOUR_SMTP_USER',
        pass: 'YOUR_SMTP_PASS'
      }
    })

    // Read email html template file
    const mailHtml = fs.readFileSync('./email.html')
    // Create HTML email
    const message = {
      from: 'YOUR_SMTP_USER',
      to: 'antonio@mydomain.com',
      subject: 'This is a test email',
      html: mailHtml.toString(),
      attachments: [
        { filename: 'image.jpg', path: 'https://mydomain.com/img/image.jpg' }
      ]
    }

    // Send mail
    transport.sendMail(message, function(err, info) {
      if (err) {
        console.log(err)
      } else {
        console.log(info)
      }
    })

I started creating the HTML template manually but soon I noticed that I was going to spend a lot of time to get a decent design that worked in multiple devices so I searched online and found beefree.io . It has a super easy to use (and free!) drag&drop designer that allows you to download the HTML file so it was super handy.

To trigger the Lambda that sends the email, I added a new endpoint in the API that I created to store the resolutions and then added a new function named sendMail() in my NewYearService.js file. This function would receive an object with the user's email address, name or whatever I want to include in the email:

    // NewYearService.js file
    export default {

      async sendMail(userDetails) {
        try {
          const res = await apiClient.post('/notifications', userDetails)
          console.log(`Mail queued ok! ${res.data}`)
          return res
        } catch (err) {
          console.error(err)
          throw err
        }
      },
      async postResolutions(resolutions) {...}
    }

Then I included the call to this function right after I receive a response from the API that stores the resolutions in the database:

    //part of NewYear.vue file
    methods: {
        submitYear() {
          console.log('sending resolutions...')

          this.isLoading = true
          if (this.$refs.submitYearForm.validate()) {
            NewYearService.postResolutions({
              done2019: this.listDone,
              undone2019: this.listUndone,
              resolutions2020: this.listNewYear,
              word2020: this.yearWord,
              name: this.userName,
              email: this.userMail,
            })
              .then(res => {
                // resolutions stored in the DB :)
                this.isLoading = false
                // move to next page
                this.stepper++
                // Call to API to send the email
                return NewYearService.sendMail({
                  name: this.userName,
                  email: this.userMail,
                })
              })
              .catch(err => {
                this.isLoading = false
                this.alertMessage =
                  '🤕 There was an error saving your data. Please try again'
                this.showAlert = true
              })
          } else {
            this.isLoading = false
          }
        },
        ...

Sending the email within a year

This part is still in progress but my firs idea is the following:

Create a new HTML template for the email with dynamic contentthat I can replace with the user's data
Create a cron job that runs daily
It will query the database that contains the user's resolutions filtering by the date (when it runs the 24th of December 2020, it will filter by 24th December 2019)
For each returned result, send an email containing the user's resolutions

I have almost a year to do this but if you have any suggestions on how you'll do it, they are more than welcome

Hope you've learnt something useful from this article and, if you want to check the exercise, you can find it here.

Happy new year and happy coding!

This article was originally posted in my website. If you like it, you may find interesting previous articles in my blog

Your first serverless function for a subscribe form

Antonio — Thu, 19 Dec 2019 18:27:08 +0000

One of the best advices I've read online when starting a new product or service is to create a landing page to explain the problem it solves and its features, then share it online to validate if it's something people will be interested in. It's never being easier to built a static site than today, with no code tools like Webflow or sites with templates like SquareSpace. I've never been a fan of this as I always find that when I have to modify very small details, things get tricky and sometimes are just not possible, so for my last side project I decided to use Vue CLI + Vuetify.

With Vue CLI I can scaffold a static site in minutes and using Vuetify I was able to leverage it's grid system and components to have a fully responsive site without the need of spending too much time creating the components, styling them etc... However when it was time to create a subscribe form I realized I was going to need something else. I didn't wanted to spin up a full back end server just to handle subscribers so I thought this was the perfect situation to use serverless functions as they come with a lot of advantages:

The code of your function just runs whenever it's triggered
Most cloud providers have a free tier which should be more than enough for most side projects
Requires less code so it's easier to maintain
Faster to develop and deploy than a back end server

As my cloud provider is AWS I used a Lambda function for my subscribe form. This is how I did it:

Creating the subscription form with Vuetify

With Vuetify it's super easy to create forms using the v-form component. You can add text fields, selectors, text areas, date pickers... whatever you might need. In addition, adding validations for your fields just requires to setup a few rules. There are multiple examples in the Vuetify v-form site, you can see mine in the following gist.

As you can see the template is done using v-row and v-col to wrap everything and the form contains two v-text-field binded to the data attributes newSub.name and newSub.email . The submit button triggers the handleSubscribe function which firsts validates if the fields contain valid data and if so, calls the postSubscriber function from the SubscriberService, a file that will contain all the necessary code to trigger the AWS Lambda function. In the component data I also included the following variables:

isLoading: will take care of displaying a loading animation in the submit button. I'll change it to true as soon as the button is clicked and turn it to false as soon as I receive a response from the API, sucessful or an error.
showAlert: will be used to display or not a message to the user.
alertType: defaulted to 'ok'. If the subscription request fails, I'll change it to 'error'. I'll use this values in different css classes in the style section of the component: alert-ok will have a green background and alert-error will have a red background.
alertMessage: will contain the message for the alert.

The SubscriptionService file will use axios to trigger the request to our Lambda function so you'll need to install it via npm/yarn. This is the code of the whole file:


import axios from 'axios'

const apiClient = new axios.create({
  baseURL: `${process.env.VUE_APP_SUBSCRIBE_API}`,
  withCredentials: false,
  headers: {
    'Accept': 'application/json',
    'Content-Type': 'application/json',
  },
})

export default {
  async postSubscriber(subscriberDetails) {
    try {
      const res = await apiClient.post('/subscribers', subscriberDetails)
      console.log(`Posted ok! ${res.data}`)
      return res
    } catch (err) {
      console.error(err)
      throw err
    }
  },
}

As you can see, first thing it does is to import axios and then it creates the apiClient passing a configuration object to the create function of axios. Notice that I'm using an environment variable to load the baseURL which will be the endpoint of the Lambda function that will handle our request. Just remember to create this environment variable after you create you Lambda function (more on this later). In my case, I can use a .env file and Vue CLI will just load them for me when the application starts.

Then the postSubscriber function will receive an object with the subscriber details (name and email) as a parameter and it'll just send a POST request using the apiClient created above. If something goes wrong I'll write the error in console and throw it so it's handled in the catch block in the Vue component.

Lambda function code

I had no idea how to start with the Lambda functions so the first thing I did was create a default function from scratch using Node.js as a runtime.

By default this creates a function that returns a hello message. To test it we have to click in the Test button in the top of the page and create an event. Events are different types of requests with different input in the request body. As our current code is not doing anything with the request body, we could leave the default one and test it, but if we want to prepare the event to simulate a subscription request, we can include name and email as the request body and then just use this event to test it.

Now is time to modify the code of the function to actually save the user's name and email in our database. I will be using MongoDB and, in case you dont have one already, you can sign up in Mongo Atlas to get a 500Mb cluster for free. This will be more than enough to store data for a few side projects so it's a really good option. You can find a step by step guide in their docs.

If you're hosting your database somewhere else, you'll need the host, user and password to connect to it.

As the code to store the data in the database is more complex and requires the mongodb dependency we'll use a code editor locally instead of the one in the Lambda console. The first thing we'll do is to create a folder to store all our code, then navigate to it in a terminal and run 'npm install mongodb' to install the mongodb dependency that we'll use to connect and interact with our database. Once the mongodb dependency is installed we can create the Javascript file that will contain all our logic to connect and interact with our database. In my case, I named it subscribe.js.

Notice that we didnt need to run 'npm init' to generate a package.json file as we'll not need to run npm install after deploying our code. Instead we'll upload our code and the node_modules folder to AWS. More on this later.

After searching online for a few tutorials and tips, I found this article about how to create the database connection and even some optimizations for lambda, like caching the database connection to increase performance. From this article I was able to extract a code example that splitted all the logic in four different functions:

connectToDatabase: async function that receives the database connection string and returns an opened connection
queryDatabase: async function that receives the database connection and the Lambda event (which has the request body). In our case this will have the name and email of the subscriber
processEvent: is a wrapper that will call the connectToDatabase and the queryDatabase functions. As these are async functions it will call them using await.
handler: this is the default function that is exported and receives as params the event and the context object.

The code from the article uses callbacks but it also contains a link to an example in GitHub which uses asyn/await instead. Let's review the functions one by one:

async connectToDatabase(uri)


const MongoClient = require('mongodb').MongoClient

//Performance optimization Step 1: declare the database connection object outside 
//the handler method so it's cached
let cachedDb = null

async function connectToDatabase(uri) {
  try {
    //Performance optimization Step 3: test that database connection exists 
    // and is valid before re-using it
    if (cachedDb && cachedDb.serverConfig.isConnected()) {
      console.log('=> using cached database instance');
      return cachedDb
    }
    const dbName = 'MY_DATABASE';
    const client = await MongoClient.connect(uri)
    cachedDb = client.db(dbName)
    return cachedDb
  } catch (error) {
    console.log(error) 
    return error
  }

}

As you can see, the variable cachedDb in the main context (not inside any of the functions) and the first thing we do is to check if it already exists and if it's connected. If it already exists we return it and if not, we connect to the server and database and assign it to cachedDb before returning. By declaring cachedDb in the main context we allow AWS Lambda to keep the database connection open for some time and it can be reusable for different executions of our function. This is explained in this section from the official AWS Lambda docs which mentions:

Objects declared outside of the function's handler method remain initialized, providing additional optimization when the function is invoked again. For example, if your Lambda function establishes a database connection, instead of reestablishing the connection, the original connection is used in subsequent invocations. We suggest adding logic in your code to check if a connection exists before creating one.

async queryDatabase(db, event)



async function queryDatabase(db, event) {
  let response = {
    isBase64Encoded: false,
    headers: {
      'Content-Type': 'application/json',
      'Access-Control-Allow-Origin': '*'
    }
  }
  try {
    var jsonContents = JSON.parse(JSON.stringify(event))

    //handling API Gateway input where the event is embedded into the 'body' element
    if (!event.body !== null && !event.body !== undefined) {
      response.statusCode = 420
      response.body = JSON.stringify({
        message: 'Invalid input'
      })
      return response
    }
    console.log('retrieving payload from event.body')
    jsonContents = JSON.parse(event.body)

    if (!jsonContents.name && !jsonContents.email) {
      response.statusCode = 420
      response.body = JSON.stringify({
        message: 'Missing params in request body'
      })
      return response
    }
    const now = new Date()

    const dbResponse = await db.collection('Subscribers').insertOne({
      name: jsonContents.name,
      email: jsonContents.email,
      createdAt: now,
      updatedAt: now,
      __v: 0
    })
    console.log('New Sub inserted: ', dbResponse)
    response = {
      statusCode: 201,
      body: JSON.stringify({
        message: 'Subscribed ok'
      })
    }

    return response
  } catch (error) {
    console.log(error)
    return error
  }
}

This function receives the database connection object and the AWS Lambda event. First thing it does is to check if the event contains a valid body and, if not, return the response object with status code 420. If the event has a body, it parses it to JSON with and then checks if it contains a name and email properties. Again, if it doesn't it will return the response with a 420 status code. Lastly, if both validations are passed, it will insert the record in the 'Subscribers' collection and return a reponse with a 201 status code.

A few things to keep in mind are:

The Access-Control-Allow-Origin header: Make sure you configure it accordingly to your website domain.
Validations: in this example I'm not validating if the email has a valid format or if the name contain just letters. Although these validations are done in the form in the website, it's important to include them in the back end as well.
The response body has to be a JSON stringifyed.

async processEvent(event)




async function processEvent(event) {
  try {
    const db = await connectToDatabase(atlas_connection_uri)
    const result = await queryDatabase(db, event)

    console.log('query results: ', result)

    return result
  } catch (err) {
    console.log('Error processing event: ', err)
    return err
  }
}

The processEvent function is just responsible of calling the connectToDatabase and queryDatabase functions using await.

handler(event, context)



exports.handler = async (event, context) => {
  try {
    var uri = process.env['MONGODB_ATLAS_CLUSTER_URI']

    console.log('remaining time =', context.getRemainingTimeInMillis())
    console.log('functionName =', context.functionName)
    console.log('AWSrequestID =', context.awsRequestId)
    console.log('logGroupName =', context.logGroupName)
    console.log('logStreamName =', context.logStreamName)
    console.log('clientContext =', context.clientContext)

    //Performance optimization Step 2: set context.callbackWaitsForEmptyEventLoop to false
    //to prevent the Lambda function from waiting for all resources (such as the database connection) to be released before returning it
    context.callbackWaitsForEmptyEventLoop = false

    if (atlas_connection_uri == null) {
      atlas_connection_uri = uri
      /*
      const kms = new AWS.KMS();
      kms.decrypt({ CiphertextBlob: new Buffer(uri, 'base64') }, (err, data) => {
        if (err) {
            console.log('Decrypt error:', err);
            return callback(err);
        }
        
        atlas_connection_uri = data.Plaintext.toString('ascii');
      }) 
      */
    }
    const res = await processEvent(event)
    console.log('Handler response is: ', res)
    return res
  } catch (error) {
    console.log(error)
    return error
  }
}

The handler function is the one we'll export and it's actually the one that will handle the request as it's the one we'll put as handler in the AWS Lambda console. It will receive the event (which contains the body of the request) and a context object. The context contains basic info like a unique identifier, the remaining time we have to execute our code etc... This function has two responsabilities:

Load the database connection string, from and environment variable or, preferibly, from an AWS Secret. This requires us to install the aws-sdk package.
call the processEvent function

The file with all the code would be similar to the one in this gist.

In order to upload our code to AWS, we have to create a .zip file containing both our index.js file and the node_modules folder. Then go to the AWS Lambda console and in the Code Entry Type dropdown, select Upload a .zip file. Once uploaded, make sure the runtime is still Node.js and that the Handler matches with you index filename and the exported function, in my case 'index.handler'.

In addition, if you're using an environment variable to load your database connection string (as in the example above), remember to add it in the Environment Variables section in the Lambda console. Keep in mind that for this type of sensitive data, it's recommended to use something more secure, like the KMS (Key Management Service), for which there youu can adapt the commented code in handler function.

Now we can test it using the Test button in the top of the screen. We can event create valid events (with name and email) and invalid ones to check if the validations we included in the queryDatabase function are working as expected.

Once we have tested our code using the Lambda console we need a way to trigger it from the outside world and for that we're going to need an API. Luckily for us the AWS API Gateway is going to simplify this task for us.

API Creation in AWS API Gateway

To start creating our API we have to go to the Designer section in the Lambda console, and find the Add trigger button. In the next screen select API Gateway in Trigger Configuration, choose Create new API and REST API as the template. In the Additional settings you can change the API name to whatever you want, leave Deployment stage as default and metrics and error logging disabled for now:

Once done, click the Add button and you new API will be created. Back in the Lambda console you should see the API Gateway as a trigger in the Designer section and if you click on it, you'll see the details and the endpoint of your API.

To test it you can copy the API endpoint and send a request using Postman/Curl. This should work out of the box but if you noticed, by default our endpoint accepts any method (GET, POST, PUT...) and ideally we'll be just listening for POST requests. To fix this, go to the API Gateway service in the AWS console and you should see your API, click on it to see its details. As you can see it has a single endpoint (named /test by default) with "ANY" method. With the Actions button, click on Create method and add the OPTIONS and POST methods. For the OPTIONS one, you'll need to select the Mock integration type and save it. This will make it return a 200 by default withouth actually calling any Lambda function or other code.

Note: we'll need the OPTIONS method as this will be triggered by the browser before actually sending a POST request.

For the POST method we'll select Lambda function as Integration Type, select the Use Lambda Proxy integration and then enter the name of our function in the Lambda function field. We'll get a popup with the message "You're about to give API Gateway permission to invoke your Lambda function", so click Ok. Now we can actually remove the ANY method using the Actions button as we'll be using only POST/OPTIONS requests.

Once done, you'll have to re add the trigger for your function in the Lambda Designer section and you should be ready to go.

Conclusion

I think serverless functions can be very useful when starting a new project or even to handle all the backend in small applications. In my case, I plan to use them for small isolated tasks in my side projects like this subscription example. In addition I plan to start writting them in other programming languages like Python and Go as it could be a nice way to start learning them 😄

Hope this helps you start playing with serverless functions

Happy coding!

This article was originally posted in my website. If you like it, you may find interesting previous articles in my blog. In addition, I'm working on a side project called the LifeBoard, an app to help people identify and achive their goals. If that sounds interesting, check out the landing page and give me some feedback in Twitter or subscribe if you want to receive updates 😉

Understanding the basics of Socket.io

Antonio — Thu, 05 Dec 2019 17:41:39 +0000

This article was originally posted in my website. If you like it, you may find interesting previous articles in my blog

After doing a lot of APIs and microservices lately, I've been trying to find new ideas for quick demos to improve my skills. In one of the projects I'm working on, I'm planning to include a feed that is refreshed with the activity of the users in real time. I wasn's sure about how to do it and, at first I thought about using RabbitMQ, but after a quick search I found WebSockets and Socket.io. If you want to learnt what WebSockets are, watch this super quick video to understand the basic concepts.

Instead of builing directly the user's feed for my project, I decided to build a quick chat demo first. There are multiple articles and videos that explain how to create a chat with socket.io but most of them don't explain exactly how all involved parts work together or are just a small demo to run locally but is not "deployable" to production. So I took all those examples as references to build my chat, took notes of everything that wasnt clear for me and built it in a way so it can be deployed to a server (even created a Docker image!). Here are all my notes.

Chat server and client responsabilities

Our chat app server will have following responsabilities:

Serve the HTML/CSS/JS client files to the users
Start Socket.io connection
Serve socket.io library to the clients (optional as clients can also load it from a CDN)
Broadcast events (like a new chat message) to all clients connected

When a user connects to our server from his browser, he'll receive the HTML/CSS/JS client files which will:

Load socket.io client library (from our server or from a CDN)
Stablish connection with the Socket.io running in our server
Ask user to enter his name so we can identify him in the chat
Emit and receive events to/from Socket.io running in our server
Add our own messages to the chat via JavaScript

Chat server in detail

First thing is to start our Node.js project with "npm init" as we'd have to install dependencies later. We can use Node's http module to create a static server that sends our client any type of files, in our case it would be html, css and js. I found this example in the Mozilla docs which was exactly what I was looking for. No framework, just an http server able to send html, css, js, images and more. They also explain how it works line by line so I'll not go into that. I put the server code in a file named server.js. The only things I changed from the Mozilla example are the port number and the path were it reads the files from, as I'll use a folder named "client":

var filePath = './client' + request.url;
console.log(filePath)
if (filePath == './client/') {
  filePath = './client/index.html';
}

Next step was to install the socket.io dependency with "npm i socket.io" include it in our server.js file and log something when we detect a connection:

var io = require('socket.io')(app);
// starts socket
io.on('connection', function (socket) {
  console.log('Socket.io started.....')
  // Manage all socket.io events next...
    socket.on('new-connection', (data) => {
    // captures event when new clients join
    console.log(`new-connection event received`)
    .........
  })
});

I've also included how to capture an event called 'new-connection', which for now, will just print something in the console. Now let's move to the client.

Chat client in detail

As mentioned earlier, I placed all our client files (html, css and js) in a folder named client. The index.html file is pretty simple:

in the header we're loading the socket.io client library, from a CDN although I've also included the code to load it from our own server
also in the header, we load our script.js file.
the body only contains a div container for all the chat messages and a form to submit new ones.

You can find the code of the index.html file in this GitHub Gist or directly in the repo.

In the client script.js file, the first thing I did was to connect via socket.io from the client to the server. As I'm loading the socket.io library before the script.js file, I have it available so I can use the io() function to create a socket connected to the server and the emit() function to send a basic event named 'new-connection' and the name of the user:

/**
 * Use io (loaded earlier) to connect with the socket instance running in your server. 
 * IMPORTANT! By default, socket.io() connects to the host that 
 * served the page, so we dont have to pass the server url
 */
var socket = io();

//prompt to ask user's name 
const name = prompt('Welcome! Please enter your name:')

// emit event to server with the user's name
socket.emit('new-connection', {username: name})

At this point, if I start the server using 'node server.js' and open the browser I get the prompt and after entering the name, I'll be connected to the socket server and see something like this in the server console:


$ npm start

> chatsocket.io@1.0.0 start /d/Projects/chatSocket.io
> node server.js

HTTP Server running at http://127.0.0.1:3000/
request  /
./client/
request  /script.js
./client/script.js 
request  /style.css
./client/style.css
Socket.io started.....
request  /favicon.ico
./client/favicon.ico

Up to this point, I was able to:

start a static server that sends the client files and opens the socket.io connection
connect the clients to the server via socket.io and emit an event called 'new-connection'
capture the 'new-connection' event in the server and print it to the console

The only things missing to complete the chat application were:

being able to link messages with the user's names
add messages we send to the chat-container div
emit event to the server containing the message sent
broadcast chat messages received in the server to all clients connected

Adding the messages we send to the chat-container div is something we can do in the client script.js file. We just need to add an event listener to capture when the form is submitted and, whenever that happens, create a new div containing the message inside the chat-container. As this is something I'll have to do also when we receive messages from other users, I created a function called addMessage(data, type) which I can call multiple times. In addition, I trigger an event called 'new-message' sending to the server an object with both the message and the client's socket id.


// get elements of our html page
const chatContainer = document.getElementById('chat-container')
const messageInput = document.getElementById('messageInput')
const messageForm = document.getElementById('messageForm')

messageForm.addEventListener('submit', (e) => {
  // avoid submit the form and refresh the page
  e.preventDefault()
  // check if there is a message in the input
  if(messageInput.value !== ''){
    let newMessage = messageInput.value
    //sends message and our id to socket server
    socket.emit('new-message', {user: socket.id, message: newMessage})
    addMessage({message: newMessage}, 'my' )
    //resets input
    messageInput.value = ''
  }
})

// receives two params, the message and if it was sent by you
// so we can style them differently
function addMessage(data, type){
  const messageElement = document.createElement('div')
  messageElement.classList.add('message')

  if(type === 'my'){
    messageElement.classList.add('my-message')
    messageElement.innerText = `${data.message}`

  }else if(type === 'others'){
    messageElement.classList.add('others-message')
    messageElement.innerText = `${data.user}: ${data.message}`

  }else{
    messageElement.innerText = `${data.message}`

  }
  // adds the new div to the message container div
  chatContainer.append(messageElement)
}

Note that I also added different styles to the messages depending if they belong to the user or if they are received from others.

Next step is to handle the 'new-connection' and 'new-message' events properly in our server.js. In the 'new-connection' event I stored the client's socket id and the user name as key:values of an object named users. Then in the 'new-message' event, I used the socket id received to find the correspondent user name, and with the broadcast() function, send the message information to all clients connected except the one that emitted the event originally.


// we'll store the users in this object as socketId: username
const users = {}

var io = require('socket.io')(app);
// starts socket
io.on('connection', function (socket) {
  console.log('Socket.io started.....')
  // Manage all socket.io events next...
  socket.on('new-connection', (data) => {
    console.log(`new-connection event ${data.username}`)
    // adds user to list
    users[socket.id] = data.username
    socket.emit('welcome', { user: data.username, message: `Welcome to this Socket.io chat ${data.username}` });
  })
  socket.on('new-message', (data) => {
    console.log(`new-message event ${data}`);
    // broadcast message to all sockets except the one that triggered the event
    socket.broadcast.emit('broadcast-message', {user: users[data.user], message: data.message})
  });
});

With these last few bits done, I had a fully functional chat application and I could test it by opening multiple browsers locally:

The only thing I havent covered up until now is the styling (which you can find in the style.css file) and minor validations, like making sure users cannot send empty messages. You can find the full code in this repo in GitHub. It also contains a Dockerfile so you can build an image and deploy it anywhere with Docker 🙃 or if you just want to try it online, visit this link.

For this app I just needed to use the emit() and broadcast() functions but Socket.io contains a lot more functionalities like assign namespaces to sockets so they have different endpoints, create rooms and even integrate it with Redis. You can find examples of all those in the docs.

Hope this helps you understand WebSockets and how Socket.io works.

Happy coding!

Vue London 2019 conference recap (slides and repos)

Antonio — Tue, 22 Oct 2019 13:30:59 +0000

On October 4 took place one of the biggest Vue.js conferences in Europe, Vue.london. As soon as I heard about it I marked it in my calendar and bought an early bird ticket. At around £250 it's not a cheap conference but given the quality of the talks, the venue, how well it was organized and all the swag (t-shirts, bags, stickers, discounts...), I think it was worth the price.

The Venue

Talking about the venue, it was in the CineWorld the O2 peninsula so the screen was suuuper big. Breakfast was served before the first talk and there were multiples options for lunch (the dim sum were super good...), coffee, tea, cakes etc...

In the lounge you could also find the booths of the sponsors: Cloudinary, Cypress.io, KendoUI, Attest, VueMastery and SamKnows (I'm probably missing a few more). There was also an advice lounge where you could ask for help or just talk with experts, the speakers or organisers, and there was even a gaming room so there was plenty of things to do during the breaks.

The talks

The first talk was by Adam Jahr, from VueMastery and it was an introduction to animations in Vue explaining how we can use animations to drive focus and then showed us how to use the transition element and combined with CSS transtions. As all the content they do in VueMastery, it was super easy to follow and it was part of their Animating Vue course so if you want to know more about the topic, you can sign up to do the full course.

Adam's talk was followed by Maya Shavin with "Scripting in Style, what's your Vue" who gave us a history lesson on the evolution of the Web and analised the pros and cons of the different ways to apply styling to our components: global style,scoped style and CSS in JS. Slides and Repository

Next was Filip Rakowski who explained some tricks to improve performance of our Vue.js apps like:

Using dependencies that can be tree shaken (lodash-es instead of lodash!) and using Bundlephobia to quickly identify the biggest dependencies in our bundle
Lazy-loading views and components by using functions instead of regular imports
Using prefetch to load parts of our web when the browser is in idle.

You can find the slides here.

Ramona Biscoveanu showed us how to use the D3 library to do data visualizations in Vue.js and how we can leverage the reactivity of the computed properties in Vue to make the data visualizations come to live. I've never used D3 but looks like it's a super powerful library for when you need something more than chartjs or similar. Slides

Vue.js core team member Eduardo San Martin Morote followed with an deep explanation of the Vue Router, common issues developers may find with it, like the importance of the order you declare your routes and its limitations. In addition he gave us some insights on how it will evolve in future versions and how they will separate responsabilities between the History and the Router. You can find the slides here.

Just before the lunch break, they did the Open Source Awards, where they recogniced some nice open source projects. The categories and nominees were:

Breaker of chains: Proppy, Portal Vue, Virtual Scroller and Grindsome.
Fun project: Vuera (winner), Vue Observe Visibility and Vue Funnel Graph.
Impactful Contributor: Vue Community, Tailwind CSS, Vue Storefront and TipTap (winner).
Developer Experience: Inkline, Vue Styleguidist (winner), Cion Design System and Vuese.

Right after lunch, we started with a few lightning talks (around 10mins each):

Accesibility and Focus Management by Maria Lamardo.
Hot to get your product owner to write your functional tests with Cypress.io . Cant remember the speaker's name but Amir Rustamzadeh gave us a great intro to Cypress at their booth so if you're interested on it, follow him on Twitter.
AwesomeJS.dev by Guillaume Chau

The rest of the talks focused on the new composition API that will be added in Vue 3. Gregg Pollack from VueMastery started with "Vue 3's Composititon API Explained Visually". First he listed the limitations of the current API and how the new API will solve them and when to use it, mainly:

When we want Typescript support
When we have code we want to reuse in multiple components (composition functions to the rescue).
When we have components that are too big, as we would be able to extract most of the code to composition functions.

The talk covered the first few lessons of their Vue 3 Essentials course so if you are interested in it you can sign up to access the full course. He also presented their Vue 3 cheatsheet that you can download here.

Thorsten Luenborg followed with a more in depth analysis of the new API methods like setup, refs, toRefs and dynamic lifecycle methods. This talk contained a lot of code examples and you can find them in the following repo.

After a long coffee break to digest all this info, Jason Yu did a live coding session builing a piano-computer-keyboard app using an audio API from the browser (with a song included). Definately one of the highlights of the day. His code is in this repo. He has also edited a 20min video you can find in YouTube.

To close the event, we had an online conference talk with the man himself Evan You in which he open sourced the code of the Vue 3 pre-alpha version. In addition, he explained the improvements done in the compiler to ignore nodes of the DOM that doesnt have reactive data, which translates in at least 6x performance improvement, and the new Suspense element that can be used to display placeholder content while an async request is done (bye bye loading = true/false in each API call).

Conclusion

I think Vue London 2019 was a big success. A well organized conference with recognized speakers, high quality talks, good sponsors, nice food and, most importantly, the mood in general was super good and welcoming. I'll try to repeat next year.

PS: The organisers told me they will release the videos of the talks so I'll update the article once they are available.

This article was originally posted in my website. If you like it, you may find interesting previous articles in my blog