DEV Community: Dominik Sumer

How to use React to generate your own OpenGraph images

Dominik Sumer — Sat, 31 Jul 2021 20:11:00 +0000

This article was originally posted on my personal website.

In this blog post, I want to show you how you can generate an OpenGraph image out of your React component. Personally, I love this approach, because I can leverage my frontend development skills to generate dynamic images (actually not only OpenGraph images).

As already stated in the title, I am going to use React to generate the image, but the approach can probably be easily transferred to other Frontend Frameworks too, so I hope you also find it helpful although you're not into React!

Using Puppeteer / Playwright

The first building stone for this approach is to use a browser automation framework like Puppeteer or Playwright. Both are very similar feature-wise and also API-wise so there shouldn't be many differences between them. Today I am going to use Playwright.

Both of the mentioned frameworks can be used to automate a (headless) browser. You can write scripts to navigate to specific websites and scrape them or do other fancy stuff. And for the generation of our OG images, we're leveraging the power to take screenshots of websites. 🙌

Check out the following snippet:

import * as playwright from 'playwright-aws-lambda';

const width = 1200;
const height = 630;

const browser = await playwright.launchChromium({ headless: true });
const page = await browser.newPage({
  viewport: {
    width,
    height,
  },
});

const imageBuffer = await page.screenshot({
  type: 'jpeg',
  clip: {
    x: 0,
    y: 0,
    width,
    height,
  },
});

await browser.close();

With these few lines we:

Fire up a headless chrome browser
Open a new tab with the given viewport (I chose 1200x630 because it is the most common og image size)
Take a screenshot of it - you can choose between PNG or JPEG and with JPEG you can even specify the quality of the image
Close the browser

That's pretty neat, isn't it? But yeah, we're now just generating a plain white og image - so how can we use React to design a dynamic image of our desire? 😄

Leverage the power of React

Imagine we have the following component which we want to use to render our og image:

interface Props {
  title: string;
}

export const OgImage = ({ title }: Props) => {
  return <div style={{ color: 'red', fontSize: '60px' }}>{title}</div>;
};

It's a very simple component, perfect for our example. It takes a title as a prop and renders it as a red text. Let's tell playwright that we want to render it onto our page.

First we're creating an instance of our React Component passing our desired title as prop:

const el = createElement(OgImage, {
  title: 'This is a test title',
});

And then we're leveraging the power of React server side rendering. We're rendering it as static HTML markup:

const body = renderToStaticMarkup(el);

Additionally we add a utility function to render our basic HTML structure:

const baseCSS = `*{box-sizing:border-box}body{margin:0;font-family:system-ui,sans-serif}`;

const getHtmlData = ({ body }: { body: string }) => {
  const html = `<!DOCTYPE html>
    <head>
    <meta charset="utf-8"><style>${baseCSS}</style>
    </head>
    <body style="display:inline-block">
    ${body}
    </body>
  </html>`;
  return html;
};

And now we tell playwright, right after opening the new page in the browser, that our generated HTML should be set as the content of the page:

const html = getHtmlData({
  body,
});

await page.setContent(html);

Voilá now we're rendering our own React component with playwright and taking a screenshot of it. 🥳 From here your imagination knows no boundaries. Just style your og image like you're used to style your frontend applications and use as many dynamic parameters as you need.

Using ChakraUI

I love to use ChakraUI to style my web applications. Since I switched to ChakraUI I would never want to style my React applications differently. Therefore I also wanted to use ChakraUI to generate my og images.

To achieve this you also need to include the <ChakraProvider> into your OgImage component so that you can access all of the functionality.

Deploying it as a serverless function

Basically, you could use this technique to generate images of your React component however you want. E.g. as a Node.js script that generates some images with the given arguments. But with this blog post, I am specifically mentioning og images, which are being fetched when a bot crawls your website.

I am using Next.js to write my React applications and my plan was to actually generate those og images while building my project. Next.js creates static sites for my blog posts and I wanted to create the static og image once the static site is created and then just serve it as static asset. But I didn't get this working on Vercel as I ran into memory limits during the build process.

So then I went for the second-best approach which came into my mind: deploy it as a serverless function (in my case a Next.js API route) which is called with dynamic parameters.

It's basically just a GET call that takes my dynamic parameters, renders the og image with playwright, and returns it as response. That's how I am rendering the og images for my blog posts here. 😄

You can find the source of this og image generation right here.

And this is the API where those og images are located / being generated on the fly.

Conclusion

I hope this blog post was somehow helpful to and maybe it could spark some ideas about how you can use this technique to generate some awesome images. If you have further questions, please don't hesitate to shoot me a DM on Twitter, cheers!

How to integrate Gumroad as a payment provider for your SaaS

Dominik Sumer — Wed, 30 Jun 2021 13:20:45 +0000

This article was originally posted on my personal website.

Maybe you’ve read my article about Stripe and EU VAT (which thankfully is deprecated because of the release of Stripe Tax) if you wanted to integrate a payment provider for your SaaS. And maybe you also thought: why does it have to be so complicated?

Most of the payment providers managed to make the process of selling digital products and taxes much easier for us over the last months. But do you know what’s even better than making the process easier? If you don’t have to deal with it at all 🙌

Today I want to introduce you to another way to integrate payments into your SaaS. A way that is super simple and causes you no headaches - which is crucial if you’re currently building an MVP for your SaaS and want to validate if your idea is worth pushing further.

What is Gumroad and how does it work?

Gumroad is a digital marketplace for selling your products. It’s not even bound to only sell digital products, but today we’re going to focus on this part. Gumroad handles many things for you. You only need to connect your PayPal account (or in some countries you can also connect your bank account directly) to your Gumroad account and that’s it.

But why is it so easy when it comes to handling invoices and the collection of taxes? Because you are not selling the digital products to your customers directly, but on the behalf of Gumroad and they take care of all the bureaucracies.

That means that Gumroad is responsible for charging the VAT from your customers and invoice them correctly. And every two weeks Gumroad pays you all the income of your products onto your PayPal account.

If you now still need to invoice Gumroad, because it is needed for your company, then you probably just need a reverse-charge invoice to have everything documented, but make sure to double check this with your accountant.

This of course doesn’t come for free. Gumroad charges you a fee for every sale, but especially when you’re at the beginning and don’t want to spend too much time on bureaucracies, it can definitely be worth it. This table includes all different use-cases and how much fees you’d have to pay in each case.

How can Gumroad be included in your payment process?

There are two ways how you can include Gumroad in your payment process. Let’s split them up into two sections and look at each of them on their own.

Redirect your customer to Gumroad

The first approach is to just redirect the user to your product page in Gumroad where they’re able to purchase it directly. This is the approach we went for because it is straightforward to implement and we had problems with the other solution (more on this later).

So you lead the user to the URL of your Gumroad product which looks like this: https://gum.co/snappify

In most cases you describe your product very well on the website of your SaaS, so you probably don’t need to show him the description page on Gumroad, but directly lead him to the checkout page. This can be achieved by appending ?wanted=true as request parameter of the URL.

So for example if you have your own pricing form, where you describe everything to the user and then lead him to the Gumroad URL of the product including the wanted parameter, he will directly land at the checkout and can purchase your product - Gumroad is taking care of the rest. 🙌

Custom form fields and how to prefill them

Sometimes you also have other form fields than just the email address of the user. In our case we need the Twitter Username so we can identify which user has purchased our product.

Those form fields can be specified directly in Gumroad. You can also specify if they are mandatory or not.

Sometimes you already have that information from the user and want to save him time by prefilling it in the Gumroad checkout form. This can also be achieved by just appending the values via request parameters.

In our case, we named the field “Twitter Username”. So to prefill it with a value we need to append the following parameter: &Twitter%20Username=dominiksumer

That’s it, you probably saved your user time which is definitely great in a checkout process. 😄

Get notified about successful purchases

After your user successfully purchased your product, he will be redirected to an URL you can specify in Gumroad. We for example made a separate page where we thank the user and tell him how he can further continue.

But like this, you still don’t know which user purchased and you would also probably need to mark this user as a customer in your database to give him access to features he paid for. This is where “Gumroad Ping” comes into play.

Gumroad Ping is a service that calls your application if a successful purchase was made. Perfect for our use case! So how does such a call look like and how can you react to it?

Gumroad Ping sends a POST request to your specified URL with all information you need about the purchase. Here is an example of how we implemented our REST endpoint to handle the Gumroad Ping call:

import type { NextApiRequest, NextApiResponse } from 'next';
import { addPro, isPro } from '../../utils/auth-util';

