vixalien's site

A love letter to mise

Thu, 30 Apr 2026 00:00:00 GMT

Recently, I have been using GNOME OS, as my daily driver.

After being a seasoned Linux for long, dabbling in distros like Alpine Linux, Arch Linux, Fedora (and even Silverblue), I tried switching to something more opinionated and that "works by default" all while being hard to break.

And given my existing relationship with GNOME, GNOME OS was a choice worth looking into.

One feature of GNOME OS is that it is immutable (i.e. system files are read-only). It also doesn't ship with a package manager, so it doesn't have functionality built-in to install extra packages.

You can install GUI Applications normally using Flathub (and Snap/AppImage), but installing non-GUI applications like development tools or CLI packages is not built-in.

There are of course several solutions you can use, such as homebrew, coldbrew, but today we will focus on mise.

What is mise?

mise pitches itself as "One tool to manage languages, env vars, and tasks per project, reproducibly."

However, I only use a fraction of it's functionality, in that I only use it to install packages.

How to install it?

The instructions are here: https://mise.jdx.dev/getting-started.html

But essentially it's as easy as running this (remember to read the source of the installer first):

curl https://mise.run | sh

Activating mise

Then you will need to "activate" mise, which essentially makes tools installed by mise available by modifying your $PATH variable

echo 'eval "$(~/.local/bin/mise activate bash --shims)"' >> ~/.bashrc

The instructions above are for bash, so you will need to consult the docs to get instructions for your shell.

You will need to re-login for the mise command to be available, or open a new shell.

A note on shims

Feel free to skip this section, as it's just an explainer

Also, note that the above command use the --shims flag, which is NOT the default. It essentially means that mise will modify the $PATH variable, instead of doing a weird thing where it will re-activate itself after each command you run.

The non-shim way to activate mise is useful when you use mise to install different package versions across different repositories, but that sometimes breaks IDEs and is our of the scope of this blog post.

Installing packages

You can start installing your first package with mise:

mise use -g java

The above command installs java globally (hence the -g flag), which you can now confirm by running:

$ java --version
openjdk 26.0.1 2026-04-21
OpenJDK Runtime Environment (build 26.0.1+8-34)
OpenJDK 64-Bit Server VM (build 26.0.1+8-34, mixed mode, sharing)

You can install much more tools, of which you can find a non-complete list here: mise-tools.

For example, you can similarly install a specific major version of nodejs

mise use -g node@22

Or install the latest LTS version of node

mise use -g node@lts

Or you can be overlay specific

mise use -g node@v25.9.0
mise use -g node@25.9.0 # this works too!

Searching

Use mise search to find packages.

mise search typ
Tool       Description                                                                                                                            
typos      Source code spell checker. https://github.com/crate-ci/typos
typst      A new markup-based typesetting system that is powerful and easy to learn. https://github.com/typst/typst
typstyle   Beautiful and reliable typst code formatter. https://github.com/Enter-tainer/typstyle
quicktype  Generate types and converters from JSON, Schema, and GraphQL provided by https://quicktype.io. https://www.npmjs.com/package/quicktype

Uninstalling

mise unuse -g node

Updating

mise self-update # updating mise itself
mise up          # updating tools installed by mise
mise outdated    # checking if you have outdated tools

Config File

Tools you install with mise globally will be saved in the file ~/.config/mise/config.toml, which you can commit to your dotfiles so you can have similar tools across different machines.

Here's an example of my mise config file at the time of writing this blog post.

# ~/.config/mise/config.toml
[tools]
bat = "latest"
btop = "latest"
bun = "latest"
caddy = "latest"
"cargo:mergiraf" = "latest"
deno = "latest"
difftastic = "latest"
doggo = "latest"
fastfetch = "latest"
fzf = "latest"
github-cli = "latest"
"github:railwayapp/railpack" = "latest"
glab = "latest"
helix = "latest"
java = "latest"
lazygit = "latest"
node = "latest"
"npm:vscode-langservers-extracted" = "latest"
oha = "latest"
pipx = "latest"
pnpm = "latest"
prettier = "latest"
rust = "latest"
scooter = "latest"
tmux = "latest"
usage = "latest"
yt-dlp = { version = "latest", rename_exe = "yt-dlp" }
zellij = "latest"
"github:patryk-ku/music-discord-rpc" = { version = "latest", asset_pattern = "music-discord-rpc" }
rclone = "latest"
mc = "latest"
go = "latest"
"go:git.sr.ht/~migadu/alps/cmd/alps" = "latest"
"npm:localtunnel" = "latest"

After the tools inside the config has changed, you can run the following comand to make mise re-install packages from the config file

mise install

Mise Backends

Mise is able to install packages from multiple sources. These sources are called "backends" by mise.

When you type mise use -g node@22, it will resolve node against the registry and figure out that the default backend for node is core

Core

The default backend is called core and tools from this backend are usually provided from the official source.

Other tools that are available from core include Node.js, Ruby, Python, etc...

We could also have been explicit with the backend we want to use

mise use -g core:node

You can find a list of all core packages here.

Aqua

You can also install packages from the Aqua registry.

Language Package Managers

You can also install tools from their respective package managers. Here are a few examples

`npm`

You can install prettier, typescript, oxlint and other JavaScript/TypeScript tools published on the npm registry. Find the tools on npm

mise use -g npm:prettier

`pipx`

You can install black, poetry and other Python tools from pypi. Find the tools on pypi

mise use -g pipx:black
pipx:git+https://github.com/psf/black.git # from a github repo

`cargo`

You can install cargo packages with this backed. You need to have rust installed beforehand though, which you can do with mise

mise use -g rust

Then install your packages

mise use -g cargo:eza

There are more language package manager backends like: gem, go and more.

Github

You can install packages from Github directly, as long as the project you are trying to install from uses Github releases

mise use -g github:railwayapp/railpack

mise will usually auto-detect which asset you want to use, but you can also specify the asset glob in ~/.config/mise/config.toml

[tools]
"github:patryk-ku/music-discord-rpc" = { version = "latest", asset_pattern = "music-discord-rpc" }

2024

Thu, 09 Jan 2025 00:00:00 GMT

Hello, reader.

This is my latest attempt at trying to write a wrap-up of my year, and also a last-ditch attempt to save this blog from all the tumbleweeds, dust and spiderwebs.

I'll be writing about what I did this year, and this year it's going to be a bit more structured and brief, atleast that's what I'm aiming for. Please read this, and maybe give me some feedback!

Life

I'd say that life has been pretty okay. I've only got sick once towards the end of the year, and only for a few days.

memories.vixalien.com

I now host a simple website at [memories.vixalien.com], which you can visit to see a few pictures I took along this journey of life. I wish to improve it, possibly using the new Masonry layout in CSS, so that the images can display better, and faster. I might also try rewriting the site in Astro, to get rid of all the JavaScript. You can read more about how it works in this blog post I wrote earlier this year about river, the name of the metaframework it uses under the hood.

Budgeting

I started using YNAB to make budgets and track my personal expenses. I wanted to do it to reduce spending on luxuries instead of saving up, and I would say it paid a huge role. Actually tracking your expenses and knowing where your money goes is such an eye-opening experience, and you will quickly realise how much money you spend on the "small things" and on the "I need to take care of myself" expenses.

The next step of YNAB is actually budgeting, instead of just tracking expenses. To be totally frank with you, this is not my strongest suit, as I still adjust the budget from time to time to cover overspending in a wants category.

If you want to try out budgeting for yourself, I recommend you follow YNAB's 4 rules:

Give every dollar a job
Embrace your true expenses
Roll with the punches
Age Your Money

You can learn more about the 4 rules with Hannah.

Social

Twitter/X

This year, I broke away from Twitter/X, as it has been... well, unusable recently. Instead, I switched to Mastodon, where you can follow me as @vixalientoots@mas.to. My fediverse client of choice is Phanpy on desktop and mobile linux, and Ice Cubes on my phone.

Instagram

Instagram is probably the social media I use the most. I use it to sink a lot of my important hours watching reels, chatting with friends, and seldomly posting about pictures I take.

I took a brief break in the timeframe northern hemisphere folks call summer. We call that season the long dry season, because we are close to the equator, and our seasons are not influenced by the tilt of the earth, but rather due to the rainfall patterns. Anyway, during that break I accidentally deleted my account instead of disabling it, and made the shocking realisation a few days after the 30-day window Instagram gives you before deleting your account for good. This was bittersweet, but I made the (bad) decision to come back to Instagram again, as my life was honestly feeling very empty.

School

Uni

This year I also tried being more serious and attentive to classes, instead of the usual lazy and unproductive self I am. This work paid off very well, and I'm no longer in the lower ranks and actually make an effort to understand course concepts before moving on. If you are in University too, or doing something else, I would recommend you give it your all.

This came after a rather stoic realisation that I'm actually paying to be at University, and that when I'm not giving it my all, I'm actually losing time and money, and you know what they say: « Time wasted does not come back ». Surely enough, money spent does not come back either!!

Open Source

GNOME

I've been contributing to GNOME Projects for a while now, usually making bug reports, contributing to some libraries and applications (sometimes unsucessfully), writing some of my own GNOME apps, and more.

The year started of well, because I became a GNOME Foundation Member which is a very notable title (at least for me), and I feel like my contributions are now more valued.

I did apply and get accepted for Google Summer of Code in the... summer! It was quite a nice experience initially, since I got to work on Workbench, specifically adding TypeScript support to the app. I would implore you to check the application out if you want to make desktop applications (linux, mac, windows and android soon?) using GTK. The application allows you to write applications in many languages, including Rust, Vala, JavaScript, Python and now TypeScript. The application was developed by Sonny Piers, an amazing person, who was also my mentor for the Google Summer of Code intern, at least initially. I wrote about my experience in GSoC in a blog post you can also read, if you're interested.

Things took a weird turn when Sonny was inexplicably and mysteriously banned from the GNOME Foundation, a sudden move that left me without a mentor for a while before they found a replacement. We (GNOME Contributors) have not yet got closure about the ban, even after we voted for new GNOME Foundation Board members, and this honestly led to the reduced trust and faith I now have in the GNOME Foundation. A side effect of this is that I've reduced my contributions to GNOME, as I'm no longer ecstatic to be a contributor anymore.

My Linux Apps

I write and maintain(ed) about 3 linux GTK applications, which have had limited contributions because of said previous issues with the GNOME Foundation.

The first, Sticky Notes, is basically on life support, as I didn't really work on it much this year. Nevertheless, I'm still sending out maintenance updates, usually just updating the app for the new GNOME SDK, but never implementing any new features. I did plan and work on a new branch targetting markdown for a while, but never finalised it, and I don't think I have the energy, will and time to work on it anymore. Sorry folks, maybe next year!

The second application I wrote, Muzika is now officially dead, as I wrote about in detail in a mastodon post. This is due to a lot of factors, but mainly due to YouTube breaking the current mechanism we used to log users in, and me not willing to play the cat and mouse game anymore. This is very unfortunate, as Muzika was basically my most famous application, and I've sunk a lot of hours into it, which made it sad to go. Anyway, we move!

The last, and newest application is called Decibels, and as you can probably guess from the name, is an audio (NOT music!!) player. It is a minimal application and requires minimal maintenance, which I like. I also have a co-maintainer (hey David!), which makes maintaining the app a breeze. It's already a GNOME Circle (basically recognised as a good GNOME application), and it's incubating to be part of the Core apps, which means you might soon have it installed by default in a GNOME installation!

Work

Karabo

It's that time in University where you have to make a project, partly to get grades, and partly to validate all the hours you've sunk doing coursework or attending lectures.

My venture is called Karabo, and I've registered the company and website here: karabo.io. I will probably write about it more, as time goes on.

Workbench + TypeScript

Mon, 26 Aug 2024 00:00:00 GMT

Prologue

When I started writing GTK apps (GTK is a cross-platform toolkit for creating graphical user interfaces. Particularly common with Linux app developers), I noticed that writing apps was noticeably more difficult.

From the perspective of a web developer: Writing desktop apps is hard. Not entirely because the languages used in writing desktop apps are harder, but I'd argue that it's because of the accomodations and tools web developers have at their disposal.

TypeScript

One of such tools that help massively with developer experience in the web development world is TypeScript. It's a programming language introduced by Microsoft in 2012. It's a superset of JavaScript, but adds static types with optional type annotations.

This means at a basic level it's just JavaScript, with the added possibility of adding types to your variables and parameters. So if you had code like this

function sayHello(name) {
  console.log(`Hello ${name}. Your name is ${name.length} characters long.`);
}

It would instead become:

// Notice the `: string`
function sayHello(name: string) {
  console.log(`Hello ${name}. Your name is ${name.length} characters long.`);
}

For platform developers, this looks seemingly normal, as most of the languages they use are probably already typed (C, C++, Rust, and more). But for JavaScript developers, this was a very novel idea and as you can probably guess, it reduces the bugs you write in the first place by a huge margin.

In the example above, in the JavaScript code you could pass a number instead of a string to the sayHello function. JavaScript will happily execute that, but then you will run into bugs sooner or later.

sayHello(12);
// Hello 12. Your name is undefined characters long.

TypeScript will easily catch these errors, though:

sayHello(12);
// ts: Argument of type 'number' is not assignable to parameter of type 'string'.

This is just the surface of what's available with TypeScript, but at this point I think you and me both can see how it massively improves the developer's experience.

Developing Desktop apps is hard

Now writing desktop apps is hard. Usually, developers use languages like C to write apps. One of the first shortcomings I found is that when you are writing apps this way, you first need to write the desired changes, compile your app and then run the app to see your changes. This is in sharp contrast with the way web development works. There is a neat feature called Hot Module Replacement where the compiler will replace the changed modules in your code while the application is running, without reloading anything. We don't (AFAIK) have this feature in GTK app development yet (this was actually supposed to be my other proposal) but we can achieve something similar with a neat little app called Workbench.

Workbench

Workbench is an app that simply allows you to write the UI interface of your app, write some accompanying behavior code and with a simple click of the "Run" button, the UI you are iterating on becomes readily available. When you are done working on this particular piece of UI, you are supposed to copy the code you've written into your application, knowing the code will work and hence skipping the complex iteration loops.

I've used Workbench quite consistently while working on my GTK applications. GTK (and the underlying libraries) are quite awesome because they allow you to write apps in a number of different languages (called language bindings). And you can write GTK apps using your favourite language, whether it's JavaScript, Rust, C, C++, Python and more. Since I was coming from web development, I chose to use JavaScript for writing GTK apps as it was quite familiar to me already.

TypeScript with GTK

But in the GTK app development ecosystem, there was a growing interest to write apps in TypeScript instead of JavaScript where possible, and I was intrigued as well. I started using TypeScript instead of JavaScript for my apps, and loved it. There was one piece missing however, Workbench, the code playground, still did not support TypeScript. To make my TypeScript code work in Workbench, I used to compile the TypeScript code into JavaScript, put it in Workbench, then rewrite the code back into TypeScript for my app. Very inconvinient.

