DEV Community: Facundo Giuliani

Storyblok React SDK now supports React Server Components 🎉

Facundo Giuliani — Mon, 22 May 2023 22:05:19 +0000

What's new?

This is not another minor release: We added React Server Components support to Storyblok's React SDK. Now, you can integrate Storyblok into your apps created with any version of Next.js, as well as the latest version of React and other React based frameworks like Remix.

Boost the performance of your new websites with full support for React Server Components and Next.js 13 App Router.
Visual Editor Live Editing is in place - keep getting instant feedback on website changes.
Enjoy the best in class DX with our new StoryblokStory and StoryblokBridge components for Next.js 13.
Leverage the performance gains of server-components-only websites with our optional "Full RSC mode".
New tests, re-modeled Readme, and new code samples to make it a breeze for you to start over.

You can now implement Storyblok for both Pages and App Router. Depending on how much logic you want to keep on the server, React SDK offers different approaches to enable the editing experience inside Storyblok's Visual Editor.

We’re confident that the new Storyblok React SDK 2.1.0 with full RSC support will help you build the next generation of dynamic, high-performance web applications.

Try it now ⚡️

Wait no more and have it running with Next.js 13 in 5 minutes, step by step. Read the tutorial here.

Want to go straight to the arena? Clone this minimal project and start playing.
Note: just ensure to replace your space token, set https and so on (the guide above explains it well).

You can read all the details on how to use the React SDK on your projects in the readme.

Words of appreciation

Special thanks to Arisa, Alex, and Chakit for investigating and experimenting the different approaches and coming up with flexible solutions.

Psst - little secret for you 🤫

Storyblok Gatsby SDK will soon adopt RSC support from Storyblok React SDK for full Gatsby 5 support (Partial Hydration, etc).

Impressions from 2022 Dev Conferences

Facundo Giuliani — Fri, 23 Dec 2022 11:40:00 +0000

After a couple of years of uncertainty and online activities, 2022 showed that developers were really missing the in-person events. Dozens of initiatives happened all around the world, with different approaches and ideas, offering the possibility to people from different backgrounds to congregate in venues of all types to learn, share, connect and enjoy.

From a personal perspective, 2022 was the first year I attended in-person conferences as a Developer Relations Engineer. Also, during this year I had the chance to present talks at in-person international conferences for the first time, being React Miami 2022 my first experience.

With this article, I’ll try to recap and share some thoughts, reviews, and impressions related to my in-person experiences during this year that is about to end.

Before the events

Among the different tasks that the organizers have to accomplish, communicating with the people is an important one. They need to send details about the conference, the venue, the talks, the tickets, pre and post-conference events, and other interesting information for the attendees. To maximize the experience, organizers should share with the people as many details of the event as possible.

From the point of view of the speaker, you may be asked to send some information in advance: An outline of your talk, the slides that you will use, equipment that you’ll need, preferences about the day/time for your talk, etc. One thing I learned is that even though not all the speakers will have the slides ready in advance, sending them to the organizers can help to verify the direction of your talk and check if you are following the code of conduct and accessibility standards. Organizers can check the font, colors, and animations to confirm that your slides will see correctly during the event.

If you are going to the event as a regular attendee, you will probably receive some emails with important information about the conference: The schedule, venue details, sponsors, details about the talks and the speakers, stats about the tickets being sold, etc. Some conferences also send regular emails, like a newsletter, with other interesting news and articles.

The trips

I’m grateful for being able to travel to different countries and cities. I always loved traveling, and doing it as part of my job makes me really happy. Visiting nice places, talking to locals, going to cool restaurants and pubs, and getting some spare time to walk around the streets, are great boosts of energy that, combined with the events themselves, end up being amazing experiences.

I had to take a lot of planes this year, and most of them were really long trips. Buenos Aires is pretty far from most of the cities in Europe and the US, and we don’t have direct flights to all of them. The more I traveled, the more efficient I tried to be with the whole experience. Traveling to the airports, going through all the security checks, waiting for the plane to take off, connecting flights, and other fun (?) experiences consume a lot of time and energy, that you would prefer to spend on other things.

Here I share some tips that helped me to get better experiences when traveling to different cities. If you, the reader, have some tips and travel hacks to share, I’ll really appreciate it!

Pack as less as possible. Avoid taking big bags with you, you will have to carry them. Also, you will need space for the swag that you will get at the conference.
Whenever it’s possible, do the check-in of your trip in advance, online.
Don’t check your bag. Most of the time spent in an airport is taken by the process of checking bags. The long line at the airline desk, waiting for the families and groups to get everything ready and leave their big bags, can be spent in a smarter way (arriving a little later to the airport, drinking a coffee, reading, etc.)
Sign up for the loyalty programs of the different airlines. And, whenever it’s possible, use the same airline to fly in order to earn more miles that can be used later.

One more important thing: Check which hotel are the speakers going to stay in, and book a room at the same hotel if it’s possible. The fun things of a conference also happen in the lobby of the hotel.

Being from South America

Something that I always insist on, and I usually tell this to the people I meet during the conferences, is how privileged I am to attend these amazing events full of people from all over the world. In Argentina, and Buenos Aires in particular (the city where I live), we have just a few dev conferences and a bunch of local meetups. And even though some of them are pretty cool, the speakers are generally local, as well as the audience.

Don’t get me wrong: That’s very cool and I really enjoy attending these events. But in other parts of the world, conferences join attendees and speakers from different countries and cities, who rarely come down to Argentina. This year I had the chance to meet amazing folks, some of them whom I already knew from the internet, and some I didn’t, and I ended up sharing amazing moments with them.

If you have the chance, at least once, to travel to a different country and attend a conference, I encourage you to do that. I know that not everyone has the chance to do it, because of different reasons. Conferences, in general, happen in places like Europe or the US. And might be hard to plan, organize and pay for a trip to those destinations from distant places, like South America. And that’s why I say I’m a privileged person and I’m thankful for that. But again, if you are lucky like me and you have the chance to travel, attending a dev conference with interesting talks, and chatting with people from different backgrounds, and from different places of the world, is a really fulfilling experience.

Also, it’s always cool to meet your heroes in person.

Speakers

I enjoyed having one-to-one talks with awesome people from the developer community. Some people that I already knew from the internet, and some people that I met for the first time and now we keep the contact. You don’t need to get to any VIP place to talk to the speakers. They spend time at the conference as any other attendee, and they are open to talking with you! Popular devs, trainers, and teachers, that have created amazing content to help other people to learn about development, are in-person at the same place as you are. And they will be happy to talk to you. That’s an opportunity that you don’t want to miss.

Conference staff usually organizes a speaker’s dinner, as a way of saying “thank you” to the people for the effort they put into creating the content, preparing the talk, and traveling to the event. This is a cool opportunity to talk to other speakers while having some food and drinks, in a place with a reduced amount of people. If you are speaking at an event, the speaker’s dinner is a great moment to talk to your colleagues and learn from them.

Something super valuable is that speakers usually attend other talks, and they share feedback about them. That’s very helpful mainly for speakers with not much experience. Also, having the chance to see them presenting is a way of learning from them. Each speaker has their own style, but you can learn something new from all of them.

If you don’t have the chance to talk to the speakers during the conference, you can do it at the after-events that usually are organized by the conference staff. I will talk more about them later in this article.

Venues

From usual office spaces to big conference venues, I had the chance to visit places very different, in size and style. It’s that the organizers consider the number of people that will attend the event, in order to have enough seats for the people that want to attend a talk, but also to have enough space to chat and walk through the sponsor booths.

