Forem: Benny Code

How I Save $1,463 per Month Using Claude Code as My Server Admin

Benny Code — Tue, 07 Apr 2026 20:35:44 +0000

Heroku was great when I started. Push code, get a URL, done. Platform-as-a-Service won the last decade because it took operational complexity away for a surcharge, and that trade-off made sense when managing servers meant writing Ansible playbooks and debugging iptables rules. But the landscape has changed. With AI coding tools like Claude Code, the complexity of managing your own server largely goes away. You describe what you want in plain English, and the tool SSHs in and runs the commands. That shifts the equation: owning your servers becomes very attractive again when the operational overhead drops to near zero.

I run several Node.js services built on TypeScript: web apps, APIs, and background workers like Telegram bots. Over time, the Heroku bills kept climbing. A basic dyno, a Postgres add-on, and a couple of worker processes added up to hundreds of dollars per year for apps that could run on a single server. I decided to migrate everything to a Hetzner dedicated server running Dokku, and the entire setup happened in the background through Claude Code's CLI while I was busy building new TypeScript projects. Here is exactly how it was done, so you can use it as a blueprint for your own migration.

Why Dokku

Dokku is a lightweight, open-source Platform-as-a-Service (PaaS) built on Docker. Under the hood, it uses Herokuish to run Heroku buildpacks, which means your existing Procfile and package.json work without changes. If your app runs on Heroku, it runs on Dokku.

Even though I migrated away from Heroku, this setup is not limited to Heroku. I also moved services from Render, Railway, Netlify, and Vercel. Any service that deploys from a Procfile or a Dockerfile works out of the box. The difference is that Dokku runs on your own server, so you pay for hardware instead of per-platform pricing.

I considered other tools like Coolify and CapRover, but Dokku won because of its simplicity. There is no web UI to maintain, no dashboard to secure, just a CLI that works over SSH. This also means less attack surface compared to something like Coolify, which exposes an admin panel on a port that needs to be locked down. If you prefer a web interface, Coolify is worth looking at, but I like the Unix philosophy of Dokku: it does one thing well.

The Plot Twist: I Didn't Write a Single Command

Before I walk you through the setup, I should confess something. Every command you see in this article, every dokku call, every gh api invocation, every ssh session, I did not type any of them. Not most of them. None of them. The entire migration was done through Claude Code running in my terminal. I described what I wanted in plain English, and Claude Code SSHed into the server and executed everything.

The workflow is simple: I created a private GitHub repo called hetzner-server and told Claude Code to use it as "infrastructure as docs", a place where every server configuration, domain change, and deployment setup gets documented in a README.md. When I start a new Claude Code session from that repo, it reads the existing notes and knows the full setup: which apps are deployed, which domains point where, which env vars are set, and how the webhook pipeline works.

When I want to deploy a new app, I just tell Claude Code "deploy this GitHub repo to my server." It SSHs into the Hetzner box, creates the Dokku app, uses the gh CLI to set up the webhook on the repo, configures the deploy key for private repos, enables Let's Encrypt, and updates the documentation. The entire deploy-a-new-app flow is a single conversation.

This works because Dokku and the GitHub CLI are both command-line tools. Claude Code can SSH into the server and run dokku commands, and it can run gh api locally to configure webhooks and deploy keys. There is no need for a server-side MCP or API. The server is just a Linux box that accepts SSH connections, and Claude Code is the glue that ties everything together. Some providers like Hostinger offer an API MCP server, but for a dedicated server you don't need one. SSH is enough.

Now, here is everything Claude Code did for me.

Setting Up the Server

I ordered a Hetzner AX41-NVMe dedicated server (AMD Ryzen 5 3600 6-Core, two 512GB NVMe drives, 64GB RAM). From there, Claude Code took over. It SSHed into the rescue system, installed Ubuntu 24.04 LTS via Hetzner's installimage, and configured RAID 1 for redundancy.

Once Ubuntu was running, it installed Dokku:

wget -NP . https://dokku.com/bootstrap.sh
sudo bash bootstrap.sh

After installation, it added my SSH key so I could deploy via git push:

echo 'YOUR_PUBLIC_SSH_KEY' | dokku ssh-keys:add admin

The entire server setup, from ordering to a running Dokku instance, took Claude Code about 20 minutes.

Choosing a Domain

Dokku assigns apps a subdomain automatically using sslip.io, a free service that resolves any IP embedded in a hostname back to that IP. For example, 95.217.148.47.sslip.io resolves to 95.217.148.47. This is great for testing, but for production you want a real domain.

I bought my domain on Cloudflare because they offer an official MCP server and API tokens with fine-grained permissions. Cloudflare provides an "Edit zone DNS" token template that grants only DNS access, nothing else. This means AI coding tools like Claude Code can manage DNS records programmatically without having access to your billing, account settings, or other services. If you already have domains on another registrar like Gandi, that works too since they have a REST API with Personal Access Tokens.

Set up DNS by pointing your domain to the server:

# A record
yourdomain.com → YOUR_SERVER_IP

# AAAA record (if you have IPv6)
yourdomain.com → YOUR_SERVER_IPV6

Then configure Dokku to use your domain:

dokku domains:set-global yourdomain.com

SSL Certificates

Dokku has a Let's Encrypt plugin that handles SSL certificates automatically. Install it once and enable it per app:

dokku plugin:install https://github.com/dokku/dokku-letsencrypt.git
dokku letsencrypt:set --global email you@example.com
dokku letsencrypt:enable your-app

The plugin handles certificate renewal automatically. For services that aren't Dokku apps (like a landing page or a webhook listener), you can use certbot directly with nginx.

Deploying Your First App

If your app already has a Procfile, deploying to Dokku is almost identical to deploying to Heroku:

dokku apps:create my-app
git remote add dokku dokku@YOUR_SERVER_IP:my-app
git push dokku main

Dokku detects the language from your package.json, installs dependencies, runs npm run build, and starts the app using the command in your Procfile. For Node.js, the version is resolved from engines.node in your package.json, or from an .nvmrc file in the repo root. If neither is present, it defaults to the latest version.

For worker processes (like a Telegram bot or background job), scale down the web process and scale up the worker:

dokku ps:scale my-app web=0 worker=1

GitHub Auto-Deploy with Webhooks

On Heroku, connecting a GitHub repo for auto-deploy is a checkbox. On Dokku, you need to set it up yourself, but it is straightforward. I used adnanh/webhook, a lightweight webhook listener that runs as a systemd service.

Install it on the server:

apt-get install -y webhook

Create a deploy script that clones the repo and pushes to Dokku:

#!/bin/bash
set -euo pipefail

APP_NAME="$1"
CLONE_URL="$2"
REF="$3"
BRANCH="${REF#refs/heads/}"

# Create app if it does not exist
dokku apps:list | grep -q "^$APP_NAME$" || dokku apps:create "$APP_NAME"

# Convert HTTPS URL to SSH for private repo access
SSH_URL=$(echo "$CLONE_URL" | sed "s|https://github.com/|git@github.com:|")

dokku git:sync --build "$APP_NAME" "$SSH_URL" "$BRANCH"

Configure the webhook with HMAC signature validation so only GitHub can trigger deploys:

[
  {
    "id": "dokku-deploy",
    "execute-command": "/opt/webhook/deploy.sh",
    "command-working-directory": "/tmp",
    "pass-arguments-to-command": [
      { "source": "payload", "name": "repository.name" },
      { "source": "payload", "name": "repository.clone_url" },
      { "source": "payload", "name": "ref" }
    ],
    "trigger-rule": {
      "and": [
        {
          "match": {
            "type": "payload-hmac-sha256",
            "secret": "YOUR_WEBHOOK_SECRET",
            "parameter": {
              "source": "header",
              "name": "X-Hub-Signature-256"
            }
          }
        },
        {
          "match": {
            "type": "value",
            "value": "refs/heads/main",
            "parameter": {
              "source": "payload",
              "name": "ref"
            }
          }
        }
      ]
    }
  }
]