export default async function (req: NextApiRequest, res: NextApiResponse) {
  const { product_id: productId, test } = req.body;

  if (!test && req.method.toUpperCase() === 'POST' && productId === 'YOUR_PRODUCT_ID') {
    const userName = req.body['Twitter Username'];
    if (!(await isPro(userName))) {
      await addPro(userName);
    }
  }

  res.status(200).send('');
}

So you can see we first check that the boolean test is false (would be true if you’re testing a purchase on your own) and if the productId is matching the id of your product. Like this, you also secure the endpoint against someone just calling it and therefore you should keep the product id a secret.

Afterward, you can read other information from the user and move on with your logic of persisting the user as a customer. Also, make sure to return the status code 200 if everything worked out well to tell Gumroad that the operation was performed successfully. If you return another status code, Gumroad will assume that there was a failure and going to retry the Gumroad Ping call up to three times.

Hint: When Gumroad is redirecting the user to your website after a purchase, it can be the case that Gumroad Ping didn’t notify your application about it yet. So make sure to deal with this asynchrony.

Embed Gumroad Widgets into your SaaS

The second approach is to embed one of the Gumroad widgets into your website. It aims for an even better user experience as the user doesn’t have to leave your website for purchasing your product.

I had some weird issues in the frontend and didn’t want to waste too much time with problem-solving. That’s why I chose the first method with redirecting the user to Gumroad directly. I would suggest you give it a try and see if it works and fits your needs!

Recurring payments

For our product snappify we wanted to keep things simple in the beginning and only offer a yearly subscription without recurring payments. This yearly subscription is just a normal Gumroad product and when we get notified via Gumroad Ping that someone purchased the product, we add him as “Pro user” to our database including the date of the purchase and that’s it.

But you maybe want to including a monthly subscription too and want to charge your customers on a monthly basis. Gumroad also got you covered on this! They call it Memberships and together with the Gumroad API you have powerful tools at your hand to offer monthly subscriptions to your customers with ease.

Summary

You’re currently bootstrapping your SaaS. You want to find out if your idea is worth pushing further. You want to concentrate on getting the MVP up and running instead of spending hours integrating a payment provider.

If you find yourself in those words, you should consider giving Gumroad a try. They take their fair share, but also take care of all the bureaucracies and the integration itself should be done in some hours.

I’ve put this blog post out there because I have the feeling that only providers like Stripe or Paddle are being mentioned when integrating a payment provider for your SaaS. But why not keep it even simpler in the beginning? Cheers!

Publishing a TypeScript library in 2021

Dominik Sumer — Mon, 31 May 2021 22:16:59 +0000

This article was originally posted on my personal website.

The last time I wanted to publish a npm package was in 2018. It was a React library which provided Components for creating Forms. It wasn’t straight forward to publish such a library back then. There were so many things to handle on your own, especially when it came to TypeScript.

Assuming you were already familiar with webpack you thought: ha that should be easy, I can leverage my knowledge and just bundle my library with webpack, exactly like my webapps. But then you suddenly heard of that new kid on the block: Rollup, which seems to do a better job at bundling libraries. So a new bundler you had to learn and still soo many things to take care of on your own.

Great that we’re now fast forwarded to 2021. There’s a new player in the town to make our lives a lot easier. Let me introduce you to tsdx.io

The zero-config CLI for TypeScript package development

The goal of TSDX is to get rid of all the pain points I’ve mentioned above and just let you focus on developing your next library, instead of “waste another afternoon on the configuration”. And oh boy, they did an excellent job with this. Actually I couldn’t find the meaning of the TSDX acronym, but I would assume that it stands for TypeScript Developer Experience - which it definitely enhances a lot.

TSDX comes with Rollup under the hood and serves you best-practices for developing and bundling modern NPM packages. It is well tested and the team behind TSDX is formium, who are also developing the popular React forms library formik, which also leverages the power of TSDX.

The best practices which come with TSDX are should be perfect for the most projects. And even if you need to do adjustments, the process is pretty straight forward. For example for our library we wanted to use less instead of writing plain css and I show you later how you can adjust the TSDX config to your needs.

Create a new TSDX project

Creating a new TypeScript library with TSDX is as easy as typing npx tsdx create mylib. The command will guide you through the setup process and afterwards you will be presented with a packed folder where you can just start to develop your new library.

TSDX has three different project types which you have to choose one from:

basic - a plain TypeScript project (we went for this because we didn’t want to include any external libraries and weren’t depending on React)
react - choose this if you want to create a React library. TSDX takes care of all the things that have to be done to create a React library out of the box
react-with-storybook - same as the option before, but including a Storybook setup

Get started

TSDX makes developing your library super easy. You can just type npm start and your project will be started in watch mode. The entry point for your library is the index.ts (or index.tsx for a React project). So when ever you will make changes in one of your corresponding files, TSDX will detect it and rebuild the library for you, leading to a super smooth development process.

Running tests

TSDX also comes with Jest setup for you, so you could just write tests for example in the format of *.test.ts(x) files and Jest will recognise and execute them automatically if you type npm test.

Try out your library locally

Of course you also want to try out your library locally before you publish it for the rest of the internet. For this, the npm command npm link comes in very handy.

Go into the folder of your library cd ~/projects/mylib
Type npm link to create a local symlink of your library
Switch to the folder of your project where you want to include your library cd ~/projects/myproject
Type npm link myproject to install the local version of your library. This will also automatically refresh if you make changes to your library and rebuild it (which is done automatically by the watch command if you execute npm start in your library project)

Be sure to execute npm link with your full library name (not the folder name) which is stated in your package.json. In our case we had to type npm link @snappify/integration because our package is included in our npm organisation.

Adjust the default configuration

Now you should be ready to develop your library and test it until you can publish it. But what if the default TSDX doesn’t fulfil your needs and you need to adjust the config?

If you want to adjust the build config, you have to create a tsdx.config.js file in the root of your library folder. In their you’re going to export an object including a rollup function which receives the default rollup config as the first argument and expects the modified config as the return value.

Here you can see our config where we added the possibility to write less instead of css:

const less = require('rollup-plugin-less');

module.exports = {
  rollup(config) {
    config.plugins.push(
      less({
        insert: true,
        output: false,
      }),
    );
    return config;
  },
};

Add helpful GitHub workflows

For a serious library, a good set of GitHub workflows are very helpful! For example you want to execute the tests or linter on every commit or you want to have a size-limit bot commenting on your pull requests if a change leads to a big increase of your package size.

Fell free to take a look at our GitHub workflows where we setup all of this for our open source library. The configuration for the size-limit can be found in our package.json.

Publish your library

So you know have everything adjusted to your needs, had enough time to develop your library and try it out locally. You’re convinced: your library is ready to be consumed by the public! So what’s next?

During the installation process TSDX made sure to add a proper prepare script in your package.json. The prepare script is executed automatically every time you execute npm publish - so every time you want to publish a new version of your package.

And what TSDX does before publishing is creating a new TSDX build, which also makes sure the build is not failing before you publish your new version. So you basically only have to run npm publish (with the corresponding arguments you want to put, e.g. if it should be published publicly) and you’re good to go!

Summary

When we wanted to create a npm package for our product snappify I was a bit scared because I remembered all the pain points of creating such a library some years ago. I knew of react-hot-toast by Timo Lins and asked him if he had some tips to get started with creating a TypeScript npm package.

He pointed me to TSDX and I started to play around with it and got hooked pretty quickly. The default best practices are just working and as the website states: you can focus on developing your library instead of trying to figuring out the right configurations.

I want to thank the whole team behind TSDX for creating this awesome tool and take a great pain away from creating TypeScript libraries. 🎉

How my first side project made me the developer I am today

Dominik Sumer — Wed, 21 Apr 2021 13:24:20 +0000

This article was originally posted on my personal website.

It was in 2010 (at the time of writing this it’s already 11 years ago 😱) when I started my first side project in software development. I was 16 years old, still in technical high school, already a bit into programming and hungry for more.

Some days ago Felix started a thread about people’s first projects where I also answered with mine. Memories flashed back into my mind and whilst thinking more about it, I thought it could be interesting to share how this project made me the developer I am today. Let me take you with me on this journey. 🗺

I wanted to make a game, but it should be online!

Since I was a little boy I had a faible for gaming. It started with the Gameboy Color and the good old Pokemon series and continued with playing multiplayer games like World of Warcraft (which actually led me to repeat one year in school, but that’s another story 😅). So if you mix a strong interest for gaming with a dedication to learn more about programming, it was pretty clear that I wanted to build a game, a multiplayer game to be more precise.

In 2009 I played around with the RPG Maker XP. I enjoyed to create my little RPGs by clicking around in the editor and always looked up to the cool other creators who created custom scripts with Ruby. I also wanted to create more sophisticated solutions with those scripts, but couldn’t wind my head around it.