For me, it’s good not to have a super small place, but either a big place can be counterproductive: People would scatter among the whole place, not enabling sporadic groups to chat to appear. It’s also cool to have quiet places available for people that need to do some work, or want to rest a little bit. About the lunch time and coffee breaks, I personally prefer the type of food and drinks that allow the people to eat standing up, while talking to other attendees.

About the stages, I personally prefer the single-track conferences. I understand that sometimes the idea is to have multiple tracks to catch the attention of people from different backgrounds, in order to cover different topics. Also, it depends on the number of people attending to the conference, since not all the venues have gigantic rooms to held all the people at the same time. But from the speaker point of view, and my personal opinion, I prefer not having to “divide” the audience and make them choose which speaker they want to see.

To mention some of the places I’ve been to this year:

Jamstack Conf was organized in some kind of raw ballroom in the center of San Francisco. A very big place with an outdoor rooftop connected to different parts of the venue.
Render ATL’s venue was a campus in Atlanta with three different stages. There were a lot of people and the weather was amazing. That helped to enjoy the curious part: An outdoor stage with no seats where, in order not to bother people working at a close office space, attendees needed to use headphones to hear the talk.
React Miami was “a conference inside a conference”: eMerge Americas, a big tech conference, was organized in a gigantic conference venue in Miami, and a big room inside that venue was dedicated to React Miami.
Kansas City Developer Conference congregated really a lot of people in a very big venue in downtown Kansas City. With multiple rooms to host the different tracks, all the rooms were always crowded with people.
Nerdearla 2022, the Argentinian conference, is held in some kind of abandoned factory pretty popular in Buenos Aires.

Attendees

I love talking to people. And the cool thing about conferences is that there is a lot of people to talk to! Listening about their stories, backgrounds, jobs, is a great experience that helps to learn a lot. People from different countries, with different levels of expertise, sharing feedback or asking questions, is something that helps the speakers to engage with the community. But also helps the developers in general to know about what is a trend in the dev world, what are the preferences when picking a tool, what is the people expecting or waiting for, what are their regular pains when working with certain frameworks, etc.

Because of the size of the conference, CityJS Brazil was probably the one with the most local attendees. It was a very cool experience, full of people that enjoyed starting a chat, asking things, and thanking for being there.

About that, something cool for the speakers is getting a “thank you” from the attendees. It may sound silly, but after presenting a talk in front of hundreds of people, you need a kind of signal to know that your talk was cool. Or probably that it was not what they were expecting: All the feedback is helpful.

Talks

I attended a lot of talks, and I had the chance to see many good ones. I personally prefer the ones that are not overloaded of data and information, but they present a specific topic in an interactive and dynamic way, triggering the interest of the attendees to learn more about that when they get back home (or to talk to the speaker later, in the coffee breaks).

Depending on the conference, you can have talks about different topics: Deep lessons about advanced topics, introductions to new tools or techniques, discussion panels, soft-skills talks, etc. That will depend on the expected audience for the conference. Conf staff will keep that in mind during the talk selection process.

What’s great for me, and it’s something I need to improve, is the way on how to present the talk. The words you use, the gestures, the design of the slides, the structure of the talk, the code that you show, the gags and jokes. I attended great talks from amazing people that I would love to learn from.

What I want to keep clear, and I think most of the speakers will agree with me, is that you don’t need to be the smartest person of the planet to stand up at the stage and present a talk. All people have great ideas to share, or interesting topics to discuss, and each one of us has its own style to present it. If you are considering to present a talk at an event, but your impostor syndrome doesn’t allow you, it’s time to present the fight. The community is rooting for you, and they want to learn what you want to share, with your personal style. If you want to get into the conference speaking world, and you don’t know how to start or you think you can’t, contact me! I will help you as much as I can.

About the questions and answers related to the talks, I prefer to do it during the coffee breaks instead of taking time in the stage. As the time is limited and I prefer to see more talks at the conference, the Q&A time can be used to fill the schedule with more talks. If the attendees want to discuss topics with the speakers, they can do it in other moments of the event.

Something that should be implemented in more conferences, from my point of view, is asking the attendees to share feedback about the talks and the speakers. That is super helpful for them, in order to review the content and the presentations that they are creating, to see if they can improve something for future opportunities. One place where I saw this implemented in a great way was Kansas City Developer Conference: There was a form that the attendees were able to fill with feedback about each one of the talks they attended. At the end of the conference, they did a raffle with super cool prizes between all the people that share feedback.

The pandemic forced the conference organizers to re-invent themselves and, as a side-effect, to open new gates. Making the events “hybrid”, doing a live-stream of the talks, allows people from different parts of the world to join and experience, in a different way, the conference. Hybrid events can go from doing a live-stream of what is happening at the conference venue, to set up a platform in order to provide a place to allow the online attendees to engage between themselves.

During the events

Event organizers try to offer the attendees and speakers the best experience possible. That takes a lot of effort, time, and energy. Even more, several in-person conferences are community-driven events, which means that people put everything in place without getting any money, just for the love of doing the event and seeing the people enjoy it. For all of that, I really respect and thank all the people involved in the organization of the conferences. Sometimes people walk through the conference venues, drinking coffee and eating snacks, going from one room to the other, or getting headphones to listen to a real-time translation of a talk, and they don’t stop on the fact that all of that is available because a group of people spent a lot of energy doing it.

During the event, it’s all about enjoying. You should consider planning your days based on the schedule and details shared by the organizers. Pick which talks you want to see and create your own schedule, especially if there are multiple tracks/stages. It’s also a good idea to leave some time to walk around the sponsor booths to know more about them and the products and services they offer and ask for career opportunities in case you are interested. And also, to grab some swag!

After parties and other events

Besides the conference itself, the event staff normally organize pre and post-events in order to have fun and do networking with other attendees and speakers. These events, from my point of view, are really valuable. Chatting while having fun, drinking, and eating is a comfortable scenario to know more about others, meet new people and make friends. You can also start interesting discussions about tech topics that can end up generating exciting ideas for you to bring home.

Some cool events I remember from the conferences I attended this year:

React Miami organized a party in a cool place with drinks and live music.
Jamstack Conf had an after-party with beer, live coding, and games in the same venue as the conference. There were also puppies that you could adopt and take home with you.
Remix Conf had a karaoke and board games night.
After Next.js Conf, attendees went to a local club to enjoy a DJ playing music while playing “foosball”, ping-pong, and other games.
Kansas City Developer Conference co-organized a tech impro/stand-up night, with fun geek and nerd jokes.
Render ATL went one step forward: Every night from the conference there were multiple events to attend. From sushi night to a music club, attendees were able to pick which type of event they wanted to go to.
React Alicante organized a post-event party where attendees needed to take a ship to get to the place.

If you are planning to attend a conference, don’t miss the “satellite events”.

Final words

As I said, I love in-person events. They are amazing experiences where you can learn new cool things and spend time with awesome people. I’m already starting to plan my 2023. Hope it is as great as the year that is ending. See you in any place in the world!

Storyblok React SDK – now with TypeScript support 🎉

Facundo Giuliani — Thu, 23 Jun 2022 12:14:22 +0000

Are you a React developer? We have great news for you: Storyblok's React SDK now comes with TypeScript support! 🙌
You will be able to add typing to your React projects, while having an even better developer experience connecting to Storyblok.

➡️ Do you want to see it in action? Take a look at this Storyblok React SDK w/ TypeScript live demo!

With the new version of Storyblok's React SDK, you get auto-completion, static typing and warnings in case something doesn’t add up, even if you are not using TypeScript yourself!

Look at this example:

Do you need help implementing TypeScript in your React project? Take a look at the official TypeScript and React documentation or this guide by Kent C. Dodds explaining how to write a React component with TypeScript.

➡️ If you want to learn how to integrate Storyblok into your React project, you can follow our 5 minutes guide to implementing React with Storyblok.