Run it as a systemd service, then add the webhook URL to your GitHub repo. You can do this from the GitHub UI or with the gh CLI:

gh api repos/OWNER/REPO/hooks -X POST --input - << 'EOF'
{
  "config": {
    "url": "https://yourdomain.com/hooks/dokku-deploy",
    "content_type": "json",
    "secret": "YOUR_WEBHOOK_SECRET",
    "insecure_ssl": "0"
  },
  "events": ["push"],
  "active": true
}
EOF

For private repos, generate an SSH deploy key on the server and add it to the repo's deploy keys. GitHub requires a unique key per repo, so if you have multiple private repos, each one needs its own key pair.

Migrating a Postgres Database from Heroku

This is the part that sounds scary but is actually simple. You need the Heroku CLI and the Dokku Postgres plugin.

Install the Postgres plugin on your server:

dokku plugin:install https://github.com/dokku/dokku-postgres.git postgres

Create a database and link it to your app. Dokku automatically sets the DATABASE_URL environment variable:

dokku postgres:create my-app-db
dokku postgres:link my-app-db my-app

Now capture a backup from Heroku, download it to the server, and import it:

# Capture a fresh backup
heroku pg:backups:capture --app my-heroku-app

# Get the download URL
heroku pg:backups:url --app my-heroku-app

# Download the dump on the server
ssh root@YOUR_SERVER_IP 'curl -o /tmp/heroku.dump "BACKUP_URL_HERE"'

# Import into Dokku Postgres
ssh root@YOUR_SERVER_IP 'cat /tmp/heroku.dump | dokku postgres:import my-app-db'

Copy over your environment variables from Heroku (excluding DATABASE_URL, which Dokku sets automatically):

# View Heroku config
heroku config --app my-heroku-app

# Set on Dokku (skip DATABASE_URL)
dokku config:set my-app KEY1=value1 KEY2=value2

Verify the migration by comparing record counts between Heroku and your new server. Before scaling down the Heroku dynos, make sure your DNS A records already point to your dedicated server and that the change has fully propagated. DNS records have TTLs (time-to-live), so changing an address is not immediate. If you scale down Heroku while DNS is still pointing there, your users will see errors until propagation completes. Lower your TTL ahead of time and verify with dig yourdomain.com A before proceeding.

Once DNS is confirmed and you are confident everything works on Hetzner, scale the Heroku app to zero dynos:

heroku ps:scale web=0 --app my-heroku-app

After a few days of running in production on Hetzner, you can delete the Heroku app entirely:

heroku apps:destroy my-heroku-app --confirm my-heroku-app

Managing Repo Settings with the GitHub CLI

The GitHub CLI (gh) is essential for this workflow. Claude Code used it to create webhooks on repos, add deploy keys for private repo access, manage branch protection rules, and close stale pull requests. Everything that you would click through in the GitHub UI can be scripted with gh api. For example, listing all webhook deliveries to debug a failed deploy:

gh api repos/OWNER/REPO/hooks/HOOK_ID/deliveries \
  --jq '.[] | {delivered_at, status, status_code}'

What It Costs

On Heroku, a "Basic" always-on dyno gives you 512 MB of RAM and costs $7 per month. Each Essential Postgres database adds another $5 per month. My Hetzner AX41-NVMe server has 64 GB of RAM, two 512 GB NVMe drives, and costs $52.24 per month (hosted in Germany, taxes included).

To get the same 64 GB of RAM on Heroku, you would need 128 Basic dynos. If each app also needs its own Postgres database, the math looks like this:

	Heroku	Hetzner + Claude Code
128 dynos ("Basic" model, 512 MB each)	$896/mo	—
128 Postgres databases ("Essential" model, 1 GB storage each)	$640/mo	—
Dedicated server ("AX41-NVMe" model, 64 GB RAM, 512 GB storage)	—	$52.24/mo
Claude Code subscription	—	$20/mo
Total	$1,536/mo	$72.24/mo

That is a 21x price difference for the same amount of RAM and more than enough disk space for 128 small databases. Of course, this comparison only holds when looking at RAM and storage. In practice, CPU will be the bottleneck long before you hit 128 apps on a single machine. A dedicated server is a monolith: you cannot horizontally scale it by adding more instances behind a load balancer the way Heroku dynos can. The same limitation applies to the databases, which all share the same Postgres instance on one machine.

Dokku actually handles more than you might expect. Zero-downtime deployments work out of the box: it starts the new container, runs healthchecks, switches nginx traffic over, and shuts down the old container after 60 seconds. Load balancing is also built in: scale an app to multiple containers with dokku ps:scale web=3 and nginx automatically distributes traffic across them. This makes sense even on a single server since Node.js is single-threaded per process, so multiple containers let you use multiple CPU cores.

For DDoS mitigation, bot protection, and WAF (Web Application Firewall), you can enable the Cloudflare proxy on your DNS records. When proxied, all traffic goes through Cloudflare before reaching your server, which hides your server's real IP and gives you DDoS protection on the free tier. Turning it on is a single toggle per DNS record. Auto-scaling is the one thing you genuinely lose compared to Heroku since Dokku only supports manual scaling.

That said, for demos, side projects, and low-traffic production services, a single Hetzner server with Dokku is the perfect sweet spot. You get the Heroku developer experience at a fixed monthly cost, and you only start thinking about scaling when your apps actually need it.

This easy math works for me as an individual running personal projects. At company scale, the effect can become even larger. David Heinemeier Hansson (DHH), co-founder of 37signals (the company behind Basecamp and HEY), wrote about their decision to leave the cloud entirely. In his post "We have left the cloud", he shared that "the napkin math is that we'll save at least $1.5 million per year by owning our own hardware rather than renting it from Amazon." That was posted back in June 2023, before models like Claude Opus 4.6 and MCP servers for major cloud hosting providers even existed. The cost of managing your own servers has only gotten cheaper since then.

DHH and 37signals also built Kamal, an open-source deployment tool that handles zero-downtime deployments across multiple servers. If you outgrow a single-server Dokku setup and need something production-grade with rolling deploys, Kamal is worth looking at as the next step up.

The Tools That Made It Work

Here is a summary of everything used in this migration:

Tool	Purpose
Dokku	PaaS on your own server
Herokuish	Heroku buildpack compatibility
dokku-postgres	Managed Postgres for Dokku
dokku-letsencrypt	Automatic SSL certificates
adnanh/webhook	GitHub webhook listener for auto-deploy
certbot	SSL for non-Dokku services
Heroku CLI	Database export and app management
GitHub CLI	Webhook setup and repo management
sslip.io	Free wildcard DNS for testing
Claude Code	CLI-based AI assistant for server management
Cloudflare	Domain registration and DNS with API/MCP

The entire migration was done over SSH with bash commands. No special server API or MCP integration was needed for the Hetzner server itself. You SSH in, run commands, and you are done. The only APIs I used were Cloudflare (for DNS), Gandi (for DNS on other domains), GitHub (for webhooks and deploy keys), and Heroku (for database export).

Keeping Everything Up to Date