But as I learned more in school I also got a better understanding of those scripts. And I began to google how I can extend my single player RPG Maker game to a multiplayer game with a server. After quite some searching I found that the RPG Maker isn’t the right platform for multiplayer games. It was somehow possible, but people suggested to use other solutions which are built on top of „real“ client-server structures. That’s when I stumbled upon Eclipse, not the IDE, but a 2D multiplayer game engine written in VB6 (which was already quite old back then lol).

I learned the most by playing around with existing solutions

Yes you read correctly, VB6. If you research Visual Basic 6 you can see that it was first released in 1998. So it was already quite old back then, in fact so old that Microsoft killed the support for it some years later with Windows 8. So why did I even start with this? Why did I spend time on that if there could’ve been more state of the art things out there? Because it was completely open source and ready to be studied and modified to my needs.

It maybe sounds a bit stubborn that I just choose this as my first solution, but I fell in love with the possibilities it offered and even more with the fact that I could tweak it to my needs. It was such an incredible feeling when I changed something in the existing codebase and saw that my changes did what I wanted them to do. This is when the real passion for software development started to sparkle inside of me. As I am writing this I can feel again how it was back then and it also makes me aware of why I am still having such a big passion: typing in some code and seeing it actually does what I want - magic.

Whilst exploring this game engine I had so many Aha! moments. It was the first time I used something like a client-server architecture and the first time hearing the word “Socket”. I learned so many things by exploring the source code, engaging with the communities and googling different solutions for the tweaks I would like to do. I started to understand that Google is the tool I need in order to learn new things and find solutions for my problems. And I learned that you could solve almost every problem if you just search thoroughly and, more important, search with the right keywords.

Finding out what sort of game I wanted to build

I definitely spend 6-12 months with this VB6 engine. After some time I had an idea what I wanted to build: a farming game. I loved Harvest Moon and I wasn’t aware of an online game with the same gaming principles as Harvest Moon. The more I thought about it, the more I liked the idea of building a farming game where players can interact with each other.

So I explained my idea in different forums and got quite some feedback! The most engaging community was a forum called “Harvest Moon Heaven” where the people loved the idea of having a Harvest Moon like game with online functionalities. I got so many positive feedback which increased the motivation to move on with the game even more. It was also the place where I made a poll with how I should name the game and that’s when Rising Farms Online was born. ☺️

Setting up my own forum / website

The community around Rising Farms grew further. We had an own sub-forum at Harvest Moon Heaven with already quite some people engaging and it was time to create an own place for the game. I bought the risingfarms-online.com domain and installed a Woltlab Burning Board there. The Rising Farms community was born. 🥳

I also created a landing page. Back then I worked much with Photoshop. I designed the whole Website in PS and sliced the pieces into images which I then imported in my website. Good. old. times. Although the asset size and the source code of the website was terrible 😅.

Sadly the earliest version of the website I could find on Wayback Machine is from 2013, but it gives you a nice impression 😄

In 2011 we’ve built a small team around Rising Farms

The community grew further and in 2011 we even built a small team of about 6 people who handled different tasks. All of those people were volunteers who thought that Rising Farms would be a great game and offered their time and skills for free. Some of them were story tellers and built the background story of the game and its characters. Others were graphic artists who created ingame pixel art.

It was such a great feeling to work with other people on my own project, we even had weekly meetings where we discussed upcoming tasks. I learned many things at this time and even a bit of project management and team coordination.

Next Stop: C# with XNA

As the game developed further it got clear to me, that VB6 isn’t a sustainable base for Rising Farms. At the end of 2010 I already had a prototype available and some people tested it, but every time it was a huge pain to get the game running on different machines, due to different dependencies which had to be installed. And when Microsoft announced that they are going to drop the support with their next Windows version it was clear to me that I have to find another way to develop Rising Farms.

In school we played a bit with XNA, a game framework for C#, and so I thought it could be a nice framework to develop Rising Farms. I spent much time with rewriting existing logic in XNA with C#. Also the Server was rewritten in C# and at the end of 2011 I again had a new version up and running. You can get an overview about how the game looked like in that time with this Trailer on Youtube.

In the beginning of 2012 I even played around with a Web based UI inside the map editor of Rising Farms which you can see in this video. Maybe you can remember those jQuery UI Accordion elements. 😅

And then followed a long break. I was busy with finishing school and having fun with my friends.

Could Rising Farms run in the Browser?

The long break lasted until the mid of 2013. Although I made that break, I never stopped thinking about Rising Farms. I still wanted to push it further and when I finished school in June 2013, I had enough time to pick it up again.

In school I learned about HTML5. It was the new kid on the block and there were even possibilities like drawing on a canvas or even using WebGL for rendering graphics with quite a good performance. I didn’t want Rising Farms to be a typical browser game where you can just play around with data via the user interface. It should be a game where players can interact with the world and other players around them. But I thought: if that’s possible in a browser, why not?

Additionally I still had a problem with the C# client back then: bringing updates to the users. Of course there were also solutions for this out there, but I tried to write my own updater application as you know it from WoW or League of Legends. It also kinda worked but I was never 100% happy with the solution. If the game would be running in the browser, I just needed to serve the latest assets and voilà: the user is running on the latest version, no outdated clients anymore.

Let’s bet on JavaScript

So I got hooked on that idea of running the game in the browser. Therefore I needed to learn more about JavaScript, what the possibilities are and what I could do with it. Soo many new things to learn: WebGL, WebSockets, playing sounds, capturing keyboard and mouse events, studying the DOM. A whole new world opened up: the world of web development, and I loved it as much as I still do today.

I had so much fun doing all of this I can’t even express it into words right now. Back then I used Google Closure for building the client. Frameworks like React or Angular didn’t exist yet, but Closure already offered a big set of opportunities. It came with dependency injection and the possibility to write UI components, I was quite happy with it especially as I didn’t knew of anything else 😅.

For rendering the game itself I used pixi.js, a 2D rendering engine which used WebGL if the browser supported it, or even had a fallback for “normal” canvas rendering. It is a great framework and made my life so much easier, I would even recommend it today as it is still maintained!

Let’s completely bet on JavaScript

Ok, so it was clear to me: I wanted to write the client in JavaScript and it should be executable in the browser. I didn’t want to write a typical browser game but the changes which came with HTML5 gave me the possibilities to create a nice game which could be experienced in modern browsers without any drawbacks.

Now the question came up: what about the server? The VB6 and C# solutions all had the benefit that I only had to write my DTOs once and then they could be used both on the client and on the server. Initially my plan was to reuse my existing C# server where the WebSocket on the JavaScript client could connect to. Then I would either need to find a way to create JavaScript DTOs out of my C# DTOs, or just write them twice.

But then I heard about Node.js and that JavaScript can be executed on the server 😱. I thought: that could be exactly what I need. I digged more into it and also fell in love pretty quickly. Again I could reuse the same DTOs on the client and the server and also reuse some of the logic.

I had so much fun

Now followed a great time. From June 2013 to February 2014 I spent very much time with Rising Farms. School was finished and at military service (which started in September 2013) I had the luck to also have much free time I could use for developing my dream game. It wasn’t only the client and the server of the game, I even built a separate editor application where all of the game data could be managed including a fully fletched map editor.

Sorry, I don’t want to brag here. I am just re-experiencing all of this again while writing this blog post and want to emphasize what a strong passion can sparkle inside of you when you’re working on something you truly thrive for.

Additionally the community also supported me genuinely. If there are people which cheer you up and wait for the next update, it’s definitely a huge motivation boost. I remember release days where 20 people moved around in-game and played together with each other. Great times!

It ended in 2014 when I started with my first full-time job

You see, I could write endlessly about my first side project. It was the project of my dreams and I still think of it here and then. But there came a point where I had to stop developing on it. It was the time when I started to work full-time as a software developer.

Additionally me and my wife (back then we weren’t married yet) moved into our first flat and many new responsibilities popped up why I had to stop the development of Rising Farms. Actually the real “stop” was 1-2 years afterwards, because before I could never really finish with it completely. I did refactorings, e.g. from JavaScript to CoffeScript - never finished. Then from JavaScript to TypeScript, moving away from Google Closure and using React as UserInterface - never finished. And at a specific time I just had to put it to an end. But to be honest I didn’t completely finish with it until today, as the domains and server, including the website, forum and the game itself are still running. And I think I still can’t shut it off completely because maybe … someday … I have time again - I don’t know. 😅

But even if I never ever find time for it, or instead move on with another, similar project, it’s cool that the website is still online and I can refer to it.

Summary

Ooh this was a nice journey through the past, thanks for reading it until the end as this story means very much to me. While writing this blog post I again got aware of how many things I learned in that time and how it really made me the developer I am today. I am so grateful for that time and that I found my passion with this project. In the end, it led me to web development which I still love doing today.

