VueJS

Going Serverless with Vue.js and Firebase Cloud Functions

Published Mar 11, 2020

Updated Feb 14, 2023

10 min read

Fire the base of Vue.js! - 3 Part Series

This article was written over 18 months ago and may contain information that is out of date. Some content may be relevant but please refer to the relevant official documentation or available resources for the latest information.

Welcome to a new episode of the Fire the base of Vue.js! series.

In this episode, I will integrate our Vue.js Notes Writer App with a serverless backend- specifically, the Firebase Cloud Functions.

If you haven’t read the other parts of this series, I highly recommend you do so before starting here.

Vue the Mirage from this angle! Storing your notes in the Cloud Firestore with Vue.js Firebase for user authentication in Vue.js

To follow up on the demo part of this article, you can use this GitHub source code repo as a starting point.

Firebase Cloud Functions, the concept

Cloud Functions are part of the Google Cloud Platform. You use them to write and deploy code that can respond to events coming from Google Cloud Services, including, but not limited to, the Firebase family of products.

With Cloud Functions, you piece together your application using different products. For instance, a user creates a new Document inside Firestore via the Web app. Consequently, a Cloud Function triggers, and responds to the event of Document Creation. The logic of a Cloud Function depends solely on the business scenario you are implementing.

Not only do they let you connect Google Cloud Services together, but they also allow you to create your own set of REST APIs to consume inside your Web or Mobile app.

The Cloud Functions project is a wrapper on top of the Google Cloud project. However, it was made easier for developers to configure and use.

The two major benefits Cloud Functions offer: Centralize your code in a safe way on Google Cloud Servers. Firebase Cloud Functions run on Google Servers. All of your apps, whether they be Web, Mobile or Desktop, can access and use them. Code security. It is better to save the access codes and keys for Firebase Services on the backend (on the Google Servers) rather than exposing them inside the client-side app code.

Cloud Functions are best used to: Trigger code in response to events coming from Firebase products. Perform writes to the Realtime Database and Firestore Upload to your Cloud Storage buckets. Respond to new accounts created in Firebase Authentication. Handle incoming HTTPs Request.

Firebase supports two flavors of Cloud Functions: HTTPs triggered Functions Background triggered Functions

Unlike Google Cloud Functions, Firebase Cloud Functions support only JavaScript/TypeScript with Node.js. The team is working on including more programming languages. Until then, let’s enjoy JavaScript!

HTTPs Triggered Cloud Functions

Let’s explore the anatomy of Cloud Functions for HTTPs triggers.

Start by ensuring Node.js version >= 8.13.0 is installed on your machine.

Next, install the Firebase CLI globally on your computer by running the following command:

npm install -g firebase-tools

Create a Firebase project by running the commands:

mkdir firebase-functions-http
cd firebase-functions-http

The next step is to log into Firebase services to connect the new project. Issue this:

firebase login

That command opens up a new tab in your default browser to ask for some permissions needed by the Firebase account.

Let’s initialize the Firebase project by running the following command:

firebase init

This command guides you through a command-line wizard to choose the Firebase features you want to add to the project.

For our case, let’s pick the following:

Which Firebase CLI features do you want to set up for this folder? Functions

What language would you like to use to write Cloud Functions? JavaScript

Do you want to use ESLint to catch probable bugs and enforce style? Yes

Do you want to install dependencies with npm now? Yes

That’s all!

Let the Firebase CLI do the project scaffolding, and get the project files ready.

The command scaffolds a Node.js project, and stores the Cloud Function related code inside the /functions folder.

The /functions.package.json lists all the dependencies needed by the Cloud Function. The most important dependencies are:

"dependencies": {
    "firebase-admin": "^8.9.2",
    "firebase-functions": "^3.3.0"
  },

Let’s make sure we have the latest bits of these packages by running the following command:

npm install firebase-admin@latest firebase-functions@latest

The /functions/index.js file contains the Cloud Function code.

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

exports.helloWorld = functions.https.onRequest((request, response) => {
    response.send("Hello from Firebase!");
});

The index.js file is a typical Node.js module file that exports a single Cloud Function named helloWorld. You can export more functions as needed.

The module starts by requiring the firebase-functions library. This library allows you to create Cloud Functions for HTTPs triggers. It exposes the onRequest() function. This function expects two parameters, the Request and Response objects. The callback function is required to return a Promise by issuing a call for response.send() function.

The popular Express.js module for Node.js is behind a Cloud Function for HTTPs trigger. When you deploy a Cloud Function on Firebase, it creates an Express.js app behind the scenes. This app will listen to any HTTPs request for /helloWorld, prepare a Request and Response object, and will call through your Cloud Function, passing it to the two objects.

You can include any code inside the onRequest() callback function like you do when writing Express.js apps.

I highly recommend reading this great article on dissecting the Express.js module, and learning how it’s made under the hood. Understanding how Express.js Works

Let’s run this Cloud Function locally by issuing the following command:

firebase serve --only functions

The command starts the Firebase Cloud Functions emulator to allow you to run the function locally, without the need to deploy it to Firebase servers.