Setting up a server is only half the job. You also need to maintain it: install security patches, update system packages, renew certificates, and keep your application dependencies current. On Heroku, this mostly happens invisibly, though not always. You still need to manually approve Heroku Stack (base image) upgrades when they roll out, and PaaS providers don't always give you the latest and greatest environment since they have to ensure compatibility and maturity across their platform. On your own server, updates are fully your responsibility, but you also get to choose exactly when and what to upgrade.

One option is to use a "managed server" from providers like Hetzner or OVH, where the hosting company handles OS updates and security patches for you. But if you are running an unmanaged dedicated server like I am, you need a maintenance strategy. The first line of defense is enabling unattended-upgrades, which automatically installs critical security patches daily without any manual intervention:

apt-get install -y unattended-upgrades
dpkg-reconfigure -f noninteractive unattended-upgrades

For everything beyond OS-level patches, like updating Dokku plugins, checking app health, and keeping dependencies current, you can automate with Claude Code.

Claude Code Scheduled Tasks solve this nicely. They allow you to automate workflows by running prompts on a recurring basis, daily, weekly, or hourly. You can set up a scheduled task that SSHes into your server, runs apt update && apt upgrade, checks for Dokku plugin updates, verifies that all apps are healthy, and commits the results to your infrastructure-as-docs repo. It turns server maintenance into a background process that runs on autopilot, just like the initial setup.

Security Considerations

When you run multiple apps on one server, a compromised app should not be able to reach the others. Dokku runs each app in its own Docker container, which provides basic process isolation. But by default, containers still have broad Linux capabilities that an attacker could exploit. You can lock this down with a few Docker security flags that Dokku lets you set per app:

dokku docker-options:add my-app deploy "--cap-drop=ALL"
dokku docker-options:add my-app deploy "--cap-add=NET_BIND_SERVICE"
dokku docker-options:add my-app deploy "--security-opt=no-new-privileges"
dokku ps:rebuild my-app

--cap-drop=ALL removes all Linux capabilities from the container, so even if an attacker gets code execution, they cannot mount filesystems, modify network settings, or load kernel modules. --cap-add=NET_BIND_SERVICE adds back only the one capability a web app actually needs: binding to a port. --security-opt=no-new-privileges prevents processes inside the container from gaining elevated permissions through setuid binaries.

This is not full VM-level isolation. All containers still share the same host kernel and Docker daemon. But it significantly raises the bar for an attacker trying to move laterally from one compromised app to another.

Beyond container hardening, you should also lock down the server itself. Enable UFW (Uncomplicated Firewall) to only allow ports 22, 80, and 443, blocking everything else from the outside. Install fail2ban to automatically ban IPs that attempt SSH brute-force attacks. And if your domain is on Cloudflare, enable the proxy (orange cloud) on your DNS records to get free DDoS mitigation and hide your server's real IP address.

# Firewall: only allow SSH, HTTP, HTTPS
ufw default deny incoming
ufw allow 22/tcp
ufw allow 80/tcp
ufw allow 443/tcp
ufw enable

# Fail2ban: ban after 5 failed SSH attempts
apt-get install -y fail2ban

For personal projects and low-traffic services, these measures combined with container hardening are a practical and solid security baseline.

Copy My Setup

This article is long. It involves server configuration, webhook scripts, database migrations, SSL certificates, and dozens of bash commands. I didn't write any of it. And you don't have to either. If you want to replicate this setup, just give Claude Code this article to read and tell it to set up your server the same way. It will SSH in, install Dokku, configure your domains, set up the webhook pipeline, migrate your databases, and document everything in a repo for you. The entire blueprint is right here.

If your Heroku bill is growing and your apps don't need Heroku's managed ecosystem, a dedicated server with Dokku gives you the same developer experience at a fraction of the cost.

Why I Don’t Like Path Aliases in TypeScript

Benny Code — Thu, 28 Aug 2025 17:15:09 +0000

If you’ve been around modern TypeScript projects, you’ve probably seen imports like this:

import { formatDate } from '@/utils/date'

instead of this:

import { formatDate } from '../../utils/date'

That little @/ is a path alias. It’s a shorthand you can configure in tsconfig.json so that you don’t need to count how many ../ levels you’re in when importing files.

What are path aliases?

In TypeScript, you enable them like this:

{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["src/*"]
    }
  }
}

Now, instead of messy relative paths, you can just import from a clean root-based alias. Looks nice, right?

The problem they solve (and why I think it’s outdated)

Path aliases exist to save you from typing ../../../../ in imports. Fair enough but here’s the thing: modern IDEs already solved that problem.

In editors like VS Code, IntelliJ, and others, autocomplete instantly suggests the correct import path. When you move files around, the imports update automatically without you touching them. Even if the path happens to be long and messy, it doesn’t matter, because you never really type it by hand anyway.

So the “typing ../.. is painful” argument feels like a relic from 2015.

But don’t imports look messy?

Not really because we barely look at them. In editors like VS Code, imports collapse to a single line by default. Unless you’re adding a new one, or reviewing a diff, they’re out of sight, out of mind.

So whether the import says:

import { foo } from '../../../../utils/foo'

import { foo } from '@/utils/foo'

... doesn’t matter during normal coding.

When aliases are useful (for me)

I’ll admit that aliases are nice in one situation: copy-pasting code into docs, blog posts, or websites.

A code snippet with:

import { formatDate } from '@/utils/date'

looks much friendlier to readers than:

import { formatDate } from '../../../../../utils/date'

When someone doesn’t have the full context of your app’s folder structure, the alias makes the snippet cleaner.

The hidden danger of path aliases

Here’s the part alias fans don’t like to talk about:

Path aliases don’t actually work in compiled JavaScript.

TypeScript only knows about them because of tsconfig.json. When you compile your code, your output might still contain @/utils and Node.js or the browser has no idea what that means.

That means you now must use a bundler (Webpack, Rollup, tsup, Vite, etc.) or a tool like tsc-alias to rewrite paths at build time. If you forget, your published package or server build will break with:

Error: Cannot find module '@/utils'

In other words, you introduced extra tooling complexity to solve a problem that wasn’t really a problem anymore.

It's Easy To Switch from CommonJS to ES Modules with TS2ESM

Benny Code — Mon, 30 Oct 2023 16:23:12 +0000

Migrating a TypeScript project from CommonJS to ESM is now incredibly simple, thanks to the TS2ESM tool and the configuration fixes in TS 5.2.

You can achieve this in just 5 simple steps:

Set type to module in your package.json
Set module to nodenext in your tsconfig.json
Set moduleResolution to nodenext in your tsconfig.json
Globally install ts2esm by running npm i -g ts2esm
Execute the ts2esm command within your project's directory

As a result, you'll see that all your relative import and export statements now either include an explicit ".js" extension or "index.js" suffix, as is required for ECMAScript modules.

The ts2esm command will also enhance imports from JSON files in your TypeScript code by using import assertions:

import fixtures from '../test/fixtures.json' assert {type: 'json'};

Video Tutorial

TypeChat: Eliminating Hallucinations in AI with TypeScript

Benny Code — Tue, 01 Aug 2023 17:00:00 +0000

Modern AI systems face a challenge called "hallucinations", where a Large Language Model (LLM) generates made-up responses to prompts. Even ChatGPT by OpenAI can experience this issue. ☠️

While it's okay for creative prompts, like "create a story about flying elephants playing soccer", we need often need reliable and accurate responses. That's where Microsoft's TypeChat comes to the rescue with its schema engineering approach.

Developers can define intent types using simple TypeScript. TypeChat then transforms prompts into JSON payloads matching with your business logic.

With just 5 minutes of setup, you're good to go! Say goodbye to AI hallucinations and welcome reliable and accurate responses with TypeChat:

From Bus Factor to Lottery Factor - Embracing Positive Framing in Team Dynamics