At some time, I began talking with Sonny Piers, and we began talking about possibly adding TypeScript support to Workbench, to allow developers to use the language rapidly gaining foothold in the GNOME/GTK app development arena. This would also help welcome new developers into GNOME, as more and more web developers are familiar with TypeScript and would provide a familiar platform language to them.

GSoC

With that in mind, I wrote a Google Summer of Code proposal titled "Add TypeScript Support to Workbench". As early as hitting the "Send" button, I started working on the project.

Adding the TypeScript View to Workbench

The first task I ever did was to add an option for "TypeScript" in the Workbench app. This was relatively simple enough in the sense that all it did was add an option to the dropdown at the top allowing the user to select "TypeScript" as their preferred language.

I used the pre-existing TypeScript SDK Extension written Christopher Davis. This SDK Extension provided the tsc (TypeScript Compiler) and typescript-language-server executables to the Flatpak environment Workbench works in.

Compiling the TypeScript to JavaScript

Even though there was a TypeScript View, the TypeScript code you entered was simply interpreted as Javascript. This means that you were not able to use TypeScript language features just yet, and hence the next step to implement would be to compile TypeScript into JavaScript and then execute the JavaScript code when you clicked the "Run" button.

This was all trivial thanks to the aforementioned TypeScript SDK Extension. All we had to do was:

Write the TypeScript code into a main.ts file.
Compile the TypeScript code into a main.js file using tsc.
Import the main.js file and then execute it.

With this in place, we had real support for running TypeScript in Workbench.

Adding GObject modules types

With that set in place, there was still an issue, and that, the types of GObject modules.

GObject, or the GLib Object System is is a library providing a portable object system and transparent cross-language interoperability. GObject Introspection (GI or GIR) is a related library providing access to typelibs and introspection data which describes C APIs.

Essentialy, this system provides a way to import and use "modules" in many languages. Gtk and many other related libraries like GLib, Pango, Gio are all GI modules and you import them to use them. For example, here is how you create a Gtk Label in GJS (GNOME JavaScript):

import Gtk from "gi://Gtk?version=4.0";

const label = new Gtk.Label({
  label: "Hello, World!",
});

// present the label

For TypeScript to be useful, we need to provide "TypeScript definition files" (.d.ts) that will essentially tell us the type of the gi://Gtk?version=4.0 and other imports. Because these files must be statically available, we need a way to source them.

`gi.ts`

Thankfully for us, there was a project named gi.ts by Evan Welsh that did exactly that. It was a binary that you would execute and point it to a GIR file, say /usr/share/gir-1.0/Gtk-4.0.gir and then it would generate the TypeScript definition files (gtk4.d.ts) and all their dependencies as we needed.

`gi-typescript-definitions`

Christopher Davis then created a repository called gi-typescript-definitions where they would regenerate the typescript definition files regularly, and we would consume the definition files instead of regenerating them ourselves.

Adding the TypeScript generation files to Workbench

I hence added gi-typescript-definitions as a submodule in Workbench, and pointed the typescript compiler to these definition files. And with everything all together, we now had Typechecking in Workbench and as a side effect, we had diagnostics and completions too!!

Typechecking with JavaScript??

As it turns out, we could use the new features (diagnostics and completions) from TypeScript in JavaScript! This is by using a special jsconfig.json file and using the aforementioned typescript-language-server for JavaScript files too, which it supports.

This means we got similar diagnostics and completions even for JavaScript!!

`ts-for-gir`

Remember the tool named gi.ts used to generate typescript definition files I talked about earlier, turns out there is an exceedingly similar tool named ts-for-gir by Pascal Garber that does the same thing!!

After the developers of both tools noticed the other one, they started working on marrying the two projects together and called the resulting project ts-for-gir v4, which is still in beta at the time of writing.

I knew that I had to start working on a way to use types generated by this new version of ts-for-gir instead of relying on gi.ts, which has now been archived and hence not receiving updates. So I now have a draft PR that switches from gi.ts to ts-for-gir, but the question of how we generate the typescript definition files is still unsolved because if you remember correctly, we were using pregenerated typescript definition files from gi-typescript-definitions and now we will need to generate them ourselves in Workbench. Unfortunately, there is currently an issue blocking this, but hopefully it will be resolved soon.

Porting the demos

Workbench has a huge library of demos, which I would also like to recommend the next time you need to familiarise yourself with how a certain platform feature works. The demos library has different code samples in various languages: JavaScript, Vala, Rust and Python.

My work would hence be incomplete without porting all the JavaScript demos to TypeScript, a noticeably complex task that is currently ongoing.

Because TypeScript compiles into JavaScript, we chose to remove all JavaScript demos and instead add TypeScript demos, and this way we can compile all the TypeScript demos into JavaScript at build time, and this way we get both TS and JS demos for the price of one. Pretty cool, right?

Wrapping up

I hope you enjoy the TypeScript support in Workbench that will hopefully be available in the next release, and start writing GNOME apps!! I also hope you liked this write-up I made about all this and don't hesitate to reach out to me if you have any questions or feedback.

Acknowledgements

I would like to thank Google Summer of Code for providing me with the opportunity of working on this, and the GNOME Foundation which administered the programme.

I would like to thank my mentors, Sonny Piers and Andy Holmes for providing me with unceasing feedback and guidance, I really appreaciate them!!

I would also like to thank Christopher Davis, for their early experimentations on working with TypeScript on GNOME, gi-typescript-definitions, the TypeScript SDK Extension and many many more. You're awesome!

I would also like to extend my thanks to Pascal Garber, for working on ts-for-gir, their feedback and putting up with me on my wild feature requests 😅.

Finally, let me thank all the other people that helped me in the internship, from Bharat, a fellow GSoCer to the whole GNOME community for helping me out when stuck.

Thank you everyone!

My Alpine Setup

Sun, 18 Feb 2024 00:00:00 GMT

This is a guide to install alpine, based on my own likings. It is a relatively easy install.

This installation guide is very inspired and based on Hugo's Installation Guide.

(Some) security considerations

This install is a bit more secure because it uses an encrypted filesystem (LUKS on top of LVM).

The whole is configured to work with UEFI + Secureboot, and the disk is automatically decrypted with the TPM (this secure chip inside your laptop) using Clevis, meaning, if you boot on your laptop, your file contents will be decrypted automatically. You will need to manually enter your password if the storage drive is used outside of your computer (evil maid attack).

To secure your laptop better, enable Secure Boot, and set a very strong BIOS/UEFI password.

A more secure approach would be to use something like systemd-homed that encrypts each user's home directory separately, but that requires systemd... There's a similar tool for alpine called pam_mount, but it's not compatible with home directories created with systemd-homed, and I haven't figured a very nice way to make it work on Alpine.

Setup the installer

Download the alpine installation disk from the Alpine downloads page, flash it to a USB and boot it up.

Configuring Alpine

Alpine has a very nice setup-alpine script that setups the Alpine installation. This is different from Arch where you'd need to do everything manually. We are going to do it to configure most stup, until we arrive to the Partitioning stage.