So I can’t stress this enough: if you have a passion for something, just get started with it and you will get better and better. Everyone is different. Some learn better with audio, some with visuals. For me I just learn the most by doing. By experimenting with existing things, look at them from different angles and try to understand how they work. And if you additionally can create something you’re also connected with, beautiful things emerge.

Currently I am experiencing such a thrive again. I am pursuing my dream of creating a product which brings great value to its users and is financially profitable so that me and my family can live from it. I do this together with my friend Anki and we are active in the makers community of Twitter, which is so helpful and inspiring - feel free to join us there! 🙌

The tech stack of our first SaaS and what we regret

Dominik Sumer — Wed, 31 Mar 2021 20:01:41 +0000

This article was originally posted on my personal website.

It was in March 2020 when Anki and I decided to tackle a new project together. After years of abandoning projects in our free time, we were dedicated to spend some time and get this done. I won’t dive deep into this journey, as we‘ve already described it in this blog post if you’re interested. 😄

But we did it: we created a new SaaS which is called TrueQ and also managed to deploy it productively. In this blog post I want to talk about the tech stack we used, decisions we made and what we regret or would do differently nowadays.

Our Background

Let me tell you a bit about our background in software development. We’re both professional software developers being specialized in web development. In general we’re doing full stack development, although we may have more experience in the frontend. But as we strive to work more on our own products in the future, we definitely have a strong passion to build a product in whole.

Before choosing the tech stack in detail, it was clear to us that it will be located in the JavaScript ecosystem, or to be more specific, the TypeScript ecosystem. In our jobs we also worked on different backend applications which were written in Java / Kotlin or C#. But our main experience lies in Node.js. Additionally we are building React Applications since almost 6 years, so this is definitely the frontend framework of our choice (and also will be for future projects).

Requirements for our product

We knew that for our product SEO is essential. TrueQ is all about finding solutions to your day-to-day problems. So these solutions have to be found easily. Therefore we knew that even though we want to build a rich web application, our server still needs to serve the content of our pages in plain HTML to make search engine’s life easier - server side rendering was a requirement for us.

We read about Max Stoibers regrets when he built spectrum, and we were sure that we don’t want to implement SSR on our own. 😅 As we were following Vercel and the development of Next.js, it was the first thing we took a closer look at.

Additionally there was an excellent blog post released at the time we started our project. Loup Topalian wrote about frameworks and libraries he would use to build a webapp in 2020 and in the end we actually adopted most of them.

Next.js

Ok lets begin with the foundation of TrueQ: Next.js. It is a production-ready React framework developed by Vercel and they’re not stopping at the client-side. With Next.js it is possible to write a fully fletched universal webapp which also takes care of server side rendering and other amazing stuff like incremental static site generation.

Very soon it was clear to us that we want to go with Next.js as it perfectly fits our needs. But now the question popped up: how should our backend look like? How should the API be connected with the Next.js application?

We definitely don’t regret the decision of using Next.js. It is a great framework and in the last year we used it, there were major improvements without any bigger breaking changes - Vercel is doing a great job here.

Just our solution of how we connected the backend to Next.js and the decision to host it on a private vServer and deploy it via Ansible wasn’t the best choice for us.

Using a custom Express.js server

So we dived deeper into the topic of how Next.js works and learned from the official docs that there is the possibility to use a custom Express.js server with Next.js where you have the whole freedom of leveraging the power as you would write a standalone Express.js application. It just wraps around Next.js so that you can specify own routes and implement all other sorts of logic with Express.js and all other routes are handled normally by Next.js.

It seemed like the best decision back then. We could move quickly, using a technology we already were familiar with and didn’t have to spin up a separate service for our backend. But for us there are some big cons to this approach which led us to the decision that we wouldn’t go this way anymore in the future.

Cons of the custom Express.js server

With Next.js we were used to fast HMR which allowed us to develop quickly. We also wanted our backend to reload automatically when we do changes to our code so we used nodemon together with ts-node (because all the backend code is written in TypeScript too). The problem here: it wasn't fast anymore. Everytime we changed code in the backend the whole Express.js server rebooted and it took quite a while until it was running again. This also influenced some parts of our frontend, as it included shared files which were also detected by nodemon. We couldn't find a solution for this and it's actually pretty cumbersome.

Additionally you're not able to deploy your Next.js application to Vercel anymore as they only provide deployments for plain Next.js applications. This also led us to custom deployment with Docker + Ansible on a vServer hosted by netcup which we’re going into detail in a later section.

Session handling and authentication

Nevertheless it is how TrueQ is currently built. That means that the session handling and authentication is also completely handled by Express.js. For authentication we use Passport.js which handles our normal E-Mail & Password login, but also third party logins via Google, GitHub and Twitter.

In production we're using a Redis server to persist the sessions (which also keeps them alive after the deployment of new versions).

GraphQL with Apollo

Until then we were used to write REST APIs. We already heard about GraphQL here and then, but never got in touch with it. We got curious and got our hands dirty to spin up an API and see how we like it.

We actually got hooked pretty fast. We love the flexibility to reuse DTOs, but at the same time only serve the fields you need for a specific usecase / view.

We're using Apollo both on the backend as server, but also on the frontend to query the API. Additionally we use graphql-codegen to generate TypeScript models of our DTOs and the React hooks for Apollo. We're very happy with that setup.

Problem with calling the API logic directly when rendering on the serverside

Now that we had an API in place we also needed to make sure that it's callable isomorphically. It should be reachable via the browser, when the Next.js application is in "SPA mode", but also on the server side when the HTML is being built for the first render.

For the browser it is pretty straight forward. It just calls the /api/graphql endpoint to execute queries and mutations. But on the serverside we thought that we somehow directly could execute the Apollo server logic. We didn't managed to get it running like this and that's why we need to do a seperate network request to https://localhost:3000/api/graphql on the serverside, to also be able to make API calls there.

All of this is wrapped in an Helper HoC which takes care of making the API calls isomorphic. Here's the code snippet of how we create the isomorphic Apollo link:

function createIsomorphLink(ctx) {
  if (ctx) {
    const { HttpLink } = require('@apollo/client'); // eslint-disable-line @typescript-eslint/no-var-requires
    // TODO: we need to look into this, as with this we are still doing a network request to our own application, but with apollo-link-schema we don't have our context available on the serverside
    return new HttpLink({
      uri: 'http://localhost:3000/api/graphql',
      credentials: 'same-origin',
      fetch,
      headers: ctx.req && {
        cookie: ctx.req.header('Cookie'),
      },
    });
  } else {
    const { HttpLink } = require('@apollo/client'); // eslint-disable-line @typescript-eslint/no-var-requires
    return new HttpLink({
      uri: '/api/graphql',
      credentials: 'same-origin',
      fetch,
    });
  }
}

Knex.js + Objection.js in connection with Postgres

So we had our API running and implemented the first CRUD operations. But where should the data be stored and be retrieved from? 😄

As I said we already had some experience with Node.js applications back then, but we mostly worked with MongoDB + mongoose for accessing the database. In the last years being employed as software developer we enjoyed to work with relational databases and also thought that it would be a better fit for TrueQ. So we decided for PostgreSQL and searched for solutions how we could easily query our DB.

Pretty soon we stumbled upon Knex.js, a SQL query builder for Node.js. It takes care of the db connection (it also has support for pooling) and gives you the possibility to write SQL queries with a query builder pattern like this:

knex.select('title', 'author', 'year').from('books');

Objection.js

Knex.js even has support for strong typing with TypeScript, but during our research we found Objection.js, an ORM which is built on top of Knex.js.

It gives you the possibility to write Models and execute queries against them with type checking of all the available fields, we're actually pretty happy with it and back then we didn't know of a better solution for handling database access.

Here you can see an example how a model plus a very simple query looks like. For more informations checkout their documentation.

import { Model } from 'objection';

class Topic extends Model {
  id!: number;
  name!: string;

  static tableName = 'topic';
}

const topic = await Topic.query().findOne({ name });

console.log(topic.name);
console.log(topic instanceof Topic); // --> true

Running migrations and seeds

Now when you're running an application productively there are also going to be database changes over the time. Therefore we also needed a solution to create migrations and run them in production.

Luckily Knex.js also got us covered with this one. 🥳 In Knex.js each migration is a JavaScript file which exports an up and a down method to either execute the migration or roll it back. Before deploying a new version of TrueQ we just make sure to execute the latest migrations with the knex migrate:latest command.

Here is an example of the migration of our question table:

exports.up = function (knex) {
  return knex.schema.createTable('question', function (table) {
    table.increments('id').primary();
    table.integer('user_id').notNullable().references('id').inTable('trueq_user');
    table.integer('views').defaultTo(0).notNullable();
    table.timestamp('deleted_at');
  });
};

exports.down = function (knex) {
  return knex.schema.dropTable('question');
};

Additionally Knex also supports Seeds for applying test data in your local environment.

Look out for Prisma

As already mentioned we actually were pretty happy with the Knex.js + Objection.js solution, but in the meanwhile we also found out about Prima. As it recently gained stable support for migrations we really consider to use it in our future applications, as it seems even more straight forward and better maintained.

Our Frontend

After showing you the architecture of our backend, let's take a look at our frontend. As already mentioned we love React, we're writing React applications for a long time already and it is the frontend framework of our choice. Not sure if this still has to be mentioned for React projects created in 2020, but just to cover it: we only make use of functional components together with hooks 😄

But as you might know, in the world of React you can pull in different libraries to solve things like routing or state management in your webapp, there are also some more things to talk about here.

State Management

So we're using Apollo on the client side for fetching data from our GraphQL API. Apollo has a powerful caching mechanism built in which stores the results from your query and it also lets you update this cache manually for optimistic updates. That means for many cases the data is just stored in the Apollo cache.

Additionally we also have quite some local logic, e.g. for our custom built editor. In those cases we're using MobX as a state management library. We love the simplicity which MobX gives you when defining state somewhere in your component tree, but at the same time taking care of only rerendering affected components down the path. It creates performant webapps by purpose.

Maybe I am doing a more in-depth blog post about MobX in the future.

ChakraUI

Of course we also needed a UI library, because we didn't want to write all sort of components on our own. Thanks to the above mentioned blog post we stumbled upon ChakraUI, an accessible and modular UI library for React.

For us ChakraUI is a bit different than other UI libraries. It simplified the way how we develop in the frontend and imho it complements the skills most web developers built up in the last years, which I describe more in detail with this blog post.

Deployment

In the summer of 2020 we came to the point that we already had quite a big part of TrueQ up and running. So we thought about how and where we're going to deploy our newly created webapp.

Due to the custom Express.js app, Vercel wasn't an option straight from the beginning. Back then we absolutely had no knowledge about services like AWS or DigitalOcean. I just had my own vServer running for the Browsergame I developed several years ago. That's why I thought it would be the best idea to also host TrueQ on our own vServer.

Docker

So when we're building TrueQ to deploy it to our test or production environment, we're creating a docker container including the Next.js build output and all necessary files. This docker image is then pushed to our container registry on GitLab.

Ansible

As we said we're deploying everything on a vServer on our own. That includes installing all necessary dependencies on the Linux server, configuring NGINX as our webserver, setting up SSL certificates, setting up the database, ensuring backups, and so on.

Because we didn’t just want to set this up by hand, we chose Ansible as our operator here. With Ansible you can create playbooks which get executed step by step as an automated way to setup your server. You just tell Ansible what to do in it's own DSL written in yaml files. That means that if for whatever reason we need to setup a new server, we just need to execute the Ansible playbook there and the Server would be up and running with TrueQ.

With Ansible it's also much simpler to keep track of the changes you're doing on your server, as all of the playbook files are also versioned via git.

In retrospective we learned very much about this whole process. But one thing we definitely learned is that we don't want to do this stuff on our own anymore. 😅 More about this in the last section of this blog post.

Analytics with the ELK stack

For the analytics we're using the ELK stack also hosted on those vServers. We're collecting logs via filebeat and metrics with metricbeat. Additionally we're having the Kibana APM in place to get even more insights from our Node.js backend application.

Also this was a very interesting step, but again too much hassle to maintain this on our own.

GitLab CI/CD

The process of building a docker image and deploying it with Ansible is all encapsulated in mostly automated steps via our GitLab pipelines.

Everytime we’re merging changes into the master branch, our whole test suite is being executed and if everything succeeds, a new version of TrueQ is being built (the Docker image) und pushed to the image registry on GitLab.

Every night we’re deploying the latest version of our Docker image to our test environment automatically and additionally there is a separate schedule for deploying the latest version to production which can only be executed manually.

During this deployment, we’re executing an Ansible role, which connects to the Server, pulls the latest Docker image there and spins it up.

Here you can see the GitLab stage configuration for deploying trueq:

deploy_trueq:
  stage: deploy_trueq
  script:
    - ansible --version
    - echo $ANSIBLE_VAULT_PASS >> .vault-pass
    - ansible-playbook -i "inventory/$ANSIBLE_INVENTORY" main.yml --tags=trueq --vault-password-file=.vault-pass
    - rm .vault-pass
  only:
    variables:
      - $ANSIBLE_INVENTORY != null
      - $DEPLOY_TRUEQ == "true"

Test Setup

So we now covered the stack we used for developing TrueQ and also how we're deploying it. Now comes a topic which we actually began with pretty soon: writing tests.

TDD is an acronym (standing for Test Driven Development) we heard pretty often in our career before, but never did it by our own. We wanted to give it a try, at least for our backend, and boy was this a good idea. 😄 Every time we began with new features, we created test cases for all the requirements and edge cases we could think of in Jest. And before writing the actual implementation we started to write the failing tests including the assertions of how things should work. After the implementation was done those test should get executed successfully.

It saved us many possible bugs and currently about 80% of our APIs are covered with tests (mostly integration tests) which give us the confidence for larger refactorings and other future changes. The Testing Javascript course by Kent C. Dodds definitely was a huge help with creating our test setup and learning some unknown things about Jest.

In the future we also consider using cypress for e2e tests to gain even more confidence.

What would you do differently nowadays?

Let’s come to an end. And in the end it’s always time for the most interesting question which probably is: what would we do differently in future products?

As already explained in the previous sections the top things we’re complaining about are:

the custom Express.js server for Next.js
the deployment which we don’t want to handle on our own anymore
maybe using Prism instead of Knex.js or another solution for accessing the database

To be honest we’re not completely sure how our future tech stack is going to look like exactly.

For the frontend we’re already very happy and definitely going to stay with React, Next.js and Chakra. Maybe we’re going to switch the Apollo client with React Query.

In the backend there will probably be more changes and depending on what we go with, it will also affect database access and hosting. We’re looking closely at Blitz.js and Supabase and consider deploying on AWS, Vercel, DigitalOcean or Render.

We're very glad that the first MVP of our new product snappify comes with barely any backend logic and is completely hosted on Vercel, but soon we need a more sophisticated solution and I am going to inform you how our updated tech stack looks like as soon as we’ve settled. ✌️

How and why to start blogging

Dominik Sumer — Tue, 16 Feb 2021 18:17:03 +0000

This article was originally posted on my personal website.

Actually I had the plan that this will be the first blog post on my newly launched website. But then I thought it’s maybe a bit ironic, that my first blogpost after years of not-blogging, would be about how to start blogging. 😅
Nevertheless, before starting to blog again I thought a lot about the topic and want to share with you my findings on how to start blogging, why to do it and what to consider when doing so.

Did you ever take a seat and just write down your thoughts about a topic? It can really pull you in. You create your own little story around it and create something unique which will additionally help a lot of other people.

🧐 Pick a topic which you’re passionate about

So you want to start with a blog, but don’t know which topic(s) you should write about? For me it works the best to choose a topic which I have a great passion for.

If you choose a topic just because it is trending and you want to achieve many clicks for it, it probably won’t work because your interest in this topic won’t be high and therefore your motivation to write a good blog post about it will fluctuate. (at least in the long run)

So in my example, most of the time I am going to be blogging about software development, or to be more specific: web development, because this is where my passion lies in. I also want to share more about my journey and build / learn in public.

Think about what bothers you the most or where you recently put much brain-power into. Then write your little story about it and share it!

📝 Create drafts

A great tip for gathering ideas for new blog posts is to create drafts (or just write down a few words) immediately after you experienced something.

When it comes to programming, for me it’s often like this: I stumble about a problem and deliberately search for a solution, but as soon as I’ve got the solution, I just move on with the next task and forget about the problem pretty fast. What if you put the „sharing“ as part of your problem solving? Your problem is only really solved if you write down some words about it and save it as a draft. And sometimes later, you might add some more content to it and write a blog post.

But actually this could be applied to every daily activity. You experience something new? Write down a draft or only some words and later work out a more detailed blog post from it.

🤔 Is this really shareable?

Now you have chosen a topic which fits perfectly but you ask yourself: is this really shareable? Does someone even benefit from my blog post or don't there already exist several blog posts about it?

Long story short: someone will definitely benefit from your blog posts. There might be similar blog posts to the same topic, but your findings, your writing style and how you describe it is unique. There is definitely someone out there who is currently in the same process as you were before writing your blog post and would be really thankful for it.