Benny Code — Mon, 12 Jun 2023 15:47:59 +0000

The bus factor is a measure of a team's resilience and their ability to function effectively when key members are unavailable. It refers to the number of individuals who possess critical knowledge or expertise about a specific software or system. This concept highlights the risk or vulnerability that arises if those individuals were suddenly no longer accessible, such as due to unforeseen circumstances like being hit by a bus.

Instead of focusing on the negative aspect of losing key team members, it's beneficial to shift our perspective to a more positive scenario. Consider a situation where team members win the lottery and choose to retire or pursue other interests. In this context, the lottery factor represents the team's capability to smoothly carry on their work and maintain productivity despite the sudden departure of these fortunate individuals.

While retirement typically involves a planned handover process, it also underscores the importance of knowledge sharing, pair programming, and having a well-documented system to ensure the team's continued success, even in the face of unexpected changes or fortunate events.

In general, adopting a positive framing and replacing the notion of the "bus factor" with the "lottery factor" can help emphasize the team's ability to adapt and thrive under various circumstances. It encourages a focus on resilience while maintaining a positive ideology.

What is control flow based narrowing in TypeScript?

Benny Code — Mon, 05 Jun 2023 17:44:33 +0000

Control flow based narrowing refers to a type inference technique that allows the TypeScript compiler to narrow down the type of a variable based on the analysis of its control flow within conditional statements (such as if statements and switch statements).

When TypeScript analyzes the control flow of a program, it can determine certain conditions that guarantee the state of a variable. This analysis helps TypeScript to infer a more specific type for that variable within the respective branch of the control flow.

Consider the following TypeScript code snippet:

function processValue(value: string | number) {
  if (typeof value === "string") {
    // TypeScript knows here that `value` is of type `string`
    console.log(value.toUpperCase());
  } else {
    // TypeScript knows here that `value` is of type `number`
    console.log(value.toFixed(2));
  }
}

In this example, TypeScript uses control flow based narrowing to determine that within the if block, the variable value is a string. Conversely, in the else block, it knows that value is a number.

This enables the compiler to provide more accurate type checking and enables developers to use the appropriate properties or methods specific to each type without explicit type assertions.

Control flow based narrowing is a powerful feature of TypeScript that enhances type safety and helps catch potential errors at compile-time by providing more precise type information based on the analysis of control flow within the code.

Control Flow Based Type Analysis

This video tutorial demonstrates control flow based narrowing:

Interested in learning more? 🎓

I've spent years working with the TypeScript programming language and have encountered its various challenges. That's why I've recorded a series of free TypeScript video tutorials, designed to help you enhancing your coding skills.

I invite you to take a look at them and provide your feedback on the videos. I'm eager to hear your thoughts and impressions. 👀

Why TypeScript is the better JavaScript

Benny Code — Sun, 07 May 2023 18:45:07 +0000

JavaScript is a powerful and widely used programming language for web applications. However, it can sometimes lead to unexpected results and errors due to its dynamic type system. In this blog post, we'll examine some of the most common errors that arise in JavaScript, and explore how TypeScript, a superset of JavaScript, can help prevent these issues with improved type safety and error handling.

Common JavaScript Errors

JavaScript is a beginner-friendly language due to its minimal setup requirements. However, the language's limited syntax and dynamic typing often lead to errors, making it challenging for even those who are familiar with the language.

Here are a few common errors when working with JavaScript:

Unexpected string concatenation: Mixing numbers and strings can lead to undesired results, such as console.log(10 + '100') outputting 10100 instead of the expected 110.

Stringified object concatenation: Using an object as an argument will result in a stringified version of the object combined with the other argument, e.g., console.log({} + '10') returns [object Object]10.

TypeError: Accessing properties of an object that are undefined or calling a non-function will trigger a TypeError, such as caught TypeError: Cannot read properties of undefined (reading 'data') when calling console.log({}.input.data).

NaN: Forgetting to pass an argument results in a non-existent number, commonly referred to as NaN for "Not a Number". Example: console.log(parseInt())

ReferenceError: Using an undeclared variable results in a ReferenceError, such as console.log(10 + abc).

Not defined functions: Calling functions that don't exist will also throw a ReferenceError. Example: console.log(abc())

TypeScript to the Rescue

TypeScript is a programming language developed and maintained by Microsoft that adds type safety to JavaScript. By using TypeScript, you can catch errors during design time (when writing code) rather than at runtime. This will help you catching common JavaScript errors before they appear in production. TypeScript code is compiled (or transpiled) to JavaScript, ensuring compatibility with web applications.

Why Use TypeScript?

TypeScript offers several benefits, including:

Strong type checking to catch errors before runtime
Code autocompletion in your IDE for a smoother coding experience
Fundamental linting rules, including detection of unused variables and parameters
Const assertions to avoid side effects in functional programming
Class decorators to facilitate dependency injection
Inherent support for JSX in the language itself
Downleveling to convert modern JavaScript to earlier versions of JavaScript
Compatibility with various module systems, such as CommonJS and ECMAScript modules (ESM)
Customizable output formatting options, including end-of-line sequence formatting
Support for polymorphism via class inheritance and interfaces in object-oriented programming

Getting Started with TypeScript

As an experienced TypeScript contributor, I've spent years working with the language and have encountered its various challenges. That's why I've created a free TypeScript video tutorials, designed to help you master the latest version and enhance your coding skills. This series focuses on the fundamentals of TypeScript, ensuring you not only grasp how things work, but also why they work the way they do.

This knowledge can be a valuable asset as you progress from a junior to a senior programmer, and can even assist you in tackling difficult questions during job interviews. The best part? This entire tutorial series is available at no cost, so tune in and enjoy your journey towards TypeScript mastery.

Understanding npm Versioning

Benny Code — Tue, 04 Apr 2023 15:00:00 +0000

In the world of software development with JavaScript and TypeScript, it is crucial to manage the versions of packages used in your projects. This blog post will show the details of npm package management, specifically focusing on the caret (^) and tilde (~) symbols, as well as other versioning notations. Get ready to better understand how to manage your project's dependencies and establish reproducible builds with consistency in package versions!

Major, minor, patch

The npm ecosystem uses semantic versioning where version numbers typically consist of three parts, separated by dots: major.minor.patch. These parts represent different types of changes made to the software, and are used to help developers and users understand the significance of a given version number.

Major version

The major version number is typically incremented when there are breaking changes to the software. It indicates that the software is no longer backwards compatible with previous versions, and users may need to make changes to their code in order to upgrade.

For instance, API contracts may change if parameters are modified:

Version 1.0.0



export function add(a: number, b: number): number {
  return a + b;
}

Version 2.0.0

The API contract for Version 1.0.0 has been violated due to changes in the input parameter types for a and b. As a result, Version 2.0.0 must be introduced to address this breaking change:



export function add(a: string, b: string): number {
  return parseInt(a, 10) + parseInt(b, 10);
}

Important: Following the npm guidelines, you can make breaking changes in your APIs as long as you are below version 1.0.0. When your package is in major version zero (e.g., 0.x.x), the semver rules change slightly. In this case, breaking changes occur in 0.x.x (minor-level), while new features and patches are implemented in 0.0.x (patch-level).

Minor version

The minor version number is typically incremented when new features are added to the software, or when there are significant enhancements or improvements to existing features. These changes are usually backwards compatible, meaning that users can upgrade to the new version without having to make major changes to their code.

Version 1.0.0



export function add(a: number, b: number): number {
  return a + b;
}

Version 1.1.0