✔  functions: Using node@10 from host.
✔  functions: Emulator started at http://localhost:5000
i  functions: Watching "/.../firebase-functions-http/functions" for Cloud Functions...
✔  functions[helloWorld]: http function initialized (http://localhost:5000/firebase-functions-http/us-central1/helloWorld).

Copy & Paste the Function URL into your browser, and you will see a plain text response of Hello from Firebase!.

To deploy the Cloud Function to Firebase platform, run the following command:

firebase deploy --only functions

Cloud Functions for HTTPs triggers can only be run under HTTPS and not HTTP.

Inside a Cloud Function for HTTPs trigger, you can call any other third party service. You can query the Firestore database, and return data from it, for instance.

You can always refer to the amazing Firebase Cloud Functions documentation to study the full range of capabilities supported by them.

Background Triggered Cloud Functions

The Background Triggered functions is the other type of functions offered and supported by Firebase.

Each and every product in the Firebase family exposes a set of events that are triggered upon a certain action.

For example, when a new Document is created inside Firestore, the OnCreate event is triggered.

Another example is when a new User is created in the Firebase Authentication module, the onCreate event is triggered.

exports.sendWelcomeEmail = functions.auth.user().onCreate((user) => {
  // ...
});

The functions object gives access to all supported types of Cloud Functions. This includes both the HTTPs, and Background triggered ones.

The example above gives you access to the user that was created. Then, you might decide to send the user an email, or push down a notification to the app. The sky's the limit!!

The Firebase Cloud Functions supports all Firebase products, and gives the developer the chance to handle many of the events triggered by them.

For a full list of all the supported background triggered functions, have a look at Trigger background functions

The Firebase Cloud Functions documentation is complete, and is extremely helpful to learning all the ins and outs. Therefore, without any further ado, let’s jump into our Notes App Writer, and add a new background triggered Cloud Function.

Demo

Clone the Notes App Writer at the add-auth branch. This is the branch we worked on in the previous article while authenticating users in the app.

Clone the app

Run the following command to clone the branch:

git clone --single-branch --branch add-auth git@github.com:bhaidar/notes-writer.git

Make sure to install all NPM packages by running this command:

npm install

Add support for Firebase Cloud Functions

If you haven’t logged into Firebase before, it’s time to do it by running this command:

firebase login

Once you log in, let’s initialize the Firebase services once again to include Functions this time.

firebase init

Follow the same steps mentioned in the HTTPs Triggered Cloud Functions section.

You will notice a new folder created under the root folder of the project named functions. This folder, as you know by now, holds all the source code for the Cloud Functions in your project.

It’s always important, whenever you add support for Cloud Functions in your project, to update the Firebase NPM packages by running the following command:

npm install firebase-admin@latest firebase-functions@latest

Use Environment Variables to store configuration settings

Let’s revisit the /firebaseConfig.js file. This file holds the Firebase connection settings as provided by Firebase Console.

I will make use of a hidden gem in Vue.js CLI v3, which allows you to use Environment Variables in your application to store such configuration settings. In fact, this is the recommended way of storing configuration settings in a Vue.js app rather than putting them in plain JSON or JavaScript files.

The CLI documentation referenced above gives you all the details about the Environment Variable files to use in your app. For now, create a new .env file at the root of the project, and paste the following keys:

VUE_APP_API_KEY=
VUE_APP_KEY_AUTH_DOMAIN=
VUE_APP_KEY_DATABASE_URL=
VUE_APP_PROJECT_ID=
VUE_APP_STORAGE_BUCKET=
VUE_APP_MESSAGING_SENDER_ID=
VUE_APP_ID=

Grab the actual keys from the Firebase Console and place them after they == sign on each and every line.

For instance,

VUE_APP_PROJECT_ID=notes-writer-f1e85

Going back to the firebaseConfig.js file, replace its content with the following:

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

// firebase init
const config = {
  apiKey: process.env.VUE_APP_API_KEY,
  authDomain: process.env.VUE_APP_KEY_AUTH_DOMAIN,
  databaseURL: process.env.VUE_APP_KEY_DATABASE_URL,
  projectId: process.env.VUE_APP_PROJECT_ID,
  storageBucket: process.env.VUE_APP_STORAGE_BUCKET,
  messagingSenderId: process.env.VUE_APP_MESSAGING_SENDER_ID,
  appId: process.env.VUE_APP_ID
}

firebase.initializeApp(config)

// firebase db
const db = firebase.firestore()

// firebase auth
const auth = firebase.auth()

// firebase collections
const notesCollection = db.collection('notes')

export {
  auth,
  db,
  firebase,
  notesCollection
}

Implement the Cloud Function

Let’s visit the functions/index.js file, and start implementing our function logic.

The purpose of this function is to listen to any new Note Document created inside Firestore, grab its details, and send them in an email.

Replace the contents of the index.js file with the following:

const functions = require('firebase-functions')
const admin = require('firebase-admin')

admin.initializeApp()

exports.onNewNoteCreated =
  functions.firestore.document('notes/{notesId}').onCreate((snap, context) => {
    const { body } = snap.data()
    const { params: { notesId } } = context

    console.log(context)
    console.log(body)
    console.log(notesId)

    return Promise.resolve(true)
  })

The JavaScript module imports the Firebase Functions Admin SDK libraries.

The Firebase Admin SDK lets you interact with Firebase from privileged environments to perform several actions.

The module exposes a single Cloud Function named onNewNoteCreated. This function subscribes to the OnCreate() event handler to run once a new Firestore Document is created.

The onCreate() event handler accepts as callback function having two parameters: DocumentSnapshot. EventContext.

The former parameter lets you access the content of the Document created, while the latter lets you access the context in which the event has occurred.

The next line extracts the body property of the Notes Document. Then, the code extracts the notesId from the EventContext parameter.

The variables are then logged to the Cloud Functions Logs database. From my experience, the Cloud Functions Logs is the best tool to debug and test your functions!

Finally, the function returns a resolved Promise. I will further discuss the concept of returning Promises from Cloud Functions in the next section of this article.

Let’s run the Cloud Function locally first by using the Firebase Functions Shell.

Run the following command:

firebase functions:shell
``

You use the Functions Shell to test your functions interactively. You can read more about it by following this link: [Test functions interactively](https://firebase.google.com/docs/functions/local-shell)

![Alt Text](https://dev-to-uploads.s3.amazonaws.com/i/yb0oljjnidl4ix4es15z.png)

Behind the scenes, the Shell loads the Functions emulator, and lists them all for reference.

To execute a single function, simply run the following on the **firebase** command line:

```bash
onNewNoteCreated({ body: "Hello Firebase Functions!" }, { params: { notesId: "note-#001" }})

Hit Enter!

The output is as follows:


'Successfully invoked function.'

firebase > >  

{ eventId: 'c6f8eec2-e7e0-463e-9966-c8c8b0a25505',
>    timestamp: '2020-02-15T08:12:02.088Z',
>    eventType: 'google.firestore.document.create',
>    resource:
>     { service: 'firestore.googleapis.com',
>       name:
>        'projects/notes-writer-f1s85/databases/(default)/documents/notes/note-#001' },
>    params: { notesId: 'note-#001' } }

>  Hello Firebase Functions!

>  note-#001

The first block of text represents the ExecutionContext object. It gives you details about the current event, and its context. For instance, the event type is a google.firestore.document.create. The full path of the new document shows inside the resource property. Finally, your Cloud Function has access to the params property that includes the ID of the new Notes Document.

The second block of text prints the body of the new Note Document.

Finally, the third block of text prints the notesId grabbed from the params property on the ExecutionContext object.

Send an email inside the Cloud Function

Let’s make our Cloud Function more useful! You have many options to do so with the Firebase family of products.

For instance, we could send the new Note as a Push Notification using the Firebase Cloud Messaging product. However, I would rather not introduce more than one Firebase product in one article.

Let’s, instead, send the contents of the new Note Document using an email. For that, we need to install an additional NPM package to allow us to send the email.

Make sure you are inside the /functions folder, run the following command:

npm install nodemailer

We are going to use the nodemailer Node.js module to send out the emails.

Replace the contents of the /functions/index.js with the following code:

const functions = require('firebase-functions')
const admin = require('firebase-admin')
const nodemailer = require('nodemailer')

admin.initializeApp()

var transporter = nodemailer.createTransport({
  host: 'smtp.gmail.com',
  port: 465,
  secure: true,
  auth: {
    user: '',
    pass: ''
  }
})

exports.onNewNoteCreated =
  functions.firestore.document('notes/{notesId}').onCreate((snap, context) => {
    const { body } = snap.data()
    const { params: { notesId } } = context

    console.log(body)
    console.log(notesId)

    const mailOptions = {
      from: '',
      to: '',
      subject: 'A new note is created',
      html: `
        <h1>New Note</h1>
        <p>A new note is created with the following details:</p>
        <p>
          Note Id: <br />
          ${notesId}
        </p>
        <p>
          Note Body: <br />
          ${body}
        </p>`
    }

    return transporter.sendMail(mailOptions)
      .then(() => console.log('Email Sent!'))
      .catch(error => console.error(error))
  })

Start by importing the nodemailer library.

Then, create a nodemailer transporter. The transporter is the object responsible for sending out the email. Nodemailer module supports SMTP based transport and other non-SMTP based transport. I will keep it simple, and use an SMTP transport for this Cloud Function.

For this to work, you need to create a new Nodemailer Transport using an SMTP account. I will be using the GMAIL SMTP account details. This is OK for testing locally but never used for production. Other options to use for production are: GMAIL OAUTH 2 and SMTP account you get from your hosting company.

Replace the user and pass fields with a real Gmail account.

Inside the Cloud Function, prepare a mailOptions object containing all the details of the email to send. Make sure to include the from, to, and the rest of the fields.

Finally, send the email by returning the transporter.sendMail(mailOptions) function call. This function returns a Promise.

That’s it! You can follow the steps above to test the function locally, using the Functions Shell.

Let’s deploy the Cloud Function to Firebase, and start receiving emails!

firebase deploy --only functions

The command above deploys all the Cloud Functions in your current app.

Now, whenever you create a new Note inside the app, the onNewNoteCreated() Cloud Function is triggered and eventually you receive an email similar to the one below:

Cloud Function Execution Process

Firebase internally manages the Server, and all the resources needed to deploy and run a Cloud Function. When a Cloud Function finishes executing, it needs to cleanup the resources used by the function.

How can Firebase tell or decide that now is the correct time to cleanup the resources, and that the Cloud Function has finished executing?

This task is certainly more complicated! Why?

Most of the Cloud Functions’ code you will be writing will interact with other Firebase SDKs, or even third party SDKs. This type of communication happens asynchronously.

A Cloud Function executes code, and returns immediately. However, there might be some kind of work that’s pending in the background, asynchronously. Therefore, Firebase cannot just run the function, and cleanup all the resources. It must wait until the function completely finishes running, and then do so.

For that reason, all of the Firebase SDKs support JavaScript Promises. What’s a JavaScript Promise?

A Promise represents some async work that should eventually complete! When work tracked by a Promise is still executing, the Promise is in a pending state. If the work completes successfully, the Promise is said to be fulfilled. If there is an error, the Promise becomes rejected.

These are the only states a Promise can go through. Once fulfilled or rejected, a Promise cannot go back to any other state.

For instance, the Firebase Admin SDK returns promises when your code: Reads or writes from a database. Interacts with files in the Cloud Storage. Sends a notification with Cloud Messaging.

Therefore, when dealing with Background-triggered Cloud Functions, it’s so important to just return the Firebase SDK API call you perform inside the Cloud Function. The Cloud Function Runner now has access to a Promise. As long as the Promise is in the pending state, it will wait, and will take no action. Once the Promise is fulfilled or rejected, it can safely remove all resources, and do the cleanup.

For an HTTPs-triggered Cloud Function, always make sure you return response.send() as the last line of the code. The Cloud Functions Runner will terminate and cleanup an HTTPs-triggered function only when the function returns a response to the client.

In this article, I’ve shown how to integrate and use a third party library, the Nodemailer. What we have implemented is a Background triggered function, hence we need to return a Promise at the end of the function. How are we doing so?

return transporter.sendMail(mailOptions)
      .then(() => console.log('Email Sent!'))
      .catch(error => console.error(error))
  })

The sendMail() function sends an email, and returns a Promise. In our case, we are sending an Email Sent! message to the logs when the Promise is fulfilled. Also, we are logging any errors when the Promise is rejected. At the same time, we are returning the sendMail() Promise to let the Cloud Functions Runner use that Promise to clean up the resources for this function. This only works because JavaScript Promises are chainnable!

Conclusion

For now, this will be the last episode on Fire the base of Vue.js! series.

Firebase is such a big topic, and requires many articles to cover it all. The team at Firebase did a great job at providing decent documentation. Still, I believe, working with the Firebase SDKs will give you experience and knowledge that theory cannot.

In the future, I might add episodes to this series. However, in the coming two weeks, I will start a new series on Vue.js development. Stay tuned!

Happy Vueing!

This Dot is a consultancy dedicated to guiding companies through their modernization and digital transformation journeys. Specializing in replatforming, modernizing, and launching new initiatives, we stand out by taking true ownership of your engineering projects.

We love helping teams with projects that have missed their deadlines or helping keep your strategic digital initiatives on course. Check out our case studies and our clients that trust us with their engineering.

About the author(s)

Bilal Haidar
Author, Developer, and Mentor: Professional ASP.NET 3.5 Security, Membership, and Role Management with C# and VB | A Complete Guide to VueJS
@bhaidar @bhaidar

Understanding Vue.js's <Suspense> and Async Components

In this blog post, we will delve into how and async components work, their benefits, and practical implementation strategies to make your Vue.js applications more efficient and user-friendly. Without further ado, let’s get started! Suspense Let's kick off by explaining what Suspense components are. They are a new component that helps manage how your application handles components that need to await for some async resource to resolve, like fetching data from a server, waiting for images to load, or any other task that might take some time to complete before they can be properly rendered. Imagine you're building a web page that needs to load data from a server, and you have 2 components that fetch the data you need as they will show different things. Typically, you might see a loading spinner or a skeleton while the data is being fetched. Suspense components make it easier to handle these scenarios. Instead of manually managing loading states and error messages for each component that needs to fetch data, Suspense components let you wrap all these components together. Inside this wrapper, you can define: 1. What to show while the data is loading (like a loading spinner). 2. The actual content that should be displayed once the data is successfully fetched. This way, Vue Suspense simplifies the process of handling asynchronous operations (like data fetching) and improves the user (and the developer) experience by providing a more seamless and integrated way to show loading states and handle errors. There are two types of async dependencies that can wait on: - Components with an async setup() hook. This includes components using with top-level await expressions. *Note: These can only be used within a component.* - Async Components. Async components Vue's asynchronous components are like a smart loading system for your web app. Imagine your app as a big puzzle. Normally, you'd put together all the pieces at once, which can take time. But what if some pieces aren't needed right away? Asynchronous components help with this. Here's how they work: - Load Only What's Needed: Just like only picking up puzzle pieces you need right now, asynchronous components let your app load only the parts that are immediately necessary. Other parts can be loaded later, as needed. - Faster Start: Your app starts up faster because it doesn't have to load everything at once. It's like quickly starting with the border of a puzzle and filling in the rest later. - Save Resources: It uses your web resources (like internet data) more wisely, only grabbing what’s essential when it's essential. In short, asynchronous components make your app quicker to start and more efficient, improving the overall experience for your users. Example: ` Combining Async Components and Suspense Let's explore how combining asynchronous components with Vue's Suspense feature can enhance your application. When asynchronous components are used with Vue's Suspense, they form a powerful combination. The key point is that async components are "suspensable" by default. This means they can be easily integrated with Suspense to improve how your app handles loading and rendering components. When used together, you can do the following things: - Centralized Loading and Error Handling: With Suspense, you don't have to handle loading and error states individually for each async component. Instead, you can define a single loading indicator or error message within the Suspense component. This unified approach simplifies your code and ensures consistency across different parts of your app. - Flexible and Clean Code Structure: By combining async components with Suspense, your code becomes more organized and easier to maintain. An asynchronous component has the flexibility to operate independently of Suspense's oversight. By setting suspensible: false in its options, the component takes charge of its own loading behavior. This means that instead of relying on Suspense to manage when it appears, the component itself dictates its loading state and presentation. This option is particularly useful for components that have specific loading logic or visuals they need to maintain, separate from the broader Suspense-driven loading strategy in the application. In practice, this combo allows you to create a user interface that feels responsive and cohesive. Users see a well-timed loading indicator while the necessary components are being fetched, and if something goes wrong, a single, well-crafted error message is displayed. It's like ensuring that the entire puzzle is either revealed in its completed form or not at all rather than showing disjointed parts at different times. How it works When a component inside the boundary is waiting for something asynchronous, shows fallback content. This fallback content can be anything you choose, such as a loading spinner or a message indicating that data is being loaded. Example Usage Let’s use a simple example: In the visual example provided, imagine we have two Vue components: one showcasing a selected Pokémon, Eevee, and a carousel showcasing a variety of other Pokémon. Both components are designed to fetch data asynchronously. Without , while the data is being fetched, we would typically see two separate loading indicators: one for the Eevee Pokemon that is selected and another for the carousel. This can make the page look disjointed and be a less-than-ideal user experience. We could display a single, cohesive loading indicator by wrapping both components inside a boundary. This unified loading state would persist until all the data for both components—the single Pokémon display and the carousel—has been fetched and is ready to be rendered. Here's how you might structure the code for such a scenario: ` Here, is the component that's performing asynchronous operations. While loading, the text 'Loading...' is displayed to the user. Great! But what about when things don't go as planned and an error occurs? Currently, Vue's doesn't directly handle errors within its boundary. However, there's a neat workaround. You can use the onErrorCaptured() hook in the parent component of to catch and manage errors. Here's how it works: ` If we run this code, and let’s say that we had an error selecting our Pokemon, this is how it is going to display to the user: The error message is specifically tied to the component where the issue occurred, ensuring that it's the only part of your application that shows an error notification. Meanwhile, the rest of your components will continue to operate and display as intended, maintaining the overall user experience without widespread disruption. This targeted error handling keeps the application's functionality intact while indicating where the problem lies. Conclusion stands out as a formidable feature in Vue.js, transforming the management of asynchronous operations into a more streamlined and user-centric process. It not only elevates the user experience by ensuring smoother interactions during data loading phases but also enhances code maintainability and application performance. I hope you found this blog post enlightening and that it adds value to your Vue.js projects. As always, happy coding and continue to explore the vast possibilities Vue.js offers to make your applications more efficient and engaging!...

Apr 24, 2024

6 mins

VueWeb PerformanceUXJavaScript

Getting started with Vitepress

Getting started with Vitepress to create your blog site Have you heard about Vitepress, but you have not checked it out at it yet? Well, in this article, we are going to cover the basic setup and share what all the fuss about this new fantastic static site generator. If you are looking for something that would allow you to quickly create a static site with Markdown support, search, Light/Dark theme, advertisement, navigation, and much more, then Vitepress is what you are looking for. Suppose you want some proof of Vitepress's power without having to invest any further time, I suggest you head over to the main Vitepress site (vitepress.dev) and experience what Vitepress can do, as the official site is built on Vitepress! What is Vitepress Vitepress is a powerful Static Site Generator powered by Vite mainly used for Documentation and Blogs with the default theme, and open to customization to be used for anything you may need it to with custom themes and theme overrides.. Vitepress power comes from its low learning curve, powerful configuration settings, and the ability to easily customize it. For example, internationalization is built-in, Theme toggling is built-in and even full-site searches require a single line in the config to be set up. What makes Vitepress so powerful is its extensive configuration and the fact that it can be customized by overriding the existing theme, creating your theme, or simply enhancing pages with custom Vue code. Prerequisites To successfully run the following demo, you will need: - Node.js version 18 or higher. - Terminal for accessing VitePress via its command line interface (CLI). - Text Editor with Markdown syntax support. - VSCode is recommended, along with the official Vue extension. Create your project To create the project, we will follow the steps shown in the official Getting Started guide. If you want to set up a Vitepress project quickly, run the following steps: - Create a new folder mkdir vitepress-tutorial - Access the folder cd vitepress-tutorial - Install Vitepress npm add -D vitepress - Run the Wizard npx vitepress init - Answer the questions: - Where should VitePress initialize the config? - Site title - Site Description - Theme - Do you want Typescript support? - run npm run docs:dev - Enjoy your site. After you run the above steps, your Vitepress will be ready and running as shown below What is available out of the box The site comes fully set up with enough to get you started. Let's see what features are available within the software: - Navbar: The site comes with a Navbar that already includes links to our blog pages - Light/Dark theme: Out of the box theming - Home page: Basic Homepage layout - Blogs: Two different blog posts with sidebar navigation All of the above is available with just 4 files! Let's move forward and see how to customize our app. Overriding the homepage It is time to modify our site by accessing its folders. What you will probably notice when opening the site, is that Vitepress follows a very simple file structure, in fact, a new installation just includes 4 extra files on top of the expected package.json and node_modules. Let's update our homepage to make it more unique. Because Vitepress follows a "file-system based router" we can find this file within the root of the project within a file called index.md. This file will be accessible at "/" or "/index.html" of your site. The content of the file is the following: ` As you can see, the file has no code in it, and it is just driven by configuration, or more specifically in this case Markdown frontmatter, that is a set of configurations accepted by markdown files that help you set up your options such as title, description, og:image. We will describe frontmatter in more detail later in the article. Before we jump into modifying the configuration of the file, you should know that Vitepress has a very extensive and well-detailed documentation site where you can find help if you are stuck or would like to learn more. In this case, we are overriding the "home" page, so the documentation can be found here: Home Page Default Theme configuration. If you read the current file within the homepage, you will notice that it defines a "layout" of "home". This layout displays a main header with CTAs and a set of feature blocks. There are three different layouts available in the Default theme: "home", "doc" and "page". The title and description have already been set from the information we provided from the installation wizard. But the rest is just a basic boiler template. Let's see what we can change: 1) Add a hero image. This image can either be externally sourced or saved within the repository. ` 2) Update the action buttons. ` As shown above, Action buttons have two themes "brand" or "alt" and can accept internal or external links. Vitepress is clever enough to set the external links to open in a new tab and set the rel="noreferrer". 3) Change the feature blocks: Features blocks are great for engaging with the user and telling them what makes your site special. This accepts an icon and some text, so let's change ours with the following: ` The homepage is now completed and updated and it should look like this: Please note that what we did on the homepage is just changing the markdown front matter of the "home" layout. What this means is that if you want to, you can easily customise the page further by either adding more blocks to the layout file or actually by writing and styling the rest of the page as normal. Site configuration In this step, we are going learn about the main site configuration and how we can use it to customize our site. The configuration file can be found in the .vitepress folder under the name of "config.mjs". Just like the homepage layout, the configuration used in the preset file is self-explanatory: ` This file is very important and you are probably going to have it open at all times as it is going to be responsible for the layout of the sidebar navigations of your site. In this section, we are going to learn how to use the Vitepress configuration file to achieve the following: - Modify the sidebar navigation - Enable Search - Add Favicon to your site Modify the sidebar navigation The sidebar is the component displayed on the left-hand side of the blog pages. This is not automatically generated, but it is manually set in this file. You can have more than one navigation, so, for example, you could specify sidebar navigation that shows in pages that have "/blog/" within their path and another one for all markdown pages that have "/tutorials/". Let's see how to implement this: ` With the above code, there will be 2 different sidebars. One will just show if the URL includes "/blog" and the other will be displayed if the path includes "tutorials". Clicking on the above items will give a 404 error as we do not have any pages in that specific location. Still, we can easily fix the issue by creating the two folders "blog" and "tutorial" and creating the required files within these folders in our case are "index.md" and "one.md" for the blog and "index.md" and "two.md" for tutorials. The sidebar has further settings like the ability to create a nested tree or create collapsable menus. You can learn more by checking out the the official documentation on default theme sidebar. Enable Search No documentation or blog site is complete until a search is fully implemented on it. Luckily for us, enabling a site-wide search is extremely simple with Vitepress. Vitepress supports two different search types: a full-text search using minisearch and Algolia based search. In this tutorial, we are going to enable the full-text search. This is fully built-in and requires no external accounts. To enable search, we need to add a "Search" parameter within our themeConfig and set the provider to "local". We can add this right below the socialLinks. ` With just a simple config change, our site will now have a full site search working as shown below: The official search documentation has further information about the look and functionality of the search. Add Favicon to your site Even if the site configuration is very extensive, there are times when you will need to add something within the site-wise page that is not available. In this section we are going to learn how to add specific attributes to the of our site, and specifically how to add a favicon. To add custom values to the head, we are going to use the "head" properties available with the Vitepress configuration. The "head" configuration is an array that accepts an array with the element type (eg. link, script, meta), and an object including all the attributes for that specific element. So for example to replicate the following HTML: ` we would define the following head config: ` We can use this technique to set up metadata and even load fonts or Google Analytics. More info in the site-config head Writing your post In the last section of this article, we are going to learn how to actually write a blog post and also learn how to customize the pages with JS and styles. Writing your first page In the previous section, we created a couple of markdown files, but they are currently empty. Let's see how to create beautiful documentation using the built-in feature of Vitepress. In this section, we are going to work on the file stored in /blog/index.md. This file can be accessed in your browser by accessing "http://localhost:5174/blog/index.html". Blog Frontmatter Every file needs to have a frontmatter defined. This is used to define basic information on the page, such as the title, description, and more. For best SEO results, it is best practice to always define a title and description for a new page. We can do this by adding the following code at the top of our file: ` Frontmatter in Markdown files are delimited by the "---". In the above code, we set our title and description. Vitepress frontmatter supports further config like lastUpdates, sidebar, outline, and more. You can find info on the frontmatter-config documentation. Frontmatter has some global configuration, such as title and description, but also "layout specific" settings that are just available on specific layouts. This is clearly explained in the documentation. Blog Markdown Now that our post frontmatter is set, it is time to write the content of it. This is done using a very extensive markdown engine. Let's start with the basics and write a heading with some text and a link as shown below: ` After saving, our development environment will show the following results: Let's add a couple of headings and a table of contents to our document using [[toc]] to the top of our page: ` The above will produce an unordered list with all our links. The last feature that I want to share about the Vitepress markdown engine is the code editors. The markdown engine used in Vitepress offers extensive features when it comes to code rendering. Features available are "code highlight", "code focus", external snippets loading and much more. The full list of features can be found in the markdown docs. Let's implement a simple code snippet with a line of code focused. This can be achieved by adding "// [!code focus]" at the end of our row. Let's give it a try: ` The output of this will be: Customize your blog with Vue In this last section, we will learn how to customize our code by adding js logic, style, and external components. Before we begin, it is important to understand that when you use the default template of Vitepress, your pages are going to be rendered with Vue. This means that we can expand the individual page's functionality by rendering other vue components and/or writing logic and styles directly on the page. To better explain this concept, we are going to create a team page. Create a file called team.md within the root of our repository. This file will be accessible on "http://localhost:5174/team.html" and will be just a simple Markdown file. First, we set up the frontmatter as before. In this case, we have to specify an additional config called "layout". This will ensure the page has no style or components loaded such as sidebar or aside. ` Then we will have to create our team variable, just like a normal Vue component; we can do so by defining a script setup tag and defining the constant there. ` In the above code, we have imported the VPTeamMembers component from the vitepress/theme and defined an array of members. The values used in the members array are hardcoded, but as you may expect, you can load this information directly from an API. We now have to use the "members" variable within our file. We can do so by writing normal JavaScript. The markdown file will evaluate the JavaScript and render it, so in the following example it will render a specific component. ` Before we move forward we need to define some style as the page is unstyled since we have loaded the layout of "page". Just like we did with the tag, we can load a tag and update our styles: ` The completed file will look like this: ` The file above now includes: - A frontmatter that specifies a "page" layout - A script tag that loads an external component and defines a variable - Styles to make the page pretty - Markdown with a custom component The completed team page would render the following: Conclusion Vitepress is an extremely flexible static site generator. Its default theme provides you with everything you need to get started quickly. The ability to load external themes, enhance the current theme, and or write custom code within your page makes this tool extremely powerful. In future articles, we will discover what components are available within the Default Theme and see how you can make the most of your Vitepress site but keep on coding....

Dec 21, 2023

12 mins

VueViteVitepress

Making sense of Multiple v-model Bindings in Vue 3

This article is one of a series of articles on what’s new in Vue 3. If you haven’t checked that series yet, you can do so by visiting the links below: - Take your App to the Next Level with Vue 3 - Async Components in Vue 3 - Teleporting in Vue 3 - Your first Vue 3 app using TypeScript - Vue 3 Composition API, do you really need it? In this installment, I will introduce the new v-model in Vue 3 and go through a new feature that allows you to use multiple v-model on the same component! By design, the v-model directive allows us to bind an input value to the state of an app. We use it to create a two-way data binding on the form input, textarea, and select elements. It handles updates in two opposite directions: When the input value changes, it reflects the value onto the state inside the Component. When the Component state changes, it reflects the changes onto the form input elements. The core concept of v-model remains the same in Vue 3 with more enhancements and features. Let’s dig in! Vue 2: v-model Vue 2 supports a single v-model on any given Component. In Vue 2, to build a complex Component that supports two-way data binding, it utilizes a single v-model with one full-blown payload. The Component handles the state internally for all the input elements. It generates a single payload object representing the state of the Component. Finally, it emits an event to the parent Component with the payload attached. This method had several pitfalls, especially for creating Vue UI Libraries. Of these pitfalls is the vagueness of the payload interface. It’s unclear what’s being included in the payload. A developer had to loop through the payload object in order to uncover what properties were there. Another is the need to write the logic inside the Component to handle the internal state and the generation of the payload object. Shortly, we will uncover what has been improved in this regard with Vue 3. However, before this, let’s review some basics on how Vue 2 handles implementing two-way data binding in Components. Vue 2: Two-way Data Binding As mentioned, Vue 2 uses the v-model directive to support two-way data binding on Components. Internally, it follows certain steps and rules in order to support the v-model directive. By default, the v-model directive uses different properties and emits different events for different input elements: Text and Textarea elements use the value property and the input event Checkboxes and Radio buttons use the checked property and the change event Select fields use the input property and the change event. Building a Component with a single input element will internally use something similar to the snippet below: ` The custom Component above defines a single prop named value as follows: ` Then, in the parent Component, you use the new custom Component as follows: ` The v-model directive assumes that the CustomComponent defines an internal property named value and emits a single event named input. What if the CustomComponent has to handle multiple inputs? How do we accomplish that in Vue 2? Well, there is no official solution. However, there are two methods that you can use: The CustomComponent defines a single property named value of type Object. Internally, it parses the object into data fields and does the mapping manually on the template. On every change of any of the fields, it prepares a payload for all the fields and emits a single input event, and attaches the payload. That’s a lot of code to write for such a custom component. The other option is to skip using the v-model directive and instead utilize individual input/event pairs. I will illustrate this in a moment. Assuming you have a custom Component to handle the user’s first name and last name, you would employ something similar: ` As for the properties, the Component defines the following: ` Finally, the parent Component uses the new component as follows: ` We are not using the v-model anymore and providing multiple two-way data bindings on the new component. Further your understanding by reading the official docs on Using v-model on Components Vue 3: v-model In Vue 3, the v-model directive has had an overhaul to give developers more power and flexibility when building custom components that support two-way data binding. The v-model directive now supports new defaults. The default v-model property is renamed to modelValue instead of the old name of value. The default v-model event is renamed to update:modelValue instead of the old name of input. You might be thinking that's more typing when using the new v-model directive. The Vue team are one step ahead and have given you a shorthand to use instead. Let’s rebuild the custom component using it. ` The custom component defines a single prop named modelValue as follows: ` Then, in the parent component, use the new custom component as follows: ` The new v-model directive offers the new shorthand that is used like this: ` The v-model directive assumes that the CustomComponent defines an internal property named modelValue and emits a single event named update:ModelValue. In case you don’t want to use the default naming convention, feel free to use another name. Just remember to be consistent when naming properties. Here’s an example of using a custom name for the modelValue property. ` The custom component above defines a single prop named modelValue as follows: ` Then, in the parent component, you use the new custom component like so: ` Notice the use of the property fullName instead of the default property name. Vue 3: Multiple v-model directive bindings I hope the Vue 3 shorthand form of the v-model directive has given you a "hand up". With this, the v-model gives the flexibility to use multiple v-model directives on a single component instance. The modelValue can be renamed to whatever you want, allowing you to do this! This great new feature eliminates the previous two solutions I offered up on handling complex custom components for Vue 2. Let's jump in and go through an example demonstration! Demo - Multiple v-model directive bindings Let’s build a custom Address component that can be embedded in any form to collect a user’s address. > You can play with the example live on: vue3-multiple-v-model. > You can check the source code for the example on: vue3-multiple-v-model. Figure 1 below shows the final app in action. Let’s start by building the HTML template of the new component. Figure 1 shows that all the fields used are of type input elements. Except for the last one which is a checkbox element. Therefore, it’s suffice to focus on a single input field that will eventually be replicated for the rest of fields. ` The address-line input field binds the :value directive and the @input event as per the new v-model directive specifications in Vue 3. The component defines the following property: ` The other fields follow the same structure and naming convention. Let’s look at the checkbox field and see how it’s defined: ` In the case of a checkbox field element, we bind to the :checked directive instead of the :value directive. Also, we use the @change event instead of the @input event as in the case of input field elements. The event name follows the same standard way of emitting events in the new v-model directive. The component defines the following property: ` Let’s now embed the new custom Address component into the App component: ` For each and every property on the custom component, we bind using the v-model:{property-name} format. The modelValue was replaced with the specific property names we have in hand. When there was a single input binding, the shorthand format was so much easier. However, when there are multiple input elements, the modelValue is in a league of its own! Now, let’s define the properties inside the App component using the new Composition API setup() function: ` You create a new reactive property with an object payload. Finally, you return the reactive property to the component and use it to set bindings on the custom Address component as follows: ` That’s it! Conclusion Vue 3 has many new features and improvements. Today, we saw how we use multiple v-model directives on a single component instance. There is so much more to learn and uncover in Vue 3. The coming installments of this series will continue to look at different features to help you move from Vue 2 to Vue 3. Happy Vueing!...

Nov 6, 2020

6 mins

Vue

Building a Stripe App: A Step-by-Step Guide to QR Code Generation

Building a Stripe App: A Step-by-Step Guide to QR Code Generation Why Build a Stripe App? I recently participated in an audio space with the Stripe team, and something they said really stuck with me: the Stripe app store is a growing area that isn't overly saturated yet. There's a lot of potential for new apps, and companies can use this opportunity to grow. I work at a company called This Dot Labs, and we've created several Stripe apps and even own one. After looking at the data, I can confirm that the Stripe team was right! Creating a QR Code Generator App For this tutorial, we'll build a QR code app that can take a URL and generate a code for it. This is a good use case to help you understand the ins and outs of Stripe's developer tools. Why QR Codes? QR codes are useful tools that have become common in e-commerce, restaurants, and other industries. While Stripe already has a QR code tool, we'll make our own to familiarize ourselves with their syntax and problem-solving approaches. Project Structure Before we dive into the implementation, let's look at the structure of our Stripe App QR Code project: * .vscode: Contains settings for Visual Studio Code * source/views: Holds the main application views * .gitignore: Specifies files to ignore in version control * stripe-app.json: Defines the Stripe app configuration * ui-extensions.d.ts: TypeScript declaration file for UI extensions * .build: this is where the built Stripe app gets placed. Step-by-Step Implementation 1\. Install Stripe Locally First, you need to install Stripe on your local machine. The documentation provides great instructions for this: * For Mac users: Use Brew to install * For Windows users: Download the package and add it to your environment variables You can find the details here in the stripe docs to install the Stripe CLI https://docs.stripe.com/stripe-cli When using Windows, you must do stripe login from Powershell, NOT from Git bash or any other tool. After the server is up, then you can continue using git bash for everything else. After stripe login, you need to enter stripe apps start. Once you do that, the server is up and running and you can go back to using git bash or any other tool. 2\. Install Dependencies We'll be using an extra package for QR code generation. Install it using npm: ` 3\. Set Up the Main Component Let's look at the home.tsx file, where we'll use Stripe's UI components: ` These components are similar to other UI libraries like Bootstrap or Tailwind CSS. 4\. Create the UI Structure Our app will have: * An input field for the URL * Validation using a regex pattern * Error handling for invalid URLs * QR code generation and display Here is the Home.tsx file that is located in the src/views folder ` * ContextView` is at the top level of the app where we see the Title and the link to the Stripe Docs that we placed in our Context View. * Box is how you use Divs. * Banners can be used to show notification errors or any other item you wish to display. * Textfields are input fields. * Everything else is pretty self-explanatory. 5\. Handle Content Security Policy One problem I personally ran into was when I tried to redirect users, the Stripe policies would block it since I did not express that I knew what it was doing. I had to go into the stripe-app.json file and mention the specific security policies. For this particular exercise, I kept these as null. This is my stripe-app.json file. ` 6\. Configure App Views As you can see here, the stripe-app.json file shows the views for each file I have. The Home.tsx file and the Invoice.tsx are also included This is our way of saying that for each view we have, show the app functionality on that page. Our stripe-app.json file will show it but also, the manifest.js file in our .build folder will also show the same. Any view that doesn't have a file will not show the application's functionality. So, if I were to go to transactions, the app would not show the same logic as the home or invoices page. By following these steps, you'll have a fully functional QR code generator app for Stripe. This is just a simple example, but the potential for Stripe apps is massive, especially for businesses serving e-commerce customers. If you need help or get stuck, don't hesitate to reach out, danny.thompson@thisdot.co. The Stripe team is also very active in answering questions, so leverage them as a resource. Happy coding!...

Dec 18, 2024

4 mins

stripe

Let's innovate together!

We're ready to be your trusted technical partners in your digital innovation journey.

Whether it's modernization or custom software solutions, our team of experts can guide you through best practices and how to build scalable, performant software that lasts.

Going Serverless with Vue.js and Firebase Cloud Functions

Fire the base of Vue.js! - 3 Part Series

Firebase Cloud Functions, the concept

HTTPs Triggered Cloud Functions

Background Triggered Cloud Functions

Demo

Clone the app

Add support for Firebase Cloud Functions

Use Environment Variables to store configuration settings

Implement the Cloud Function

Send an email inside the Cloud Function

Cloud Function Execution Process

Conclusion

Bilal Haidar

You might also like

Understanding Vue.js's <Suspense> and Async Components

Getting started with Vitepress

Making sense of Multiple v-model Bindings in Vue 3

Building a Stripe App: A Step-by-Step Guide to QR Code Generation

Let's innovate together!

You might also like

Understanding Vue.js's <Suspense> and Async Components

Getting started with Vitepress

Making sense of Multiple v-model Bindings in Vue 3

Building a Stripe App: A Step-by-Step Guide to QR Code Generation