➡️ Are you using a React based framework? We have you covered, too! We have 5 minutes tutorials for Next.js, Gatsby, and Remix!

At Storyblok, we're working in order to roll out TypeScript support for all our SDKs. Vue and Svelte SDKs already support TS, more will be updated soon!

We would love to hear what you think. What do you like about it? What could be improved? Please, share your comments! ⬇️

GraphQL vs REST: which API is better for your web app?

Facundo Giuliani — Tue, 30 Mar 2021 22:11:49 +0000

Are you planning to build an API for your web application and you don't know what architectural approach to take? In this article, we will describe REST and GraphQL APIs. We will see their features, advantages, disadvantages, and use cases.

Introduction

At the moment of designing and developing a web service that will be used by our app, we need to think about the architecture we want to use. Over the last years, REST has been a widely used API design. But in 2015, Facebook released GraphQL to the public, a query language for APIs, and it became an alternative to REST. The two approaches have a different way of working, and clients will have to implement a certain type of communication, based on the architecture used on the server. Let's talk about both approaches, the differences between them, and which one best suits our project.

What is an API?

An API (Application Programming Interface) is a group of protocols and definitions used to integrate different components of a system. It defines a contract between a "provider" and a "consumer", and all the parameters involved in the communication between them:

The requests to be made.
How to make them.
The different responses.
Data types.

With an API we can reuse existing services from other components of our app, with an abstraction layer over the details of how those services are implemented.

What is a REST API?

REST (Representational State Transfer) is a group of architecture principles followed to create web services that work using the HTTP protocol. These principles are:

Client-Server: APIs should be designed with an architecture where the client and the server are decoupled. The client doesn't need to know implementation details from the server. This is helpful if we want to use the same server across multiple clients.
Stateless: Each API request coming from the client must include all the information related to it, as it is independent of other requests. No context or session is stored in the server.
Cacheable: Response data should be cacheable. Using a cache system gives the possibility to reuse responses from an endpoint for repeated HTTP requests and optimize interactions between client and server.
Uniform Interface: Simplify the architecture by defining a uniform interface for all the interactions between client and server. To do this we have to accomplish the following conditions:
- Resources should be identifiable and independent of the representation sent to the client. Each resource must have a URI (Uniform Resource Identifier).
- The client should be able to manipulate the resources through representations, as they contain enough information to allow this.
- Self-descriptive messages sent to the client should contain all the information needed to process them.
- It should implement Hypermedia as the Engine of Application State (HATEOAS), so any client accessing a resource should be able to know all the available actions at the moment.
Layered System: An architecture with hierarchical layers, to get better performance, security, and scalability.
Code On Demand (optional): The server can send executable code to extend client functionality.

A RESTful API is an interface that accomplishes all the previously listed principles.

Information is grouped and distributed in resources. Every resource has its uniform resource identifier (URI). The server that manages these resources creates representations of them that are sent to the client. The client will operate with the API through these representations. A resource representation consists of metadata, information, and hypermedia.

The client doesn't need to know which technology was used to develop the server, since the behavior is encapsulated. That makes the implementation of the client easier, and independent of the technologies used by the server. The only thing that matters is the format of the request and response (usually JSON or XML), so the client knows how to handle the messages and information coming from the server.

To operate with the resources we use resource methods. They are normally associated with HTTP verbs (GET/POST/PUT/DELETE), even though they are not the same.

There is no established standard for REST APIs. That is one of the reasons why there are APIs presented as RESTful that don't follow the original principles.

Pros of using a REST API

REST is the industry standard. It has the most mature developer tooling and has been around since Roy Fielding presented it in 2000.
REST APIs use HTTP methods, making the implementation predictable for the client.
REST APIs support various data formats (XML, JSON, HTML, plain text, etc.).
REST allows data to be cacheable, which might improve performance and scalability.

Cons of using a REST API

As the representation is defined by the server, it's complicated to customize the requests and bring only specific data. This can cause over-fetching: bringing data that we don't need.
All the requests return one resource representation from a unique source.
Generally, we need multiple round trips to get all the needed data.

When to make REST APIs

Public APIs where we want to determine what to expose to the clients.
Simple applications that we don't want to overcomplicate.

What is GraphQL?

GraphQL is a query language for APIs, with a syntax that describes how to request data. It is also the runtime executed in the server to process the queries. It operates over a unique endpoint using the HTTP protocol. It has some main characteristics:

A type system is used to define and describe the data.
The client specifies exactly the data that it needs.
Multiple data sources can be queried in the same request.
GraphQL follows the relationship between objects, hierarchically. The data returned to the client follows a graph structure.
It isn't tied to any storage engine, allowing the GraphQL server to manage the data with custom logic.

By using the type system it's easier to validate if a query is valid or not, before runtime. After the validation, the query is executed and the result is returned, normally as a JSON object.

GraphQL has an introspection system that allows an app to explore the schema definition and determine which queries are supported. This is also helpful in case we want to generate documentation about our GraphQL API.

There is an IDE called GraphiQL, which allows the user to explore a GraphQL API and build queries.

Pros of using GraphQL

One unique endpoint to query.
No over-fetching or under-fetching: As the client is responsible to define the data requirements, it won't download more (or less) information than needed from the API.
Query one or more resources in the same request. This will avoid making multiple API calls for an operation.
Defining a type system and a GraphQL schema helps to understand what can be requested and returned from the server. After that, Frontend and Backend teams can work without depending on each other.
Extending APIs and adding functionality wouldn't affect existing client GraphQL queries.
A growing and maturing ecosystem of tooling.

Cons of using GraphQL

GraphQL uses a single endpoint and custom requests, so caching is complicated.
Adding the support for custom queries to an API makes it more exposed to arbitrary requests.
Only supports JSON representation for responses.
GraphQL queries can become large. We have to specify everything we want to bring, and sometimes we are tempted to do a lot in one request.

When to use GraphQL

Applications where we usually need nested data to be fetched. i.e. blog posts with their comments and people details.
APIs that will be consumed by mobile devices, smartwatches, etc., where we need to limit bandwidth usage.
Apps that receive data from multiple APIs/sources. For example, bringing data from different analytics tools to display in a control panel.
When we want to handle different microservices.

Alternatives to REST and GraphQL APIs

Sanity.io offers an open-source query language called GROQ (Graph-Relational Object Queries). It allows us to describe what information we want in our application, join data from different documents, and generate a response with only the information that is needed.

Let's say we want to retrieve data related to a movie from an API. This is how it will look like using a REST API:

GET http://test-api.com/movies/11

This will be using GraphQL:

http://test-api.com/movies/

query {  
    movie(id: 11) {
        _id
        title
        releaseYear
    }
}

And this is how a GROQ query looks like:

[_id == 11]{
    _id, 
    title, 
    releaseYear
}

Conclusion

After going through the features of REST and GraphQL APIs, and describing their similarities and differences, we can say that neither is better than the other. What we have to evaluate is the requirements of the project that we will develop, the clients that will connect to our API, and based on that determine which architecture fits better for our use case.

Check the inclusion of Jira Issue Keys in PRs with GitHub Actions

Facundo Giuliani — Sat, 12 Sep 2020 20:46:40 +0000

Do you use Jira as the issue tracker in your company? Do you link GitHub PRs with Jira issues, and you want to ensure that link exists in every created PR of your repository? This GitHub Action is for you!

My Workflow

Defining a Jira "prefix" issue, Jira Issue Key Checker will verify every PR created in your repository contains a linked Jira issue key in both the PR title and description. You can see how to configure and trigger the action here:
https://github.com/fgiuliani/jira-issue-key-checker/blob/master/README.md

To see the complete code of the project, you can go here:
https://github.com/fgiuliani/jira-issue-key-checker