The add function has been updated to accept an indefinite amount of numbers, improving on its original implementation. This update does not affect prior API calls, as the function can still be used by providing just two numeric arguments, maintaining backwards compatibility.

In addition to the existing add function, a new subtract function has been added. It requires a minor release (1.1.0) to introduce these new features:



export function add(...numbers: number[]): number {
  return numbers.reduce((sum, current) => sum + current, 0);
}

export function subtract(a: number, b: number): number {
  return a - b;
}

Patch version

The patch version number is typically incremented when bugs or security issues are fixed in the software. These changes are generally small, and do not involve major changes to the functionality or features of the software.

Let's assume we updated the subtract function from version 1.1.0 to 1.2.0, adding the ability to also accept an indefinite amount of numbers as input:

Version 1.2.0



export function subtract(...numbers: number[]): number {
  return numbers.reduce((sum, current) => sum - current, 0);
}

Suppose we've discovered that using 0 as the initial value for the subtract function was a mistake. Rather than subtracting from 0, we want the function to subtract from the first number that is given as input. As a result, we'll need to release a patch version (1.2.1) to fix this issue:

Version 1.2.1



export function subtract(...numbers: number[]): number {

  return numbers.reduce((sum, current) => sum - current);

}

Understanding Caret (`^`) and Tilde (`~`)

When specifying dependencies in our package.json file, the caret and tilde symbols have special significance in determining the range of acceptable package versions.

Video Tutorial

Caret (`^`)

The caret symbol indicates that npm should restrict upgrades to patch or minor level updates, without allowing major version updates. For example, given "^5.0.2", npm will permit updates within the same major version (e.g., 5.1.0, 5.0.3), but not a jump to a new major version (e.g., 6.0.0) when running npm update.

Tilde (`~`)

By altering the caret symbol to a tilde symbol, we would only receive updates at the patch level. If we were to use "~5.0.2", we would obtain version 5.0.3 if it were available, but not 5.1.0.

Trick to remember

A helpful way to remember the difference between these symbols is by envisioning a house: the tilde is the floor, while the caret represents the rooftop, enabling you to reach higher version numbers:

Alternative Versioning Notations

If you're not concerned with specifying the precise minimum version and simply want to obtain the most recent version in a certain range, you can use alternative notations.

Latest Patch Version

To get the latest patch version, use the notation 5.0.x. This will install the most recent version with the given major and minor numbers (e.g., 5.0.6).

Latest Minor and Patch Versions

Similarly, to obtain the latest minor version, along with its most recent patch, use the notation 5.x.x. This will permit updates within the same major version, but without restrictions on the minor version (e.g., 5.1.3 or 5.2.0).

Updating Dependencies

It's essential to properly manage your dependency updates when changing version numbers in your package.json file.

npm install

Executing the npm install command installs a package's dependencies and any dependencies that these dependencies rely on (transitive dependencies). It also creates a package-lock.json file if it doesn't exist.

Important: It is worth mentioning that npm install will download compatible versions when there is no package-lock.json file present. This means that the version you receive may not be the latest minor version, even if you've specified a version range using the caret symbol.

Example

If you've included typescript@^4.8.3 in the devDependencies section of your package.json file, you may expect to receive the latest minor version (currently 4.9.5) when you run npm install. However, you will receive the latest patch version (4.8.4) as it is compatible with your version range. In order to obtain 4.9.5, you will need to execute npm update.

Dependency	npm install	npm update
`typescript@~4.8.3`	`4.8.4`	`4.8.4`
`typescript@^4.8.3`	`4.8.4`	`4.9.5`
`typescript@4.8.X`	`4.8.4`	`4.8.4`
`typescript@4.X.X`	`4.9.5`	`4.9.5`

npm update

To apply changes to the version numbers in your package.json, use the npm update command. Unlike npm install, which only downloads a compatible version, npm update will also update the package to the latest version that matches the specified range. Additionally, the package-lock.json file will be updated.

Recording Exact Versions

You might wonder: "How can I determine which version was actually downloaded?" That's where the package-lock.json file comes in. This file records the exact version retrieved during the initial installation, or any subsequent updates.

With a package-lock.json file in place, future runs of npm install will download the same build, ensuring reproducible results for your project's dependencies. This is particularly important in collaborative development environments, where multiple team members work on the same project, as it guarantees consistency across all installations.

Traffic Light Control

If you use the Yarn Package Manager instead of npm and run the command yarn upgrade-interactive --latest, you'll see a color-coded legend that indicates the likelihood of a package update breaking your code:

Patch updates are indicated in green, as they typically include backward-compatible fixes and pose the least risk of breaking your application
Minor updates are indicated in yellow, as they typically involve more changes than patch updates and therefore carry a higher risk of causing issues if their package maintainers don't strictly adhere to semantic versioning guidelines
Major updates are indicated in red, as they often include backward-incompatible changes that may require you to update your code in order to maintain compatibility

Screenshot

Conventional Commits

As we've learned, major version updates should only be issued when there are breaking changes. To draw attention to a breaking change, the Conventional Commits specification suggests using an exclamation mark (!) after the type or scope in a commit message.

Example

refactor(api)!: use stringified numbers in calculations

Tools for publishing, such as Lerna (when using the --conventional-commit flag), follow this convention when incrementing package versions and generating changelog files.

Publishing packages

Publishing packages with npm is a crucial step in sharing your code with the wider community. The npm CLI provides commands (npm version and npm publish) to assist with proper versioning and release of your own packages, in accordance with semantic versioning rules.

Video

npm version

The npm version command is used to update the version of a package in the package.json file. If run in a Git repository, it will generate a Git tag and a new commit with a message that includes the version number.

npm publish

The npm publish command is used to publish the package to the registry, making it available for installation by others.

Release Workflow

The npm version and npm publish commands can be used to set up release workflows within the scripts section of a package.json file:



{

  "scripts": {

    "preversion": "git checkout main && git pull && npm install && npm test && npm run build",

    "release:major": "npm version major",

    "release:minor": "npm version minor",

    "release:patch": "npm version patch",

    "postversion": "git push origin && git push origin --tags && npm publish --access public"

  }

}

Conclusion

In this blog post, we've explored the significance of the caret and tilde symbols in npm versioning, as well as alternative versioning notations. We've also looked at how to use the npm update command and the importance of the package-lock.json file.

With a better understanding of npm package management and the tools available to manage dependency versions, you can ensure a stable, consistent, and reproducible development environment for your projects. Happy coding!

What is the difference between null and undefined?

Benny Code — Sun, 12 Mar 2023 17:28:15 +0000

The convention in TypeScript is that undefined values have not been defined yet, whereas null values indicate intentional absence of a value.

Example with `null`

The below function shows how null can be used by returning an object that always has the same structure, but with intentionally assigned null values when the function does not return an error or result:

function divide(a: number, b: number) {  
  if (b === 0) {  
    return {  
      error: 'Division by zero',  
      result: null  
    };  
  } else {  
    return {  
      error: null,  
      result: a / b  
    };  
  }  
}

Example with `undefined`

On the other hand, undefined represents the absence of any value. It is a value that is automatically assigned to a variable when no other value is assigned. It often indicates that a variable has been declared but not initialized. It can also signify a programming mistake, such as when a property or function parameter was not provided:

let ratio: number | undefined;  

if (ratio === undefined) {  
  console.log('Someone forgot to assign a value.');  
} else if (ratio === null) {  
  console.log('Someone chose not to assign a value.');  
}

Best Practice

The TypeScript Coding guidelines recommend using only undefined and discouraging the use of null values (see here). It is important to note, however, that these guidelines are tailored towards the TypeScript project's codebase and may not necessarily be applicable to your own projects.

