Forem: Jakub Skoneczny

IsEven API - SaaS platform for checking if number is even 🚀

Jakub Skoneczny — Fri, 26 Nov 2021 18:21:39 +0000

Have you ever heard about the SaaS platform for if a number is even? Well, I've decided to recreate a service like this of my own! 😄

Not for the profit, of course - who would need the paid service for checking the parity of a number? 😄 I wanted to create a full-stack project from start to end and then deploy it. It seemed like a great challenge that would require gathering all my knowledge, structuring it, and maybe even learning some new stuff along. So this idea of creating a non-real SaaS platform fascinated me!

So this is it! I present to you my latest project - is-even.eu. It is open-source, so go ahead and check the codebase.

About the project

The main idea behind this SaaS platform is that a customer can purchase a plan (different plans allow different API usage). He can then perform an analysis of a number via a protected route. Users must use API Key to have access to that route. The application tracks the usage for each user, and if he reaches the limit, he can no longer use our services.

Core features are:

Users can signup and login,
User can place orders and fulfill them,
User can create API Keys
User can use the service within his credits limit
User can monitor the usage of his credits

Technical informations

The project gathers some of the best practices of project development and maintenance. It shows how one can implement a working system from start to end, deploy it and monitor it. This project contains of:

modern Frontend application written in Next.js
robust Backend application written in Nest.js
infrastructure as a code with AWS CDK
Typescript codebase for every application
docker environment for local development
monorepo manager to control all the and its dependencies
CI/CD pipelines for running tests and deployment

The frontend application is deployed on Vercel, one of the first choices for deploying the Next.js application.

The backend application is deployed on AWS ElasticBeanstalk. I've found this challenging to create an infrastructure setup with AWS CDK, but it was worth it! Infrastructure as a Code is fantastic because now I can set it up from the start in no time!

This whole project is a template, ready to copy and use accordingly to your start-up idea! Feel free to fork it and adjust to your needs 😉

I've decided to use some new modern technologies in this project. One of the essential mentions is XState - a library that brings state machines to Javascript. I enjoy doing state management in React with that library.

Other worth mentions are:

Stripe
ChakraUI
Rush.js as monorepo manager
Next.js as frontend framework
Nest.js as backend framework
Multiple AWS services like: Cognito, RDS, EBS, ELB etc.

For complete documentation and more information, please check out the official Github repository or special page about the project

I encourage you to have a look, examine the code, and write your thoughts. What do you think about this project? What's missing or what could have been done differently?

Contributing

If you have a suggestion to improve this project, please fork the repo and create a pull request. You can also open an issue with the tag enhancement. Any contributions are welcome.

References

If you wonder why I decided to go with monorepo, here are some good reasons that I've written in my previous article:

Control your Monorepo 🗄️

Jakub Skoneczny ・ Aug 4 '21

#architecture #codequality #discuss #javascript

Also, I've written a more hands-on tutorial for setting up the infrastructure with AWS CDK:

Deploy scalable NodeJS application with Postgres database using AWS CDK

Jakub Skoneczny ・ Jan 1 '21

#aws #node #javascript #devops

Control your Monorepo 🗄️

Jakub Skoneczny — Wed, 04 Aug 2021 18:49:31 +0000

You might have heard the phrase monorepo earlier before. But, for those who haven't heard anything about it, monorepo is an architectural pattern where you keep multiple projects inside a single git repository.

Imagine working on a semi-large project that includes some back-end, web front-end, and mobile applications. The most common approach would be to create different repositories for each of those applications. Then, developers would work on each part separately, developing, committing, and pushing to those repositories.

But, as the work goes along, you start to notice some issues with your workflow:

you see that you have some code duplication between your projects
detecting critical/breaking changes became difficult since many problems came up only in the staging environment

How to get around code duplication?

The most common approach to deal with duplication is to move code "up" and separate it into reusable functions or maybe reusable typings. But, since your whole project consists of three separate repositories, there is no common spot to place reusable code.

The only way to achieve this opportunity to lift code 'up' is to create another repository for that reusable code. A package or library, which we will keep inside that repository, must be later built and published on the NPM registry.

Of course, since our two applications would use this package to import and use it, any change in that common library would create a need to publish a new version of that library on NPM.

We would have to keep track of releases and bump the version of that reusable package accordingly to the changes, probably using semantic versioning.

How to deal with late bug detection?

Introducing multiple apps and packages in a separate repository to maintain brings more significant problems than keeping proper versioning in mind. Imagine the following situation:

you are working on a back-end application, and you need to change the response shape of some endpoint
you commit your changes, the PR passes all the necessary tests, and your code ships to the staging environment
after deployment, you realize that part of the front-end application related to that prior endpoint has stopped working 😮

Did it happen because you haven't tested your changes locally with the front-end application? Yes. But did it also occur because your workflow is not resilient enough? Also yes!

It's hard to test everything, so we developers have CI/CD tools to take some weight off our shoulders.

We create automatic pipelines that run tests and perform code analyses, which are run on push. For example, in our case, we could have had two pipelines configured, one for running all of the checks for the front-end application, the other to do the same but for the back-end application.