Submission Category:

Maintainer Must-Haves

Init project and install packages

As we'll use Node.js to create this GitHub Action, we will run npm init in our directory to generate package.json file. In this file we will set the details of our project. We will also install some dependencies that will help us to integrate our code with GitHub.

npm install @actions/core
npm install @actions/github

The @actions/core package provides an interface to the workflow commands, input and output variables, exit statuses, and debug messages.

The @actions/github package grants access to GitHub Actions contexts.

Create an action metadata file

Create a file called action.yml. It defines action's inputs and details. It also tells the action runner how to start running this JavaScript action. Write the following example code in the file:

name: "Jira Issue Key Checker"
description: "Checks If a PR contains its linked Jira issue key in both the title and the description."
on: [pull_request]
inputs:
  GITHUB_TOKEN:
    required: true
  jira-prefix:
    required: true
    description: "Jira issue key prefix. Ex. ABC-1111, prefix would be ABC"
runs:
  using: "node12"
  main: "index.js"

Write the action code

Let's create index.js file, which will containg the action code.

const core = require("@actions/core");
const github = require("@actions/github");

const jiraPrefix = core.getInput("jira-prefix");

async function run() {
  try {
    const prTitle = github.context.payload.pull_request.title;
    const prBody = github.context.payload.pull_request.body;

    let regex = new RegExp(`${jiraPrefix}-[0-9]+`);
    if (!regex.test(prTitle) || !regex.test(prBody)) {
      core.setFailed("Jira Issue Key missing in PR title or description.");
      return;
    }
  } catch (error) {
    core.info(error);
  }
}

run();

Some aspects to consider about the code:

GitHub Actions provide context information about the webhook event, workflow, action, etc. To access the context information, you can use the github package.
core.getInput("jira-prefix") will get the prefix we defined for the issues we want to check.
github.context.payload.pull_request exposes information related to the PR we're evaluating with the action.
core.setFailed marks the PR as failed If it doesn't pass the evaluation of the Regular Expression that validates both PR title and description contain the linked Jira issue key.

Commit, tag, and push the action to GitHub

Commit all the files inside the directory of your project. You will also need to commit node_modules folder.

git add .
git commit -m "My GitHub Action"

It's a good practice to also add a version tag for releases of your action. Let's create a version and push the changes to the repository.

git tag -a -m "My GitHub Action" v1
git push --follow-tags

Test and use the action

Take any GitHub repository and create the file .github/workflows/jira-issue-key-checker.yml. In the file, paste this example code:

name: "Jira Issue Key Checker"
on:
  pull_request:
    types:
      - opened
      - edited
      - synchronize

jobs:
  publish:
    runs-on: ubuntu-latest
    steps:
      - uses: [your-user]/[your-action-repository]@v1
        with:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          jira-prefix: "ABC"

Add this file to your GitHub repository. After this, whenever a new PR is created in that repository, the GitHub Action will run and evaluate it. You will be able to see the workflow execution and details about that clicking on the Actions tab.

Yaml File or Link to Code

fgiuliani / jira-issue-key-checker

Jira Issue Key Checker - GitHub Action

Checks If a PR contains its linked Jira issue key in both the title and the description.

Inputs

`GITHUB_TOKEN`

Required

`jira-prefix`

Required The Jira issue key prefix. Ex. ABC-1111, prefix would be ABC.

Example usage

Create a workflow (eg: .github/workflows/jira-issue-key-checker.yml see Creating a Workflow file) to utilize the jira-issue-key-checker action with content:

name: "Jira Issue Key Checker"
on:
  pull_request:
    types:
      - opened
      - edited
      - synchronize

jobs:
  publish:
    runs-on: ubuntu-latest
    steps:
      - uses: fgiuliani/jira-issue-key-checker@v1.0.0
        with:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          jira-prefix: 'ABC'

View on GitHub

Public bookmark list and URL shortener with Fauna, Next.js and Auth0

Facundo Giuliani — Tue, 08 Sep 2020 03:37:15 +0000

Serverless architecture has gone far and beyond in these days. If we want to create a modern web application, we have a lot of products, tools and services that make our lives easier and prevent us from reinventing the wheel. Frameworks, authentication platforms, headless content management systems, databases. We have a huge amount of tools that will help us to build fast, stable, and secure web applications, with a great developer experience. No backend configuration, no server management: Build serverless applications focusing on what we want to create.

In this demo we will create a platform where a user can create bookmarks with shortened URLs that can be used as shortcuts to the saved pages. The user will be authenticated to create those bookmarks, and shortened URLs will be exposed as a public bookmark list, selecting which links should be displayed publicly and which links should be private.

To create the platform we will use several products:

Next.js, the React Framework, will be used to handle server- and client-side rendering for the pages of the platform. It will also allow us to create API routes that will be deployed as lambdas/serverless functions.
Fauna will be used as the database where we will store all the bookmarks and their details.
Auth0 will handle user authentication and authorization.

Keep in mind that all of these products are free at a small scale, so you won't have to pay anything to start creating and playing with this project. Let's start!

As I don't want to create a super long post, I will omit some details not fully related to the idea of the article (css, styling, form advanced validations, login/signup custom pages, etc).
If you want to see the final code of the demo, you can clone and run: https://github.com/fgiuliani/fauna-next-auth0-example.

SignUp for a Fauna Account

Fauna is a global serverless database platform that offers you a fast, consistent and reliable service for your data operations. You can sign up for a free account and start creating and setting up a new database in a simple way.

What's also cool about Fauna is its integrations with modern platforms and frameworks. We will use a JavaScript driver to query our database, with simple methods and easy setup. You don't have to worry about configuration or anything; in a few steps you will be querying data from a NoSQL document collection.
If you don't have a Fauna Account yet, go to the sign-up page to create one.

Create a new database

Once you've created your account and logged in, click on "New Database". Name your database whatever you want. Maybe "bookmarks" would be appropriate.

Create a new collection

On the left database menu, click on "Collections" and then on "New Collection". Let's call it "Bookmarks". The collection will be populated with documents from the app, so you don't need to add anything here.

Create indexes

From the app, we will use indexes to help us to query the bookmarks that we want to create, load, delete, or use. Let's create them by clicking on "Indexes" on the left sidebar, and then on "New Index". Let's create two:

getBookmarksByUsername: This index will help us get all the bookmarks for a specific user. This will be used to generate the bookmark list. The index should be created over Bookmarks collection, and we should add "username" as the term.
getBookmarkByUsernameAndSlug: This index will be used to retrieve one specific bookmark, filtering by user and "slug". We will use this to redirect users to the URL that we shortened. We will also use the index when we delete a bookmark. The index should be created over Bookmarks collection, and we should add two terms: "username" and "slug".

Create Server Key

In order to access the database, we will need a key that we'll config in our Next.js application. In the left sidebar, go to "Security" and click on "New Key". Select "Server" role and save. After generating the key, copy it in a safe place. You won't see this key again!

SignUp for an Auth0 Account

If you don't know about Auth0 yet, I recommend you to read about the platform and all the different products they offer. In this demo, we will use their Universal Login feature. We don't need to worry about creating login pages or handling user databases, hashes, or encryption. We rely on Auth0's out-of-the-box authentication platform to manage all the authentication and authorization that we need in our app. What I want to show in this example is how you can use a platform created by security specialists and avoid reinventing the wheel creating your own authentication module.
If you don't have an Auth0 Account, go to the sign-up page and create one. The free tier will be sufficient to complete this tutorial.

Configure Auth0 project

Go to the Auth0 dashboard and create a new application of type "Regular Web Applications". After that, go to the settings page of the application and configure the following settings:

Allowed Callback URLs: Add http://localhost:3000/api/callback
Allowed Logout URLs: Add http://localhost:3000/

Create Next.js app

Next.js is one of the most popular React frameworks nowadays. It offers features to generate static pages, create server-side rendered pages, and combine both types in the same site. You can also create your own serverless API inside the same app. With little configuration, or no configuration at all, we can create fast serverless web applications. Plus: The platform is open source.
To create a brand new Next.js app, we will use create-next-app, which sets up everything automatically for you. To create the project, run:

npx create-next-app [name-of-the-app]
# or
yarn create next-app [name-of-the-app]

To start the dev server locally and see the site just created in your browser, go to the new folder that you created

cd [name-of-the-app]

and run

npm run dev
# or
yarn dev

Now you can go to http://localhost:3000 in your browser and see the sample site working.

Install dependencies

Using yarn add or npm install, add some dependencies that we'll use and will help us to make things easier when coding:

faunadb: A driver we will use to interact with our database.
swr: A React Hooks library for data fetching.
react-hook-form: A form validation library, so we can build forms easier.
@auth0/nextjs-auth0: A library that we'll use to connect to Auth0 authentication platform and handle user sign up, login, logout, etc.

Add Environment Variables

Create a file called ".env.local" in the root of the project directory. This will be global configuration for our app. Depending on which platform you use to deploy the app, it will affect how you configure these settings.
Set the following variables:

# App Server path, used to redirect to external sites
SERVER_PATH=http://localhost:3000

# Fauna DB Server Key
FAUNA_SERVER_KEY=[FAUNA_SERVER_KEY]

# Public Environment variables that can be used in the browser.
NEXT_PUBLIC_AUTH0_CLIENT_ID=[Can be found in the Auth0 dashboard under settings]
NEXT_PUBLIC_AUTH0_DOMAIN=[Can be found in the Auth0 dashboard under settings]

NEXT_PUBLIC_AUTH0_SCOPE="openid profile"
NEXT_PUBLIC_REDIRECT_URI="http://localhost:3000/api/callback"
NEXT_PUBLIC_POST_LOGOUT_REDIRECT_URI="http://localhost:3000"

# Secret environment variables
AUTH0_CLIENT_SECRET=[Can be found in the Auth0 dashboard under settings]
SESSION_COOKIE_SECRET=[A 32 characters secret used to encrypt the cookies]
SESSION_COOKIE_LIFETIME=7200

Create clients

Create a directory called "lib" in the root of the project directory. We'll create two files with clients that will connect to Fauna and Auth0 platforms.

lib/fauna-auth.js

import faunadb from "faunadb";

export const serverClient = new faunadb.Client({
 secret: process.env.FAUNA_SERVER_KEY,
});

lib/auth0.js

import { initAuth0 } from "@auth0/nextjs-auth0";

export default initAuth0({
 clientId: process.env.NEXT_PUBLIC_AUTH0_CLIENT_ID,
 clientSecret: process.env.AUTH0_CLIENT_SECRET,
 scope: process.env.NEXT_PUBLIC_AUTH0_SCOPE || "openid profile",
 domain: process.env.NEXT_PUBLIC_AUTH0_DOMAIN,
 redirectUri:
   process.env.NEXT_PUBLIC_REDIRECT_URI ||
   "http://localhost:3000/api/callback",
 postLogoutRedirectUri:
   process.env.NEXT_PUBLIC_POST_LOGOUT_REDIRECT_URI ||
   "http://localhost:3000/",
 session: {
   cookieSecret: process.env.SESSION_COOKIE_SECRET,
   cookieLifetime: Number(process.env.SESSION_COOKIE_LIFETIME) || 7200,
 },
});

Now that we have all the initial setup and configuration ready, let's create the pages of our site!

Create components

First, we'll create some components that will be helpful to avoid repeating code in our pages.
Let's create the "Header" and "Layout" components, two things that we'll have in all our pages:

components/header.js

import Link from "next/link";

function Header({ user, loading }) {
 return (
   <header>
     <nav>
       <ul>
         {!loading &&
           (user ? (
             <>
               <li>
                 <Link href="/">
                   <a>Profile</a>
                 </Link>
               </li>
               <li>
                 <Link href={`/${user.nickname}`}>
                   <a>Bookmarks</a>
                 </Link>
               </li>
               <li>
                 <a href="/api/logout">Logout</a>
               </li>
             </>
           ) : (
             <li>
               <a href="/api/login">Login</a>
             </li>
           ))}
       </ul>
     </nav>
   </header>
 );
}

export default Header;

Some things to consider:

"user" is the object that contains all the data related to logged in users. If the user is not logged in, "user" will be null. We'll see more details about this in the pages that include this component.
If the user is not logged in, we'll display a "Login" link, which connects to Auth0 to start the authentication process. We'll use a Next.js API route for that.
If the user is already logged in, we'll display "Profile", "Bookmarks", and "Logout" links. "Profile" is the page where we'll display some of the user's details. "Bookmarks" is the page where all the saved links will be listed. "Logout" will disconnect the logged in user, using an API route. Pay attention to the routes of the links, we'll create those pages later.

components/layout.js

import Head from "next/head";
import Header from "./header";

function Layout({ user, loading, children }) {
 return (
   <>
     <Head>
       <title>Fauna Next Auth0 Example</title>
       <link rel="icon" href="/favicon.ico" />
     </Head>

     <Header user={user} loading={loading} />

     <main>
       <div className="container">{children}</div>
     </main>
   </>
 );
}

export default Layout;

We see how Layout contains the Header that we created before.

Let's create one more component, "DataRow". We'll use it to display each bookmark's details in the list page.

components/data-row.js

import Router from "next/router";

function DataRow({ title, user, username, slug, url, description }) {
 const onClick = async () => {
   try {
     const res = await fetch(`/api/${username}/${slug}/delete`, {
       method: "DELETE",
     });
     if (res.status === 200) {
       Router.push(`/${username}/`);
     } else {
       throw new Error(await res.text());
     }
   } catch (error) {
     console.error(error);
   }
 };

 return (
   <div>
     <p>
       <a href={url} target="_blank">
         {title}
       </a>
     </p>
     <p>{description}</p>
     {user && user.nickname === username ? (
       <div>
         <button onClick={onClick}>Delete</button>
       </div>
     ) : (
       <></>
     )}
   </div>
 );
}

export default DataRow;

Let's dig into DataRow:

Each instance of the component will receive all the information we need from the bookmarks to display them.
The title/name of the item will be a link to the URL that we're shortening with the bookmark we created.
There's a Delete button that calls an "onClick'' function, used to remove a bookmark. Take a look at the comparison we do between the "username" we get from the bookmark with the nickname of the logged in user. A user can only delete the bookmarks that he created, so the username (creator) of the bookmark should match the logged in user nickname to say "this bookmark is yours". Later, we'll also see an extra validation in the API route that we'll use to delete bookmarks.

Create pages

We'll have four pages the users will browse in our site.

pages/index.js

import auth0 from "../lib/auth0";
import Layout from "../components/layout";

function Profile({ user }) {
 return (
   <Layout user={user}>
     <h1>Profile</h1>

     <div>
       <p>username: {user.nickname}</p>
       <p>name: {user.name}</p>
     </div>
   </Layout>
 );
}

export async function getServerSideProps({ req, res }) {
 const session = await auth0.getSession(req);

 if (!session || !session.user) {
   res.writeHead(302, {
     Location: "/api/login",
   });
   res.end();
   return;
 }

 return { props: { user: session.user } };
}

export default Profile;

This will be the initial page of our site.

If the user is logged in, we will display his name and nickname (the username we will use to save the bookmarks).
If the user is logged out, we will redirect him to Auth0 authentication platform so he can create a new account, or login if he already has one. To do this, we'll take advantage of the getServerSideProps function provided by Next.js. This function will execute before the page is rendered.