Want more?

If you found this short explainer helpful, hit that subscribe button on my YouTube channel or give me a follow on Twitter to level up your TypeScript game.

Best practices with const assertions in TypeScript

Benny Code — Tue, 03 Jan 2023 18:38:14 +0000

TypeScript 3.4 introduced const assertions, a feature that allows you to claim a value as immutable. This feature is particularly valuable in combination with array literals, as it prevents new values from being pushed into an existing array.

const declarations

A const declaration only makes the array reference immutable.

Example

// 'const' only makes the array reference immutable
const myArray = [1, 2, 3];
// Values of the array can still be removed
myArray.pop();
// ...or pushed
myArray.push(4);
// ... but reassignments become impossible
// TS2588: Cannot assign to 'myArray' because it is a constant.
myArray = [4];

const assertions

With a const assertion you will get immutability for your array reference and array values at design-time.

Example

// A 'const assertion' protects the reference and elements of your array
const myArray = [1, 2, 3] as const;
// TS2339: Property 'pop' does not exist on type 'readonly [1, 2, 3]'.
myArray.pop();
// TS2339: Property 'push' does not exist on type 'readonly [1, 2, 3]'.
myArray.push(4);
// TS2588: Cannot assign to 'myArray' because it is a constant.
myArray = [4];

Important note

One important thing to note is that const assertions are a TypeScript feature at design-time and do not actually make values immutable at runtime. This means that you will still be able to modify values at runtime using plain JavaScript. If you want to achieve a higher level of immutability, you can make use the Object.freeze() API.

Example

const myArray = [1, 2, 3];
// The static 'freeze' method makes your array immutable at runtime
Object.freeze(myArray);
// This will happen when you try to manipulate your array in JavaScript:
// Uncaught TypeError: Cannot add property 4, object is not extensible
myArray.push(4);

Best Practice

You can combine a const assertion with Object.freeze to get type safety at design-time and runtime:

// Protection at design-time
const myArray = [1, 2, 3] as const;
// Protection at runtime
Object.freeze(myArray);

as const with objects

A const assertion can also protect an object literal by marking its properties as readonly:

// Protect your object properties from changes at design-time
const objectLiteral = {
  age: 35,
  name: 'Benny'
} as const;

// TS2540: Cannot assign to 'age' because it is a read-only property.
objectLiteral.age = 30;

as const with strings

You can narrow the type for a string to a specific string using as const:

// Don't use an explicit return type to make use of type inference
function getName(firstName: string, lastName: string) {
  return `${firstName} ${lastName}` as const;
}

let displayName = getName('Benny', 'Code');
// TS2322: Type '"..."' is not assignable to type '`${string} ${string}`'.
displayName = '...';

Alternative Options

You can use the ReadonlyArray type of TypeScript 3.4 to disallow array value modifications at design-time:

Example

const array: ReadonlyArray<number> = [1, 2, 3];
// TS2339: Property 'pop' does not exist on type 'readonly number[]'.
array.pop();

Shorthand Syntax

const array: readonly number[] = [1, 2, 3];
// TS2339: Property 'pop' does not exist on type 'readonly number[]'.
array.pop();

Video Tutorial

Record in 4K with Sony Alpha A6400 & Elgato Cam Link 4K

Benny Code — Sat, 14 May 2022 15:05:33 +0000

Most of my programming tutorials, like 5 tips to write better TypeScript code, have an intro in 4K resolution. I record my intros using a Sony Alpha 6400 mirrorless camera. I get the video signal from my Sony A6400 through my PC, but it wasn't that easy to capture it in 4K with 30 frames per second (2160p30). In this post, I will show you how I managed to do it.

Sony Imaging Edge

First I tried using Sony's Imaging Edge Webcam software as I was hoping I could simply use a USB cable and get the video signal. It actually worked but the maximum resolution was limited to 1024×576 pixels. Higher resolutions are not available using the the USB output of the Sony Alpha 6400. Sony's documentation confirms this limitation and also mentions that the Imaging Edge Webcam software does not handle audio from the camera's built-in microphone or a connected microphone.

Elgato Cam Link 4K

Since 4K recording via Micro USB isn't possible with the A6400, I switched to recording via Micro HDMI in combination with a so called video capture card. I bought the Elgato Cam Link 4K as it promises out of the box recording with up to 4K resolution at 30 frames per second.

USB Cable

To connect my camera with the Cam Link 4K, I bought a Micro HDMI to HDMI cable of 3m length that has been certified for 4K at 60Hz. The length of the cable plays an important role. Long HDMI cables can cause a video signal degradation. Best is to check with the HDMI cable manufacturer for more details.

USB Port

I had to make sure that the Capture Card is connected to its own USB port on my mainboard, so that it doesn't share the USB controller with any other device. I connected it to a USB 3.1 port but the documentation says that a USB 3.0 port is sufficient. When I had the Capture Card connected to a USB Hub, then it didn't work as it shared the bandwidth with other devices (such as my webcam) and as a result didn't get enough bandwidth to transfer the video signal without interruptions. I had to balance the load on my USB controllers.

USB Controller

Here is how you can verify if your Cam Link 4K is connected to its own USB controller on Windows:

Open Windows' Device Manager
Select "View" and "Devices by type"
Select "Cameras" and "Cam Link 4K"
Change "View" to "Devices by connection"

It should show you now the USB controller to which your Cam Link 4K is attached. Make sure your capture card doesn't share the USB controller with another device:

For macOS you can find out here how many USB Root Hubs are available on your machine and what is connected to them.

Software

Elgato advertises Plug'n'Play installation which means that you can simply connect the Cam Link 4K USB stick to your computer and use it directly in applications without installing any additional software. While that is true, I recommend you to install the Elgato 4K Capture Utility 1.7.6 for troubleshooting. There is also the Elgato Camera Hub but it won't give you as much recording information as the Capture Utility.

The first thing I noticed in the 4K Capture Utility was that my camera was only sending 25 (not 30!) frames per second. That was mainly because it was set to PAL instead of NTSC.

In the screenshot you can see that there is a problem with the recording setting:

Video Settings

Here is how I fixed my recording settings to make the Sony A6400 (ILCE-6400) capturing 4K video with 30fps.

At first you have to turn the mode dial to the "Movie" icon. Afterwards you have to go through the following settings using the "MENU" button:

Setup → Setup2 → NTSC/PAL Selector → Change to NTSC and reboot your camera
Setup → Setup4 → HDMI Settings → HDMI Resolution → Select 2160p/1080p to stream 4K video via HDMI
Setup → Setup4 → HDMI Settings → HDMI Info. Display → Select Off to disable menu icons in your video stream (Clean HDMI Output)
Camera Settings2 → Movie1 → File Format → Select XAVC S 4K to record movies in 4K resolution (3840×2160)
Camera Settings2 → Movie1 → Record Setting → 30p 60M to record with 30 frames per second and a bitrate of approx. 60 Mbps. You can also use 30p 100M if your computer handles the data well during post-processing and you have enough disk storage for 100 Mbps. However, the 4K Capture Utility only supports 70 Mbps and the difference between 60 Mbps & 100 Mbps is marginal.
Connect HDMI cable to your camera to see the 4K Output Select option
Setup → Setup4 → 4K Output Select → HDMI Only (30p) to stream 30 frames per second via HDMI

Here is how it should look in the "4K Capture Utility" when all settings are correct:

Note: You don't have to insert a SD card or press the record button on your Sony camera as the video signal will be streamed through the High Definition Multimedia Interface (HDMI). Recording happens on your computer. If you want to record over a longer period of time without draining your battery, then I recommend to buy the Sony NP-FW 50 power adapter.