Keyboard: us.
Keyboard variation: us.
Hostname: name.vixalien.com.
Network adapter: wlan0.
Wifi network.
Wifi password.
IP address: dhcp.
Networks: done.
Manual network configuration: n.
root password: stronkpassword
Time zone: Africa/Kigali.
User account: alien. This user will automatically be a member of the wheel group, and has (by default) privileges to use doas (alpine's alternative to sudo).
The defaults are fine for all remaining steps.

Make Sure to stop the setup-alpine tool when they ask for disk, as we will do it manually.

Partitioning

Firstly, we will need to create a boot partition (aka EFI System Partition) to hold all our kernel information and bootloader (optional). Please make the partition 500 MB large, otherwise some distros like Fedora might refuse it, and the space might run out faster than you think if you decide to make backups of your UKIs or go distro-hopping, so 1GB is actually a better recommendation.

Then we are going to create an LVM partition that will be encrypted and have volumes for all our other partitions (alpine, home, swap...). I ('d) like to setup one partition called linux so it can be reused by my other linux installations.

Installing the necessary packages.

For partitioning, we will use gdisk. Let's also install other packages for ext4 and btrfs filesystems.

apk add lsblk gptfdisk btrfs-progs e2fsprogs

Activate the btrfs kernel module:

modprobe btrfs

cryptsetup is needed for LUKS encryption

apk add cryptsetup

LVM

apk add lvm2

Overwriting the disk

It might be a good idea to overwrite the disk using a tool like haveged to clear any leftover data.

TODO: there is probably an alternative for SSDs

Setup Disks

gdisk /dev/nvme0n1

Use n to create 2 partitions:

EFI partition. size: 512M. GUID: ef00 (EFI System Partition)
LVM partition. size: (leave blank). GUID: 8309 (Linux LUKS)

For more info about gdisk Hex codes see https://wiki.archlinux.org/title/GPT_fdisk#Partition_type

Populate /dev with new partitions:

partprobe /dev/nvme0n1

Identify your partitions

Find your partition names using lsblk:

NAME         MAJ:MIN RM   SIZE RO TYPE  MOUNTPOINTS
nvme0n1      259:0    0 511.9G  0 disk  
├─nvme0n1p1  259:1    0   500M  0 part  
└─nvme0n1p2  259:2    0 511.5M  0 part

In this case, /dev/nvme0n1p1 is the EFI partition, while /dev/nvme0n1p2 will be our LUKS partition.

Configuring LUKS

This step will ask for a password to encrypt your whole disk with. Remember it, and make it strong.

cryptsetup luksFormat /dev/nvme0n1p2

You might want to familiarise yourself with different LUKS options. I find the defaults okay.

Open the LUKS partition:

cryptsetup luksOpen /dev/nvme0n1p2 lvmcrypt

LVM Physical and Logical Volumes

Create a physical volume

pvcreate /dev/vg0/lvmcrypt

Create a virtual volume named vg0 (or something else, this one is memorable)

vgcreate vg0 /dev/vg0/lvmcrypt

Create partitions

Swap partition. I have a 32GB RAM laptop:

lvcreate -L 32G vg0 -n swap # I have a 32GB RAM laptop
lvcreate -L 50G vg0 -n alpine # root
lvcreate l 100%FREE vg0 -n home

Create file systems

mkfs.exfat /dev/nvme0n1p1
mkfs.btrfs /dev/vg0/alpine
mkfs.ext4 /dev/vg0/home

Activate swap

mkswap /dev/vg0/swap
swapon /dev/vg0/swap

Create Btrfs Subvolumes

Temporarily mount the alpine partition to create subvolumes.

mount /dev/vg0/alpine /mnt

Create the subvolumes adapted from Snapper's Suggested filesystem layout

btrfs subvolume create /mnt/@ # /
btrfs subvolume create /mnt/@var_log # /var/log

Find the id of the @ subvolume. Note it as <root-subvol-id>. It will probably be 256 or something.

btrfs subvolume list /mnt

Change the default subvolume to @ (Replace <root-subvol-id> with the ID you got from the previous step).

btrfs subvolume set-default <root-subvol-id> /

Unmount the partition

umount /mnt

Mount partitions

Create mountpoints and mount our partitions and subvolumes

mount /dev/vg0/alpine -o subvol=@ /mnt/

# Create mountpoints
mkdir -p /mnt/boot /mnt/boot /mnt/var/log

# Mount the remaining subvolumes
mount /dev/vg0/alpine -o subvol=@var_log /mnt/var/log

# Mount the efi system partition
mount /dev/nvme0n1p1 /mnt/boot

# Mount the home partition
mount /dev/vg0/home /mnt/home

Installation

Install a base alpine system

BOOTLOADER=none setup-disk -k edge /mnt

The BOOTLOADER=none tells the script to not install any bootloader (grub is the default), and -k edge tells the script to install the edge kernel instead of the lts one.

Chroot into the filesystem

chroot /mnt
mount -t proc proc /proc
mount -t devtmpfs dev /dev

Switch to the edge branch, and enable the community and testing repositories. This is done by editing /etc/apk/repositories and replacing its contents with:

http://dl-cdn.alpinelinux.org/alpine/edge/main
http://dl-cdn.alpinelinux.org/alpine/edge/community
http://dl-cdn.alpinelinux.org/alpine/edge/testing

You can choose a mirror closer to you if you want

Setup a local apk cache

I like having my downloaded apks available locally. In case I want to reinstall them or something... You can skip this step if you want a really minimal design. When prompted, say /var/cache/apk for the cache directory.

setup-apkcache

(No) bootloader

The next step would be to install a bootloader like GRUB or systemd-boot/gummiboot. However, we don't need one of them since we instead create a Unified Kernel Image (UKI) which can be directly booted by the UEFI firmware, hence removing the need for a traditional bootloader. A UKI contains the following, and some more:

The kernel itself
The kernel’s command line parameters
A small stub that execute the kernels with that command line
The initramfs (or initrd): a small read-only filesystem with the necessary userspace utilities to boot into the main system.

The stub itself is provided by the gummiboot-efistub package. It is considered deprecated, but no solid alternative is available. The bundle itself is built by efi-mkuki, and secureboot-hook will rebuild the bundle after each kernel upgrade.

apk add secureboot-hook gummiboot-efistub

Install blkid which will be used in a moment. This tool prints the UUID (and a few other details) for a specified partition. This is the recommended way to address a partition ambiguously:

apk add blkid

secureboot-hook

Edit /etc/kernel-hooks.d/secureboot.conf with the following contents.

cmdline=/etc/kernel/cmdline
signing_disabled=yes
output_dir="/boot/EFI/Linux"
output_name="alpine-linux-{flavor}.efi"

/<efi>/EFI/Linux is a more or less standard directory, and will be discovered by systemd-boot if you have that installed.

Signing is disabled only temporarily until I install the proper keys.

/etc/kernel/cmdline

Also create a file /etc/kernel/cmdline that will contain arguments passed to the kernel from the bootloader (UKI, in this case).

root=UUID=5021db58-cc3a-4829-a630-2d468f8d1761
rootflags=subvol=@
rootfstype=btrfs
cryptroot=UUID=0db973a0-1b95-4a23-a63f-cb6248fe2bf7
cryptdm=lvmcrypt
cryptkey
modules=sd-mod,btrfs,nvme
quiet
ro

The root UUID can be determined with:

blkid /dev/vg0/alpine >> /etc/kernel/cmdline

The cryptroot UUID:

blkid /dev/nvme0n1p2 >> /etc/kernel/cmdline

initrams

Edit /etc/mkinitfs/mkinitfs.conf to add features which are needed for our encrypted root setup to work. While editing this line, it is also safe to delete virtio, which is used only in virtual machines. Also add kms to enable kernel mode setting. These features will be included in the generated initramfs.

features="ata base ide scsi usb btrfs ext4 lvm kms keymap nvme cryptsetup cryptkey resume"
disable_trigger=yes

Boot Entry

We use efibootmgr to create a boot entry that (hopefully) shows in the EFI firmware, although you can always use the UFI's boot from file function or execute the UKI from a UEFI shell. I heard reports that the boot entries may disappear after firmware upgrades or other vendor EFI quirks, so bear that in mind.

First exit the chroot using exit. We can't use efibootmgr inside the chroot because it won't be able to read and set the EFI variables, mounted at /sys/firmware/efi/efivars. Then install efibootmgr:

apk add efibootmgr

Then create a boot entry named "Alpine Linux".

efibootmgr --disk /dev/nvme0n1 --part 1 --create --label 'Alpine Linux' --load /EFI/Linux/alpine-linux-edge.efi --verbose

Note: This procedure only needs to be done once; after that the Unified Kernel Image will be generated automatically every time the kernel is upgraded.

Finally, trigger the newly created kernel hook so that all the right files are copied into /boot

apk fix kernel-hooks

Hibernation

To setup hibernation, we'll first need to find the UUID of our swap partition:

lsblk -f

Edit the /etc/kernel/cmdline to let the system know where you will be resuming from.

resume=UUID=<UUID of /dev/vg0/swap>

Enable the swap service during boot:

rc-update add swap default

Install zzz and test hibernation

apk add zzz
zzz -Z # or ZZZ

You can now reboot and test your system

Desktop

Fonts

Installing the Noto fonts make almost every characters rendered (CJK and emoji):

apk add font-noto font-noto-cjk font-noto-extra font-noto-emoji

Install my preferred fonts

apk add font-jetbrains-mono font-liberation-serif

And configure fontconfig to use them at /etc/fonts/local.conf

<?xml version="1.0"?>
<!DOCTYPE fontconfig SYSTEM "fonts.dtd">
<fontconfig>
  <alias>
    <family>sans-serif</family>
    <prefer>
      <family>Cantarell</family>
    </prefer>
  </alias>
  <alias>
    <family>monospace</family>
    <prefer>
      <family>JetBrains Mono</family>
    </prefer>
  </alias>
  <alias>
    <family>serif</family>
    <prefer>
      <family>Liberation Serif</family>
    </prefer>
  </alias>
</fontconfig>

Snapper

Snapper is a tool to automatically or manually take snapshots of btrfs systems. I use it because I sometimes mess up my root system. Let's install it and setup up our first snapshot.

Remember: Snapshots are NOT backups.

apk add snapper

snapper -c root create-config /

This will create a new subvolume at /.snapshots. Each snapshot will be stored at /.snapshot/<snapshot-number>/snapshot. It will also add a new line to /etc/conf.d/snapper.

Create a first snapshot:

snapper -c config create --description 'Base Installation'

You can also use LVM snaphots, but that is an alternative I have not explored yet. It like a more interesting option tbf.

Enable & Start function

I like to have this function handy. It is synonymous to systemctl enable --now. You can put it in /etc/profile or somewhere

rc-init() {
  if [ $# -lt 1 ] || [ $# -gt 2 ]
  then
    >&2 echo "Invalid number of arguments provided (1-2 acceptable)"
    return 1
  fi

  RUNLEVEL="${2:-default}";
  rc-service $1 start
  rc-update add $1 $RUNLEVEL;
}

rc-deinit() {
  if [ $# -lt 1 ] || [ $# -gt 2 ]
  then
    >&2 echo "Invalid number of arguments provided (1-2 acceptable)"
    return 1
  fi

  RUNLEVEL="${2:-default}";
  rc-service $1 stop
  rc-update del $1 $RUNLEVEL;
}

GNOME

Setup the GNOME Desktop Environment (what I use, No I don't use sway or hyprland yet:))

setup-desktop gnome

Allow updates to be carried out in GNOME Software.

rc-init apk-polkit-server

Allow switching the power profiles in the quick settings

apk add power-profiles-daemon

If you have a convertible, allow turning your laptop to flip it

apk add iio-sensor-proxy

Hardware acceleration

apk add intel-media-driver

NetworkManager

Setup NetworkManager to manage your... network. Also setup WiFi and a TUI (nmtui). I also prefer using iwd instead of wpa_supplicant as the actual WiFi backend, since it's what I'm familiar with.

apk add networkmanager networkmanager-wifi networkmanager-wifi networkmanager-dnsmasq

I like to use this configuration:

[main] 
dhcp=internal
plugins=keyfile
dns=dnsmasq

[device]
wifi.scan-rand-mac-address=yes
wifi.backend=wpa_supplicant

[connectivity]
uri=http://nmcheck.gnome.org/check_network_status.txt

There are probably other configuration options to set.

Enable and activate the service:

rc-init networkmanager

Since we are now using NetworkManager to manage our connections, we can disable the default networking service.

rc-update del networking

You might also see that chronyd takes a while to sync on boot. We can tell it to do that in the background on boot instead by editing /etc/conf.d/chronyd and setting

FAST_STARTUP=yes

Bluetooth

apk add bluez bluez-openrc

Enable the Bluetooth experimental features to view the battery charge of your bluetooth earphones at /etc/bluetooth/main.conf

Experimental=True

Reboot or load the kernel module

modprobe btusb

Start & enable the bluetooth service

rc-service bluetooth start
rc-update add bluetooth default

Sound

By default, checking dmesg seems to indicate missing firmware:

> dmesg | grep firmw
[    1.096997] i915 0000:00:02.0: [drm] Finished loading DMC firmware i915/tgl_dmc_ver2_12.bin (v2.12)
[   36.239398] iwlwifi 0000:00:14.3: loaded firmware version 77.2df8986f.0 QuZ-a0-hr-b0-77.ucode op_mode iwlmvm
[   36.363387] Bluetooth: hci0: Minimum firmware build 1 week 10 2014
[   36.365863] Bluetooth: hci0: Found device firmware: intel/ibt-19-0-4.sfi
[   36.447917] sof-audio-pci-intel-tgl 0000:00:1f.3: Direct firmware load for intel/sof/sof-tgl.ri failed with error -2
[   36.447919] sof-audio-pci-intel-tgl 0000:00:1f.3: error: sof firmware file is missing, you might need to
[   36.447921] sof-audio-pci-intel-tgl 0000:00:1f.3: error: failed to load DSP firmware -2
[   36.714932] psmouse serio1: trackpoint: Elan TrackPoint firmware: 0xa1, buttons: 3/3
[   38.519487] Bluetooth: hci0: Waiting for firmware download to complete

apk add sof-firmware

Reboot or try to load the kernel module using the relevant soundcard name found using find /lib/modules/* -type f -name '*.zst' -name '*sof*' -name '*tgl':

modprobe sof-audio-pci-intel-tgl

Install PipeWire packages and friends.

apk pipewire wireplumber pipewire-pulse pipewire-alsa pipewire-spa-bluez gst-plugin-pipewire

Future considerations

Use Unl0kr
Use Clevis

References:

How River Works

Thu, 18 Jan 2024 00:00:00 GMT

The other day, I saw a mastodon post by Jakub Steiner (jimmac), a seasoned artist whom I well respect, about a site he's made to house his collection of arts. The website is hosted at https://art.jimmac.eu/ and I encourage you to visit the website to see the art for yourself.

While I'm fascinated by the art, I was even more fascinated by the website itself. It's a very minimalistic single-page app that shows a stream (grid) of images and allows you to click on each image to see it in full size. It's beautiful, and I've always been looking for a way to make something similar for myself, basically a way to show off a few of my photos.

source code

I learnt that Jakub has another similar site for his photos, https://photo.jimmac.eu/, and decided to check out the source code.

While checking out the implementation, I saw that the website(s) themselves are forked versions of photo-stream, a "home for your photos" initially created by maxvoltar.

photo-stream

photo-stream is a git repository that contains a jekyll site that shows the photos in a predefined location inside the git repo.

I was not the best fan of this approach, as I don't really like using git for non-code stuff (in this case images), as git repositories can get quite large if you put too many binaries in them. It was hence not a good fit for me, as where I live bandwidth is not cheap nor fast.

Hence, I decided a more sane and ingenious solution would be to utilise images stored somewhere else, and just show them in a nice format like Jakub's site.

vsco

I already have a VSCO account, and I've been using it as a more sane alternative to my Instagram, which is private. Basically I put images on VSCO that I want to be public, like landscapes or just random photos I take.

So I thought it would be a nice idea to use VSCO as a source of images for my photostream, instead of relying on a git-based workflow. This means that I can simply upload an image to my VSCO using the mobile app, and it will be instantly visible on my photostream.

It's important to note that in this case, VSCO is just an implementation detail, as I initially wanted to a less proprietary solution, like pixelfed, but I didn't have the time to explore the ecosystem and set it up, so I just went with VSCO (at the moment).

However, VSCO doesn't have an API, but since the website is a webapp and makes requests client-side, I can just inspect the network requests and see how the website gets the images.

reverse engineering

So now let's invoke the developer tools and look at how VSCO gets that crispy data about the images.

The website is a SSR webapp and that means it initally loads the pages (for example, the user profile) are initially generated by the server and returned as HTML. This means getting data from VSCO would require scraping the HTML and parsing it, which is not a very good idea.

However, we are lucky. If you then navigate to another page (say you click on an image), the website doesn't reload the page, but it makes a data client side request to an internal API which returns the data in JSON format. This means that we can get data for a user's profile by first making a request to a user's photo page (which is returned as HTML), and then clicking on the user's username to get the JSON data.

Using this method, it was easy to know some of the endpoints that the VSCO API provides.

vsco's API

By clicking around VSCO's website, you will see it making a view requests to it's API, and that's how I discovered a few of the endpoints needed to get the data I wanted.

Here are the details I found about VSCO's API:

base URL

The base URL for the API is https://vsco.co/api.

versions

When you inspect the requests, you will see that the API is versioned. There are 2 versions in use concurrently at the time of writing this article: v2 and v3. The 2 VSCO APIs seem to coexist and are both utilised by VSCO, buy they are incompatible. This means that some resources are only visible in v2 and some are only visible in v3.

It's very weird that VSCO uses 2 versions of the API at the same time, but it's what they do, and we have to deal with it.

authentication

If you try to make a request to the API normally, the API will deny you access and return a response with a 401 status code. This means that we need to authenticate (or identify) ourselves to the API.

Luckily, VSCO uses a simple token authentication scheme (also known as a bearer authentication). All the (web)apps need to do to gain access to the API is to include a special "token" that identifies them to the server.

Normally, other APIs use something more sophisticated, like OAuth to make sure each user has their own "token" or tokens, but VSCO doesn't do that and keeps the granularity of the tokens to the app level.

To provide the token, the apps provide a standard Authorization header in the request body. The header the auth-scheme of Bearer. This means that the full header looks like the following:

Authorization: Bearer <token>

Note that the <token> is a placeholder for the actual token, and for the purposes of this article, I will not be showing the actual token used, although you can easily get it by inspecting the requests made by the VSCO website or the VSCO Studio.

Some good news is that v2 and v3 both use the same token, so we don't have manage multiple tokens.

endpoints

After identifying how to connect to the API, I started looking at the endpoints and the kind of data they return.

`/2.0/sites?subdomain=<username>`

This endpoint returns the data about a user's profile. The subdomain query is used to identify the user. For example, if you want to get the data for the user vsco, you would make a request to /2.0/sites?subdomain=vsco.

The data returned by this endpoint is a bit too verbose, but there is really one field you need, which is the id field. This field is used to identify the user in other endpoints.

{
  "sites": [
    {
      // other fields hidden for brevity
      "description": "",
      "domain": "vsco.co/vsco",
      "externalLink": "",
      "name": "VSCO",
      "subdomain": "vsco",
      "id": 113950 // <-- this is the site id
    }
  ]
}

`/3.0/medias/profile?site_id=283527326&limit=14&cursor=`

This endpoint returns the data about a user's photos. This endpoint has a few query parameters:

site_id is the required user id of the user you want to get the photos of. This is the id field from the previous endpoint.
limit is the optional number of photos to return. The default is 10, and the maximum is 30.
cursor is the optional cursor to use to get the next page of photos. This is used for pagination, and is not needed for the first page.

The data returned by this endpoint is a bit too verbose, and I invite you to try it for yourself to get a complete response but here is a sample:

{
  "media": [
    {
      "type": "image",
      "image": {
        // some fields are hidden for brevity
        "_id": "IDOFIMG",
        "grid_name": "vsco",
        "adaptive_base": "/i/IDOFIMG",
        "site_id": 283527326,
        "site_profile_image_url": "i.vsco.co/IDOFIMG",
        "description": "",
        "description_anchored": "",
        "capture_date": 1705541060652,
        "capture_date_ms": 1705541060652,
        "upload_date": 1705541060652,
        "last_updated": 1705541060652,
        "permalink": "http://vsco.co/vsco/media/id",
        "share_link": "http://vsco.co/vsco/media/id?share=tracking",
        "responsive_url": "im.vsco.co/aws-us-west-2/blurb/etc/id/not-real.jpg",
        "image_meta": {
          "aperture": 0,
          "copyright": "Copyright 2024. All rights reserved.",
          "flash_mode": "Off, Did not fire",
          "iso": 0,
          "make": "Sony",
          "model": "ZV E-1",
          "shutter_speed": "128/100000",
          "white_balance": "Auto",
          "orientation": 1,
          "capture_date": 1705541060652,
          "flash_value": 10,
          "file_size": 1010000,
          "file_hash": "hash"
        },
        "height": 1000,
        "width": 100
      }
    },
    {
      // ... another image
    },
    {
      // ... yet another image
    }
  ],
  "next_cursor": "use-this-to-get-the-next-page-of-results"
}

I know that's a lot of data, but we only need a few fields from each media object:

image._id is the id of the image. This is used to identify each image uniquely.
image.responsive_url is the URL of the image. This is the URL we will use to get and display the image.
image.description is the user-provided caption of the image. May be used to show more context about the image.
image.capture_date is the timestamp of when the image was captured. This is used to sort the images by date. However, this field is not always present, so we will use the image.upload_date field if that's the case.
image.image_meta is the metadata of the image. This is used to show more context about the image.

That's actually all the endpoints we need to get the data we want. With this information in mind, we can now start building the webapp that shows the images.

I then build a minimal VSCO API client that can be used to get the data from VSCO.

webapp

The original photo-stream is a jekyll app. And by looking at the source code, jekyll looks like a very nice tool, but there are caveats that rendered the original app an unsuitable choice for me:

The git based workflow, as explained before, is not for me. You need to basically fork the repo, add your images, and then push the repo to GitHub and then GitHub pages will build the site for you. This means that you will need to maintain a fork of the repo, and I'd rather not.
I'm not even sure if GitHub pages will be able to build the site, and hosting providers that provide virtual machines are not my thing. I'd rather host my website on a serverless platform using JAMStack preferrably.

It was clear that I needed to build my own webapp, and in the ever-growing landscape of JavaScript frameworks, it was not easy to pick a choice. However, I ended up settling on Fresh, a preact framework optimised for Deno. This means that I can host the app on Deno Deploy and it will just work.

The webapp itself just fetches data from the API, and presents the images in a nice UI ~~stolen from~~ inspired by photo-stream. It's basically a re-implementation of photo-stream in TypeScript.

Of course, I have made some minor modifications to the UI, but mostly they are the same concept.

You can find the website's source code on GitHub.

flow

Now that the webapp is built, let's look at how exactly it gets the images.

Now, we don't have to add images to a git repo, so you might be wondering how exactly we get images for the photostream.

1. setup VSCO

You will need to create a VSCO account if you don't have one already. An account is free, although you can pay for a subscription to get more features.

2. clone river

You now need to make a clone of river, then clone the forked repo to your local machine.

git clone https://github.com/vixalien/river

2. get your site id

Remember that we use the site id (in contrast to username) to identify the user in the API. To get the site id, you need can run the following command in the root of the cloned app to know your site id. This is so we don't have to always fetch the site id from the API.

deno task get-id <username>

Remember to replace <username> with your username.

3. configure river

Now let's configure the app. You need to create a .env file in the root of the cloned app, and modify the configuration to your liking.

There is a .env.defaults file that contains all the possible configuration values. You can refer to the file to add configuration files as needed.

For example, here is the configuration of my site at https://memories.vixalien.com/:

# .env
TITLE=vixalienʼs memories
AUTHOR_NAME=vixalien
AUTHOR_WEBSITE=https://vixalien.com
DESCRIPTION=A few snapshots from a life that I probably lived.
URL=https://memories.vixalien.com
SHOW_RSS_FEED=0

ALLOW_ORDER_SORT_CHANGE=0

INSTAGRAM_USERNAME=username
CUSTOM_LINK_NAME=© 2024 vixalien
CUSTOM_LINK_URL=https://vixalien.com

# this is the only required configuration
USER_ID=281297126

Note that you should probably change the settings to reflect your own site. And the .env file is ignored by git, so you don't have to worry about accidentally committing it.

5. run

Now that you have configured the app, it's time to run it. Run the following command in the root of the cloned app:

deno task start

You should now have a local server running at http://localhost:8000/ that shows your photostream, similar to the following

4. deploy

Now that you have configured the app, you can deploy it to Deno Deploy or any other provider of your choice. I'll focus on Deno Deploy as it's the one I used, and is free for my use case.

Create an account at https://deno.com/deploy
Clone river to your GitHub account
Create a new project on Deno Deploy at https://dash.deno.com/new
Connect your forked repo to the project
Add configuration variables by going to Project > Settings > Environment Variables.
Visit your project's URL!!

conclusion

I hope you enjoyed this article. I know it's a bit long, but I wanted to explain this (useless) little project of mine deeply. The next step is to fix some items on the todo list add more features to the app.

On the wishlist is supporting other sources of images, like pixelfed and maybe even Instagram. I also want to add support for videos, but I don't have a use case for that yet.

If you already forgot, the source code of river is available on GitHub.

The source of the banner image is https://memories.vixalien.com

2022

Fri, 23 Dec 2022 00:00:00 GMT

Hello everyone! It's almost the end of the year 2022, and I hope you had a wonderful year. As we look ahead to 2023, I wish you an even better year ahead!

Overview

The past year was one of change, with many important events taking place around the world. Some of these events, such as the February Russian Invasion of Ukraine and the continued impact of COVID-19, had significant and far-reaching consequences. Other notable events included the global population reaching 8 billion people and the death of Queen Elizabeth II.

I won't be trying to list every single event that happened this year, but instead will focus on what happened in my own life and what I learned from it. I'll also interpret some events that happened and provide my thoughts on what may happen in the future. This blog post is divided into three sections: Personal, News, and Development.

Personal

In this section, I'll share some of the important events that happened for me this year, and my thoughts and feelings about them.

Graduating

I graduated from high school in August, and looking back, I realize that I'm going to miss school. It's not just about the fun and memories, but also about the people. I've made so many wonderful connections and experiences, and it's hard to think about moving on and starting a new chapter in my life. I know that I won't always have the same group of friends and colleagues, and that can be sad.

Work

After graduating, I started working at RWARRI, an NGO that helps people in poverty and refugees, as a web developer and IT specialist. It's been a challenging and busy year, with less time for personal pursuits, friends, and hobbies. But on the positive side, I've met some great people and gained some valuable experience in a work environment and with socializing.

Work Travel/Missions

As part of my job at RWARRI, I've had the opportunity to travel and meet people in different areas who are facing difficult circumstances. These experiences have really helped me appreciate how lucky we are, even when we have very little. It's easy to take our basic needs and comforts for granted, but seeing firsthand how others struggle to meet their basic needs has made me more grateful for what I have.

In addition to helping me appreciate what I have, these experiences have also reminded me of the importance of giving more than I receive. This can be as simple as volunteering my time or resources to help others, or simply being there to listen and offer support. As Jesus said:

It is more blessed to give than to receive. (Acts 20:35)

I've learned that these values are important not just in our personal lives, but also in our work and relationships with others. At RWARRI, we strive to serve others with compassion and generosity, and I feel fortunate to be a part of that mission. If you're interested in learning more about RWARRI and how you can get involved, you can visit their website here.

Money

All is vanity. (Ecclesiastes 1:1)

This verse reminds us that everything is fleeting and temporary, and that we shouldn't place too much value on material possessions. This is a lesson that I've learned more deeply this year as I've started working and earning a salary.

While I've never been one to care excessively about money, my work has given me a greater appreciation for the role that it plays in our lives. It's not just about being able to afford the things we want, but also about having the resources to meet our basic needs. Seeing others who struggle to put food on the table has made me more grateful for the financial security that I have.

At the same time, I've learned to be mindful about how I spend my money. I try to focus on buying the things that I really need, and save the rest for future needs. I think the key is to prioritize spending on important things and not get caught up in materialism.

University/College

I just received my results for my final exams a few days ago, and I'm happy to report that I passed. Now, I'm looking forward to the next stage of my education and considering my options for university or college. I'm hoping to secure a scholarship and, even more hopefully, study abroad. I know that university will be a different experience, with more challenges and demands, but I'm excited for the opportunity to learn and grow.

I'm still in the process of researching and deciding on a major, so if you have any useful tips or advice, please don't hesitate to reach out. I'm open to hearing from others who have gone through this process and can share their insights.

Digital Interactions

In today's world, it's almost impossible to avoid having digital interactions with others, whether through social media, group chats, or online communities like Discord or Matrix. While these platforms can be a great way to connect with others and share ideas, I've also learned that people can be more rude and vicious online than they would be in real life. This has led me to be more selective about who I engage with online, and to prioritize building trust and relationships in person.

That being said, I'm not suggesting that you should abandon your online friends or delete your social media accounts. But I do think it can be beneficial to limit your digital interactions and focus on more meaningful activities. It's easy to get sucked into the endless scroll of social media and waste valuable time that could be spent on things that are more meaningful and fulfilling. Next year, consider setting limits on your digital interactions and prioritizing face-to-face connections.

Depression

This year, I struggled with depression as a result of work-related stress and other events in my life. At times, I felt overwhelmed, lost all motivation and will to live, and struggled with impostor syndrome. These feelings were compounded by external events that made things worse. As a web developer, my productivity was severely impacted, and I found it difficult to complete tasks and contribute to my team.

Depression is a serious issue that can last for years or even a lifetime, and it's not something that can simply be brushed off or dismissed. Unfortunately, there are still many people who don't understand or take depression seriously, and this can make it harder for those who are struggling to get the support and help they need.

If you're struggling with depression, I encourage you to speak to someone about it. This could be a friend, family member, therapist, or healthcare professional. It's important to have someone to talk to and share your feelings with. For me, speaking out about my depression really helped, and it made a big difference to know that I wasn't alone. If you ever need someone to talk to, feel free to reach out to me.

There are also many other resources available to help with depression, including counseling, therapy, medication, and self-care techniques. It's important to find the right combination of treatments that work for you and to be proactive in seeking help. Remember, you don't have to suffer in silence – there is help and hope available.

Music

Music has always been an important part of my life, and this year was no different. I found myself constantly plugged into my earphones or headphones, listening to music to help me focus and stay motivated while programming or completing routine tasks. Music has a way of filling in the silence and providing a sense of calm and therapy, at least for me.

I've also been experimenting with using white noise to help me sleep better. A friend recommended rain sounds, and I have to say, they work wonders for me. If you have trouble sleeping, you might want to try incorporating some white noise into your bedtime routine.

In terms of music genres, I really enjoyed listening to amaPiano this year. I usually use Spotify, but I'm slowly switching over to YouTube Music. Here's a playlist with 10 tracks I can recommend easily.

Hobbies

This year, I discovered a new hobby: cycling. It's been a great activity for me, not only because it's fun and enjoyable, but also because it helps me stay fit and explore new places. If you're looking for a new hobby, I highly recommend giving cycling a try.

In addition to cycling, I've also been listening to a lot of informative podcasts and reading more this year. While I've enjoyed these activities, I haven't been able to practice my hobbies as much as I'd like due to work and other commitments. I'm hoping to have more time for my hobbies next year, and to find ways to balance work and leisure more effectively.

News/Opinions

In this section, I want to discuss some of the major events that happened in 2022 and share my (unprofessional) thoughts and opinions on them. Please keep in mind that some of these topics are sensitive, and I will try to be as neutral as possible.

Covid-19

The COVID-19 pandemic has had a significant impact on the world this year, and we are finally starting to see some progress in terms of vaccination efforts and returning to pre-COVID situations. While it's sad to think about all the time and opportunities that were lost during the pandemic, I'm hopeful that we are on the path to recovery and normalcy.

Russian Invasion of Ukraine

In February, Russia invaded Ukraine and sparked a conflict with other Western countries. While Ukraine has been able to resist Russia's efforts, thanks in part to support from NATO countries, the situation remains tense and unresolved. It's important to respect the sovereignty of all countries and to strive for peaceful relations with our neighbors.

One aspect of this conflict that has particularly concerned me is the treatment of Russian citizens. The war is largely being orchestrated by Putin and his allies, rather than the average Russian person. It's wrong to view all Russians as enemies and to discriminate against them, especially in fields like software development where Russian developers have faced job loss and account suspensions.

In my opinion, unity is always preferable to conflict, and war should be avoided at all costs. It's important to remember that ordinary people on both sides are affected by these conflicts, and we should strive for peaceful resolutions whenever possible.

Elon Musk's acquisition of Twitter

In 2022, Elon Musk made headlines when [he acquired Twitter for $44 billion][twitter-aquisiton]. This acquisition has had a significant impact on the social media platform and on the world at large. Musk has claimed that there were shady deals happening with the leadership of Twitter and the US government, and he has fired a significant number of employees (from around 7,500 to around 2,900).

The mass layoffs at Twitter have had a domino effect, with other companies following suit and also reducing their workforce. This has led to a decrease in demand for software development jobs and has caused many people to question if it's still a viable career path.

It's important to remember that these changes at Twitter and other companies have far-reaching consequences, and they can have a significant impact on the employment prospects of individuals in the tech industry. It's always a good idea to stay informed about developments in your field and to be proactive in building a strong career.

AI

This year, OpenAI released ChatGPT, an AI system that can engage in real-time conversation and provide almost-perfect answers to any question you ask. While this technology is impressive and has raised questions about the future of humanity and the potential dominance of AI, it's important to remember that it's still in its early stages and has limitations. For now, ChatGPT is available for free, but it's unclear how long that will remain the case.

OpenAI also released DALL-E 2, a deep learning model that can generate digital images based on natural language descriptions or "prompts." This model and others like it, such as Stable Diffusion and Midjourney, demonstrate the increasing power and capabilities of AI. However, the use of AI for image generation has also sparked a movement among artists who feel that their work has been used without their consent. This has led to a global conversation about the ethical implications of AI art and the need for consent and proper attribution.

Development

In this section, I want to share some of my thoughts and experiences as a web developer. This year, I've been interested in Linux systems, particularly GNOME and GTK, and have been exploring alternative technologies and approaches.

Contributions

This year, I discovered many open source libraries that I really enjoyed, especially those that I have used in my own projects. The scope of these libraries is quite broad, but some of the ones that stand out to me include:

Rabbet, a small link aggregator that I developed (similar to Linktr.ee)
Deno, an alternative runtime to Node.JS
Libvips, an image processing library

It's worth noting that, as a developer, it's often common to contribute to these types of libraries, especially if you rely on them in your daily work.

New Technology/Skills

I am in the process of rewriting a small link aggregator I made, Rabbet using Deno and hope it'll be ready early next year.

I also started using new software/alternatives:

Gitlab instead of Github (mainly for GNOME-related contributions)
Notion for note-taking, finance management, and more
Supabase, an open source alternative to Firebase
Linux, specifically Arch Linux as an alternative to Windows
Mastodon, an open source alternative to Twitter
and more I probably forgot...

Deno

One technology that I've been particularly excited about is Deno, a runtime for JavaScript and TypeScript that is an alternative to Node.JS. I've had a chance to work with Deno this year and have really enjoyed it. In fact, I even used Deno to rewrite my blog. Deno has matured significantly in recent years, and I think it has a bright future ahead of it. I've also attempted to create Deno bindings for GObject, a library for creating and using GObjects, which are used to create object-oriented code in C, with the goal of allowing GTK programs to be written with Deno. This project is called Geno.

GNOME Mobile

In the third quarter of this year, I lost my phone and had to purchase a new one. I was struck by the limited options available: it's either Android or iPhone. I believe that GNOME Mobile, a mobile operating system based on Linux, could bring significant improvements and potentially challenge the dominant players in the market. There are other Linux-based mobile OSes such as Plasma Mobile, sxmo, and others, but GNOME Mobile particularly caught my attention. I hope that it becomes a viable option in the future.

Developing with GTK

In addition to working with Deno and GObjects, I've also started learning to make GTK apps (using Vala, with the goal of learning Rust in the future). It's been an interesting journey, but one that has had its challenges, particularly the lack of good documentation. However, efforts are underway to improve the documentation, and I hope that it will become less of an issue in the near future.

Geno

Geno is a project I started to create GObject bindings for Deno. It is still in the early stages, but I hope to complete it soon and potentially create a GTK app with it.

Linux and the Community

I have been using GNU/Linux for some time now and have grown to really appreciate it. One of the best things about it is the community of people who share a passion for GNU/Linux. Many of the people who work on projects such as GNU, Linux, KDE, Fedora, Arch, and others related to GNU/Linux are not paid for their efforts. They do it because they are passionate about it and I think that is truly amazing.

In addition to the strong sense of community in the GNU/Linux world, it is also important to address the issue of mental health. If you are struggling with depression, it can be helpful to seek support from friends, family, or a mental health professional. There are also online resources and support groups available that can provide a sense of community and assistance during difficult times. It is important to remember that you are not alone and that help is available.

Closing

In conclusion, it is clear that the year 2022 has been a year of significant events and challenges, both globally and personally. From the impact of COVID-19 and the Russian invasion of Ukraine, to the release of powerful AI systems and the emergence of new technologies, it has been a year of change and adaptation. As we move into 2023, it will be important to continue learning and growing, and to prioritize the things that truly matter in our lives.

I finally wish you all a Merry Christmas and Happy new year!

<br/>

Banner Photo by Kelly Sikkema on Unsplash

Setting up React Cosmos in Remix

Mon, 22 Aug 2022 00:00:00 GMT

Hello friends!

As many of you might already know Remix is a framework to build websites. Much like Next.js, it's production-grade, but unlike Next, it is extremely robust, easy and considerate. If you didn't check it out already, now might be the time.

Remix 💔 Storybook

I was building an app using Remix, then as usual, I started writing some components like Buttons, Select, Forms etc. I wanted to prototype those components and view them in the browser as a way to speed up the development process using Storybook. But sadly, Storybook does not work on Remix. It's fine as long as you don't use some of Remix's provided components. This is because of the way Remix works, and that if you use Remix's features such as Link, NavLink or useTransition, you need to wrap your app in a certain Remix component. That Remix component doesn't in fact exist, and is just a combination of a React Context, Router (provided by react-router and config.) I'm sure if we try hard, we may be able to make it work on Storybook, but right now, I don't know of anyone who has figured it out yet.

Remix 💝 Cosmos

React Cosmos is yet another tool that aims to achieve exactly the same as Storybook. Given, it doesn't have the docs, community or polish of Storybook, but I had used it before and it worked exceptionally well. So I thought I might give it another try. I found Rasmus who already made Remix work with Cosmos. you can read his blog post as it explains what he did. I extended on his work to make it work better in my use case, and I hope it can be helpful for you too.

My approach

I based my work on Rasmus' and made some other modifications. Here is the full list of file changes.

Structure of changes:

.
├── .gitignore
├── cosmos.config.json
├── package.json
├── prod.cosmos.config.json
├── app
│   ├── components
│   │   └── cosmos.decorator.tsx
│   └── routes
│       └── cosmos.tsx
└── scripts
    └── generate-cosmos-userdeps

cosmos.config.json

{
  "staticPath": "public",
  "watchDirs": ["app"],
  "userDepsFilePath": "app/cosmos.userdeps.js",
  "experimentalRendererUrl": "http://localhost:3000/cosmos"
}

This file is pretty much self explanatory. It is Cosmos's config. I don't think the staticPath is necessary, because Cosmos doesn't inherently need it, but i haven't tested it yet, so there it is. The experimentalRendererUrl must match the URL you use for Remix in development, just add the /cosmos path, for which we'll create a page route soon. The userDepsFilePath is a file that is generated by Cosmos, and it outlines all the files that it uses (decorators, fixtures, config).

prod.cosmos.config.json

{
  "staticPath": "public",
  "watchDirs": ["app"],
  "userDepsFilePath": "app/cosmos.userdeps.js",
  "experimentalRendererUrl": "https://whereveryourappishosted:3000/cosmos"
}

This is almost a perfect clone of the cosmos.config.json, but notice the changed experimentalRendererUrl that points to wherever you app is hosted for production, this is important.

app/routes/cosmos.json

import { useCallback, useState } from "react";
import { useEffect } from "react";
import type { HeadersFunction } from "@remix-run/node";
import type { LinksFunction } from "@remix-run/node";

/// @ts-ignore - is generated everytime by cosmos
import { decorators, fixtures, rendererConfig } from "~/cosmos.userdeps.js";

// only load cosmos in the browser
const shouldLoadCosmos = typeof window !== "undefined";

// CORS: allow sites hosted on other URLs to access this one.
export const headers: HeadersFunction = () => {
  return { "Access-Control-Allow-Origin": "*" };
};

// mount the DOM renderer, notice it hydrates into `body`
function Cosmos() {
  const [cosmosLoaded, setCosmosLoaded] = useState(false);
  const loadRenderer = useCallback(async () => {
    /// @ts-ignore - works
    const { mountDomRenderer } = (await import("react-cosmos/dom")).default;
    mountDomRenderer({
      decorators,
      fixtures,
      rendererConfig: {
        ...rendererConfig,
        containerQuerySelector: "body",
      },
    } as any);
  }, []);

  useEffect(() => {
    if (shouldLoadCosmos && !cosmosLoaded) {
      loadRenderer();
      setCosmosLoaded(true);
    }
  }, [loadRenderer, cosmosLoaded]);

  return <div className="cosmos-container" />;
}

export default Cosmos;

This is almost the same as Rasmus's version.

app/components/cosmos.decorator.tsx

import { CustomApp } from "~/root";
import { MemoryRouter } from "react-router-dom";
import { useEffect, useState } from "react";
import { createTransitionManager } from "@remix-run/react/dist/transition";
import { LiveReload, Scripts, ScrollRestoration } from "@remix-run/react";

const clientRoutes = [
  {
    id: "idk",
    path: "idk",
    hasLoader: true,
    element: "",
    module: "",
    action: () => null,
  },
];

let context = {
  routeModules: { idk: { default: () => null } },
  manifest: {
    routes: {
      idk: {
        hasLoader: true,
        hasAction: false,
        hasCatchBoundary: false,
        hasErrorBoundary: false,
        id: "idk",
        module: "idk",
      },
    },
    entry: { imports: [], module: "" },
    url: "",
    version: "",
  },
  matches: [],
  clientRoutes,
  routeData: {},
  appState: {} as any,
  transitionManager: createTransitionManager({
    routes: clientRoutes,
    location: {
      key: "default",
      hash: "#hello",
      pathname: "/",
      search: "?a=b",
      state: {},
    },
    loaderData: {},
    onRedirect(to, state?) {
      console.log("redirected");
    },
  }),
};

const Decorator = ({ children }: { children: any }) => {
  const [result, setResult] = useState<any | null>(null);

  useEffect(() => {
    /// @ts-expect-error i swear to God importing is allowed
    import(
      /// @ts-expect-error Node expects CommonJS, but we're giving him ESM
      "@remix-run/react/dist/esm/components"
    ).then(
      (
        { RemixEntryContext }:
          typeof import("@remix-run/react/dist/components"),
      ) => {
        setResult(
          <RemixEntryContext.Provider value={context}>
            <MemoryRouter>
              {children}
              <ScrollRestoration />
              <Scripts />
              <LiveReload />
            </MemoryRouter>
          </RemixEntryContext.Provider>,
        );
      },
    );
  }, []);

  if (!result) return <>Loading...</>;

  if (result) return result;
};
export default Decorator;

This is the file that took me most of the time to implement. One drawback is that it only renders on the client, so Cosmos won't have SSR. It basically wraps around all other components in a directory deeper than it is app/components/** in this case. It wraps the provided children around inside a MemoryRouter which allows react-router specific things to work (such as Link or NavLink) It then wraps (decorates) that around in a RemixEntryContext Provider together with a very fake context (it was partially stolen from Remix test data).

scripts/generate-cosmos-userdeps.js

const { generateUserDepsModule } = require(
  "react-cosmos/dist/userDeps/generateUserDepsModule.js",
);
const { getCosmosConfigAtPath } = require(
  "react-cosmos/dist/config/getCosmosConfigAtPath",
);
const { join, relative, dirname } = require("path");
const { writeFileSync } = require("fs");

const config = getCosmosConfigAtPath(
  join(process.cwd(), "prod.cosmos.config.json"),
);

const userdeps = generateUserDepsModule({
  cosmosConfig: config,
  rendererConfig: {},
  relativeToDir: relative(process.cwd(), dirname(config.userDepsFilePath)),
});

writeFileSync(config.userDepsFilePath, userdeps);

This file generates the userDeps that I talked about earlier. There is no direct script to generate it on the CLI, but this works.

package.json

Here are some convinience scripts to build the mix.

{
  "private": true,
  "sideEffects": false,
  "scripts": {
    "build:remix": "remix build",
    "build:userdeps": "node scripts/generate-cosmos-userdeps.js",
    "build": "yarn build:userdeps && yarn build:remix",
    "dev": "remix dev",
    "start": "remix-serve build",
    "cosmos": "cosmos",
    "build:cosmos": "cosmos-export --config prod.cosmos.config.json",
    "start:cosmos": "serve cosmos-export"
  }
}

.gitignore

/app/cosmos.userdeps.js
/cosmos-export

Thanks for being with me today. One love!

Hello Deno Blog!

Sat, 20 Aug 2022 00:00:00 GMT

Hello! I'm back to blogging!

Today, I bring very exciting news!! I migrated my blog to Deno fully. And now it runs on the EDGE.

Preface

Deno is really a solid choice:

Deno is much faster than Node in practice (think time to build)
Deno is no longer a project in it's infancy
Amazing community, packages & docs (seriously, everything is documented)
Deno Deploy

I recommend you watch Ryan Dahl's talk about his dream stack, which inspired me to migrate my blog to Deno. Ryan is the creator of both Deno and NodeJS. He created Deno to try and fix the mistakes and regrets that have been made in NodeJS. Watch 10 Things I Regret About Node.js by Ryan Dahl, which is his legendary talk about him explaining the mistakes he made with NodeJS.

Plot

I decided to use the deno_blog package as it seems too easy to work with. It's also made by the Deno core team. For example, here is the entire configuration of Ryan Dahl's blog. It's just a single Javascript file and the other files are markdown and a few other static files such as images that all live in /posts.

import blog, { ga, redirects } from "https://deno.land/x/blog@0.3.3/blog.tsx";

blog({
  title: "Ryan Dahl",
  author: "Ryan Dahl",
  avatar: "./ry.jpg",
  avatarClass: "full",
  links: [
    { title: "Email", url: "mailto:ry@tinyclouds.org" },
    { title: "GitHub", url: "https://github.com/ry" },
  ],
  background: "#fff",
  middlewares: [
    ga("UA-91675022-1"),
    redirects({
      "iocp-links.html": "iocp_links",
      "rant.html": "rant",
    }),
  ],
});

In the beginning, I built the very same app using a similar configuration but I soon realised I'm too stubborn and need something more custom. Mainly because I had integrated too much with marked (which is a library that converts markdown to HTML) and Deno Blog uses gfm (Github Flavored Markdown). I know it's bad (fragmentation instead of contributing new features) but I forked deno_blog and made downstream changes because I thought this might be overkill comparing to the KISS nature of everything in Deno. I hence created my fork so that it can render my site exactly as it was before all while being open to being extended. Success!

Here is my current script (Notice the different import URL):

/** @jsx h */

import blog, {
  h,
  highlight,
  imageContainer,
} from "https://deno.land/x/vixalien_deno_blog@0.4.9/blog.tsx";

blog({
  author: "Angelo Verlain",
  title: "vixalien's blog",
  avatar: "favicon/maskable.webp",
  avatarClass: "border-none rounded-full",
  port: 3001,
  dateStyle: "medium",
  links: [
    { title: "Email", url: "mailto:hey@vixalien.com" },
    { title: "GitHub", url: "https://github.com/vixalien" },
    { title: "Twitter", url: "https://twitter.com/vixalientweets" },
    { title: "Resume.pdf", url: "/Resume.pdf", icon: <IconFile /> },
  ],
  canonicalUrl: Deno.env.get("URL"),
  description:
    `Hello! I'm Angelo Verlain, but you can call me vixalien. I am a web \
    developer. This is my website, a collection of projects and writings.`,
  middlewares: [await highlight(), await imageContainer()],
  headLinks: [
    {
      rel: "apple-touch-icon",
      sizes: "192x192",
      href: "/favicon/android-chrome-192x192.webp",
    },
    {
      rel: "icon",
      type: "image/webp",
      sizes: "192x192",
      href: "/favicon/android-chrome-192x192.webp",
    },
    {
      rel: "icon",
      type: "image/webp",
      sizes: "512x512",
      href: "/favicon/android-chrome-512x512.webp",
    },
    { rel: "manifest", href: "/manifest.json" },
    { rel: "shortcut icon", href: "/favicon.ico" },
    { href: "/css/app.css", rel: "stylesheet" },
  ],
  lang: "en-US",
});

function IconFile() {
  return (
    <svg
      width="1em"
      height="1em"
      stroke-width={2}
      stroke="currentColor"
      fill="none"
      stroke-linecap="round"
      stroke-linejoin="round"
      viewBox="0 0 24 24"
    >
      <path d="M0 0h24v24H0z" stroke="none" />
      <path d="M14 3v4a1 1 0 001 1h4" />
      <path d="M17 21H7a2 2 0 01-2-2V5a2 2 0 012-2h7l5 5v11a2 2 0 01-2 2zM9 9h1M9 13h6M9 17h6" />
    </svg>
  );
}

And all I need to do is run a single commad, then the app is live (INSTANT: NO COMPILATION).

deno run -A mod.tx

Then to push it to production, I just push to Github, at which point Deno Deploy pushes my script to no less than 30 locations worldwide (the real edge, 👀 Vercel) for free.

The source of my new website is hosted on Github on the deno branch.

Aftermath

Pictures are work 100 words right?

Layout

Before

After

Comment: No visible changes, but under the hood, everything changed.

Total Files

Before

After

Command: tree .

Comment: Deno uses significantly less files per project as dependencies are stored in central cache (~/.cache/deno). Node's node_modules caused it's demise.

Disk Usage

Before

After

Command: du -h .

Comment: Deno caches every single URL (compressed). If you run an app once, it's dependencies will be cached for the next time. Cache is stored in a central location so that multiple projects can reuse the cache which is not the case for Node

Performance

Before

After

Measured using Lighthouse.

Comment: Deno is almost always 2 times faster because there is good management of code on Deno(on my part) which causes only 2 requests to be served, but nevertheless it's quite amazing to see Deno win because the app deployed to Vercel is a static app whereas on Deno some actual JS code runs everytime a user hits a route. This is because Deno Deploy pushes to more than 30 locations for free so when you actually request a resource, it's fetched from the nearest data center unlike Vercel which routes all requests to Washington DC (in the free plan atleast).

Thanks for reading! Have a nice day!

Setup Git

Fri, 01 Apr 2022 00:00:00 GMT

After you've learnt the basics of Git, it's time to make Git your own by creating a workflow that suits you.

How to setup Git

This is my default setup

1. Install Git

Git has a high chance of being already installed on some systems. First run git version to see if it is installed and up-to-date.

brew install git # on macos

yay -S git # arch (or use pacman)
sudo apt install git # ubuntu
sudo dnf install git # fedora

# this guide is not really meant for windows but everything should work, go to https://git-scm.com/download/win to download git for windows

2. Update Git settings

Create a file called .gitconfig in your home directory. On Windows, it is C:\Users\username\.gitconfig.

# ~/.gitconfig
# Tell Git who you are
[user]
    email = email@domain.tld
    name = First Last Name
[push]
    default = current
	autoSetupRemote = true
[credential]
    helper = store
[alias]
    silly = commit --amend -a --no-edit
    tree = log --graph --pretty=format:'%Cred%h%Creset -%C(yellow)%d%Creset %s %Cgreen(%cr) %C(bold blue)<%an>%Creset%n' --abbrev-commit --date=relative --branches
    # logs
    lg1 = log --graph --abbrev-commit --decorate --format=format:'%C(bold blue)%h%C(reset) - %C(bold green)(%ar)%C(reset) %C(white)%s%C(reset) %C(dim white)- %an%C(reset)%C(bold yellow)%d%C(reset)' --all
    lg2 = log --graph --abbrev-commit --decorate --format=format:'%C(bold blue)%h%C(reset) - %C(bold cyan)%aD%C(reset) %C(bold green)(%ar)%C(reset)%C(bold yellow)%d%C(reset)%n''          %C(white)%s%C(reset) %C(dim white)- %an%C(reset)' --all
    lg = !"git lg1"
    adog = log --all --decorate --oneline --graph
[filter "lfs"]
    required = true
    clean = git-lfs clean -- %f
    smudge = git-lfs smudge -- %f
    process = git-lfs filter-process
# Set the default branch to main
[init]
    defaultBranch = main
[commit]
    verbose = true
[rebase]
    autoStash = true
    stat = true
[tag]
    forceSignAnnotated = true
[fetch]
    prune = true
[color]
    ui = true
[core]
      editor = flatpak run com.visualstudio.code -w

Github/GitLab/...

Git is decentralised, however, you usually need to host your files on a server somewhere to make them available to other people. Git Forges make it easy, and there are many options available, such as GitHub, GitLab, Forgejo, Bitbucket, and more. Here's how you can set up your local Git to work with your favorite forge correctly.

1. Using SSH

Your hosted git server will need to authenticate you. We use SSH, or Secure SHell to generate a pair of keys that will help establish the link to the server. One is a public key which means we can share it with anyone, while the other is a private key which means it needs to stay on the coumputer

1. Generate SSH keys

ssh-keygen -t ed25519 -f ~/.ssh/[filename] -C "[comment]"

Replace [filename] with the name of your forge, and add a comment to help you remember what this key is for. For example, here is how I'd generate a key for github:

ssh-keygen -t ed25519 -f ~/.ssh/github -C "email@domain.tld"

2. Copy the contents of the `[filename].pub`

For a reminder, it's located at ~/.ssh/[filename].pub.

3. Add your SSH to your forge

For convenience, here's how to add an SSH key to Github.

Go to your Github's Account Settings
On the sidebar, Click on "SSH and GPG keys".
Scroll and click on "New SSH Key".
Add a descriptive label and paste the text you had copied from the previous command and save.

4. Create an SSH config

Now, we need to create a config file that tells SSH which key to use for which domain at ~/.ssh/config

Host github.com
  HostName github.com
  IdentityFile ~/.ssh/github

Feel free to add even more domains for each forge.

5. Test SSH

To test SSH, run the following command:

ssh -T git@github.com

If you see something like the following, it worked:

Hi username! You've successfully authenticated, but Github does
not provide shell access.

Also, don't mind it if you see a message that says the authenticity of 'github.com' can't be established. It's normal, and once you trust the domain, SSH will remember that.

Now clone a repo using SSH by running your clone commands in the form:

git clone git@github.com:user/repo.git

2. Adding a GPG Key to your account.

You can show a Verified Badge or a blue tick next to your commits by setting up a GPG Key and using it to sign your commits. Commits made through the Github web interface are automatically signed.

1. Install gpg

brew install gpg # on macos
# it's usually preinstalled on linux
# on windows go to https://www.gnupg.org/download/

2. Generate a new GPG Key

To create a GPG key quickly:

gpg --quick-generate-key [email@domain.tld]

<pre class="not-code"> We need to generate a lot of random bytes. It is a good idea to perform some other action (type on the keyboard, move the mouse, utilize the disks) during the prime generation; this gives the random number generator a better chance to gain enough entropy. We need to generate a lot of random bytes. It is a good idea to perform some other action (type on the keyboard, move the mouse, utilize the disks) during the prime generation; this gives the random number generator a better chance to gain enough entropy. gpg: key <i><b><code>YOUR KEY WILL BE HERE</code></b></i> marked as ultimately trusted dgpg: revocation certificate stored as '/home/<i>USERNAME</i><wbr>/.gnupg/openpgp-revocs.d/RANDOM40CHARACTERSIDKWHYUREADINGTHISLMAO.rev' public and secret key created and signed.

pub rsa4096 2022-03-31 [SC] [expires: 2022-06-29] RANDOM40CHARACTERSIDKWHYUREADINGTHISLMAO uid <i>"Beautiful name (The comment you provided) <good@email.dne></i> sub rsa4096 2022-03-31 [E] [expires: 2022-06-29] </pre>

At this point you will be demanded to enter a password twice. Please remember it or save it somewhere (in a password manager, does paper still exist in the future?)

3. Export the key and add it to Github

Run the following command using the [KEY_ID] from the previous command to export your newly-created GPG key.

gpg --armor --export [KEY_ID]

This will generate a large block of text. In the following format.

-----BEGIN PGP PUBLIC KEY BLOCK-----
[SCRAMBLE]
-----END PGP PUBLIC KEY BLOCK-----

Copy the whole text including the comments.

As an example, here's how to add the key to Github.

Open Github
Go your settings
On the sidebar, Click on "SSH and GPG keys".
Scroll and click on "New GPG Key" in the "GPG" keys section. (Below the SSH section).
Paste the text you had copied from the previous command and save.

4. Configure Git to always sign commits

Now that you have GPG set up with Git, run the following commands to tell git to always sign your commits with your GPG key.

git config --global user.signingkey [KEY_ID]
git config --global commit.gpgsign true

If you do not enable commit.gpgsign you can always sign each commit individually by running git commit -S.

Now try and commit to one of your projects. And it should show a verified commit.

Troubleshooting

If you run into issues while on the last part and the response says the commit can't be verified, try running the following command.

echo "test" | gpg --clearsign

If it fails, set the GPG_TTY variable.

export GPG_TTY=$(tty)

Then try re-running the command and it should be successful.

It is also a good idea to kill the GPG client so that it asks for the password the first time.

gpgconf --kill all
gpg-agent --daemon

Sources

Building a blog with Explosiv

Sun, 19 Dec 2021 00:00:00 GMT

Earlier this year, I created Explosiv ↗, a lightweight & fast static site generator that allows pages to be built with JSX. This is a tutorial on how to build a functional blog with Explosiv.

Terminology

We'll first talk about how the blog will be built. You can directly jump to the programming part or directly view the source code of the final blog on Github.

What's in this blog?

The blog will be a simple one with room for improvement (I invite you to be creative.) It will simply render a homepage, an about page and a group of posts. That's it. We'll not be using any heavy styling or custom components library. Of course we'll use Explosiv to build the blog and we'll write the blog posts themselves in Markdown.

Explosiv?

Explosiv ↗ is a NodeJS framework that uses JSX to render pages. It transforms .jsx files into .html files. That is: you write code that uses components, run js etc and Explosiv convert them into native HTML ready to be displayed to your favorite web browser.

JSX?

JSX ↗ stands for XHTML in JSX and it allows you to write HTML inside JS files simplifying data binding. JSX was created by the React team and is famously used within React so if you come from React, Explosiv will be easy for you to understand because it uses that same loved JSX syntax. Here is an example of JSX syntax.

// JSX syntax is coool!
let Site = (data) => {
	return <div>Hello {data.name}!</div>
}

<details><summary>Why not use React instead? or NextJS? or Gatsby? - Rant</summary>

Why not use React instead? or NextJS? or Gatsby?

React is only a library. React is in the core of NextJS or Gatsby and they all use it to create their own opinionated way of rendering React pages into HTML pages.

NextJS ↗ is a framework created by Vercel and it provides many features to build very complex web apps: API Routes, Internationalisation, Analytics, Typescript, Image Optimization. It's many features means you can use it to create any type of website, from TikTok to Twitch to others ↗. However this means that it's also pretty bloated for simple websites like blogs where you end up not using much of the features. And the site ends up containing many and many JS files you'll not use and takes some time to load.

As you can see in the above screenshot from https://www.joshwcomeau.com/blog/how-i-built-my-blog. NextJS served more than 120 requests weighing 6 MBs in 13 seconds. Hmm??

Gatsby ↗ touts itself as a fast static site generator that also uses React. It is NOT fast ↗. It takes about 30 seconds to make a production build. Imagine what would happen if you customize your site. Plus there are also some features that I think are overkill like GraphQL integrations. I mean I get it, but I would like to install GraphQL as a plugin, not baked into my static site that won't use it

Markdown?

Markdown is a lightweight language that will convert plain text to formatted text. It's the language we'll use to write our own blog posts. It is used by bloggers, software developers and documentation writers. All those README.md files on GitHub are Markdown!. You can view the simple syntax of Markdown here:

# This is a heading

This is a paragraph wil _emphasized_ and **strongly emphasized** text. And this is [a link to Google](https://google.com)

1. This is an ordered list
2. Another list item
3. - A nested unordered list
   - Another list item.

This blog post you are reading is written in markdown too! You can view the source code here ↗.

Code

Explosiv is a NodeJS framework. That means you'll need to have NodeJS installed first. NodeJS comes with a package manager called npm and we'll use it to install Explosiv.

1. Install Explosiv

The first step is creating a folder for your blog. I used explosiv-blog for mine. Open the folder in your favorite shell (or command prompt or command line interface). You'll first need to initialize the folder as a NodeJS project.

npm init -y

NPM will generate a package.json that will be used to identify your app and manage your dependencies. The next step is to install Explosiv.

npm install explosiv

You're now ready to start building with Explosiv.

2. Create homepage and about page.

Now go ahead and create a folder called pages at the root of your project. This folder will hold all Explosiv pages.

Homepage

Create a file called index.js for our homepage. index is a special name as it denotes that this file will be the first one that the user sees when they visit our site for the first time. Add some simple JSX to our index page to show a warm welcome message to visitors of the blog.

// index.js
let Homepage = () => {
	return <>
		<Head>
			<title>my blog</title>
			<meta name="description" content="This is my own blog"/>
		</Head>
		<main>
    		<h1>Welcome to my blog</h1>
    		<p>This is my cool new blog built with Explosiv. <a href="/about">About Me</a></p>
    	</main>
	</>
};

export default Homepage;

We can now see how our site will look in the browser. Switch to your shell and run the following command.

Explosiv Development mode

npx explosiv dev

This will start Explosiv in Development Mode, build the app then serve it locally at http://localhost:3000. Visit the URL to view the homepage.

About Page

Create a file called about.js. This will be our about page and it will be accessible at /about on our website. Add some JSX for the about page as well.

// about.js
let About = () => {
	return <>
		<Head>
			<title>about my blog</title>
			<meta name="description" content="About my blog"/>
		</Head>
		<main>
    		<h1>About my blog</h1>
    		<p>Hey there! Welcome to my new blog built with Explosiv. Here you can find all my blog posts. <a href="/">Go back to homepage</a></p>
    	</main>
	</>
};

export default About;

Now go to http://localhost:3000/about to view the about page. Note that Explosiv automatically rebuilt the app because we started explosiv in development mode.

ProTip: Creating a page at pages/about.js is equivalent to creating one at pages/about/index.js.

3. Styling

Now the page looks a little bit ugly doesn't it? We can add CSS styles to make our site look nicer. We'll create a folder called public/ and create a stylesheet at public/app.css. Files in the public/ folder will be publicly accessible so you can visit http://localhost:3000/app.css to view the stylesheet.

/* public/app.css */
body {
  max-width: 600px;
  padding: 0 20px;
  margin: 0 auto;
  font-family: system-ui, -apple-system, "Segoe UI", "Roboto", "Ubuntu", "Cantarell", "Noto Sans", sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol", "Noto Color Emoji"
}

Now to allow Explosiv to include the above CSS, create a document file at pages/_document.js to customize the overall behavior of the blog.

// pages/_document.js
let Document = () => {
	return (<html lang="en">
		<head>
			<meta charset="utf-8"/>
			<meta name="viewport" content="width=device-width,initial-scale=1"/>
			<link rel="stylesheet" href="/app.css"/>
		</head>
		<body>
			<div class="root"></div>
		</body>
	</html>)
}

export default Document;

The _document.js file is a special one because it provides a wrapper to the whole site, hence it can be used to customize the site. Let's explain the components of this _document.js:

<html lang="en"> specify the language of our site.
<meta charset="utf-8"/> to specify the character set of our site to prevent incorrect renderings of our site's text.
<meta name="viewport"> to correctly scale the site for mobile users.
<link rel="stylesheet"> to allow web browsers to fetch our stylesheet.
<div class="root"></div> where the main page's content will be rendered.

You can now refresh http://localhost:3000 in your browser to see the updated page.

Now you know how to add custom styles, the limit is the sky. You can start to style your app this way. You can even use PostCSS or Stylus to build stylesheets faster.

4. Blog Posts

Writing the first blog post

Off to writing the real posts now. Create a blog post at blog/first-post.md:

---
title: My First Blog Post
description: "The first blog post to be created on this site."
created: 1639915508100
---

Hello people, a warm welcome to you. This is the first blog post on this site.

Note: Notice the block at the beginning of the file that starts and ends with ---. This is called Front Matter and is used to describe the blog posts like who wrote it, the title, when was it written etc. Also, be sure to update the created field to show the real time you created it. View time in terms of milliseconds after the UNIX epoch.

Showing the blog posts on the homepage

Now comes the part that requires us to be a little bit ingenious. We are going to show all the blog posts on the homepage and provide links to them.

First of all, we'll be installing 2 other dependencies to allow us deal with Markdown files.

npm install front-matter marked

front- matter: Allows use to parse page's front matter.
marked: Allows use to parse Markdown files into HTML.

We are going to write a script at src/posts.js that loads all blog posts then give us info about them.

// src/posts.js

// Import dependencies
let path = require("path");
let fs = require("fs");
let fm = require("front-matter");

// This function resolves where files or folders are relative to the `cwd` or current working directory.
let resolve = (...link) => path.resolve(process.cwd(), ...link);

// Where all our blog posts are stored
let blogsPath = resolve("blog");

let blogs = fs
    // Get all blog posts in the `blogsPath` folder.
	.readdirSync(blogsPath)
	.map((blog) => {
     	// Get the slug. i.e `first-post` from `first-post.md`
		let slug = blog.replace(/\.md$/, "");
		// And return an array of posts and their front matter
		// Example: [ "first-post", { title: "My First Blog Post", created: 1639915508100, description: "..." } ]
		return [
			slug,
			{ slug, ...fm(fs.readFileSync(resolve(blogsPath, blog), "utf8")).attributes },
		]
	})
	// Sort the blog posts by date created
	.sort(([_, a], [$, b]) => b.created - a.created);

// Export the posts as an object
module.exports = Object.fromEntries(blogs);

We are then going to display all blog posts on the homepage. To do this, we'll create a component at components/posts.js that uses the post data to display a list of info about posts.

// components/posts.js
// Load the posts as an object.
import postsJSON from "../src/posts";

let PostsCard = ({ ...props }) => {
    // Convert the posts object into an array.
	let posts = Object.entries(postsJSON)

	return (
		<p>
			<h2>Posts</h2>
			<div className="posts">
     			{/* Display the posts one by one */}
     			{/* Display each post's title, date of creation and description with a link to read the post */}
				{posts.map(([slug, { title, description, created }]) => (
					<p>
						<a href={"/post/" + slug}>{title} &rarr;</a><br/>
						<small>{new Date(created).toDateString()}</small><br/>
						<span>{description}</span>
					</p>
				))}
			</div>
		</p>
	);
};

export default PostsCard;

We'll then modify pages/index.js to show blog posts using the newly created component on the homepage.

// index.js
import PostsCard from "../components/posts.js";

let Homepage = () => {
	return <>
		<Head>
			<title>my blog</title>
			<meta name="description" content="This is my own blog"/>
		</Head>
		<main>
    		<h1>Welcome to my blog</h1>
    		<p>This is my cool new blog built with Explosiv. <a href="/about">About Me</a></p>
    		<PostsCard/>
    	</main>
	</>
};

export default Homepage;

At this point you can visit http://localhost:3000 to view the site in a web browser. Notice the list of posts

Showing the blog posts on their URLs

Yay!! Our blog can now show posts. But if you click on the link to read the blog post, you'll reach a 404 page. We are going to create a page that will render each blog post to allow readers to read it.

Meet dynamic pages

We would need to write each blog's page like /pages/post/first-blog.js and /pages/post/second-blog.js etc. However, there is a feature called Dynamic Pages that simplify the development of related pages. We will be creating one single dynamic page at /pages/post/[slug].js that will render each post according to the [slug] provided. For example, visiting /post/first-blog will render /pages/post/[slug].js with a slug that is equal to first-blog.

Note: You can change [slug] to any other name you like. For example [id] or [post]. However, it is important to enclose the slug in brackets ([]).

// pages/post/[slug].js

// Import dependencies, will be used later
import { promises as fs } from 'fs'
import path from 'path'
import matter from 'front-matter'
import { marked } from 'marked'

// The Post component will be used to render each post
const Post = ({ post }) => (
	<>
		{/* Add a HEAD that shows the title of the page and expose the description of the post */}
		<Head>
			<title>{post.attributes.title} - vixalien</title>
			<meta name="description" content={post.attributes.description} />
		</Head>
		<main>
			{/* Show a link to the homepage */}
			<div style={{marginTop:"20px"}}><a href="/">Homepage</a><br/><br/></div>
			<small>{new Date(post.attributes.created).toDateString()}</small>
			<h1>{post.attributes.title}</h1>
			<p>{post.attributes.description}</p>
			<div>===</div>
			<br/>
			{/* Render the post's content as HTML in an `article` tag */}
			<article html={post.content}/>
		</main>
	</>
)

export default Post;

`getPaths` and `getProps`

However, the above content is not enough for a dynamic page to work. For it to work correctly, we need to export 2 other functions beside the default export which is the main page JSX.

The first needed export is getPaths and it is used to determine the number of all acceptable paths (or slugs). For example, it can be used to allow /post/first-blog to be rendered and /post/unknown-post to return a 404 page (Not Found). In our case, it's pretty straightforward to know the range of acceptable slugs. We just read the blog folder and see which blog posts are there:

// Append to the end of `pages/post/[slug].js`
export const getPaths = async () => {
	// Read all files in the `blog` folder.
	const files = await fs.readdir(path.resolve('blog'))
	// Remove the training extensions like `.md` (remove the 3 last characters of filename)
	return files.map((filename) => filename.slice(0, filename.length - 3))
}

Now that we know what posts are there, we'll use getProps to read info about the post themselves given the slug. The getProps function is provided with a slug and use it to get information that will be passed to default export of the function (as props.)

// Append to the end of `pages/post/[slug].js`
export const getProps = async (slug) => {
	// Read the file named `slug`+.md in the `blog` directory with the utf-8 format.
	let post = await fs.readFile(path.join('blog', `${slug}.md`), 'utf-8')
	// uses the `front-matter` package to get the post's attributes.
	post = matter(post)

	// parse the post's body to get the raw HTML content.
	post.content = marked(post.body)
	// Return an object that will be passed onto the default page export.
	return { post }
}

Now visit http://localhost:3000/post/first-blog to read first-blog.

Final Steps

Now that you are done, here are a list of things you should do next.

Visit Explosiv on Github for docs, stars etc.
Host your site on Vercel
Provide feedback in Github Issues
View the source of this site, which is written with Explosiv as well.

How Rabbet Works

Fri, 17 Dec 2021 00:00:00 GMT

Rabbet is a very small and minimal app that allows users to create pages on the Internet with a set of URLs.

I will try my best to share how Rabbet works in this short write-up. You can try to browse the source to follow along the explanations.

Useful links:

Rabbet is a monorepo

Rabbet is built as a monorepo. That is, it is one repository (folder) but it contain other packages inside of it. The monorepo doesn't use any repo manager like Lerna or Yarn workspaces as the packages are not tightly coupled. The different packages are for different uses:

render: a simple library that consume pages as JSON and return rendered HTML ready to be used in pages or dash to preview pages.
db: a library that allows other packages to access the database where the users and pages are stored.
pages: the express app that serves the rabbet pages at [username].rabbet.me/[page-slug].
dash: a NextJS app that renders the Rabbet dashboard ↗ that serves as a front end that allows users to sign in and create pages.

Render

render was one of the hardest packages to create. The hardest part is that it has different templates so that a user can choose a template they choose.

Templates

TODO: Allow user to select template in Dashboard UI

Templates reside in the /templates directory. The default template is called Lnks. Templates favorably use React and Stylus to render HTML and CSS respectively. Because the render package is meant to be run in the browser, Templates can't access the filesystem. So the template is split into 2 files:

`metadata.js`

This file is run at build time and is used to get all files necessary using require statements. For example, Lnks use metadata.js to load it's JSX file (the one that will be used to render the page into HTML.) And the CSS file that will be used to style the rendered page.

const jsFn = require("./page.jsx").default;
const cssString = require('./style.css');

module.exports = async () => {
	return { cssString, jsFn };
}

`page.js`

This file is used to provide info about the template itself. It exports a JSON object with the following properties and a render function.

{
	"label": "lnks",
	"settings": [
		{
			"key": "show_rabbet",
			"label": "Show Powered by Rabbet",
			"description": "Show the text 'Powered by Rabbet' at the end of the page.",
			"type": "boolean", // can be boolean, number, string
			"default": true,
		}
	],
	render,
};

The settings property affect Settings related to the template itself.

The render function is a function that is fed the Page JSON and a meta attribute (which is the data returned from metadata.json.) The render function returns an object with properties that will be converted into HTML.

let render = (page, meta) => {
  return {
    title: "Sample page",
    about: "A sample page",
    scripts: [
      { src: "https://uri", type: "module" },
      { html: "console.log(\"Hello\")" },
      "https://uri",
      "console.log(\"Hello\")"
    ],
    links: [
      { href: "https://uri", rel: "stylesheet" },
      "https://uri"
    ],
    styles: [
      { html: 'body { color: "red" }' },
      'body { color: "red" } '
    ],
    html: "HTML"
  }
}

The html attribute is what will be in the body of the rendered page. The reason for styles, links and scripts is that the template may or may not need some scripts. For example, Lnks only use Lite Youtube scripts and external CSSs when the page's hero is a YouTube Embed.

DB

Note: All DB functions are expected to be promises.

This is the most trivial package of all. It provides an /init script that is called before any database operation (may be called multiple times.) It's main export is a file that provide a set of trivial operations such as:

DB operations.

get(COLLECTION, id): Get an item with given id from collection.
set(COLLECTION, id, data, merge = false): Update data for an item with given id from collection and whether to merge the new data with already exisiting data.
add(COLLECTION, data): Add an item with given data to collection. The id is inferred automatically.
query(COLLECTION, ...queries): Perform a set of queries on given collection.
deleteAll(COLLECTION, ...queries): Delete all records that match a set of queries on given collection.

A query is built with the exported where property. For example, to get all users who have the given username use:

import db from "@rabbet/db";

db.get("users", db.where("username", "==", "exampleusername"));

Account operations

In the future, all account operations will be moved to /account instead of the current default export.

getCurrentUser(): Get the logged in user or null.
getRealUser({ uid }): Get the real user's info (from the database) based on the uid returned from login.
onCurrentUserChange(callback): Calls the given callback when the current user changes (logged out, logged in, loaded, logged out remotely)

Note: Firebase take a while to initialize so when yu call getCurrentUser for the first time it will always return null. Rabbet doesn't use getCurrentUser but instead listen to the onCurrentUserChange to get a real result when the user has changed.

Example:

import db from "@rabbet/db";

let user = await dbgetCurrentUser();

Optimized Account operations

Optimized account operations are located at /account.

login {}: Currently an object with { withGoogle } that launchs a login dialog.
logout(): Logout from the current device.

Example:

import account from "@rabbet/db/account";

loginWithGoogleButton.addEventListener("click", account.login.withGoogle);
logoutButton.addEventListener("click", logout);

Pages

pages is a small Express app that resides at https://rabbet.me. It renders a page from the given url. You can always visit a test rabbet page ↗.

Assuming the root URL is rabbet.me, the pages app routes using the following rules:

[username].rabbet.me/[slug]: Return the page with given slug created by user with given username.
rabbet.me/: Redirects to Rabbet dashboard.
A 404 page with a link to the Rabbet dashboard when a resource isn't found.

Note: Pages doesn't currently use the db package but use a custom implementation that access the firebase API using URLs instead of a native driver (library) because it was thought to be faster. TODO: fix this.

Dash

This is the dashboard that appears to all visitors of the service. It allows users to log in and create accounts, create, modify and delete pages. It is a NextJS app.

The package has the following directory structure:

dash ├─ components: Components used throughout the app. ├─ lib: Useful libraries and tools. │ ├─ constants: Holds app constants. ├─ pages: Contains JSX files for the project. │ ├─ account: Pages related to user accounts' │ ├─ pages: Pages related to linkpages created by users │ ├─ home: Homepage: the site which the users see when not logged in. ├─ public: Static files ├─ partials: Reused high-level components ├─ schemas: Validation schemas for different objects ├─ stores: Zustand stores for different objects like user, pages etc. ├─ stylus: Stylus for the site that will be transcribed into CSS

</pre>

<br/>

If you've read this much, you might as well create a PR for a template. Inspirations: Orcd ↗ Linkfire ↗ Dev.page ↗

Learn Git!

Sun, 01 Aug 2021 00:00:00 GMT

So now you understand a certain programming language and coffee is your new best friend. But everywhere there is code, you see Git. They say a true developer must know Git and here you are, knowing nothing about Git, but longing to getting started.

I have to admit, Git is as complex as it is popular. However, you don't need to know all the 160+ commands of Git to do daily operations. Here is a short but comprehensive tutorial that will teach you the most used features of this world-famous version control system.

What is a Version Control System?

A Version Control System (VCS) is a system that track and manages changes to files. A project with a VCS is usually called a repository or repo for short.

A VCS allows you to have multiple versions of a project. To visualize the need for a VCS, imagine you are working on a new feature in a project, and a bug that needs to be fixed immediately is reported. With a VCS, you can easily create a new version of your repository, fix the bug, then return to the previous version when you are done fixing the bug. You can also see the different changes you've made in your repository over time and can easily rollback when a change is undesired or introduced a bug. If you also modify your files or lose them, you can restore your repository to the last saved snapshot.

What is Git?

Git is a version control system that manages a collection of files in a certain directory. Git is a Distributed Version Control System. This means Git does not rely on a central server to store all the versions of a project's files. Instead, every person "clones" a copy of a repository and get all the history and branches (more on that later) of the project. Although the original source code of a repository may be stored on a third-party hosting service like Github, any person can have their own copy of the project.

Git was created by Linus Torvalds in 2005 for development of the Linux kernel, with other kernel developers contributing to its initial development.

Installation

Note: You'll need to be able to work with the command line fluently before learning Git. Even though there are Git GUIs, Git itself is a command line application. If you don't understand the arts of the command line yet, you can check Tania's command line tutorial.

You can download Git for macOS, Windows, Linux or build it from source from the Official Git website.

When you are finished installing, you can check if git is installed by running the following code in your Terminal (or Command Prompt for windows).

git --version

If you see a result like the following, you are good to go.

git version 2.30.2.windows.1

Configuring Git

After you install Git, you will have to set some configurations. These include your name and email and are used to mark changes that you introduce in a repository. That way, people can see changes you made and contact you easi;y.

git config --global user.name "Firstname Lastname"
git config --global user.email username@email.com

The above commands tell Git your names and email. Remember to change Firstname Lastname and username@email.com to your own names and email respectively.

You can type the following command to check the saved config:

git config --list

And you may get results similar to this:

color.ui=auto
core.editor='C:\Program Files\Sublime Text 3\subl.exe' -w
core.symlinks=true
core.eol=lf
user.email=username@email.com
user.name=Firstname Lastname

Git workflow

Any git repository consists of 3 "trees" maintained by Git:

Working Directory: This is your folder with the actual files, the one you can see in File Explorer.
Index: This is a staging area where Git put files that you are going to commit soon. (i.e. changes that are going to be marked as a new version.) This is because there are certain files that you may want to mark as finished and won't change, while there are others you are still working on and don't want to be released in this version.
HEAD: This is a reference that points to the last commit you've made.

So you add files from the Working directory to the Index. As you work further, you can add more files to the Index or even remove (restore) files from the Index. When you are ready, you commit your changes. This will next generate a commit and a new HEAD that points to your last commit.

Working with repositories

In this tutorial, we will need a new blank directory to learn Git and follow along. You can create a new folder anywhere to start experimenting with Git. I created mine at D:\project.

Initializing a Git repository

By Initializing a Git repository, you convert an unversioned project to Git or as in our case, create a new empty repository. (Yep, you can now call your project a repository!) You will need to run the rest of the commands in the root of the project. You can type cd to see where you are now and check if it is indeed where you are planning to create a new repository.

git init

After initializing your git repository, you should see a message like: "Initialized empty Git repository in C:/project/.git/" to confirm that a new repo has been created successfully. Note that Git create a hidden folder called .git to store version and history data.

Tracking files

You will now need to create two files at the root of your project folder: index.html and style.css. You can use your favorite text editor (I ❤ Sublime Text) to save them to the root of your repository.

Checking the status of a repository

You can check the status of your local repository by using the git status command. You will use this command a lot while working with Git repositories.

git status

Output:

On branch main

No commits yet

Untracked files:
  (use "git add <file>..." to include in what will be committed)
        index.html
        style.css

nothing added to commit but untracked files present (use "git add" to track)

Note: On some older versions of Git, the main branch may be called master by default, this is normal. To change the name of the master branch to main, run: git checkout master then git branch -M main

Staging files

The output above tells us that Git knows there are new files in the Working Directory but they are not tracked (They are not part of our Git repo; Git is not tracking changes to them, yet). We have to stage the files using the git add command.

git add .

Adding/Staging the files put them to Git's Index.

The . (or *) tells git to add EVERYTHING to the repo.

You can also add a single file to the index at a time by using the git add <filename> syntax. git add index.html would add index.html only.

You could also add a range of files using the * (wildcard character). git add hello/* would add all files in the hello folder.

Committing changes

Let's check the status again with git status.

On branch main

No commits yet

Changes to be committed:
  (use "git rm --cached <file>..." to unstage)
        new file:   index.html
        new file:   style.css

We are now ready to commit the files (i.e. mark the changes we made a version).

git commit -m "Initial Commit"

Output:

[main (root-commit) 154dcd7] Initial Commit
 2 files changed, 2 insertions(+)
 create mode 100644 index.html
 create mode 100644 style.css

While committing, the option -m can be used to provide a commit message, in this case "Initial Commit". You are encouraged to always provide a descriptive commit message that show a gist of the changes you've made.

If you don't provide a commit message, Git will use the default editor, set in the installation process on Windows or otherwise Vim, which could be weird for users who don't know to use Vim because it shows a strange screen where you can no longer enter any commands. To quit Vim, press <kbd>ESC</kbd> and type :q! followed by <kbd>ENTER</kbd>. You can learn how to configure Git to use your favorite text editor.

Branches

Branches are used to develop features isolated from each other. The main branch (or master, depending on the version of Git) is the "default" branch when you create a repository. Use other branches for development and merge them back to the main branch upon completion.

Creating a new branch

In this project, we will be creating a new branch to add javascript. You use the git chekout -b <branch-name> syntax to add a new branch.

git checkout -b javascript

Switched to a new branch 'javascript'

Listing all branches

You can use the git branch command to list all branches in the current repository.

git branch

* javascript
  main

The current branch is highlighted in green and an asterisk is shown before it's name.

We can starting working on code in our new branch. Create a file called script.js. We can the use git status to view the state of our repo.

git status

On branch javascript
Untracked files:
  (use "git add <file>..." to include in what will be committed)
        script.js

nothing added to commit but untracked files present (use "git add" to track)

Notice that the output shows that we're on branch javascript and that script.js is untracked. We will need to add it to the Index.

git add .

Then commit.

git commit -m "Add script"

[javascript 355fad9] Add script
 1 file changed, 1 insertion(+)
 create mode 100644 script.js

Reviewing and Merging

When you are done implementing a feature in a branch, the only thing left is to merge it to the main branch. Merging is Git's way of taking a forked history (an independent line of that divergd from the current branch) and incorporating it the current branch. Merging allows you to "combine" different versions of code that diverged from a shared branch. We are going to merge code from the javascript branch back into the main branch.

We'll need to go back to the main branch first.

git checkout main

git diff

It is good practise to first review changes before merging or committing. You can use the git diff command (short for difference) to show changes between different revisions or paths. (You can use it to compare branches, commits and whatnots).

If you provide only one argument, Git shows the changes in your working tree relative to the named reference. You can use HEAD to compare it to the latest commit, or a branch name to compare it to the tip of a different branch, which is what we'll do here.

git diff javascript

diff --git a/script.js b/script.js
new file mode 100644
index 0000000..d7ac302
--- /dev/null
+++ b/script.js
@@ -0,0 +1 @@

git merge

After now reviewing the changes we are about to merge, it's time we merge the actual changes back into the main branch.

git merge javascript

Updating 154dcd7..355fad9
Fast-forward
 script.js | 1 +
 1 file changed, 1 insertion(+)
 create mode 100644 script.js

After the branch is merged successfully, we can now delete the javascript branch because it is no longer needed.

git branch -d javascript

Git tries to auto-merge changes. Unfortunately, this is not always possible and results in conflicts. You are responsible to merge those conflicts manually by editing the files shown by git. After changing, you need to mark them as merged with git add <filename> before merging changes.

Logging

You can type git log see the repository's history and confirm that the branch has been merged.

commit 355fad97c2d442bb4a307385bfd6bac2198e825d (HEAD -> main)
Author: Firstname Lastname <username@email.com>
Date:   Sun Aug 1 15:35:31 2021 +0200

    Add script

commit 154dcd7ce38589eb903346f6996e810401fa4910
Author: Firstname Lastname <username@email.com>
Date:   Sun Aug 1 15:07:37 2021 +0200

    Initial Commit

Because git feeds git log results to a pager, you may need to press q when the log is too long.

You can add a lot of parameters to make the log look like what you want. Here are a few examples:

To see only the commits of a certain author: git log --author=alice
To see a very compressed log where each commit is one line: git log --pretty=oneline
Or maybe you want to see an ASCII art tree of all the branches, decorated with the names of tags and branches: git log --graph --oneline --decorate --all
See only which files have changed: git log --name-status

These are just a few of the possible parameters you can use. For more, see git log --help

The End

You are now mostly ready to contribute to projects while using Git to track your projects. Although you must note that this is only a basic tutorial of Git and you still have more to learn namely working with remotes. Git is a very complex software and has more than 160 commands but it's amazing how you don't have to know even a half to contribute to open source projects and track your project's progress. You'll know more git commands naturally as you become more experienced with Git and when the need for them comes.

Resources

Let it snow!

Sun, 31 Jan 2021 00:00:00 GMT

Easter egg: Run this page with #snow at the end

🌨⛄ Do you like snow? Does it snow in your region? Are we in December yet?

We are going to create virtual snow using the chilly Web Animations API.

A snowflake!

First and foremost, let's create a snowflake! Our snowflake will be loaded as an .svg file provided by the beautiful Ionicons.

Loading the snowflake

You can store it as a local file then load it as SVG, or use it from Ionicon's library, but we will be storing it as a string.

let svg_str = `<!-- snowflake svg text here -->`;

Parsing the string into a DOM element

Then we'll use DOMParser to parse the string into an actual DOM element.

let snow = new DOMParser().parseFromString(svg_str, "text/xml").children[0];

Note: Because parseFromString returns a #document, we used .children[0] to get the <svg> element instead. (<svg> is equivalent to <html>.)

Setting the snowflake to float

Our snowflake is fixed (it doesn't scroll like other elements) and initially, it is placed just above the screen.

snow.style.position = "fixed";
snow.style.top = "-24px";

Creating a new snowflake

Because our page will have many snowflakes, we'll clone the snowflake we just created.

let newSnow = () => {
	let clonedSnow = snow.cloneNode(true);
	// we pass true to clone the node deeply (that is, with all it's children).
};

Note: from now on, our code will be in the newSnow function.

Next, we'll generate a random left position for that snowflake

let left = Math.floor(document.body.offsetWidth * Math.random());
// we use Math.floor to ensure left is an integer
clonedSnow.style.left = left + "px";

Then we'll just add it to the DOM

document.body.append(clonedSnow);

Animating the snowflake

Here we'll just use Web Animations API to animate an element. To use the API, we run element.animate(keyframes, options). You can read more in the MDN Page.

To make real snow effect, we will also generate a random speed (think the animation's duration)

let time = Math.max(10 * Math.random(), 5) * 1000;
// Math.max choose the largest argument it was given. By using it here, we restrict time to be larger than 5.

We will animate the snow to change it's top CSS property gradually. At the end, the element will be placed just below the viewport, where you can't see it.

let anim = clonedSnow.animate(
	{
		top: window.innerHeight + 24 + "px",
	},
	{ duration: time, fill: "forwards" }
);

One last thing, we'll do Garbage Collection. When the animation ends, delete that snowflake as it is no longer useful.

// garbage collection
anim.onfinish = el => el.target.effect.target.remove()

Now go ahead, in your console, run newSnow(). You'll see a snowflake falling slowly.

Snowing!!!

So far, we can only create snowflakes on demand by running newSnow() everytime we need it. What about we create a loop that create as many snowflakes as possible?

The problem with native JS loops

If you use for loops or while or whatever, it won't work. Why? It will create many snowflakes at a time. Your browser will be filled with snowflakes and unless you are on a supercomputer, your browser will crash, badly. This creates a need for a custom loop!

Looping asynchronously

Async Iterate

Here's an implementation of an async loop.

let asyncIterate = async (start, iterations, fn) => {
	// initialize the iterator
	let i = start;
	let call = res => fn(res)
		// waits for the function to resolves before calling the next iteration
		.then(async result => {
			if (i >= iterations) return result;
			i++
			return await call(i)
		});
	return await call(i);
}

It accepts 3 parameters. start is what the iterator is initialized as. iterations is pretty self-explanatory. it is the number of times the function will run. then fn is the function to execute.

It is important to remember that this is an async loop. That means, it will run the function, then waits that it resolves. then execute the next iteration.

wait

Next is the wait function. This is a wrapper around setTimeout. It waits some time (in milliseconds), then execute a function. (It is available on the npm registry as async-wait-then).

wait = time => new Promise(res => setTimeout(res, time))

Here is a simple example using wait.

wait(1000)
	.then(() => console.log('This will be logged after one second!'));

Using `wait` and `asyncIterate` to snow

By combining wait and asyncIterate, we get a powerful function set that uses the Promises API.

So, to create realistic snow (and prevent browser crashes) we'll have to wait before we create a snow element

asyncIterate(0, 10, async () => {
	await wait(1000)
	newSnow()
})

This will make it rain 10 snowflakes, but with an interval of 1 seconds between each snowflake

To make it look more realistic (and add some suspense), we will wait for a random amount of time instead of the static 1 second.

asyncIterate(0, 10, async () => {
	await wait(Math.max(3 * Math.random(), 1) * 300)
	newSnow()
})

But then, this will only create 10 snowflakes. Let's make it rain forever.

asyncIterate(0, Infinity, async () => {
	await wait(Math.max(3 * Math.random(), 1) * 300)
	newSnow()
})

The full code, complete with some optimizations is posted as Github Gist

How Explosiv Works

Thu, 28 Jan 2021 00:00:00 GMT

Explosiv npm ↗ Github ↗ is a static site generator for JSX content.

This article is about how Explosiv works, if you want to want to learn how to use Explosiv go to Explosiv's Github Page instead.

Why Explosiv was made.

While I was creating this blog, I thought.

About all the front-end options I had. Because, I was not going to write static HTML for a fully featured site! While I had already met stylus for all my CSS needs, I was still looking for an option to write my markup seamlessly.

React

TBH, I love React. It's syntax, it's community, it's everything really. Yet, React also put so much overhead on your site, like Build times, Babel, Webpack, hydrating or rendering etc. After some digging, I found out the foundation behind React was JSX, dubbed as XHTML within Javascript.

// JSX syntax is coool!
let Site = (data) => {
	return <div>Hello {data.name}!</div>
}

Well because JSX is tightly coupled with React, I kinda thought it would not work on it's own, but yet kartiknair made Dhow, which proved me otherwise.

Dhow

Dhow, is a static site generator, that uses JSX to render static HTML at build time, ready to be served as is. It is quick, very fast and still uses JSX, so migrating my app from React was a breeeeze. Until I encountered the severe limitations of Dhow.

Dhow was very young. That means It just implemented JSX, nothing else. Many features were lacking. While creating this site, I cloned Dhow. I found myself adding many features as I wanted. I saw it was incredible. I decided to push it to My Github as Explosiv

Explosiv

Explosiv, being a clone of Dhow, inherits all it's current features. Here is a simple example.

First, add explosiv to your site's dependencies.

npm i explosiv

And install explosiv globally, so that you can use the CLI wherever you are...

npm i explosiv -g

Or, to keep up with modern standards, although I personally like the first syntax more, use npx to always use the latest version of explosiv

npx explosiv

To make an Explosiv site, just create a folder and generate a pages/ directory. Add a simple index.js file to get started.

// pages/index.js
import Explosiv from 'explosiv'

export default () => (
	<main>
		<h1>Hello there!</h1>
		<p>
			This is a super simple example of generating static files using Explosiv.
			You can learn more at{' '}
			<a href="https://github.com/vixalien/explosiv">here</a>
		</p>
	</main>
)

To build, and serve, the site use:

explosiv build
explosiv serve

Et voìla! A static site was generated in your /out directory. Magic right!

How it works

You can learn how JSX works by this article from the React team.

You can read a very nice article by kartiknair, the creator of Dhow about converting JSX into HTML without React.

TL;DR: We use a pragma function that generate real DOM elements using a minimal DOM implementation, min-document.

// A general overview of how it works.
// !! Not real code
const document = require('min-document');

const createElement = (tag, props, ...children) => {
	const element = document.createElement(tag)

	children.forEach((child) => {
		element.appendChild(child)
	})

	return element
}

We transpile Javascript using ESBuild, a verrry fast, yet fully featured transpiler. We transpile the code in the pages directory from JSX into pure, native Javascript, while replacing all instances of JSX with our pragma function.

The transpiled file will look like this

// transpiled/index.js
let { createElement } = require('explosiv')

export default () => (
	createElement('main', null,
		createElement('h1', null, 'Hello there!'),
		createElement('p', null,
			'This is a super simple example of generating static files using Explosiv.',
			'You can learn more', ' ',
			createElement('a', {
				href: "https://github.com/vixalien/explosiv"
			}, 'here'
		),
	)
)

At the end we render our DOM into static HTML by using document.toString() and piping the output into the relevant output directory.

Impovements over Dhow

Explosiv, is a personal project. It is not a competitor, or even an alternative to Dhow, yet all current improvements are listed for anyone interested. Many of these can also be implemented in Dhow if worth it.

Provide an explosiv serve command that serve a static directory on a specified port (defaults to 3000).
Head elements are added on top of document.head instead of the bottom (allowing overriding existing tags)
Rewritten for build code to be independent and ease debugging
Does not use polka but the more minimal connect.
Use middleware deemed as useful like morgan which log all requests and compression which compress resources on HTTP.
Fixed bugs on edge cases like rendering <> (aka Fragment tags) as root elements and rendering empty children.
Added support for className HTML attribute.
Fixed bug where self-closing (like <img src="/path/to.img">) elements doesn't render correctly.
Use tabs instead of 4 spaces lol!
And other many but subtle changes.