So whenever you’ve achieved something and your mind tells you: "mhh this can be done by anyone, I am sure no one would benefit from it", then give your mind a kick and jump into the cold water! You'll also gain many benefits by doing so. 🙂

🌱 Why should I share my knowledge?

You have a topic and know it is shareable, but what benefits do you have from sharing it? Why give some of your knowledge to the public for free? Lets look at all the benefits blogging brings us.

1. Improve your writing skills

Having good writing skills can help you in many areas. May it be to write professional emails, describe yourself in a resumé or when writing documentation.

If you start blogging and writing down your thoughts about your experiences, you will see that those writing skills will greatly improve and that it will get easier over time.

2. Gain an even deeper knowledge about the topic

Writing down your thoughts will strengthen your knowledge!

By formulating your achievement into words and creating a small story around it you will remember it better in the future. And if you publish it as a blog post you can refer to it in conversations.

3. Make yourself more visible

If your blog is publicly available it will make yourself more visible. Don't underestimate the power of this fact. By sharing your knowledge in a specific area you will gain credibility in this field and will also make new connections which could bring up opportunities you never would've thought of.

I guess there are even many more benefits when it comes to blogging, which I didn't list above. So be sure that writing and publishing blog posts isn't just a waste of time.

☕️ Motivate yourself for writing

Ok so now comes the time where you say: I see the benefits, I have a topic, but I don’t want to write something.
I must admit, you probably need to have fun with writing up some content. Otherwise it won’t be a sustainable thing you do over a longer period of time. But have you ever tried it?

Did you ever take a seat and just write down your thoughts about a topic? It can really pull you in. You create your own little story around it and create something unique which will additionally help a lot of other people.

If writing content is not already a big part of your daily job it can really be relaxing to just take some time, let your thoughts flow and write them down. Our society is built up to rush from one stressy moment into the other. Calming down, really think of what you've experienced and form it into words is a great way to spend your time.

I would suggest to just try it out and see if you like it.

💻 Which technologies should I use to create my blog?

Of course you also need a place for your blog. There are already well-known and stable platforms like wordpress.com, dev.to, hashnode.dev or medium.com which you can use to create outstanding blog posts.

If you are a web developer, you probably also play with the thought to just creating your own blog with the technologies you're familiar with.

In the end you should choose the solution which you're feeling most comfortable with. I had fun creating my new website + blog from scratch, but it can also be overwhelming when you want to create the perfect experience before starting to blog.

🙌 Don’t overthink it

Ok now comes probably the most important tip:
Don't. Overthink. It.

The biggest enemy of your blogging journey is your mind. When you again start to overthink, when you want to be prepared for every situation, want to do everything right in the beginning, it can end with demotivation pretty fast.

To avoid this, I found it helpful to have a checklist which kept only the things that are essential for my blog before launching it (and some gimmicks I had fun implementing). Additionally I made a seperate list with things I want to have implemented for my blog in the long run.

But before showing you this checklist for my individual example, I want to mention that what I consider a must have, doesn’t need to be a must have for you. Only put things on your checklist which you think are necessary to have done upfront. The other stuff can also be done over time when you’ve already started your blogging journey. Don’t let any bureaucracies demotivate you.

Must haves

Setup Analytics for better insights about visitors
Make sure to set a canonical url
Setup Google search console
Create a sitemap.xml to be crawled by Google
Newsletter and author section at the bottom of every blog post
Configure open graph tags properly
Create a nice open graph image
Nice design for code snippets

Nice to haves

Setup an email subscription list with ConvertKit
Provide a RSS feed
Add Share Buttons
Progress bar while scrolling
Copy functionality for code snippets
Maybe integrate with a CMS for better handling - still unsure about this

🤠 Get inspirations from other blogs

While working on something new, it’s always good to look at other people in the field and see how they are doing it. It doesn't matter if you're now building the blog on your own or if you use a familiar platform: you can get great inspirations for your blog by looking on other blogs out there.

I don't mean you should copy and paste from another blog, just get yourself some inspirations to begin with. Over the time your blog will develop further and get your own touch.

Here are some blogs I really like and took inspirations from:

phiilu.com - Florian's blog has smooth page transitions, all features you need for a blog and at the same time very informative posts 🤩
rhnmht30.dev - I love the sleek design of Rohan's blog and wanted to keep the design of mine as simple as his 🙂
danielwirtz.com - I also like the clean design of Daniel's blog and took that as an inspiration for my blog ✌️
samuelkraft.com - Recently I stumbled upon Samuel's blog. It's neatly crafted by hand and his blog posts are awesome too! 🔥

📖 Great resources with tips and tricks

It's time to come to an end with this blog post. Hopefully some of those tips helped you to start with your blogging journey. You can also send me your blogs, I am excited to see them - my Twitter DMs are open.

Last but not least I want to share some great resources which helped me while starting to blog:

The free Blogging for devs newsletter by @monicalent
A great blog post about Learn in public by @swyx
Browsing through Twitter's #learninpublic or #buildinpublic hashtags to find some inspiring blogs

A guide to make your Stripe Checkout EU VAT compliant

Dominik Sumer — Sun, 31 Jan 2021 16:44:58 +0000

As Stripe released their new Tax feature, this blog post is probably deprecated for most of us. Checkout Stripe Tax to make your life a lot easier. :)

This article was originally posted on my personal website.

You’re located in the EU, want to bring your SaaS (or any other digital product) to customers over the whole world and are not sure what you exactly need to do? You’re implementing the payment process with Stripe Checkout but don’t know what exactly needs to be done in order to be EU VAT compliant? I’ve gone through the same and with this blog post I want to give you a step-by-step guide to make your Stripe payment process EU VAT compliant.

I want to state that I am no accountant, financial advisor or anything like that. I can’t guarantee to keep this information up-to-date or that it really applies to your specific situation in your country. Please check back with your accountant before going live with a payment process to be sure everything works as expected and you don’t need to worry about illegal activities or large payments to the tax office.

What is the EU VAT

The term VAT stands for Value Added Tax which is applied to basically all goods and services that are bought and sold for use or consumption in the European Union. So it also applies to digital productions and you have to ensure to correctly collect and pay the VAT. Every EU country has its own VAT percentage and you can find them here.

When and how much VAT do you need to collect

I assume you have a business registered in the EU and you want to sell your product to customers all over the world. There are four different scenarios depending on your country, the country of the customer and if you sell to a business or private customer.

1. Selling to customers outside the EU 🪶

If your customer is located outside the EU, independent if it’s a business or private customer, no VAT has to be charged.

2. Selling to customers in your home country 🤝

If your customer is located in your home country, you have to charge the corresponding VAT percentage of your home country and pay it to the tax office.

3. Selling to EU businesses outside your home country ✌️

If it is a business customer located outside your home country you don’t have to collect a VAT, as reverse charge applies.

But you definitely have to make sure to collect the VAT number of the business and its billing address. You also have to validate the VAT number and ensure that the business is valid and really exists.

4. Selling to private EU customers outside your home country 🤔

Last and least, the most cumbersome case. For private EU customers outside your home country you have to collect the corresponding VAT of the customers country. You also need to pay it to the corresponding tax office.

You also need to save/verify the location of the customer with the billing and IP address for future proof.

Hint: it can be easier based on your yearly turnover with MOSS. But I didn’t dive into this topic.

Stripe Checkout

Ok now that we covered the different cases, let’s move on with the Stripe Integration and make sure to handle everything correctly in our Stripe Checkout Session.

Prerequisites

I assume you already have the Stripe Checkout set up correctly as I won't go through the process itself in detail. If not I can recommend the official guide directly from the Stripe Docs.

Manage a list of countries

As I am currently writing this blog post, Stripe doesn’t automatically take care of managing available countries and their VAT percentage. So you have to do it on your own.

As list of countries I can recommend you this public json file which includes basically all countries over the world. Then you can extend all the EU countries with two fields: isEU and vatPercentage, which tells us that the country is a member of the EU and how much the corresponding VAT percentage is.

Here an example list:

export const COUNTRIES = [
  { name: 'United States', code: 'US' },
  ...
  // WARNING these values are not being maintained
  { name: 'Austria', code: 'AT', isEU: true, vatPercentage: 20 },
  { name: 'Belgium', code: 'BE', isEU: true, vatPercentage: 21 },
  { name: 'Bulgaria', code: 'BG', isEU: true, vatPercentage: 20 },
  { name: 'Croatia', code: 'HR', isEU: true, vatPercentage: 25 },
  { name: 'Cyprus', code: 'CY', isEU: true, vatPercentage: 19 },
  ...
];

Update the VAT taxes via the Stripe API