Exposure Settings

Further settings that I use when recoding my intros:

Camera Settings1 → AF1 → Focus Mode → Continuous AF to make sure that the focus gets automatically adjusted when I move in front of my camera
Camera Settings1 → AF1 → Focus Area → Wide to focus my whole scene / room
Camera Settings1 → Colors → White Balance → Auto so that I can record at different times with different lighting conditions without manually adjusting my white balance setting (WBS)
Camera Settings1 → Exposure1 → ISO Setting → ISO → ISO 100 or in general the lowest value possible that doesn't make my scene look too dark
Camera Settings1 → Exposure1 → Metering Mode → Multi to determine the proper exposure for your entire scene
Camera Settings1 → Exposure1 → Face Priority in Multi Metering → On to make sure that your face always gets exposed in your scene
Camera Settings2 → Movie1 → Exposure Mode → Manual Exposure to control your aperture and shutter-speed manually
Make sure your shutter speed is set to 1/60 to adhere to the "180 Degree Rule of Shutter Speed" (shutter speed should be set to 1/frame rate x 2) when recording with 30fps
Movie → Movie2 → AF Tracking Sens. → Responsive because I am filming just myself and not a crowd so the auto focus should act as soon as it recognizes a (my) movement
Movie → Movie2 → AF drive speed → Normal if you don't move much (don't do sports) in front of your camera to keep the automatic focus adjusment to a minimum
Setup → Setup2 → Auto Power OFF Temp. → High to allow your camera to get hotter during recording without shutting down

I use the control dial to set my aperture to the lowest value possible (in my case F1.4 or ƒ/1.4) to get a bright picture with a nice Bokeh effect. I can recommend you the DOF Simulator to test different focal lengths and settings without a real camera:

Recording

If everything is set correctly, you can use your favorite recording software and capture your "Cam Link 4K" device. I am recording my video stream with Camtasia 2021. My audio is being recorded with my Shure SM7B but that's another story.

Razer Ripsaw X

I want to report that I have also tried a Razer Ripsaw X which doesn't come with any software but relies on automatic resolution detection. It failed to record 4K video for me and only allowed me to capture Full HD (1920x1080) resolution.

Resources

Videos that helped me with my settings:

How to Set Up Elgato Cam Link 4K with Sony A6400 from Elgato
Configure SONY cameras for LIVE STREAMING (2020) from Nilson1489
Sony a6400 Tutorial from Think Media

Getting started with GitHub Actions and workflows

Benny Code — Sun, 03 Apr 2022 12:55:37 +0000

GitHub Actions are a great way to automate your own software development cycle. GitHub Actions are free of charge for public repositories and provide you with a whole CI/CD platform. It allows you to automate all parts of your software supply chain and run it in virtual environments or even your own environment using self-hosted runners.

Much of what used to be done with a Jenkins job can now be done with GitHub Actions. In this article, I will give you a quick start in GitHub Actions and explain what actions, workflows, events, jobs and steps are. As an example we take a JavaScript application for which we set up a test automation.

What are GitHub Actions?

GitHub Actions are reusable scripts that can be used on GitHub's platform for continuous integration and continuous delivery (CI/CD). You can write your own actions using JavaScript (and other languages) or use published actions from the GitHub Marketplace.

There are already actions for various tasks like sending a message to a Slack channel (slack-send), uploading code coverage reports (codecov) or deploying code to the Google Cloud (setup-gcloud). In this tutorial, we will use existing GitHub Actions and wire them together in a so-called "workflow".

What are workflows?

A workflow is a description for your CI/CD pipeline on GitHub Actions. A workflow always runs one or more jobs and each job consists of steps which can be calls to GitHub Actions or regular shell commands. A workflow is triggered by an event (e.g. a commit in your branch) and runs on a virtual environment on GitHub (called "hosted runner") or your own environment (called "self-hosted runner").

Test Automation with GitHub Actions

To ensure that pull requests are compatible with your code, you can setup a GitHub workflow to run a test automation pipeline. I will show you how to do this by using a JavaScript demo project for which we will run npm test when new code comes in.

Setting up a workflow

Setting up a workflow is done by creating a YAML file inside of the .github/workflows directory of your repository on GitHub. We will save our test automation in test.yml:

.github/workflows/test.yml



# Name of our workflow
name: 'Test'

# Events that will trigger our workflow
on: [ 'pull_request', 'push' ]

# List of custom jobs
jobs:
  # Job is called "test"
  test:
    # Using a "label" to assign job to a specific hosted runner
    runs-on: ubuntu-latest
    steps:
      # Checks-out our repository under "$GITHUB_WORKSPACE", so our job can access it
      - name: 'Checkout repository'
        uses: actions/checkout@v3

      # Runs commands using the runners shell
      - name: 'Run tests'
        run: npm ci && npm test

Specify Node.js version

GitHub provides hosted runners which can run your workflow in different virtual environments. The "ubuntu-latest" environment already contains a recent version of Node.js which is ideal for testing JavaScript applications.

You can also use the setup-node action to configure any Node.js version you like to use:



name: 'Test'

on: [ 'pull_request', 'push' ]

jobs:
  test:
    # Using a build matrix to route workflow to hosted runner(s)
    runs-on: ${{ matrix.os }}
    strategy:
      matrix:
        os: [ 'ubuntu-latest' ]
        node-version: [ '16.x' ]
    steps:
      - name: 'Checkout repository'
        uses: actions/checkout@v3

      # Uses specific version of Node.js
      - name: 'Use Node.js v${{ matrix.node-version }}'
        uses: actions/setup-node@v3
        with:
          node-version: ${{ matrix.node-version }}

      - name: 'Run tests'
        run: npm ci && npm test

Define workflow triggers

Currently our workflow is executed on every git push event and every event in a Pull Request. Pushing commits in a PR triggers our action twice because it is a push event and an event in our PR. To prevent this, we can restrict the events that trigger our workflow. We will limit the push events to the "main" branch, which is useful when we squash and merge a PR into our "main" branch:



name: 'Test'

on:
  pull_request:
  # Limit push events to "main" branch
  push:
    branches: [ 'main' ]

jobs:
  test:
    runs-on: ${{ matrix.os }}
    strategy:
      matrix:
        os: [ 'ubuntu-latest' ]
        node-version: [ '16.x' ]
    steps:
      - name: 'Checkout repository'
        uses: actions/checkout@v3

      - name: 'Use Node.js v${{ matrix.node-version }}'
        uses: actions/setup-node@v3
        with:
          node-version: ${{ matrix.node-version }}

      - name: 'Run tests'
        run: npm ci && npm test

Note: Simply leave the value for pull_request empty to match any branch name.

Run workflow manually with `workflow_dispatch`

We can also define a workflow_dispatch trigger which will allow us to run a workflow manually from the "Actions" tab of our repository:



name: 'Test'

on:
  pull_request:
  push:
    branches: [ 'main' ]
  # The "workflow_dispatch" event gives us a button in GitHub's "Action" UI
  workflow_dispatch:

jobs:
  test:
    runs-on: ${{ matrix.os }}
    strategy:
      matrix:
        os: [ 'ubuntu-latest' ]
        node-version: [ '16.x' ]
    steps:
      - name: 'Checkout repository'
        uses: actions/checkout@v3

      - name: 'Use Node.js v${{ matrix.node-version }}'
        uses: actions/setup-node@v3
        with:
          node-version: ${{ matrix.node-version }}

      - name: 'Run tests'
        run: npm ci && npm test

Screenshot:

Run multiline shell commands