Unfortunately, when it comes to having two separated pipelines for two different applications, the fact that they are passing doesn't give us much confidence. What about that reusable library, which we had moved to a separate repository? Is it even tested? Does the front-end use the same version of that package as the back-end? Those are the type of questions that we lack an answer for. Of course, our code is bug-free, and all the tests are passing, but will those two applications work together?

Even most minor changes, like extending the shape of a response with the extra field, maybe breaking change if the front-end does some strict runtime validation for static types (runtypes, zod, etc.)

Monorepos to the rescue

What if we had put our applications together in the same repository? Code duplication would no longer be a problem since we could move all the reusable code to another module or directory. Late bug detection would also not be a problem anymore because the pipelines for our front-end and back-end applications would run simultaneously. Linting, type checking, and static code analysis would also run globally.

In fact, we would ensure that both our applications would be compatible with each other at any point in time since none of the breaking changes could be done to one package without updating the other ones.

There are also other advantages of using monorepo over separate repositories:

we could have common configs and enforce the style and linting rules across multiple applications,
developers working on the project would have better visibility into the codebase,
dependency management would be simplified as we could enforce an exact version of the same package used in multiple applications,
we could manage our git history better since changes to multiple packages can be packed into a single commit

Disadvantages of using monorepo

Despite many visible pros of using monorepo, this architectural pattern comes with some limitations. The most significant limitation is the lack of control over packages to which developers have access. If all of the applications and packages are stored in the same repository, then the person having access to that repository can now look into the whole codebase. Some companies enforce strict access control and restrict some parts of the app, which is irrelevant to the user.

The other big concern is performance. Since there is a lot of code in one place, the build time is higher, and there are many commits that Git tracks. watching for changes and rebuilding only the packages that have changed can shorten build times and pipelines. I've heard that some tools allow you to fetch only one package along with its dependencies to speed git locally, but I haven't tested them out.

Monorepo tooling

There are great tools and utilities for constructing monorepo with multiple modules inside and a pleasant developer experience. Here I specify the most popular ones, which I've had an opportunity to get familiar with:

Yarn workspaces

Yarn workspaces link your dependencies together, which means that your packages can depend on one another. In addition, it sets up a single node_modules folder without cloning dependencies throughout different packages in the project.

Details on how to set up yarn workspaces can be found on yarn's official docs

I would recommend yarn workspaces to anyone who uses yarn as a dependency manager. It is easy to set up and maintain.

Nx

Nx is an advanced set of extensible dev tools for monorepos, emphasizing modern full-stack web technologies. It provides nifty features like incremental builds and generating dependency graphs.
Nx comes with a CLI that allows you to quickly generate and add new packages, applications, or libraries into your project.

More on that can be found in the Nx docs

Rush.js

Rush.js is a robust monorepo infrastructure open sourced by Microsoft.
One of its key features is that Rush.js installs all dependencies for all projects into a shared folder and then uses isolated symlinks to reconstruct an accurate node_modules folder for each project.

Rush.js also helps to ensure there are no phantom nor duplicated dependencies. Along with the PNPM package manager, it allows you to save disk space by installing your dependencies only once.

It also allows you to manage your packages, build and publish them. At the present moment, Rush.js is my favorite among other tools that I've mentioned.

More on Rush.js can be found on the official docs

Final thoughts

Monorepo architecture is a controversial architectural pattern. It comes with significant advantages as well as some big challenges. Even though many of the biggest companies use monorepos (Google, Facebook, Microsoft), this pattern has many opponents.

What do you guys think? Do you have some thoughts about monorepos? Do you have some good or bad experiences with them? I would like to know your opinions, and I am looking forward to the discussion.

I hope you liked this introduction to monorepos. 🙂 Feel free to comment or ping me with DM! ✉️

Thanks for reading! If you are interested in the latest tech news, you can follow my account since I plan to post here regularly. I also tweet on a regular basis so that you can follow My Twitter account as well!

A weekly dose of best resources and articles for a full stack web developer 🔥 #2

Jakub Skoneczny — Mon, 01 Feb 2021 17:44:34 +0000

For about some time, I've been pinning the best articles and resources I've come across while learning web development. Since I can no longer find myself in my Google Chrome bookmarks, I've decided to publish them online for better organizing and for other people to have access to them. 😃

The first set of articles is available in the previous post.

A weekly dose of best resources and articles for a full stack web developer 🔥 #1

Jakub Skoneczny ・ Jan 21 '21

#webdev #javascript #node

I've got articles covering topics like Javascript, React, Serverless, Cloud, CI/CD, DevOps, and others. Due to lack of time, I will try to post them gradually. Here are another 10 of my pinned articles:

Finding the cause of a memory leak in Jest tests

With increasing test coverage using Jest and React Testing Library, you may start seeing some “out of memory” errors. In this article, you will find how to solve this and how to find the cause of a memory leak.

Push Notifications in JavaScript? Yes, you can!

With this tutorial, you will get started with JavaScript Push Notifications with working code samples and an easy explanation.

Let's Bring Spacer GIFs Back!

Learn how to design components so they only affect their inner layout and not the whole page

Multiple NodeJS apps on single server