As we now have a list of all EU countries and their corresponding VAT percentage, we need to keep them up-to-date in our Stripe account. Stripe doesn't take care of managing those values, we have to do it on our own and the most straight forward way to do this is via the Stripe Tax Rates API.

Before I show you the logic I'm using for keeping those taxes up-to-date I want to explain the process a bit. Basically I store all EU tax rate in a table in the DB of my application. The DB Model looks like this:

import { Model } from 'objection';

export default class TaxRateModel extends Model {
  countryCode!: string;
  stripeId!: string;
  vatPercentage!: number;

  static tableName = 'tax_rate';

  static get idColumn() {
    return 'countryCode';
  }
}

So when my application boots up, I am looping through all EU countries from the list, and if they don't exist, I send them to Stripe via the API and save them in the DB. If they already exist in the DB, I know that I've already sent them to Stripe and just check if the VAT percentage differs. If it differs, I tell Stripe that the old Tax Rate is deprecated and create a new one. (Updating the VAT percentage is not possible, to keep history of older payments intact)

With this we can use the country list to manage the VAT percentages of all EU countries and keep them automatically updated in Stripe. 🎉

export async function createOrUpdateVatTaxRates() {
  const EU_COUNTRIES = COUNTRIES.filter((c) => !!c.isEU);
  for (const country of EU_COUNTRIES) {
    const existingTaxRate = await TaxRateModel.query().findOne({ countryCode: country.code });
    // we only move on if no taxRate exists yet in our DB or the vatPercentage differs
    if (!existingTaxRate || existingTaxRate.vatPercentage !== country.vatPercentage) {
      getLogger().info({}, 'TaxRate changed for country: ' + country.code);

      // either way we're creating a new taxRate via the Stripe API
      const taxRate = await stripe.taxRates.create({
        display_name: 'VAT ' + country.name,
        inclusive: false,
        percentage: country.vatPercentage,
      });

      if (existingTaxRate) {
        // if there is already an existing tax rate, we set the old one to inactive via the Stripe API
        await stripe.taxRates.update(existingTaxRate.stripeId, { active: false });
        // and we update the tax rate in our DB with the new vatPercentage and stripeId
        await existingTaxRate.$query().patch({ stripeId: taxRate.id, vatPercentage: country.vatPercentage });
      } else {
        await TaxRateModel.query()
          .insert({
            countryCode: country.code,
            stripeId: taxRate.id,
            vatPercentage: country.vatPercentage,
          })
          .returning('*');
      }
    }
  }
}

Collect the customers billing address

Now that we have all tax rates available in Stripe, let's move on with the first step in our payment process to ensure we charge the correct VAT rate.

The form I am using to collect the customers billing address looks like this:

Here we collect all necessary data in order to check if the user is

located in our home country
located in the EU
is a business customer or not (and collect the VAT number of the company)

So before we start the Stripe Checkout session, we upsert the customer via the Stripe API and can already tell if the customer has to pay the VAT normally, if reverse charge applies or if we don't have to charge any VAT, because the customer is not located in the EU. Here is the corresponding code for upserting the customer:

function mapUserToStripeCustomer(user: UserModel, isEUCustomer: boolean): Stripe.CustomerUpdateParams {
  // our business is located in Austria, so we have to check if the customer is also from Austria
  const HOME_COUNTRY_CODE = 'AT';
  let taxExempt: Stripe.CustomerUpdateParams.TaxExempt;
  if (isEUCustomer) {
    if (user.billingVatNumber && user.billingCountryCode !== HOME_COUNTRY_CODE) {
      // if it is a country in the EU and not from austria, reverse charge applies
      taxExempt = 'reverse';
    } else {
      // b2c in EU or business from our home country, VAT applies normally
      taxExempt = 'none';
    }
  } else {
    // customer from outside the EU, no VAT applies
    taxExempt = 'exempt';
  }

  return {
    email: user.billingEmail,
    name: user.billingName,
    address: {
      city: user.billingCity,
      country: user.billingCountryCode,
      line1: user.billingStreet,
      postal_code: user.billingZip,
    },
    tax_exempt: taxExempt,
  };
}

export async function upsertStripeCustomer(user: UserModel, updatedVatNumber: boolean) {
  const userCountry = COUNTRIES.find((c) => c.code === user.billingCountryCode);
  const isEUCustomer = !!userCountry?.isEU;
  const baseData = mapUserToStripeCustomer(user, isEUCustomer);

  if (user.stripeCustomerId) {
    // if our user is already existing in Stripe, we update his record

    if (isEUCustomer && updatedVatNumber && user.billingVatNumber) {
      // we create a new tax id (VAT number) for the customer if he changed it
      await stripe.customers.createTaxId(user.stripeCustomerId, { type: 'eu_vat', value: user.billingVatNumber });
    }

    // update the record via the Stripe API
    await stripe.customers.update(user.stripeCustomerId, baseData);

    return user.stripeCustomerId;
  } else {
    // create a new customer record via the Stripe API
    const customer = await stripe.customers.create({
      ...baseData,
      tax_id_data:
        isEUCustomer && user.billingVatNumber ? [{ type: 'eu_vat', value: user.billingVatNumber }] : undefined,
      metadata: {
        trueqId: user.id,
      },
    });

    // assign the stripeCustomerId to our user
    const success = (await user.$query().patch({ stripeCustomerId: customer.id })) > 0;
    if (!success) {
      throw new Error(`Error updating the stripe customer id (${customer.id}) of the user with id ${user.id}`);
    }

    return customer.id;
  }
}

As you can see we're also telling Stripe the VAT number of the customer. Stripe will automatically check if the VAT number is in a correct format, if not it will immediately throw an error with the code tax_id_invalid.