pages/add.js

import { useState } from "react";
import Router from "next/router";
import { useForm } from "react-hook-form";
import Layout from "../components/layout";
import auth0 from "../lib/auth0";

function Add({ user }) {
 const [errorMessage, setErrorMessage] = useState("");

 const { handleSubmit, register, errors } = useForm();

 const onSubmit = handleSubmit(async (formData) => {
   if (errorMessage) setErrorMessage("");

   try {
     const res = await fetch(`/api/${user.nickname}/add`, {
       method: "POST",
       headers: {
         "Content-Type": "application/json",
       },
       body: JSON.stringify(formData),
     });
     if (res.status === 200) {
       Router.push(`/${user.nickname}/`);
     } else {
       throw new Error(await res.text());
     }
   } catch (error) {
     setErrorMessage(error.message);
   }
 });

 return (
   <Layout user={user}>
     <h1>Add Bookmark</h1>

     <form onSubmit={onSubmit}>
       <div>
         <label>Title</label>
         <input
           type="text"
           name="title"
           placeholder="Title"
           ref={register({ required: "Title is required" })}
         />
         {errors.title && <span role="alert">{errors.title.message}</span>}
       </div>

       <div>
         <label>Slug</label>
         <input
           type="text"
           name="slug"
           placeholder="test-link"
           ref={register({ required: "Slug is required" })}
         />
         {errors.slug && <span role="alert">{errors.slug.message}</span>}
       </div>

       <div>
         <label>Url</label>
         <input
           type="text"
           name="url"
           placeholder="e.g. https://www.google.com"
           ref={register({ required: "Url is required" })}
         />
         {errors.url && <span role="alert">{errors.url.message}</span>}
       </div>

       <div>
         <label>Description</label>
         <input type="text" name="description" placeholder="" ref={register} />
         {errors.description && (
           <span role="alert">{errors.description.message}</span>
         )}
       </div>

       <div>
         <label>Private Bookmark</label>
         <input type="checkbox" name="isPrivate" ref={register} />
         {errors.isPrivate && (
           <span role="alert">{errors.isPrivate.message}</span>
         )}
       </div>

       <div>
         <button type="submit">Add</button>
       </div>
     </form>

     {errorMessage && <p role="alert">{errorMessage}</p>}
   </Layout>
 );
}

export async function getServerSideProps({ req, res }) {
 const session = await auth0.getSession(req);

 if (!session || !session.user) {
   res.writeHead(302, {
     Location: "/api/login",
   });
   res.end();
   return;
 }

 return { props: { user: session.user } };
}

export default Add;

This page will be the form used to create new bookmarks. As only logged in users can create items, we use again the getServerSideProps to ensure that we display the page only to authenticated users. The page has all the fields we use for bookmarks and a submit function, used to save the data (calling an API route). We have some basic validation provided by the packages we installed, but I encourage you to add other kinds of validations (URL format, slug format, etc).

Now, we'll create a couple of pages with dynamic routes. This will help us to handle data related to the user we want. Inside "pages", let's create a new directory and call it "[username]".

pages/[username]/index.js

import DataRow from "../../components/data-row";
import Layout from "../../components/layout";
import Link from "next/link";
import useSWR from "swr";
import { useRouter } from "next/router";
import auth0 from "../../lib/auth0";

const fetcher = (url) => fetch(url).then((r) => r.json());

function BookmarkList({ user }) {
 const router = useRouter();
 const { username } = router.query;

 const { data } = useSWR(`/api/${username}`, fetcher);

 return (
   <Layout user={user}>
     <h1>Fauna Next Auth0</h1>

     {user && user.nickname === username ? (
       <Link href="/add">
         <a>Add</a>
       </Link>
     ) : (
       <></>
     )}

     <div>
       {data ? (
         data.map((d) =>
           !d.data.isPrivate ||
           (d.data.isPrivate && user && user.nickname === username) ? (
             <DataRow
               key={d.ref["@ref"].id}
               id={d.ref["@ref"].id}
               title={d.data.title}
               user={user}
               username={username}
               slug={d.data.slug}
               url={d.data.url}
               description={d.data.description}
             />
           ) : (
             <></>
           )
         )
       ) : (
         <></>
       )}
     </div>
   </Layout>
 );
}

export async function getServerSideProps({ req, res }) {
 const session = await auth0.getSession(req);

 if (!session || !session.user) {
   return { props: { user: null } };
 }

 return { props: { user: session.user } };
}

export default BookmarkList;

This page is the bookmark list itself. You don't need to be logged in to see a user's list, but there's some content that will be displayed only If the user is authenticated and he's seeing his own profile. That's why we still request logged in user data with getServerSideProps, but we don't redirect the user If he's not authenticated: We set user = null.
In this page, we use the "username" received in the query to load all the bookmarks created by that user. We'll only display the bookmarks that weren't marked as "isPrivate" when they were created, unless the user browsing the page is the creator of them. If that's the case, we'll list all the bookmarks and we'll display the "Add" button so he can create new items.

pages/[username]/[slug].js

function RedirectPage(props) {
 return <h1>{props.error}</h1>;
}

export async function getServerSideProps(context) {
 const { username, slug } = context.query;

 try {
   const res = await fetch(
     `${process.env.SERVER_PATH}/api/${username}/${slug}`,
     {
       method: "GET",
     }
   );
   if (res.status === 200) {
     const bookmark = await res.json();

     context.res.writeHead(303, { Location: bookmark.url });
     context.res.end();
   } else {
     throw new Error(await res.text());
   }
 } catch (error) {
   return {
     props: { error: error.message },
   };
 }
}

export default RedirectPage;