Learn about what is web server and application server and how to deploy multiple NodeJS applications on a single server with Reverse Proxy

How to analyze 100 GB of data on your laptop with Python

Learn the best way of approaching that kind of datasets, which are a bit uncomfortable to use

Why React Context is Not a 'State Management' Tool (and Why It Doesn't Replace Redux)

This post will clarify what Context and Redux actually are, how they're meant to be used, how they're different, and when you should use them.

Introduction to Reactive Programming for Everyone

RxJava, RxJS... - do you see technologies like these listed in the job requirements and feel a little bit scared? With that article, you will get to know your opponent!

How To Set Up a Node.js Application for Production on Ubuntu 16.04

This tutorial will cover setting up a production-ready Node.js environment on a single Ubuntu 16.04 server. The server will run a Node.js application managed by PM2 with Nginx Reverse Proxy.

Fast-Paced Multiplayer (Part I): Client-Server Game Architecture

First in a series of articles exploring the techniques and algorithms that make fast-paced multiplayer games possible

18 DevTools for productivity 🚀

This may sound crazy, but developers are lazy. We need to automate lots of our tasks because repetition can be tiring. Here is a list of some tools I find extremely useful

That's it for now. 😀 If you also have great resources pinned or saved on your computer, you can send me some (comment or message), and I will include them in my list.

You can find the whole list of resources on my personal website:
Resources | Jakub Skoneczny - Javascript Developer

If you are interested in the latest tech news, you can follow my account since I plan to post here regularly. I also tweet on a regular basis so that you can follow My Twitter account as well!

Run Git commands from Node.js application using JavaScript! 🚀

Jakub Skoneczny — Mon, 25 Jan 2021 17:00:49 +0000

When dealing with large applications and with complex, CI/CD pipelines with multiple staging environments, it might be useful for you to have some way to automate applying the latest changes from one environment to the other.

Consistency between multiple environments

At my work, we have three environments - one is the production environment (PROD), and two others are for fixing critical errors (HOTFIX) and developing new stuff (STAGING) with the possibility of introducing breaking changes.

While creating a pull request with a quick fix of some bug and merging it to the HOTFIX environment (with future deployment to production), it is also necessary to have this code in the STAGING environment, so the future deployment of STAGING into PROD would not cause conflicts.

The easiest way for having this cross-environment consistency is to make cherry-pick of the commit to STAGING after it is merged into HOTFIX. Easy, but manual, and since it's manual, someone can forget to do this. 😅 Plus, we need to know the specific identifier of a commit, so it's rather tricky for automatization.

Another way to achieving this is to rebase STAGING on top of HOTFIX periodically. By doing it, we will have all of our feature changes as well as fixes of bugs. And also, it is somewhat manual work, but this time it is easy for automatization.

For this automatization, we will use a simple-git library.

A lightweight interface for running git commands

Simple-git is a tool for running git commands in any Node.js application.
It gives us access to make all kinds of permutations on top of your commits and branches. With that library, we can easily create a script responsible for releasing our latest changes and running it from the command line.

All we need to do in order to start using simple-git is to include into our JavaScript app and create a git instance:

const simpleGit = require("simple-git");
const git = simpleGit.default();

Then, we have access to any git command as well as for options supported by that command. You can later visit the public API of the library to see the full list of available methods.

For now, simply try to checkout on some test branch:

await git.checkout("test-branch");
const branch = await git.branch();

// logs "test-branch"
console.log(branch.current)

It works, and it's plain and simple like standard git commands! 🙂

Note: Remember that from within your script, any git command is like a side-effect, and it is not synchronous.

Let's imagine having a script like one below, which executes all the commands needed for rebase one branch into another:

async function main() {
  try {
    const status = await git.status();

    if (!status.isClean()) {
      return;
    }

    await git.checkout("HOTFIX");
    await git.reset("hard", ["origin/HOTFIX"]);
    await git.pull();

    await git.checkout("STAGING");
    await git.reset("hard", ["origin/STAGING"]);
    await git.pull();

    await git.rebase(["HOTFIX"]);
    await git.push("origin", "STAGING", ["--force"]);
  } catch (error) {
    const status = await git.status();

    if (status.conflicted.length > 0) {
      return;
    }

    console.log(error);
  }
}

Our script fetches the latest changes on every branch, then it rebases STAGING branch on top of HOTFIX. Before executing anything, we check for not committed files since a hard reset will discard any changes made in development. Unfortunately in case of an error or merge conflicts, we must continue manually.

So we have an automated way of rebasing branches to date with the latest HOTFIX environment. And with chalk, we can make it a beautiful command-line script:

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

Now with this script, which takes care of rebasing for us, the whole process of making your environments consistent is encapsulated in one single file, which can be executed from the command-line.

node update-branches.js

// or we can specify a command in package.json
yarn update:branches
npm run update:branches

I guess it is even possible to hook up this script in the deployment pipeline, for example, with Github Actions or Husky. I will explore this topic in the future. 😃

I really recommend you to inspect this awesome library for yourselves!

A weekly dose of best resources and articles for a full stack web developer 🔥 #1

Jakub Skoneczny — Thu, 21 Jan 2021 22:13:49 +0000

I've got articles covering topics like Javascript, React, Serverless, Cloud, CI/CD, DevOps, and others. Due to lack of time, I will try to post them gradually. Here is the first set of them:

Building an augmented reality (AR) application using the WebXR Device API

Tutorial on building an AR web application. The application uses JavaScript to render 3D models that appear as if they exist in the real world.

The Perils of Rehydration

How to avoid rehydration problems with Gatsby and React SSR in depth. If you have ever experienced a warning about the mismatch between elements rendered on the server and on the client-side, this article is for you.

Building a game with TypeScript

Series of tutorials on how to build a board game from scratch with TypeScript and native browser APIs. Includes Canvas API and state machines.

Create Your Own Compiler

This tutorial explains the mechanism of how JavaScript works. The Super Tiny Compiler is a simple compiler written in Javascript and you will write it step by step from scratch.

Using React + Google Sheets as your CMS

Tutorial on how to serve up any data from a Google Sheet into a real React application. Maybe it's not meant to be used in production apps, but for a quick solution, it is perfect!

Introducing Handsfree.js - Integrate hand, face, and pose gestures to your frontend

Handle any kind of gestures into your web application. Handsfree.js is a client-side library that helps you add hand, face, and pose estimation to your front end projects.

Using the Web Speech API

The Web Speech API enables you to incorporate voice data into web apps. With this official MDN documentation, you can learn In-depth about speech recognition.

Continuous Deployment for Node.js on the Google Cloud Platform

Setup your Node.js application to deploy to App Engine on GitHub push. Covers the basics of Google Cloud Platform and Cloud Build.

Dockerizing and autoscaling Node.js on Google Cloud

Learn how to dockerize a Node.js server for hosting in Google Cloud and configuring your VM instances to auto-scale proportionally with traffic.

Getting Started with Terraform and Google Cloud Platform

Terraform is an automation tool used to ease the process of setting up infrastructure on which you can deploy applications. It can be used for describing infrastructure as a code regardless of the cloud provider.

That's it for now. 😀 If you also have great resources pinned or saved on your computer, you can send me some (comment or message), and I will include them in my list.

If you are interested in the latest tech news, you can follow my account since I plan to post here regularly. I also tweet on a regular basis so that you can follow My Twitter account as well!

The easiest way to internationalize your NextJS application! 🌎

Jakub Skoneczny — Mon, 18 Jan 2021 17:09:03 +0000

From version 10, Next.js has built-in support for internationalized routing. This feature allows you to support multilanguage versions of your application just by providing a list of locales.

Start with changing your Next.js configuration, which is inside next.config.js:

module.exports = {
  i18n: {
    /**
     * Provide the locales you want to support in your application
     */
    locales: ['en-US', "pl"],
    /**
     * This is the default locale you want to be used when visiting
     * a non-locale prefixed path e.g. `/hello`
     */
    defaultLocale: "pl"
  },
}

Accessing the locale information

After configuring the supported locales, you can access the locale information with the Next.js built-in router. The router has the following properties inside:

locale, which contains the currently active locale,
locales, which includes all configured locales,
defaultLocale, which provides for the configured default locale.

Router is accessible from the functional components by the useRouter hook:

const { locale, locales, defaultLocale } = useRouter()

When doing SSR with getStaticProps or SSG with getServerSideProps, the locale information is provided in the function's context.

Transition between locales

You can use the built-in Link component along with the useRouter hook to transition between locales:

import Link from "next/link";

/**
 * Inside your component
 */
const { asPath, locale } = useRouter();

return (
  <>
    <Link active={locale === "pl"} href={asPath} locale="pl">
      PL
    </Link>

    <Link active={locale === "en-US"} href={asPath} locale="en-US">
      ENG
    </Link>
  </>
);

Presenting multilanguage data

Now you can define an object in which we will store multi-language data for our components. After reading the current locale value, we can get translated texts just by accessing the property on an object:

/**
 * Define your multi-language data
 */
const data = {
  pl: {
    title: "Cześć!",
  },
  "en-US": {
    title: "Hello!",
  },
};

/**
 * Inside your component
 */
const { locale } = useRouter();
const title = data[locale].title;

What about type safety?

When reading the value of locale from the useRouter hook, you may notice that your IDE identifies the type of the locale as a string. Unfortunately, at this moment, Next.js does not provide typescript support for locales.

If you want to get full type safety, you may want to introduce your own custom hook for reading the value from of locale

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

After defining your own type for supported locales and reading the current locale's value from the router, let's return this value with a simple as type assignment.

I've rebuilt my portfolio. Now it loads in less than 1 sec! Here's how I did it! ⚡

Jakub Skoneczny — Mon, 11 Jan 2021 17:00:49 +0000

Some time ago, during my early PHP years, I had created a website for myself, which combined my resume and some space for sharing my thoughts with the world. That website was well designed and had many features like tagging posts, filtering, and searching. But on the other hand, that website was cumbersome. The application took about 5 to 6 seconds to load on a good internet connection!

I realized that at some point, I would need to rewrite everything from scratch. That moment came when I have learned about the React ecosystem. Now, after it's done, I would like to share my thoughts on how I have managed to make the website incredibly fast.

Note: When writing this article, I intend to explain what can be done to improve any website's performance. Please note that some of those points may not be valid for your use case since not all websites are the same (blog is different than e-commerce application).

Use the right tools for the job 🔨

PHP language was fantastic, as so Laravel, which is a framework for developing web applications. But after I have learned the React and its ecosystem, I have decided to go with NextJS. And oh, boy, it was an excellent choice! NextJS supports two forms of rendering your content:

Static Generation: The HTML is generated at build time,
Server-side Rendering: The HTML is generated on each request.

Static generation is perfect for use cases like blogs or personal websites, where the content does not change often. After you build the application with that approach, you end up with a bunch of static HTML files, which you can deploy on any hosting. And nothing is more performant than simple HTML files.

Optimize your assets 📦

It seems like an obvious thing to do, but I will mention this anyway. Any static assets that you use on your website should be optimized. It includes minifying your CSS files and JavaScript files but also compressing images. For example, if you use a picture for your avatar, you don't need a file that has 500x500px dimensions and a weight of 200 Kb. Choose a resized file instead.

Tip: Almost any image can be optimized by dropping its quality to about 80%, and there will be no visual difference between the compressed version and the original.

If you use modern web frameworks like NextJS, all of your bundles are already optimized. But be careful if you put external stylesheets or scripts to your website because they are not always minified.

Preload external scripts 🕖

When dealing with external JavaScript files, you need to be careful where you put those scripts inside your HTML because this will affect the loading time. By putting external scripts in the head of the document, your browser will try to fetch and execute the script before rendering DOM. It is recommended to move external scripts at the end of the body or specifying defer property on those scripts.

Deferring scripts will result in them being downloaded with other resources but executed after the HTML is parsed and rendered. I recommend you to read this excellent article on that topic: Efficiently load JavaScript with defer and async

Lazy load images 🖼️

We tend to use a lot of images on our websites. Whether they are put in the background, or we want to share something, it's unnecessary to load them all at once. The standard way to deal with images is to load only those directly in the viewport or close to it. We don't need to load an image that is far down the page and isn't visible to the user yet.

There are many techniques to implement lazy loading, but the most common way is to use the Intersection Observer API or a library that depends on it. Recently, native lazy load support has been added to the Google Chrome browser. It is as simple as adding a loading property onto the img element.

<img loading=lazy>

Not every browser yet supports it, but this will be the standard of lazy loading images in the future. You can learn more on that here: Browser-level image lazy-loading for the web

Use service worker 📝

A Service Worker is a script that executes in the background, in a separate thread from the main JavaScript bundle. A service worker can intercept all network request, so it's often used for caching assets and some of the critical API payloads that make possible for a website to function without an internet connection.

Using the service worker will not increase your website's speed on the very first load, but every other reload will be faster since some of the assets are already downloaded and stored inside the browser's cache.

Note: A service worker is recommended for the browsers to treat your application as an installable SPA.

Use CDN 🌎

A Content Delivery Network is a way to deliver content from your website to clients more quickly and efficiently, based on their geographic location. It allows for the quick transfer of assets needed for loading your content, including HTML, scripts, and stylesheets from the server located closest to the client.

The main benefits of using a CDN in front of your web server or static hosting are:

Improving website load times, because the website and its assets are cached and served from the closest server in the network,
Reducing bandwidth costs since requests are interested and not directed to your server.

Many CDN providers (e.g., Cloudflare) provides you as well with security improvements for your application. They support you with a free SSL certificate for your domain and with protection from DDoS attacks.

Effect? Blazing fast website ⚡

After developing my new website and implementing all of the tips listed above, I have reduced the loading time to about 1 second! The effect had shocked me positively. Check out the lighthouse report:

I realize that those numbers come only from a simulation, and they may differ on real devices. But seeing that audit with the time of First Meaningful Paint being 0.7 seconds makes me smile. 😀

Thanks for reading, and I hope you have enjoyed this article. I would love to receive your feedback on my portfolio site since it is new and freshly designed. Check it out, and let me know your opinions. 😊

My portfolio: blog.jskoneczny.pl

Skona27 / fancy-portfolio

My new fancy portfolio

PS: If you are interested in the latest tech news, you can follow my account since I plan to post here regularly. I also tweet on a regular basis so that you can follow My Twitter account as well!

Future of state management in React with XState

Jakub Skoneczny — Tue, 05 Jan 2021 15:15:17 +0000

It is common to see a poll on social media asking for the most common ways to manage state in React. In many cases, the options are limited to MobX or Redux, React Context + Hooks, Recoil, but more recently, also XState.

With the other tools being well known and primarily accepted (maybe without Recoil, since it's also new), XState is still relatively unknown to most developers.

Note: The purpose of this post is not to compare XState to other state management tools, but rather to tell about the problem it solves and give you a quick introduction, so you can jump and start learning by yourself.

So without further ado, let me tell you more about XState.

What is XState?

XState is a library that brings state machines to Javascript and Typescript world. State machines are a mathematical concept that has been introduced for describing complex systems. To explain it quickly, imagine a block schema - you have multiple blocks connected with lines and arrows. Those blocks represent states in your application, and lines with arrows represent the flow between those states.

If you start from the first block, you can only transition into the block you have a connection with. Therefore you are automatically prevented from transitioning to any block you want. And this is the most significant advantage of using state machines - you can only transition between states that have defined and allowed connections.

Let's now drop this analogy tho schema and use the proper terminology.

Every state machine has:

a finite number of states (such as idle or loading),
a finite number of events (such as { type: 'SEARCH' } can trigger a transition between states).
a list of defined transitions, which say, "Given some event, go from state idle to pending".

Also, every state machine may have:

a context which is data stored inside the machine,
a final state, after which the machine stops

Okay, so we know what a state machine is. But when seeing a designed schema, it is easy to think about it as a machine. Let's see how one can think of anything like a machine and write it using XState.

Describing ordinary things in the form of a state machine

Think about water. Just regular water. How does it behave? If we start with the liquid form, it freezes when it's cold, and it vaporizes when we boil it. We can even heat it more and more until it becomes plasma. Let's try to write it down in block schema:

When water becomes plasma, we can no longer heat it because it can't change farther. We can only freeze it from there. If we start to freeze plasma, it will become a gas again. The same thing is with ice. If water is in ice form, we can't longer freeze it. We can only heat it.

If you look closely, you will notice that water has no final form. We can always make a transition between its states. Let's see how we could implement it with XState.

import { Machine } from "xstate";

const waterMachine = Machine({
  initial: "liquid",
  states: {
    ice: {
      on: {
        HEAT: {
          target: "liquid",
        },
      },
    },
    liquid: {
      on: {
        HEAT: {
          target: "gas",
        },
        FREEZE: {
          target: "ice",
        },
      },
    },
    gas: {
      on: {
        HEAT: {
          target: "plasma",
        },
        FREEZE: {
          target: "liquid",
        },
      },
    },
    plasma: {
      on: {
        FREEZE: {
          target: "gas",
        },
      },
    },
  },
});

We need to import a Machine creator and pass it into the machine's object. Machine's object has states property where we define our states. In each state, we can put the on property, which handles events that are defined within.

Event handlers are objects in which we can put target property pointing on a different state. This means that when the HEAT event in the ice state comes, the machine will transition from an ice state to a liquid state.

This explanation may sound complicated, but it starts to be straightforward if you look into the code.

Using XState with React

XState is a Javascript library, which means it is framework agnostic. But when it comes to React, XState gives us hooks for using a defined state machine inside React components. All we need to do is to call it, and then we have access to properties like:

state that represents the current state of the machine and its data,
send, a function that sends events to the machine

With that, you can use your machine inside components. You can read its current state (e.g., rendering different components based on state), you can read its context (for displaying data), and you can send events to that machine (make transitions between states).

Just see the usage of our water machine inside the React application:

import { useMachine } from '@xstate/react';

// use hooks inside your component
const [state, send] = useMachine(waterMachine);

console.log(current.value)
// 'liquid' 

// send event for making a transition
send("HEAT")

console.log(current.value)
// 'gas'

Prototyping and debugging with ease

State machines built with XState can be visualized with the usage of XState Viz. This fantastic tool allows you to do many things with your machines like debugging, live preview, and interactivity. Just see how we can interact with our water state machine.

Designing complex systems with state machines

When thinking of large web applications, often it comes for us developers to introduce huge and intricate features. Some components are built with dozen or hundreds of child components that also have some logic inside. Coming up with a sound state management system for that can be tricky. Fortunately, state machines fit well for that.

A state machine can be just like a single block in block schema. Your application can have multiple state machines, which communicate with each other. Also, you can have one main state machine which controls the others and enables that communication.

And all of that logic nested inside multiple state machines can be later visualized with XState Viz and be interactive. What a great business value for your PM!

In my opinion, this is the most valuable advantage of state machines over other state management tools - it's not just a library for state management. It is a whole new ecosystem for designing and controlling business logic.

Going further with XState

If you want to dive deeper into XState concepts, I highly recommend visiting the official XState documentation. Documentation is written clearly and is pleasant to read. For those of you who instead prefer video sources over reading documentation, I have prepared an introductory course that is available on Udemy - Introduction to State Machines with XState and React.

Thanks for sticking for that long! If you are interested in the latest tech news, you can follow my account since I plan to post here regularly. I also tweet on a regular basis so that you can follow My Twitter account as well!

This post has been originally posted on my personal blog. Please make sure you see it there as well :)

PS. Comment if you have used XState in production!

Deploy scalable NodeJS application with Postgres database using AWS CDK

Jakub Skoneczny — Fri, 01 Jan 2021 14:40:32 +0000

This simple tutorial will show how to deploy any NodeJS application on AWS cloud with AWS Cloud Development Kit usage. Our application will use the Postgress database, but code from this tutorial can be a basis for deploying any database with your application.

I will not cover the AWS CDK basics since there are plenty of good resources, which explain everything from scratch and show how to bootstrap your AWS CDK project.

If you need to check the basics, here are some good sources:

What is AWS CDK (Cloud Development Kit) and why it's awesome
AWS CDK repo

Here I specify what we are going to do:

Create secrets using AWS Secret Manager and read them from our custom stack
Create an RDS stack with database definition
Create ElasticBeanstalk stack for application deployment
Create VPC stack and connecting everything

Note: This tutorial is inspired by two other posts. Without them, it would take me much longer to figure out everything:

I tell you a secret: Provide Database credentials to an ECS Fargate task in AWS CDK
Complete AWS Elastic Beanstalk Application through CDK (TypeScript)

So without further ado, let's get started!

Create secrets in the AWS Secret Manager

Go to your AWS Console and search for Secret Manager service and create two secrets to store your username and password for the database connection. AWS suggests you keep their naming conventions, so let's use prod/service/db/user as a name for user secret and prod/service/db/password as a name for the password.

Once you create those secrets, keep the ARN, which you will get back. They will be required to set up our connection.

Create stack for keeping credentials

Let's create a file called lib/credentials-stack.ts in which we will read credentials that were saved in Secret Manager.

import * as cdk from "@aws-cdk/core";
import { ISecret, Secret } from "@aws-cdk/aws-secretsmanager";

export interface Credentials {
  username: ISecret;
  password: ISecret;
}

export class CredentialsStack extends cdk.Stack {
  readonly credentials: { username: ISecret; password: ISecret };

  constructor(scope: cdk.Construct, id: string, props?: cdk.StackProps) {
    super(scope, id, props);

    const secretUsername = Secret.fromSecretCompleteArn(
      this,
      "BackendPersistenceUsername",
      // Pass your username secret ARN
      ""
    );

    const secretPassword = Secret.fromSecretCompleteArn(
      this,
      "BackendPersistencePassword",
      // Pass your password secret ARN
      ""
    );

    this.credentials = {
      username: secretUsername,
      password: secretPassword,
    };
  }
}

We have made a new stack in which we read secrets required for connecting to our database and keep them in the credentials property attached to this stack. Later on, we will be able to pass those credentials to other stacks.

Create RDS stack with Postgress database

Now we need to create a stack that will hold definitions for our Postgress database. For that, let's create a file called lib/rds-stack.ts.

import * as cdk from "@aws-cdk/core";
import * as ec2 from "@aws-cdk/aws-ec2";
import * as rds from "@aws-cdk/aws-rds";
import { Credentials } from "./credentials-stack";

export interface RdsStackProps extends cdk.StackProps {
  credentials: Credentials;
  vpc: ec2.Vpc;
}

export class RdsStack extends cdk.Stack {
  readonly postgreSQLinstance: rds.DatabaseInstance;

  constructor(scope: cdk.Construct, id: string, props: RdsStackProps) {
    super(scope, id, props);

    const username = props.credentials.username.secretValue.toString();
    const password = props.credentials.password.secretValue;

    this.postgreSQLinstance = new rds.DatabaseInstance(this, "Postgres", {
      engine: rds.DatabaseInstanceEngine.postgres({
        version: rds.PostgresEngineVersion.VER_12_4,
      }),
      instanceType: ec2.InstanceType.of(
        ec2.InstanceClass.T2,
        ec2.InstanceSize.MICRO
      ),
      vpc: props.vpc,
      vpcPlacement: {
        subnetType: ec2.SubnetType.PUBLIC,
      },
      storageType: rds.StorageType.GP2,
      deletionProtection: false,
      databaseName: username,
      port: 5432,
      credentials: {
        username,
        password,
      },
    });

    this.postgreSQLinstance.connections.allowDefaultPortFromAnyIpv4();
    this.postgreSQLinstance.connections.allowDefaultPortInternally();
  }
}

Since any database in AWS must always be created in the scope of some VPC, we have defined an interface for props to our stack and specified that vpc must be passed when instantiating this stack. Also, we will need to pass credentials, which we keep in credentials-stack.

This Postgress instance, which we have defined, uses a basic T2 MICRO instance, and is placed in public scope - our database will be reachable from the internet. Please note that we allow connections by invoking special methods (allowDefaultPortFromAnyIpv4 and allowDefaultPortInternally) on our instance.

Creating deployment with ElasticBeanstalk

We can then create a stack responsible for copying our application files to S3 and then deploying it to ElasticBeanstalk service. Let's create a file called lib/ebs-stack.ts and paste the code presented below.

import * as cdk from "@aws-cdk/core";
import * as EB from "@aws-cdk/aws-elasticbeanstalk";
import * as S3Assets from "@aws-cdk/aws-s3-assets";

import { Credentials } from "./credentials-stack";

export interface EbsStackProps extends cdk.StackProps {
  dbCredentials: Credentials;
  dbHost: string;
  dbPort: string;
  dbName: string;
}

export class EbsStack extends cdk.Stack {
  constructor(scope: cdk.App, id: string, props: EbsStackProps) {
    super(scope, id, props);

    const username = props.dbCredentials.username.secretValue.toString();
    const password = props.dbCredentials.password.secretValue;

    // Here you can specify any other ENV variables which your application requires
    const environmentVariables: Record<string, any> = {
      POSTGRES_USER: username,
      POSTGRES_PASSWORD: password,
      POSTGRES_DB: props.dbName,
      DB_HOST: props.dbHost,
      DB_PORT: props.dbPort,
      DB_SCHEMA: username,
    };

    const environmentOptions = Object.keys(environmentVariables).map(
      (variable) => {
        return {
          namespace: "aws:elasticbeanstalk:application:environment",
          optionName: variable,
          value: environmentVariables[variable],
        };
      }
    );

    const applicationName = "Server";

    const assets = new S3Assets.Asset(this, `${applicationName}-assets`, {
      // Change path to your applications dist files
      // In my case I've created a monorepo, so path was like ../server/dist
      path: "path/to/your/application/dist",
      exclude: ["node_modules",],
    });

    const application = new EB.CfnApplication(this, `${applicationName}-app`, {
      applicationName,
    });

    const appVersionProps = new EB.CfnApplicationVersion(
      this,
      `${applicationName}-version`,
      {
        applicationName,
        sourceBundle: {
          s3Bucket: assets.s3BucketName,
          s3Key: assets.s3ObjectKey,
        },
      }
    );

    const options: EB.CfnEnvironment.OptionSettingProperty[] = [
      {
        namespace: "aws:autoscaling:launchconfiguration",
        optionName: "IamInstanceProfile",
        value: "aws-elasticbeanstalk-ec2-role",
      },
      {
        namespace: "aws:ec2:instances",
        optionName: "InstanceTypes",
        value: "t3.small",
      },
    ];

    new EB.CfnEnvironment(this, `${applicationName}-environment`, {
      environmentName: "develop",
      applicationName: application.applicationName || applicationName,
      solutionStackName: "64bit Amazon Linux 2 v5.2.3 running Node.js 12",
      optionSettings: [...options, ...environmentOptions],
      versionLabel: appVersionProps.ref,
    });

    appVersionProps.addDependsOn(application);
  }
}

The first step is to create an S3 bucket, including the source files for our application. This S3 logic fires before the CloudFormation template is acted upon to be available for EBS.

Then, the environment for the application is created, and the application is assigned to it. We also specify the version for our application (addDependsOn), which is unique for the uploaded source files.

Create VPC stack and connect all the stacks

VPC is like a private network in the scope of our services that can communicate with each other. Any database in AWS must always be created in the scope of some VPC, so let's define a stack for that. Create a file called lib/vpc-stack.ts. This one will be pretty short:

import * as cdk from "@aws-cdk/core";
import * as ec2 from "@aws-cdk/aws-ec2";

export class VpcStack extends cdk.Stack {
  readonly vpc: ec2.Vpc;

  constructor(scope: cdk.Construct, id: string, props?: cdk.StackProps) {
    super(scope, id, props);

    this.vpc = new ec2.Vpc(this, "VPC");
  }
}

We have created a new, default VPC instance and assigned it to vpc property on VpcStack.

Now, as we have all of the parts ready, we can connect it by creating an executable stack in bin/infrastructure-stack.ts

#!/usr/bin/env node
import * as cdk from "@aws-cdk/core";

import { EbsStackProps, EbsStack } from "../lib/ebs-stack";
import { CredentialsStack } from "../lib/credentials-stack";
import { RdsStack } from "../lib/rds-stack";
import { VpcStack } from "../lib/vpc-stack";

const app = new cdk.App();

const vpcStack = new VpcStack(app, "VpcStack");
const vpc = vpcStack.vpc;

const credentialsStack = new CredentialsStack(
  app,
  "CredentialsStack"
);

const rdsStack = new RdsStack(app, "RdsStack", {
  credentials: credentialsStack.credentials,
  vpc,
});

const dbInstance = rdsStack.postgreSQLinstance;

const ebsEnvironment: EbsStackProps = {
  dbCredentials: credentialsStack.credentials,
  dbName: credentialsStack.credentials.username.secretValue.toString(),
  dbHost: dbInstance.instanceEndpoint.hostname.toString(),
  dbPort: "5432",
};

new EbsStack(app, "EbsStack", ebsEnvironment);

We import all of our custom stacks and create instances of VpcStack and CredentialsStack. Then we can create a new database instance using the RdsStack. Do not forget to pass VPC and credentials as props. We can then create an EbsStack instance and pass every environment variable for the database connection.

With some luck, running yarn build && cdk deploy --all will have your application packaged and deployed to CloudFormation. In there, you can verify that ElasticBeanstalk and RDS services were created and are running correctly.

Thanks for reading, and feel free to contact me!

Introduction to State Machines with XState and React

Jakub Skoneczny — Fri, 13 Nov 2020 19:57:25 +0000

My first online course on Udemy

I have recently made a course about creating state machines with XState and using it inside React apps.

State machines with XState is a fresh topic for Frontend development, which allows us to better manage applications state.

If you are new to finite state machines' concepts or if you have ever heard about state machines, but you have no clue what is that about, then go and check on this course.

Check it out: https://www.udemy.com/course/introduction-to-state-machines-with-xstate-and-react

Sample coding video with Video Player component

I also present a sample coding video from this course in which I code a Video Player component with a cool autoplay option. Video is to be seen on Youtube. Link below:

I really appreciate all kinds of feedback! Reviews and comments are welcome :)