Stripe will also check in the background, if it is a valid VAT number (or if e.g. the company doesn't exist anymore). You will receive an event from stripe called customer.tax_id.updated so you can manually check if your customer has provided a valid VAT number and if it matches his billing address.

Be aware! Stripe only validates the VAT number initially. If you have recurring payments you actually need to check on your own if the VAT number is still valid for future invoices.

Pass the correct tax rate to the Stripe Checkout Session

As we have the billing data collected from our customer and told Stripe about the tax situation of the customer, let's move on with the creation of the Stripe Checkout session and specify which VAT rate the customer has to pay.

For this we only need to get the country of the customers billing address, fetch the corresponding tax rate from our database and get its Stripe ID. This can then be passed to the Stripe Checkout API Call and everything should work as expected. 🥳

Hint: you don't have to check if the customer is a business customer, because we set the tax_exempt property of the customer to reverse, so Stripe makes sure that he isn't charged with VAT

export async function createStripeCheckoutSession(stripePriceId: string, user: UserModel) {
  const userCountry = COUNTRIES.find((c) => c.code === user.billingCountryCode);
  const isEUCustomer = !!userCountry.isEU;
  let taxRate: TaxRateModel;
  if (isEUCustomer) {
    taxRate = await TaxRateModel.query().findOne({ countryCode: userCountry.code });
  }

  try {
    const session = await stripe.checkout.sessions.create({
      mode: 'subscription',
      customer: user.stripeCustomerId,
      payment_method_types: ['card'],
      line_items: [
        {
          price: stripePriceId,
          quantity: 1,
          // here we pass the VAT rate if one applies
          tax_rates: taxRate ? [taxRate.stripeId] : undefined,
        },
      ],
      allow_promotion_codes: true,
      success_url: `${applicationUrl}stripe/success?session_id={CHECKOUT_SESSION_ID}`,
      cancel_url: `${applicationUrl}profile/${user.userName}/billing`,
    });

    return session.id;
  } catch (e) {
    throw new Error(e.message);
  }
}

When the customer proceeds to the Stripe Checkout (and is going to be charged with VAT), he will already see how much VAT is going to be charged.

The invoices you're obtaining from Stripe will now of course also contain the corresponding VAT you've charged.

Summary

We're finished! 🎉

Let's recap what we've done:

managing a list of EU countries and there VAT percentage
make sure to keep the Tax Rates up-to-date via the Stripe API
collect the billing address of the customer, validate the VAT number of a company and tell Stripe if VAT, reverse charge or nothing should be applied
pass the correct tax rate to the Stripe Checkout API

What you still should take care of:

check if the VAT number of a company is valid and matches with the billing address
verify the VAT number also for recurring payments

I hope you enjoyed this guide and you could get some helpful insights!

I've spent some time over the last weeks to get more insights into Stripe which aren't covered in this blog post. If you have any further questions, I am happy to help out. I would suggest to ask a question in the corresponding section of our developer community TrueQ, where I'm subscribed and get notified about new questions. ✌️

Stripe is working on an easier solution

The Stripe support team contacted me and said that they're working on a better solution for this. Chances are high that they calculate the taxes based on our home country and we don't have to do this on our own anymore.

I am excited and looking forward to future changes by Stripe, until then I hope some of you can find some value in this blog post.

How ChakraUI complements your existing web development skills

Dominik Sumer — Sun, 10 Jan 2021 18:44:00 +0000

This article was originally posted on my personal website.

Over the last years many different React component libraries got released. For example Ant Design, React Bootstrap, MaterialUI. They all battle-powered us with components we‘ve needed in day-to-day UI development, but none of them changed the way I develop as ChakraUI did.

Chakra brings new paradigms on the plate and at the same time complements the skills you've built up over the last 10 years as a web developer.

CSS as you know it

Do you know CSS? Oh well, then you already know how to develop with ChakraUI. When you’re styling components you’re able to style them with props which map 1:1 to existing CSS properties as you know them.

import { Box } from '@chakra-ui/react';

const YourComponent = () => (
  <Box padding={2} border="1px solid black">
    Hello World!
  </Box>
);

As you’re applying those properties to your components, ChakraUI takes care of generating CSS classes containing those styles. Chakra provides you different components and you're able to apply those styles to basically all of them. Of course some are restricted to specific types (e.g. flexbox properties to the Flex component).

In addition to all known CSS properties, ChakraUI gives you some abbreviations which map to CSS properties in order to increase readability of your code (as soon as you know what they stand for). For example w maps to width, m maps to margin, pos maps to position and so on. Have a look at the list of all available style props in Chakra.

Approachable CSS-in-JS

To be honest I never felt comfortable with existing CSS-in-JS solutions and always ended writing less files which held the styles for the corresponding components. I don't think that it's only the fault of those solutions as I also was lazy diving deep into them and seeing the benefits. Nevertheless: Chakra changed this.

With it’s composable nature it’s a breeze to either just style single elements in your component, or creating new components which extend the styles of another one. Your freedom is endless.

Pseudo Styling

Ok now you maybe think: what's with pseudo styles? You want to style the hover or focused state of your desired element, so what? Chakra of course also backs you up on this one.

<Box _hover={{ bg: 'red.500' }}>Hello World!</Box>

With properties like _hover or _focus you can style the corresponding state with the above described styling props. The documentation for pseudo styles can be found here.

In addition Chakra even provides you basic features for using pseudo styling in the case of grouped elements. It doesn't cover all usecases (e.g. nested groups) but is a great companion most of the time and keeps your code clean and simple.

<Box role="group">
  <Box _hover={{ fontWeight: 'semibold' }} _groupHover={{ color: 'tomato' }}></Box>
</Box>

Responsive Styles

In the past years the "mobile first" approach got a lot of attentation. Legitimately as many users are surfing the web with different device sizes. So how does Chakra helps us with this?

<Box m={{ base: 2, sm: 4, md: 6, lg: 8 }}>Hello World!</Box>

On most of the styling props you're able to specify values for different device sizes. Chakra also follows the mobe first approach, because the style for the smallest specified breakpoint will also apply to all breakpoints above.

Chakra comes with its default defined breakpoints, but you can adjust them to fulfill your needs.

As a shorthand method, you can also pass it as an array with ascending values. This may reduce code, but also can decrease readablity and removes the possibility to leave out breakpoints in between. Here is the same code as above, written with the shorthand method:

<Box m={[2, 4, 6, 8]}>Hello World!</Box>

Flexible Theming

As we've just talked about adjusted breakpoints, let's also talk about adjusting other stuff. Every component library has the problem, that as it grows in popularity, it's design gets worn out. I guess everyone of us remembers when every third webapp had the standard bootstrap look. Luckily you can adjust the look and feel of Chakra heavily with it's flexible theming approach.

Here is the code snippet how I am adjusting the default Chakra theme for this blog:

import { ButtonProps, extendTheme } from '@chakra-ui/react';
import { mode } from '@chakra-ui/theme-tools';

const ButtonNavVariant = (props: ButtonProps) => ({
  _hover: {
    bg: mode('blackAlpha.200', 'whiteAlpha.200')(props),
    textDecor: 'none',
  },
});

const customTheme = extendTheme({
  styles: {
    global: {
      html: {
        scrollBehavior: 'smooth',
      },
      'html, body': {
        overflowX: 'hidden',
        w: '100%',
        h: '100%',
      },
    },
  },
  fontSizes: {
    '3xl': '2em',
  },
  lineHeights: {
    shorter: '1.2em',
  },
  components: {
    Button: {
      variants: {
        nav: ButtonNavVariant,
      },
    },
    IconButton: {
      variants: {
        nav: ButtonNavVariant,
      },
    },
  },
});
export default customTheme;

As you can see you're not only able to apply global styles with this approach, you can also adjust other stuff like default fontSizes, lineHeights and also styles for internal Chakra components. I really love how flexible it is.

Checkout the documentation of the default theme and all possibilities for customization.

Chakra Factory

Ok so it's cool to change the default look of a Chakra component, but what if you don't want to change the default style of a component, but create a new component with some adjustments to the original one?

Here comes the Chakra factory to the rescue, a very powerful tool!

import { chakra, Box } from '@chakra-ui/react';

const MyBox = chakra(Box, {
  baseStyle: {
    bg: 'papayawhip',
    color: 'red.500',
  },
});

// use the newly created component anywhere in your code
<MyBox />;

As you see in the example you can just pass existing Chakra components to the factory function and apply baseStyles.

The cool thing is, you're not only able to adjust existing Chakra components, but also standard HTML elements like div, input, span, etc. And if you're styling those elements with the Chakra factory, they also have the superpower to be adjusted with style props afterwards. This is really awesome 🎉

import { chakra } from '@chakra-ui/react';

const MyDiv = chakra('div', {
  baseStyle: {
    bg: 'papayawhip',
    color: 'red.500',
  },
});

// the newly created component now also has superpowers
<MyDiv margin={2} />;

Styling nested elements

Let's also cover a special usecase, where you have to style nested elements which aren't in you reach of being styled in the "Chakra way". As an example I use the Image component provided by Next.js.

Consider you have the following way of styling the component:

import Image from 'next/image';

<Image src="yourimage.png" width={200} height={100} style={{ margin: '20px' borderRadius: '10px' }} />

But that's not the way we like it mh? We want to style it with Chakra, because e.g. you want to define different margins depending on the device size. Let's have a look the the sx property of Chakra, another powerful tool.

import Image from 'next/image';
import { Box } from '@chakra-ui/react';

<Box sx={{ img: { margin: { base: '20px', md: '30px', lg: '40px' }, borderRadius: '10px' } }}>
  <Image src="yourimage.png" width={200} height={100} />
</Box>;

With the sx property you can basically style any nested element. Just apply the correct css selector. Even a selector like div > img.className is possible here, just pass it as a string literal.

It also helps with css properties which aren't yet supported natively by ChakraUI. Here you can see an example for styling scrollbars and specific WebKit properties.

Accessibility

Another awesome thing to mention is, that Chakra comes with accessibility in mind. All the components which are provided to you by ChakraUI have accessibility baked in.

As webapps should be as accessible as possible, this is an awesome prerequisite for starting to develop your webapp.

Framer Motion

Since Version 1, Chakra comes with Framer Motion as default animation library. Chakra components are using Framer Motion for their animation and it is also recommended to use it for your custom animations throughout your app.

For more information of Framer Motion checkout the official docs or the integration example for Chakra. Framer Motion is an awesome animation library and I can just recommend to have a closer look at it.

Deeply integrated support for Dark Mode

Dark mode is getting adopted more and more. Not only in the web but also in several operating systems. If you also want to support dark mode in your webapp you'll be happy to know that Chakra has a deeply integrated support for it.

Chakra also takes care of saving the user's decision, either in the local storage or as a cookie which is helpful for server side rendering. It also can detect the users OS setting.

There are several utilities to style or adjust your app depending on the current color mode.

Helpful Hooks

Chakra also has some hooks which come in handy. For example I see myself using useColorModeValue very often to provide a value depending on the current color mode.

There are also hooks like useClipboard and useMediaQuery which could make some of the other dependencies in your project obsolete.

Awesome Community

The community is a big part of a framework / library and I can say that the community around Chakra is just awesome. The people are friendly and want to help you. Checkout the Chakra GitHub Discussions if you have any questions.

I also want to mention that my Twitter friend Achim created a new project called Chakra Templates. A growing collection of responsive Chakra UI Templates ready to drop into your project.

What if I don’t use React?

At least I am happy to tell you that there's also an official Chakra version for Vue.

Summary

Hopefully you find this short overview about ChakraUI helpful. I wanted to show how it complements existing approaches in web development and extends them with nice paradigms and helpful utilities.