This page with two dynamic parts in the query is the shortener module itself. This page is public and it has no markup (technically it has, but if we see the markup it's because we used an invalid link).
Taking advantage of getServerSideProps we call a dynamic API route that will call Fauna to evaluate both username and slug, to retrieve a link that matches both terms (if there are any). If it matches, we use the shortened URL to redirect the user to that page. If it doesn't, we display an error message.

So If my user nickname is "test" and I created a bookmark with the slug "link", pointing to Google, if a user browses http://localhost:3000/test/link, he will be automatically redirected to https://www.google.com/.

Create API Routes

We have all the pages and components ready. Now, we need to create the API routes that will execute the queries to our database. But first, let's create three small API routes to handle user authentication status:

pages/api/login.js

import auth0 from "../../lib/auth0";

export default async function login(req, res) {
 try {
   await auth0.handleLogin(req, res);
 } catch (error) {
   console.error(error);
   res.status(error.status || 500).end(error.message);
 }
}

pages/api/logout.js

import auth0 from "../../lib/auth0";

export default async function logout(req, res) {
 try {
   await auth0.handleLogout(req, res);
 } catch (error) {
   console.error(error);
   res.status(error.status || 500).end(error.message);
 }
}

pages/api/callback.js

import auth0 from "../../lib/auth0";

export default async function callback(req, res) {
 try {
   await auth0.handleCallback(req, res, { redirectTo: "/" });
 } catch (error) {
   res.status(error.status || 500).end(error.message);
 }
}

Not much to say about these three. Some boilerplate code to handle user login, logout, and callback (the place where Auth0 redirects the user after a valid login).

Now, we'll create the API routes that interact with Fauna. First of all, let's create the "Add Bookmark" route.

pages/api/add.js

import { query as q } from "faunadb";
import { serverClient } from "../../lib/fauna-auth";
import auth0 from "../../lib/auth0";

export default auth0.requireAuthentication(async function addBookmark(
 req,
 res
) {
 const { title, slug, url, description, isPrivate } = req.body;
 const { user } = await auth0.getSession(req);

 try {
   await serverClient.query(
     q.Create(q.Collection("Bookmarks"), {
       data: {
         username: user.nickname,
         title,
         slug,
         url,
         description,
         isPrivate,
       },
     })
   );
   res.status(200).end();
 } catch (e) {
   res.status(500).json({ error: e.message });
 }
});

Look how simple the query is. If we break it down:

"Create" creates a new document.
"Collection("Bookmarks")" is a reference to the collection where we want to create the document.
"data: { }" contains the data of the document we will create. We require authentication (since only logged in users can create bookmarks), we grab the user's nickname as the "username" of our bookmark, and we use all the data filled in the form of our "add" page to create a new bookmark with a shortened URL. We could add some validation so the slug of our bookmark is unique, since we shouldn't repeat them.

pages/api/[username]/index.js

import { query as q } from "faunadb";
import { serverClient } from "../../../lib/fauna-auth";

export default async (req, res) => {
 const {
   query: { username },
 } = req;

 try {
   const bookmarks = await serverClient.query(
     q.Map(
       q.Paginate(q.Match(q.Index("getBookmarksByUsername"), username)),
       q.Lambda("X", q.Get(q.Var("X")))
     )
   );
   res.status(200).json(bookmarks.data);
 } catch (e) {
   res.status(500).json({ error: e.message });
 }
};

The API route that generates the bookmark list for a specific user. We use one of the indexes we created in the Fauna dashboard to get all data related to the items created by the user:

"Paginate" returns an array of references to documents.
"Match" uses the index "getBookmarksByUsername" and sends the var username as the filtering term.
"Map" grabs an array, performs an action on each item of this array, and returns a new array with the new items.
"Lambda" is the Fauna equivalent of an anonymous function in JavaScript. It performs lazy execution of custom code. In our example, "Lambda" defines a parameter X that "Var" evaluates and returns a document reference. Finally, "Get" receives the reference and returns the actual document.

pages/api/[username]/[slug]/index.js

import { query as q } from "faunadb";
import { serverClient } from "../../../../lib/fauna-auth";

export default async (req, res) => {
 const {
   query: { username, slug },
 } = req;

 try {
   const bookmark = await serverClient.query(
     q.Map(
       q.Paginate(
         q.Match(q.Index("getBookmarkByUsernameAndSlug"), [username, slug]),
         { size: 1 }
       ),
       q.Lambda("X", q.Get(q.Var("X")))
     )
   );

   if (bookmark && bookmark.data[0]) {
     res.status(200).json(bookmark.data[0].data);
   } else {
     res.status(500).json({ error: "Invalid link" });
   }
 } catch (e) {
   res.status(500).json({ error: e.message });
 }
};

In this API route, we use the other index that we created to retrieve the bookmark that matches the username and slug from the query. This route returns the item to the redirect module we previously created. The query is very similar to the previous one, except for:

"Match" takes two terms instead of one
We force "Paginate" to return only one result with "{ size: 1 }"

pages/api/[username]/[slug]/delete.js

import { query as q } from "faunadb";
import { serverClient } from "../../../../lib/fauna-auth";
import auth0 from "../../../../lib/auth0";

export default auth0.requireAuthentication(async function deleteBookmark(
 req,
 res
) {
 const {
   query: { username, slug },
 } = req;

 const { user } = await auth0.getSession(req);

 if (user.nickname != username) {
   res.status(500).json({ error: "Invalid User" });
 }

 try {
   await serverClient.query(
     q.Map(
       q.Paginate(
         q.Match(q.Index("getBookmarkByUsernameAndSlug"), [username, slug]),
         { size: 1 }
       ),
       q.Lambda("X", q.Delete(q.Var("X")))
     )
   );
   res.status(200).end();
 } catch (e) {
   res.status(500).json({ error: e.message });
 }
});

The last API route we'll create is the one used to delete a bookmark. We validate that the user is logged in and he's the creator of the item. We then use the same index we used in the previous route to retrieve the only result that matches the username and slug specified, then we delete it.

Last words

Now we have a cool platform to create public bookmark lists and shorten URLs, with integrated authentication. You can see that we didn't code too much, and the setup/config was pretty minimal.
You can run the app with the dev server, or you can deploy it to one of the many cloud platforms existing in the market. I recommend Vercel, a cloud platform created by the same organization that's behind Next.js. It has a simple and focused integration to build and deploy serverless web apps, especially If they were created using Next.js.
Forget about maintaining a web server or configuring your backend. We have many products and options that help us to create fast and secure web apps.

Notify YouTube comments with Azure Functions

Facundo Giuliani — Thu, 03 Sep 2020 13:18:00 +0000

This article is part of #ServerlessSeptember. You'll find other helpful articles, detailed tutorials, and videos in this all-things-Serverless content collection. New articles from community members and cloud advocates are published every week from Monday to Thursday through September.

Find out more about how Microsoft Azure enables your Serverless functions at https://docs.microsoft.com/azure/azure-functions/.

If our organization has a YouTube channel with videos, users may comment on them with questions or doubts. If only one person checks the channel, regular notifications may be enough. But what would happen If we want to notify other people whenever a user posts a comment in one of our videos?

In this article, we'll use Azure Functions and a couple of third-party APIs to create a JavaScript serverless application to send emails when new comments are added in any video from a YouTube channel. We will call the YouTube API from the app, using a Google Developer Project to get an API Key.
As we don't have anything like push notifications to get new comments automatically, we will create a serverless application to do that. It will run on a schedule (seconds, minutes, or hours), and it will verify If we have new comments in any of the videos of a specific channel. To do that we will call the YouTube API. If we get new comments, this app will send a notification email to a list of people using SendGrid API.

If you want to see the final source code, you can check out the repository on GitHub

We will use Node's package manager to install the dependencies we need for this demo.

Create Google Developer Project to get a YouTube API Key

Go to https://developers.google.com/ and log in with your Google Account (or create an account, if necessary).
Go to https://console.developers.google.com/project and click on Create Project. Put the details you prefer for the project.

Go to the project you just created and click on Enable APIs and Services and look for YouTube Data API v3. Select it and click on Enable.

Go to Credentials and click on Create Credentials -> API Key. Save the generated key. We will need it in our Azure Functions app.

Create SendGrid account to get an API Key

SendGrid is a powerful tool used to send emails, but it can also track user interaction. You can create marketing campaigns, generate reports, and see different types of statistics.

Sign Up on SendGrid. You don't need a credit card to create an account. The free tier will be enough to go through this tutorial.
Go to https://app.sendgrid.com/settings/api_keys and click on Create API Key. Set a name for it and give it Full Access.
Click on Create and View. Copy the generated key somewhere safe since it won't be displayed again.

After that, you will need to Verify a Single Sender. We need to add some information to clarify which email account we will use later in the app to be the sender of our notifications, and some details related to that account.

Create an Azure Account

Microsoft Azure is a cloud computing service for building, testing, deploying, and managing applications. It offers different products to help us with our applications. For our project, we will use Azure Functions, the serverless application service from Azure. Different languages are supported to create these Functions. We will use JavaScript.

Sign Up on Microsoft Azure. There is a free tier for many of the services offered, and a trial period for other features. You won't need to pay anything for this demo.
After setting up your account, let's create an Azure Storage account. This will be the space you will use to host the Function.

Select your storage account, select Access keys in Settings, then copy the first Connection string. We will need it later.

Install Azure Functions Extensions

The IDE I use is Visual Studio Code. It's a powerful editor with many plugins and customizations. I recommend using it for this demo because there's an Azure Functions Extension, which will make our job easier and will help us create and deploy the Function.

After installing the extension, in the left menu, you should have an Azure icon. Click on it and sign in with your Azure Account, so the IDE links your personal account.

Finally, to enable local debugging, we need to install the Azure Functions Core Tools.

Now it's time to code!

Create a new Azure Function Project

In Visual Studio Code, in the same menu, you signed in, now you should see your Azure Subscription. Click on the icon with a folder and a thunder that says Create New Project and follow the steps:

Name your project.
The language we'll use is JavaScript.
You should select the template Timer Trigger.
I want my Function to run every 5 hours, so I set the time interval cron as "0 0 */5 * * *". You can read more about the cron format here. You will be able to change this later in the function.json file.

After following these steps, we should have all the initial files of our Azure Function Project generated.

Install NPM packages

To call the YouTube API, we will use Google APIs Node.js Client. We need to run npm install --save googleapis in the terminal to install the package so our Azure Function can use it.

For the SendGrid API, we also have an NPM package that we will use to send the emails. Run npm install --save @sendgrid/mail to install [Mail Service for the SendGrid v3 Web API.

Define Environment variables

We will need some key values to be stored as environment variables. Go to local.settings.json file and add these keys inside "Values":

"YouTubeAPIKey": "[YOUTUBE_API_KEY]", // The API Key generated in your Google Developer Project.
"YouTubeChannelID": "[YOUTUBE_CHANNEL_ID]", // The ID of the YouTube channel you want to watch.
"SendGridAPIKey": "[SENDGRID_API_KEY]", // SendGrid API Key.
"EmailFrom": "[SENDER_EMAIL]", // The sender email for the notifications.
"EmailTo": "[RECEIVER_EMAIL]" // The receiver email for the notifications.

The channel ID is the identifier of the YouTube channel you want to keep track of. If you see, the URL of a channel looks like https://www.youtube.com/channel/[ChannelID].

"EmailTo" could contain more than one email address. You have to separate them with commas, ','.

Also, you will need to set the connection with your Azure Storage account. To do this, paste the connection string you previously generated as the value of the key AzureWebJobsStorage.

The Function

Let's go now to the index.js file inside the project directory. We will start coding our app.
First, we will initialize the YouTube and SendGrid API clients. We will use the NPM packages we installed in the previous section, and the environment variables we defined. This is how the code inside our function should look like:

  const { google } = require("googleapis");
  const sendGridClient = require("@sendgrid/mail");

  const youtubeClient = google.youtube({
    version: "v3",
    auth: process.env["YouTubeAPIKey"],
  });

  sendGridClient.setApiKey(process.env["SendGridAPIKey"]);

After that, we will call the YouTube API to get a list of the last comments (and replies) posted in all the videos of a specific channel.

  const response = await youtubeClient.commentThreads.list({
    part: "snippet,replies",
    allThreadsRelatedToChannelId: process.env["YouTubeChannelID"],
    maxResults: 100,
    order: "time",
  });

A few things to consider here:

We call commentThreads endpoint because we want to retrieve all the comments and their replies.
We use the environment variables we set before with the channel ID.
The API supports a maximum of 100 results. That's the number of results we will bring not to lose any comment.
order: "time" sets the order of the results from the newest to the oldest.

You can read the YouTube API documentation to see the details of the results we get from the YouTube API. It will be helpful for the following part of the code.

  if (response.data) {
    const lastRun = new Date(myTimer.scheduleStatus.last);

    response.data.items.forEach(function (comment) {
      const topLevelComment = comment.snippet.topLevelComment.snippet;
      const topLevelCommentDate = new Date(topLevelComment.publishedAt);

      if (topLevelCommentDate.getTime() > lastRun.getTime()) {
        sendEmail(
          topLevelComment.authorDisplayName,
          topLevelComment.textDisplay,
          `https://www.youtube.com/watch?v=${topLevelComment.videoId}&lc=${comment.id}`
        );
      }

      if (comment.snippet.totalReplyCount > 0) {
        comment.replies.comments.forEach(function (reply) {
          const replyDate = new Date(reply.snippet.publishedAt);

          if (replyDate.getTime() > lastRun.getTime()) {
            sendEmail(
              reply.snippet.authorDisplayName,
              reply.snippet.textDisplay,
              `https://www.youtube.com/watch?v=${reply.snippet.videoId}&lc=${reply.id}`
            );
          }
        });
      }
    });
  }

Let's break this down:

  if (response.data) {

We'll keep executing the function only If we get any result.

    const lastRun = new Date(myTimer.scheduleStatus.last);

Azure Functions exposes a timer object, which contains the data related to the execution of the timerTrigger function. We can use it to get the last execution time to compare it with the comments date/time. If the comment is newer, we assume we didn't notify the users about it, so we send the email. We have to make that comparison with every comment we get from the API.

    response.data.items.forEach(function (comment) {
      const topLevelComment = comment.snippet.topLevelComment.snippet;
      const topLevelCommentDate = new Date(topLevelComment.publishedAt);

      if (topLevelCommentDate.getTime() > lastRun.getTime()) {
        sendEmail(
          topLevelComment.authorDisplayName,
          topLevelComment.textDisplay,
          `https://www.youtube.com/watch?v=${topLevelComment.videoId}&lc=${comment.id}`
        );
      }

But also with the comments' replies (If they have any)

      if (comment.snippet.totalReplyCount > 0) {
        comment.replies.comments.forEach(function (reply) {
          const replyDate = new Date(reply.snippet.publishedAt);

          if (replyDate.getTime() > lastRun.getTime()) {
            sendEmail(
              reply.snippet.authorDisplayName,
              reply.snippet.textDisplay,
              `https://www.youtube.com/watch?v=${reply.snippet.videoId}&lc=${reply.id}`
            );
          }
        });
      }

You should have noticed we're calling twice a function called sendEmail, sending as parameters the comment's user, text, and the direct URL. Let's create that function, which will call the SendGrid API to send the emails. Write the code for the function inside the main function.

  function sendEmail(user, comment, url) {
    let body = "There is a new comment in one of your videos\n";
    body += `User: ${user}\n`;
    body += `Comment: ${comment}\n`;
    body += `Url: ${url}`;

    const msg = {
      to: process.env["EmailTo"],
      from: process.env["EmailFrom"],
      subject: "There is a new comment in your YouTube Channel",
      text: body,
    };

    sendGridClient
      .send(msg)
      .then(() => {
        console.log("Email sent");
      })
      .catch((error) => {
        console.log(error.response.body);
      });
  }

As we said, sendEmail receives the user, the comment, and the URL. Then, it creates the email body, and instantiates a msg with all the email details. After that, it calls the SendGrid API with the client we initialized, and we send the email to the users.

That would be all the code for the Azure Function. You can execute it locally and debug it directly from Visual Studio Code, using its integrated debugger (press F5 to debug). Consider that we created a timerTrigger, and it will follow the time interval we defined even when debugging locally. So, If you want to debug in a better way, maybe you should define a smaller time interval to execute the function more frequently.

Deploy the function to Azure

With the Azure Functions Extension, deploying from Visual Studio Code is very simple.

Click on the Azure logo to open the Azure Explorer. Under Functions, click on the blue up arrow.

At the prompt, select Create new Function app in Azure.
Enter a globally unique name for your Function.
Choose the Node.js version/runtime.
Select the Azure region of your preference.

After following these steps, and waiting for a while, your Function will be up and running in Azure.

Final words

In this demo, we learned how to create, debug, and deploy an Azure Function (time-triggered) using JavaScript and Visual Studio Code. We developed some basic integrations with YouTube and SendGrid APIs.

A next step would be analyzing the resources consumed by the function and evaluating the costs it would incur while working in Azure. If you don't want to keep the Function, you can clean up the resources. Right-click the Function App in the Azure: Functions explorer and select Delete Function App.