When working with TypeScript, it is advisable to check the validity of your types before running tests. This way errors can be catched even before setting up the test runner. We will accomplish this by running tsc --noEmit just before executing our test script. In order to have a better overview of our commands, we will replace the && link with a multiline command using the pipe (|):



name: 'Test'

on:
  pull_request:
  push:
    branches: [ 'main' ]
  workflow_dispatch:

jobs:
  test:
    runs-on: ${{ matrix.os }}
    strategy:
      matrix:
        os: [ 'ubuntu-latest' ]
        node-version: [ '16.x' ]
    steps:      
      - name: 'Checkout repository'
        uses: actions/checkout@v3

      - name: 'Use Node.js v${{ matrix.node-version }}'
        uses: actions/setup-node@v3
        with:
          node-version: ${{ matrix.node-version }}

      # Runs multiple commands using the "|" operator
      - name: 'Run tests'
        run: |
          npm ci
          npx tsc --noEmit
          npm test

Skip workflow execution

We can prevent our full test setup from running when adding a specific text (like [skip ci] or [ci skip]) in our commit message:



name: 'Test'

on:
  pull_request:
  push:
    branches: [ 'main' ]
  workflow_dispatch:

jobs:
  test:
    runs-on: ${{ matrix.os }}
    # Condition to run the job using GitHub's event API
    if: |
      contains(github.event.commits[0].message, '[skip ci]') == false &&
      contains(github.event.commits[0].message, '[ci skip]') == false
    strategy:
      matrix:
        os: [ 'ubuntu-latest' ]
        node-version: [ '16.x' ]
    steps:      
      - name: 'Checkout repository'
        uses: actions/checkout@v3

      - name: 'Use Node.js v${{ matrix.node-version }}'
        uses: actions/setup-node@v3
        with:
          node-version: ${{ matrix.node-version }}

      - name: 'Run tests'
        run: |
          npm ci
          npx tsc --noEmit
          npm test

Note: By default GitHub skips checks for commits that have two empty lines followed by skip-checks: true within the commit message before the closing quotation:



git commit -m "Some commit message
>
>
skip-checks: true"

Using expressions in workflows

The workflow syntax for GitHub Actions allows us to use expressions. There is a set of built-in functions, like success() and failure(), that can be used in expressions and are very handy to check the status of your workflow. We will use failure() to send a message to our Slack channel whenever our tests fail:



name: 'Test'

on:
  pull_request:
  push:
    branches: [ 'main' ]
  workflow_dispatch:

jobs:
  test:
    runs-on: ${{ matrix.os }}
    if: |
      contains(github.event.commits[0].message, '[skip ci]') == false &&
      contains(github.event.commits[0].message, '[ci skip]') == false
    strategy:
      matrix:
        os: [ 'ubuntu-latest' ]
        node-version: [ '16.x' ]
    steps:
      - name: 'Checkout repository'
        uses: actions/checkout@v3

      - name: 'Use Node.js v${{ matrix.node-version }}'
        uses: actions/setup-node@v3
        with:
          node-version: ${{ matrix.node-version }}

      - name: 'Run tests'
        run: |
          npm ci
          npx tsc --noEmit
          npm test

      - name: 'Post error notification to Slack channel'
        uses: slackapi/slack-github-action@v1.18.0
        # Use built-in function in expression
        if: ${{ failure() }}
        with:
          channel-id: my-channel
          slack-message: 'Test run <${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}|${{ github.run_id }}> failed.'
        env:
          SLACK_BOT_TOKEN: ${{ secrets.MY_SLACK_BOT_TOKEN }}

Note: To make use of the Slack Action, you have to create a Slack App for your Slack workspace with an OAuth scope of chat.write. Afterwards, you have to make your "Bot User OAuth Token" available as environment variable (e.g. MY_SLACK_BOT_TOKEN) in your GitHub repository. This can be done in Settings → Secrets → Actions. It will then be accessible in your workflow file using the ${{ secrets.MY_SLACK_BOT_TOKEN }} expression.

Branch protection rules

Once you have a testing workflow and sufficient tests covering your code, you can setup a branch protection rule. This can be done by navigating to Settings → Branches → Branch protection rules → Add rule in your GitHub repository.

The "Branch name pattern" supports fnmatch syntax but also allows to set a single branch name (like "main"). In order to protect your branch from incompatible dependency updates you have to activate "Require status checks to pass before merging". You can use GitHub Actions as status checks by searching for their job names (e.g. "test").

Screenshot:

The branch protection rule will warn you when new code fails your testing pipeline. It will also prevent merging broken code into your "main" branch when you are not an administrator who can override such rules.

Running your GitHub Actions locally

If you want to have faster feedback loops, you can also run GitHub Actions locally using the act cli. It requires Docker and a local installation through your favorite package manager.

After installing "act", you can run it locally from your terminal by passing it the job name of your workflow, e.g. act -j test. It will then download the necessary Docker image. Depending on the complexity of your workflow, this image can be 20+ GB in size. For our small test setup a micro image (below 200 MB) that contains only Node.js is good enough when we remove our "skip ci" condition.

Screenshot:

Where to go from here?

Congratulations! You have just learned the fundamentals of GitHub Actions and you are now able to create your own workflows. With your newly acquired skills, you can build great CI/CD pipelines. 🎊

If you want to learn more about GitHub Actions, then I recommend the following topics:

Forem: Benny Code

How I Save $1,463 per Month Using Claude Code as My Server Admin

Why Dokku

The Plot Twist: I Didn't Write a Single Command

Setting Up the Server

Choosing a Domain

SSL Certificates

Deploying Your First App

GitHub Auto-Deploy with Webhooks

Migrating a Postgres Database from Heroku

Managing Repo Settings with the GitHub CLI

What It Costs

The Tools That Made It Work

Keeping Everything Up to Date

Security Considerations

Copy My Setup

Why I Don’t Like Path Aliases in TypeScript

What are path aliases?

The problem they solve (and why I think it’s outdated)

But don’t imports look messy?

When aliases are useful (for me)

The hidden danger of path aliases

It's Easy To Switch from CommonJS to ES Modules with TS2ESM

Video Tutorial

TypeChat: Eliminating Hallucinations in AI with TypeScript

From Bus Factor to Lottery Factor - Embracing Positive Framing in Team Dynamics

What is control flow based narrowing in TypeScript?

Control Flow Based Type Analysis

Interested in learning more? 🎓

Why TypeScript is the better JavaScript

Common JavaScript Errors

TypeScript to the Rescue

Why Use TypeScript?

Getting Started with TypeScript

Understanding npm Versioning

Major, minor, patch

Major version

Minor version

Patch version

Understanding Caret (^) and Tilde (~)

Video Tutorial

Caret (^)

Tilde (~)

Trick to remember

Alternative Versioning Notations

Latest Patch Version

Latest Minor and Patch Versions

Updating Dependencies

npm install

npm update

Recording Exact Versions

Traffic Light Control

Conventional Commits

Publishing packages

npm version

npm publish

Release Workflow

Conclusion

What is the difference between null and undefined?

Example with null

Example with undefined

Best Practice

Want more?

Best practices with const assertions in TypeScript

const declarations

const assertions

Important note

Best Practice

as const with objects

as const with strings

Alternative Options

Video Tutorial

Record in 4K with Sony Alpha A6400 & Elgato Cam Link 4K

Sony Imaging Edge

Elgato Cam Link 4K

USB Cable

USB Port

USB Controller

Software

Video Settings

Understanding Caret (`^`) and Tilde (`~`)

Caret (`^`)

Tilde (`~`)

Example with `null`

Example with `undefined`

Run workflow manually with `workflow_dispatch`