Opensource Odyssey

Building a timeless tech stack

Tue, 16 Jul 2024 00:00:00 GMT

When learning technology, I've tried to seek out projects that will be around for a long time.

The origin story {#the-origin-story}

I used to be a Windows/MacOS user like you, but then I took an arrow to the knee.

Windows was the default. What I - and probably you - grew up with. Not a concious choice, just a matter of fact.

Then I "emanzipated" myself and "graduated" to MacOS. In the early 2010s, you were some kind of hipster if you used Apple. But the main selling point was the "it just works". However, after some years of being an Apple apostel, I was burnt. My MacBook Pro broke and my frustration with Apple grew.

So I looked elsewhere and my gaze fell onto GNU/Linux. I installed Linux Mint as my first distro on an older machine. Tough daunting, it wasn't so bad. And paired really well with my efforts of learning how to code and how computers work.

Proprietary software vs. open source software {#proprietary-software-vs-dot-open-source-software}

What really appealed to me with Linux was the open source nature.

This difference - that the codebase of the Linux Kernel is open source, while Windows and MacOS are not - became a litmus test for me. Why even bother with software, that I can't control? Am I an end-consumer that doesn't understand what is happening, or am I a sovereign individual?

If you don't control your tech-stack, your tech-stack controls you.

At first I was petrified: Which software do I use? But quickly found out that there is a whole ice-berg outside of the shiny, official app stores by the big companies. The landscape of open source is almost limitless. Because it is open, and there are no barriers to entry.

Moreover, open source software tends to be more robust and secure than proprietary software. Read more arguments in the amazing booklet "The cathedral and the bazaar".

Open source allows you to tinker and customize everything to your preferences. It is an immense increase in personal sovereignty.

Open source is hard to kill, because it only takes one lunatic to host the code.

In times where advertisements are everywhere and your data is the digital oil for 3rd parties, open source grants transparency. An open source codebase can be audited as to what is acutally going on behind the scenes.

Hard mode: Open source is not enough {#hard-mode-open-source-is-not-enough}

While open source has become a buzz word, it's important to know that not all open source is the same. Famously, Richard Stallman made the distinction between plain open source and free libre open source software (free as in freedom), aka FLOSS.

The emphazise with FLOSS software is the sovereignty of the user. This is the antithesis of the contemporary dominance of Silicon Valley and the creeping influence of Chinese tech companies.

Why yes, of course I FLOSS.

Running completly on FLOSS is significantly harder than just relying on FOSS. Some hardware drivers are proprietary, and if you want to avoid those, you will be significantly limited in the hardware you can use. Personally, I'm not religious about using only FLOSS. But if I can help it, FLOSS it is.

The tech stacks I chose {#the-tech-stacks-i-chose}

But enough with the abstract words. To me the tech that fulfills these requirements is:

The linux kernel: Thousands of contributors, has been around since the 90s, on countless devices (including servers and mobile)
The GNU utils: Learning these empowers you to use any UNIX system - super powerful and truly timeless
The Emacs editor: Invented by the Stallman himself, has been around since 70s, with a hardened community of power users
Vim motions: Vi has been around since the 70s and has a mode-based text-editing experience. With vim motions a text document becomes a different playing field. If this is new to you, then go watch this gem.
Nix: nix is many things, amongst others it is a functional programming language that allows you to specify packages and their configurations for your systems.

These are some examples of technologies that I invest my time in. Technologies that I learn with joy, because I know that learning these things will serve me for the rest of my life.

Yes, the road, especially initially, is hard. But it gets easier. Things actually make sense after a while.

Conclusion {#conclusion}

When you are at the cross-road to learn a new technology, ask yourself:

Is it open source?
Will it be around for a while?
Is it worth the time invest?

And have the courage to look elsewhere if you answered these questions with "no".

This simple principle will pay dividends as your knowledge grows.

hello world

Mon, 15 Jul 2024 00:00:00 GMT

My odyssey into the seas of open source software started a few years ago. Now, I want to use this site as an outlet to document this journey.

What to expect in this blog {#what-to-expect-in-this-blog}

This blog is for computer adventurers that like to take ownership of their tech stack.

Some things I try are pretty "niche". Like, using Emacs, using Linux (NixOS, to be precise) and having a keyboard-oriented productivity flow. It's not always easy to find resources on these topics. For myself, some of the best pointers I have found, have been on sites like this one. In other words, enthusiasts documenting their trials and errors.

An overview of what I'm enthusiastic about {#an-overview-of-what-i-m-enthusiastic-about}

Linux (namely NixOS)
Doom Emacs
Tiling window managers (currently using hyprland)
Shortcuts and keyboard-focused workflows
Coding (mostly typescript) for web-apps and CLI tools

My posts will cover these topics (and maybe more).

Join the odyssey {#join-the-odyssey}

This site offers RSS feeds - for all posts & for individual tags. You can subscribe to the RSS feed with the URL https://opensource-odyssey.net/index.xml or navigate to a tag and click the RSS icon next to it. This way you can be notified about new content and select what you are interested in.

Expect a true epic. An epic to gain mastery over technology and use it to your benefit.

Thanks for checking out this site! Enjoy the content and feel free to share!

My Linux Odyssey

Sat, 27 Jul 2024 00:00:00 GMT

<div class="heading">Table of Contents</div>

Phase I: Discovering Linux - Abandoning MacOS - The first Linux desktop - Distro hopping - From Debian-base to Manjaro - Gaming on Linux
Phase II: Tiling windows and dotfiles - Tiling window managers - QTile - Off the beaten path: Arco Linux - Establishing dotfiles
Phase III: Mastering Arch - Daring Arch - Learning how to solve problems - Versioning packages - Managing two systems
Phase IV: Declaring reproducibility - The final distro hop: NixOS - Settling on NixOS - Switching to Flakes - Killer feature: Generations
Phase V: Nix verstehen - Flexing the nix muscles - MVP: Vimjoyer
Epilog

</div>

OpenSource, for me, really began with Linux.

This is a long post. But then again, I am compressing 5 years of adventures.

Just sit back, get your tea and enjoy.

Phase I: Discovering Linux {#phase-i-discovering-linux}

Abandoning MacOS {#abandoning-macos}

Before Linux I used MacOS (and loved Apple). But my beloved MacBook broke - wouldn't charge anymore, not even on power supply. My attempts to repair left me a few hundred dollars lighter and with a broken MacBook. Frustration grew, a new solution was needed.

At the same time I started to code. One of the early lessons for any becoming coder is the UNIX philosophy. In short, building a program that does one thing, but really well, and that is modular to be used in combination with other such programs. The approach appealed to me and with nothing to lose, I installed Linux Mint on an older laptop.

The first Linux desktop {#the-first-linux-desktop}

"Flashing a boot-able usb-drive" sounds fancy, but it's not hard to do. With a simple Internet search anybody can do it. Downloading an ISO file also requires no skill. The installation process was plain simple and the default desktop charmed me. I made the decision then and there to keep walking this path.

Using Linux Mint as a daily driver took any angst and reservation. It really wasn't that complicated. Navigating the desktop felt intuitive, the user interface was beautiful and the performance was great. Doing all basic things like browsing and editing code files with VSCodium were a breeze.

Soon after familiarizing myself with the basics and getting my groove, I looked to the horizon: Distro hopping.

Distro hopping {#distro-hopping}

Distro hopping means installing another linux distro in hopes for a better computing experience.

Because... there are a lot of distros out there. How do you know you already found the best distro for you? Ubuntu with all it's flavors alone can be smothering.

But I tried them all anyway. Was I more of a KDE Plasma or Gnome type of person? Or maybe Budgie? Cinnamon? I learned that the desktop environment is something different than the distro.

A desktop is basically the look and feel of your computer. How the windows are decorated, how the cursor looks, the opening and closing animations, as well as some programs like a file finder, password key-chain etc. There is a ton of variants out there. All open source and free to use.

Keep the distinction in mind: A distro or distribution is a complete package of software packages and desktop environment.

I realized what I like is actually "making the computer mine". This allows me to have shortcuts to quickly open certain programs and be more productive.

Distro hopping is kind of a phase as you grow as a Linux user. But it's not all futile. It broadens your horizon and shows various approaches to solve the same issue.

From Debian-base to Manjaro {#from-debian-base-to-manjaro}

As I was distro hopping, "package managers" started to peek my interest.

A package manager is a program that manages which software is installed on your machine and with what version. The package manger handles installation of new software and system updates. On Ubuntu and Debian the package manager is apt, on Arch it is pacman etc.

Apparently with the arch package manager you could get access to something called "the A.U.R.". Apparently this would make life easier. And Manjaro delivered on that promise. It came with everything built in, supported Gnome and Plasma as desktop environments, and could enable the AUR.

During those times I gradually abandoned the graphic user interfaces (GUIs) and adopted the command line (CLI) more and more. First only to update the system, but then also to navigate the directory tree and tweaking with copy+paste snippets from the Internet.

Gaming on Linux {#gaming-on-linux}

Manjaro also had a great reputation for gaming support. Gaming was a thing I was still missing a bit. Granted, on MacOS the gaming department is also fairly limited. The Manjaro hardware detection tool (mhwd) would automatically install any NVIDIA driver or other for you. This worked great! Linux computing was getting easier.

With Lutris, I was even able to play League of Legends on the older computer!

So gaming was slowly coming around. Nowadays this is a non-issue. If "but I can game on Linux" is what's holding you back to switch to Linux, be assured: Almost any steam game now runs out of the box.

Valve, the company behind Steam, has since come out with the Steam Deck which runs on the Arch package manager.

Phase II: Tiling windows and dotfiles {#phase-ii-tiling-windows-and-dotfiles}

Tiling window managers {#tiling-window-managers}

If you don't know what that term means, good for you! Jokes aside, you know how a window opens when you double-click an application? Have you ever asked yourself how the size and position of that window is determined? Well, tiling window managers manage that.

Why would you want to worry about that? If you are a true keyboard warrior, your entire worth is measured in how little you have to touch a mouse to use a computer. Allegedly, if you keep the hands over your keys at all time, you can actually work faster.

A window manager (short WM) arranges the window on your screens. A tiling window manager automatically arranges the windows in tiles on your desktop. This ensures maximum real-estate usage of the screen and alleviates the hustle of manually resizing windows.

QTile {#qtile}

I took that leap, dipped my toes into i3 and awesomewm, but landed on qtile. The reason was that Python was the only programming language I knew & QTile is written in Python. This was a great match, because I could practice programming on my own configuration! Also, it was again a declarative approach, which meant "re-installations" were easy.

QTile challenged me to solve small issues like the status bar myself. But it also empowered me to configure things exactly how I wanted.

What motivated me was the idea that my work will not be lost.

I am always building and improving.

But QTile on top of a Manjaro installation is... Well not ideal. Either you have an entire unused desktop environment installed, or you look elsewhere.

Off the beaten path: Arco Linux {#off-the-beaten-path-arco-linux}

The time with Manjaro and pacman came in handy. I could leverage the same packages on a more "headless" distro. After some research I found Arco linux.

Arco is cool, because it gives you an easy and customizable arch-base install. It allows for easy auto-install scripts and fit my need really well.

But Arco is not pure Arch. For some months this didn't bother me too much. But then, the nagging that I could not honestly say "I use arch, BTW" was too much. I had to dare the dreaded install.

Establishing dotfiles {#establishing-dotfiles}

With my existing use of doom emacs, I was no stranger to storing configuration in text files that are checked into a repo. So I consolidated my emacs configuration with my qtile configuration and some useful scripts and had my first dotfiles repo!

The gist is that you can keep all configuration files in a single place - and repo. With the gnu stow command the files can then be symlinked to their proper place. A very powerful workflow that I still use to this day for some stuff.

Phase III: Mastering Arch {#phase-iii-mastering-arch}

Daring Arch {#daring-arch}

Some consider Arch linux the pinnacle of GNU/Linux: Rolling release, AUR, most packages, you name it.

The Arch install was not that hard. But I do consider it a "rite of passage". Now I was finally part of the cool kids! And I would never distro hop again. Right!?

Learning how to solve problems {#learning-how-to-solve-problems}

In all honesty, the install and everything to do with Linux taught me how to approach problems and solve them. To this day I can't remember a single problem that I have not managed to solve. My process boils down to this: Try => fail => formulate hypothesis why it fails => research => tweak steps. Repeat.

Now, on that "research" part, the best resource I found was the arch wiki. It became the first site I would go to, to learn more about a particular aspect of the computer. Having such a "bible", a single place of knowledge, is invaluable.

Even if you are not using arch, the wiki may be able to help you out.

Versioning packages {#versioning-packages}

By now, the command line had become my bread and butter. Especially for administering the packages installed on my machine.

To discover new software I used paru. Not a complete stand-alone package manager, paru wraps pacman to ease the interaction with the AUR. It also comes with a great CLI search.

I also played around with aura, which actually is a stand-alone package manager that creates snapshots (like lock-files) of all packages installed. Aura can be used for creating more "reproducible" systems. For example if you want to keep to machines in sync in terms of the software they are running.

Managing two systems {#managing-two-systems}

I started having a work laptop. Of course this machine had to be configured the same as my personal machine. Thanks to the installation scripts and dotfiles I was quickly able to set it up. This was great! Just imagine on your first day of work to come in and for the first few hours wait as your computer is automatically installing everything you are used to.

As time progressed, I tried to keep my work and home laptop configured in sync. Things I configured on one system should also be available on the other.

But this was cumbersome. Merging the inevitably diverging git branches became an hour-long task. And even then, some configuration commands I did on one system I had forgotten on the other - a doomed endeavor.

But what could solve this problem? Could there be a better distro out there for me?

Phase IV: Declaring reproducibility {#phase-iv-declaring-reproducibility}

Yes. Yes, there could: NixOS.

The final distro hop: NixOS {#the-final-distro-hop-nixos}

A coding colleague brought it to my attention, as he was interested in it and knew about my excessive doom-emacs usage. HLissner, the creator and maintainer of doom is also a NixOS user. Henrik has this funny answer on his dotfiles repo:

Why NixOS?

Because managing a fleet of servers, a hundred strong, is the tenth circle of hell without a declarative, generational, and immutable single-source-of-truth configuration framework like NixOS.

Sure beats the nightmare of brittle capistrano/chef/puppet/ansible/shell scripts I left behind.

Should I use NixOS?

Short answer: no.

Long answer: no really. Don't.

Long long answer: I'm not kidding. Don't.

Unsigned long long answer: Alright alright. Here's why not:

Its learning curve is steep.

You will trial and error your way to enlightenment, if you survive the frustration long enough.

NixOS is unlike other Linux distros. Your issues will be unique and difficult to google. A decent grasp of Linux and your chosen services is a must, if only to distinguish Nix(OS) issues from Linux (or upstream) issues -- as well as to debug them or report them to the correct authority (and coherently).

If words like "declarative", "generational", and "immutable" don't put your sexuality in jeopardy, you're considering NixOS for the wrong reasons.

The overhead of managing a NixOS config will rarely pay for itself with 3 systems or fewer (perhaps another distro with nix on top would suit you better?).

Official documentation for Nix(OS) is vast, but shallow. Unofficial resources and example configs are sparse and tend toward too simple or too complex (and most are outdated). Case in point: this repo.

The Nix language is obtuse and its toolchain is not intuitive. Your experience will be infinitely worse if functional languages are alien to you, however, learning Nix is a must to do even a fraction of what makes NixOS worth the trouble.

If you need somebody else to tell you whether or not you need NixOS, you don't need NixOS.

If you're not discouraged by this, then you didn't need my advice in the first place. Stop procrastinating and try NixOS!

This intrigued me.

On a spare laptop I gave it a try. The installation of NixOS was super easy. But I had acquired some particular tastes: QTile. Configuring python dependencies for NixOS is still a daunting task for me, but after enough bashing my head against the wall it worked (with a nixpkgs overlay I believe).

Settling on NixOS {#settling-on-nixos}

The beauty of nix is that if you configure something on one system, you can reuse that configuration on another. So the work on the spare laptop could easily be translated to my home machine.

The entire configuration of my machine could now be checked into my dotfiles repository! Adding the work machine was also not that hard, granted I used duct-tape-based methods to make it all work.

But nix allowed me to rely on the software that is installed and how its configured. It took away the issue of forgetting to instruct my computer about a configuration, because I would declare the configuration in a text file.

Switching to Flakes {#switching-to-flakes}

Are they still experimental? Anyhow, flakes in nix are the future. When you are using them for a nix configuration, the flake creates a flake.lock alongside your flake.nix. This lock file pins a commit hash of the nixpkgs repository. With this commit hash you can actually reproduce the exact version of software across systems. Let that sink in.

Moreover, with a flakes setup you can have multiple machines share the same configuration in your repo. The system configuration can be modularized and so you can for example write a tool-belt.nix file that contains all the CLI tools you want to share across all computers.

Finally, I achieved the dream: my personal and work machine could share the same configuration. There was no more drift between the systems! I was able to also setup a home-server running with the same configuration and just omit all the desktop related packages.

Killer feature: Generations {#killer-feature-generations}

The real killer feature of NixOS is the generations. Every time you change something about the config, you create a new "atomic" snapshot of the software and its version at that point in time. In the background all packages are installed in the /nix/store and just symlinked into a profile. Yes, this bloats the disc some, but you can always garbage collect.

Simply: When you boot your machine, you are presented with the choice to roll back to any previous generation.

[dramatic pause]

Do you have any idea how many times I busted my setup and started from scratch - as in, usb-drive, wipe the machine, install fresh, run my scripts, configure everything... Do you have any idea?!

With Nix, this is a non-issue. Power off, roll back, you're good.

Damn.

Phase V: Nix verstehen {#phase-v-nix-verstehen}

Or in English: "understand noting". It's a double-entendre, because "nix" in German means "nothing", too.

The "Nix"-way of doing Linux is so different to what is already out there. But I believe that it's the "right" way to configuration. When it finally "clicks", for example when you build an existing configuration on a brand new machine and suddenly you are in your familiar environment, with everything down to the color scheme, font, shortcuts, bash aliases, wallpaper. In that moment you glimpse the greatness and potential of the Nix-way.

Flexing the nix muscles {#flexing-the-nix-muscles}

To show off a little what conveniences I now get to enjoy:

home-manager - declare the user-space

Home Manager can be what manages the user-space on your machine. So not on a system level, but user-level. You can use it even in non-NixOS setups - looking at you MacOS people.

All user installed software, services, configuration and more can be configured with home-manager. When using NixOS you can simply plug it in to your system configuration. It allows a much finer grained controlled of the user environment.

hyprland & waybar - a modern environment

QTile bit the dust when I tried to switch to wayland. Apparently it supports it, but I couldn't get it to work. Also, whenever QTile did break while tinkering, it left the system in a near-unusable state (learned about the tty this way).

Now my desktop environment - i.e. hyprland and some more packages, are declared in my flake. This is so cool!

When I find a cool waybar example from some other nix user, I can just copy+paste it!

nh - the nix helper

To have some visual sugar while updating the system, nh has you covered. Now, all you need is the nh os switch command, because nh takes the hostname of your machine and applies the same named flake part!

The YouTuber Vimjoyer has a video how to set it up.

stylix - theme everything

Ricing is usually only for folks that really have too much time on their hands (not excluding myself here). Because going through every single program and customizing the theme and get it right is nigh impossible.

What if there were a program that could do it all. Automatically.

Meet stylix.

This post is too long already, so just watch this video by Vimjoyer.

MVP: Vimjoyer {#mvp-vimjoyer}

Speaking of whom... His YouTube channel is so unbelievably helpful. If you are considering giving Nix a try, you must watch the videos. You will not get a more up-to-date, concise nix on-boarding.

Epilog {#epilog}

Told you I had some adventures...

What can we now take away from this? Personally, I learned that pursuing my ambitions pays off. As I build my timeless tech-stack there is only one way: up. No matter how difficult the problem, with the tried-and-true approach Try => fail => formulate hypothesis why it fails => research => tweak steps. Repeat. nothing is unachievable.

This process teaches you about the technology you use. You become the master of your system. Able to determine every little detail of the setup. Navigating the computer becomes muscle memory and you are free to focus on what really matters.

All of this was a long-winded way of saying:

Check out my rice 😎

Touching base, or: reverting to the default

Wed, 17 Jul 2024 00:00:00 GMT

I've been using Doom Emacs for a few years now. After picking it up, the configuration and customization via a text file (the config.el) caught my interest. It allows the config to grow organically, be checked into git, be versioned, breaking changes can easily be reverted and transfering the exact config to a new system becomes a non-issue.

As the yeas passed by, my config grew and grew. A lot of trial and error was still inside that I didn't bother to clean up. Then, the other week, I had an issue with my Emacs configuration and I re-installed Doom and just used the default configuration.

Dropping everything for the default config {#dropping-everything-for-the-default-config}

Quickly the realization dawned on me, that the default Doom config was much faster than my own aged configuration. And I decided to start over.

In other words, go through my existing file, only take the parts that are truly needed and leave out all of the rest.

This took my config from 588 lines to 196 (granted, not everything I used in my old config is in the new config). Importantly, I'm not really missing anything and noticed significant improvements in the default doom configuration. Like new packages being used as defaults etc.

Not only is the config file now much more readable, but the speed improvement is still there.

The default doom emacs configuration is really great.

Hitchhiking on the backs of masters {#hitchhiking-on-the-backs-of-masters}

Truth is that I'm not the brightest bulb in the shed.

Other people have thought much deeper about certain issues and have much more know-how how to solve them. Instead of re-inventing the wheel, have a look at what the state-of-the-art is.

Then just copy the state-of-the-art. Or at least take inspiration from it. Especially, if your original starting point was the "state-of-the-art".

Swimming with the swarm {#swimming-with-the-swarm}

I'm not one to go for what is the most popular: Not using Windows or MacOS, not using iOS or Google Android, not using Microsoft or Google products, etc.

This "swimming against the swarm" has its costs. Convenience mainly. Make no mistake, it also has it's upside, but it's a tough climb.

It's not about doing the opposite of what everybody else is doing. If it were, I would be using TempleOS. It's about having principles and within these confines picking the most viable solution. And swimming with the swarm of other individuals that have the same principles.

Conclusion {#conclusion}

In conclusion, be encouraged to touch base with the projects that you've started using.

You'll be surprised how good most of the defaults are!

Configuring Doom Emacs to be your Typescript IDE

Sun, 04 Aug 2024 00:00:00 GMT

For a while I struggled with using Emacs as a IDE for modern web-development. In other words, Typescript, prettier, .tsx files, etc.

In the end it's not hard, here is how I have my Doom configured:

settings in the `init.el` {#settings-in-the-init-dot-el}

First up, we have to make sure that we are using the power of a language server protocol (short lsp). The lsp is a client-server protocol where your IDE is getting all the type-hinting, Intellisense, auto-complete etc from. As far as I understand this, this does not mean you are connected to the Internet, you are hosting the lsp automatically locally.

In the ~/.config/doom/init.el, set these (along your other config, of course):

(doom!
  :tools
  (lsp +peek) ; +peek is optional, read more about it in the lsp README (g d)
  (debugger +lsp) ; we'll get to this later

  :lang
  (javascript +lsp)
)

This takes care of a solid setup already! However, there are some further tweaks needed for a fully Integrated Developer Environment.

💡 Remember, you can always rebuild your Doom with SPC h r r, this will automatically install the packages required.

`typescript-mode` {#typescript-mode}

With this mode we already have an automatic connection to the lsp-mode. When you open a .ts file for the first time, you will get an interactive dialog to download a language-server. I use ts-ls.

(use-package! typescript-mode
  :mode "\\.ts\\'" ; set the mode as default for .ts files
  :config
  (require 'dap-node) ; enable the debugger
  (dap-node-setup) ; setup the debugger
  (setq typescript-indent-level 2) ; set typescript indent level
  (add-hook 'typescript-mode-hook #'add-node-modules-path) ; for mono-repo support
  (add-hook 'typescript-mode-hook #'prettier-js-mode) ; use the prettier config of the project
)

`typescript-tsx-mode` {#typescript-tsx-mode}

For React, a similar setup can be used for .tsx files.

(use-package! typescript-tsx-mode ; automatically installed with (javascript +lsp)
  :mode  "\\.tsx\\'" ; default for .tsx files
  :config ; see above
  (add-hook 'typescript-tsx-mode-hook #'add-node-modules-path)
  (add-hook 'typescript-tsx-mode-hook #'prettier-js-mode)
)

Don't forget to rebuild your config.

Trying it out in a fresh `bun` project {#trying-it-out-in-a-fresh-bun-project}

Give it a try, for example with a new bun repo (make sure to have it installed):

mkdir typescript-test
cd typescript-test
bun init -y
bun run index.ts

This creates the basic project that is typescript ready. Go into the index.ts and try it out!

Next steps: Debugger {#next-steps-debugger}

Now, to have a real IDE, we need a debugger. Unfortunately, I am no wizard and have not found a good solution yet. The best I have so far is a basic dap-mode setup.

If you have solved this for a typescript setup - especially in mono-repos, do let me know! The debugging experience in Doom Emacs is not that great and often times I result to console.log(), which is obviously less than ideal.

How I published this blog post

Thu, 18 Jul 2024 00:00:00 GMT

Follow me on my journey on how this blog post was written and published. You may discover an amazing workflow to quickly bring your thoughts to the web as well.

The basic setup with org-mode {#the-basic-setup-with-org-mode}

In the beginning there was darkness. Then, a fresh new .org file appears. The opensourceodyssey.org file, to be precise.

Org or org-mode is a markdown syntax for Emacs. You can do a lot with it; such as: taking notes, tracking tasks, writing literal code files (like Jupyter notebooks for Python), and exporting to all kinds of other formats (like .md, .html or reveal-js presentations).

Every post you read is a level 2 heading in the opensourceodyssey.org file that is marked as "DONE".

Notice in the top, the #+hugo_base_dir variable, that has a value of a server ssh alias and a file path on that server. We'll get back to this.

In summary, org and Emacs is the place to write the content.

Go Hugo! {#go-hugo}

Next step is to setup a simple hugo project. Hugo calls itself "The world’s fastest framework for building websites" and you can confirm this by navigating this very site. It specializes in static site generation, in other words sites where the information does not change based on the user. This is perfect for a blog.

After installing hugo, just create a new hugo project with hugo new site [SITENAME] --format yaml. Replace [SITENAME] with the name of your project. The entry folder will have this name. I prefer YAML over TOML, so I opt for YAML.

Hugo takes care of the "business logic". To make things look pretty, we need a theme. Hugo offers a wide variety of free-to-use themes.

I picked a beautiful theme: PaperMod. The features include a light/dark mode, posts with navigation to the previous/next post, automatic word count and reading time calculator and much much more.

Each theme comes with its own installation instructions. Follow them and make the changes in your newly crated hugo project.

Great! In short, with org we write the posts and with hugo we render the HTML for a browser.

Publishing the post with `ox-hugo` {#publishing-the-post-with-ox-hugo}

Now we need some kind of glue to tie it all together. Fortunately, Emacs has us covered with ox-hugo. Moreover, Doom has maybe the easiest installation ever for this integration:

Go into the init.el of your ~/.config/doom and change the line of org to be like

(org +hugo)

then rebuild the configuration (with SPC h r r).

Now, in any org document you can execute the org-export-dispatch (with SPC m e) to pop the export menu.

Then I select "Export Hugo-compatible Markdown" and choose to export all subtrees. The destination will be the #+hugo_base_dir: we set at the top of the file!

Yes, it's that easy. Navigate to the hugo directory and check the content/ directory for your posts.

Adding metadata to a post {#adding-metadata-to-a-post}

You should also add metadata to the individual subheadings to support the "export all subtrees" command.

The "Posts" h1 has the following properties right underneath it:

:PROPERTIES:
:EXPORT_HUGO_SECTION: posts
:END:

And the individual h2 (that each represent a post) have the following properties underneath it:

:PROPERTIES:
:EXPORT_FILE_NAME: reverting-to-the-default
:EXPORT_HUGO_SECTION: posts
:EXPORT_DATE: 2024-07-17
:EXPORT_HUGO_CUSTOM_FRONT_MATTER: :cover '((image . "@/assets/post-images/touching-base.png") (alt . "A ship docked at land"))
:END:

Notice the :EXPORT_HUGO_CUSTOM_FRONT_MATTER: setting. ox-hugo supports putting any custom frontmatter in the generated .md document! According to the PaperMod docs and sample Page.md, the frontmatter for a cover image looks like this:

cover:
    image: "<image path/url>" # image path/url
    alt: "<alt text>" # alt text
    caption: "<text>" # display caption under cover
    relative: false # when using page bundles set this to true
    hidden: true # only hide on current single page

cover is the first-level key, containing an object. Ergo: (:EXPORT_HUGO_CUSTOM_FRONT_MATTER: :cover '((image . "@/assets/post-images/touching-base.png") (alt . "A ship docked at land"))). Now this just works when triggering ox-hugo export.

The tags of each post is set directly behind the heading with :tagname: syntax. Our hugo theme takes care of creating pages for our tags.

We can then test our setup on localhost with executing hugo server in the hugo base directory. http://localhost:1313 then shows our site.

Hosting the site {#hosting-the-site}

Finally, we have our site and our content and we just need to bring it online.

For this I rented a VPS and a domain. Point the domain to the static IP of the VPS with DNS records. Then all that is needed is a webserver on the VPS to handle requests. I chose caddy. Caddy is a very easy to use webserver that automatically handles certificates for you.

Since Hugo is a static site generation tool, caddy is simply serving static files. Here is the Caddyfile config for a hugo blog.

opensource-odyssey.net {
        root * /server/public
        file_server

}

www.opensource-odyssey.net {
        redir https://opensource-odyssey.net{uri}

}

💡 /server/ is the directory where the hugo site lives. It's owned by the caddy user and group.

The hugo command builds our site and places everything in the public/ folder.

Now restart caddy with sudo systemctl restart caddy and voila, the site is online!

Running an astro blog through org mode

Sun, 08 Feb 2026 00:00:00 GMT

I love Doom Emacs. By now, you should know that. Also quite fond of sharing my passion and findings with the world, hence blogging. When I started this project back in 2024, I used Doom Emacs to write articles and would publish them on the web with GoHugo. That was a lovely work-flow, since with a key-chord I could not only transform my .org file into markdown, but also sync it to the VPS, where it would be picked up by Hugo through a cron job.

There was, however, one thing that bugged me: I don't understand Go and Go templates. This limited me in customizing the appearance of my site. Don't get me wrong, the Hugo Themes are georgeous, but they felt too cookie cutter to me. The desire to stand out ate away at me.

A little hiatus {#a-little-hiatus}

My profession is web development, and around last year I went all in on PayloadCMS. For the unaware, Payload is <span class="underline">the</span> content management system for NextJS. And since everything looked like a nail, the decision to rewrite the blog in PayloadCMS and just use the admin interface for content felt close. Even went so far to start a YouTube channel to document the creation of this new site.

However, after (checks notes) 17 episodes my motivation fades. Creating videos, producing them, uploading them and maintaining all this content was too much. After all, I'm a developer and therefore lazy af. Or put in more formal way: "The friction of producing the content was too high".

I fell off.

The kindling of a new flame {#the-kindling-of-a-new-flame}

But the spark never went away. I still want to share my passion with the world, just with less "friction".

Reminiscing about the good ol times, when publishing content could be as easy as pressing some buttons, a new spark arose.

There must be some solution to my "cannot customize the template" situation.

With AI being so good nowadays, I asked the almighty what path forward I should choose. After all, I could dip my toes into Go...

But nay. There was an even better way to leverage all my web development skills and still keep using my established workflow with Doom Emacs, org-mode and ox-hugo.

Enter Astro.build {#enter-astro-dot-build}

Astro wasn't completely new to me. Here and there I heard tales of the blazingly fast performance of astro sites - with great developer experience, too. The question was just if there was a org-mode exporter for Astro.

But the AI schooled me and informed me that I could just keep using ox-hugo for the content management and use Astro as the visual representation on the web.

Vince-McMahon.jpg

Hol up. You're telling me that I can do that? Yes. Yes you can.

It's what you are looking at right now: a site build with Astro, TypeScript, React, TailwindCSS - in short tech I'm familiar with. But the article was still written in an org-mode file.

Let's dive deeper into how it works.

Scaffolding Astro {#scaffolding-astro}

The creation of the project was straightforward.

# Create the project (select "Empty" template)
pnpm create astro@latest my-blog

# Add integrations
cd opensource-odyssey-blog
pnpm astro add react tailwind
pnpm add -D @tailwindcss/typography

I initialized the Astro project and added the React/Tailwind integrations.

Using ox-hugo to export markdown to Astro {#using-ox-hugo-to-export-markdown-to-astro}

The key realization was that at the core, ox-hugo just transforms .org files into .md files and places them in some specified content/ directory. Fortunately, Astro also expects markdown files to live in such a directory. Granted, there is a little gotcha, in that Hugo expects the content/ directory to be at the root of the project, whereas Astro has it nested in src/content/, but by setting the HUGO_BASE_DIR to ./src/ that can be mitigated.

This is how the header of my .org file now looks.

#+TITLE: Opensource Odyssey Blog
#+AUTHOR: Alex
#+HUGO_BASE_DIR: ./src/
#+HUGO_FRONT_MATTER_FORMAT: yaml
#+STARTUP: indent

With this configuration it is as easy as pressing SPC m e H A and the entire .org file with the headlines as sub-trees are converted to .md and placed in the directory.

The rest is just Astro stuff.

Creating a src/pages/posts/[...slug].astro file that will render the articles

import { getCollection, render } from "astro:content"
import Layout from "@/layouts/Layout.astro"

export const prerender = true

export async function getStaticPaths() {
  const posts = await getCollection("posts")
  return posts.map((entry) => ({
    params: { slug: entry.slug },
    props: { entry },
  }))
}

const { entry } = Astro.props
const { Content: PostContent } = await render(entry)

Adding more frontmatter to each headline

:PROPERTIES:
:EXPORT_FILE_NAME: running-astro-through-org-mode
:EXPORT_DATE: 2026-02-08
:EXPORT_DESCRIPTION: I love Doom Emacs, but I don't know Go. Soooo, I'm turning away from GoHugo and towards Astro.
:END:

And creating a src/content.config.ts to validate the frontmatter with zod.

import { defineCollection, z } from "astro:content"

const Post = defineCollection({
  schema: z.object({
    title: z.string(),
    description: z.string().optional(),
    date: z.coerce.date(),
    updatedDate: z.coerce.date().optional(),
    heroImage: z.string().optional(),
    tags: z.array(z.string()).default([]),
    draft: z.boolean().default(false),
    cover: z
      .object({
        image: z.string(),
        alt: z.string().default("Post cover image"), // Default alt text if missing
      })
      .optional(),
  }),
})

export const collections = { Post }

There is a little more to it, of course, but these are the essential parts. I am sure you can figure them out by yourself.

That's it. It was that easy!

Summary about this journey {#summary-about-this-journey}

So I'm back - and in style! At the time of writing I sank about 5 hours into the entire process, from setting up the project to migrating my old articles to publishing everything on the web.

Finally I have full control over the look and feel of the site. There are more features that I'm envisioning, but these will come with time.

Astro is really, really amazing. You should check it out - maybe it fits a need that you have.

I'm very glad to have picked up another tool and not done everything in NextJS/PayloadCMS. This broadens my horizon, sharpens my skills and makes me a more versed developer.

Writing an awesome CLI with typescript

Thu, 22 Aug 2024 00:00:00 GMT

<div class="heading">Table of Contents</div>

An overview of the tech stack
Setting up the project & installing dependencies
Quality of life: Typescript path alias imports with bun
Quality of life: Prettier & package.json scripts
File structure and separation of concerns
The CLI menu - menu.ts
The last run configuration from DB - db.ts
Bringing it all together - main.ts
Conclusion

</div>

If you have ever wanted to build a Command Line Interface (short: CLI) in typescript, this post is for you!

Granted, Typescript is not the most conventional language to do this. Maybe you're better served with Go and Cobra-cli. But in case TS is your go-to language - like it is for me right now - continue reading.

An overview of the tech stack {#an-overview-of-the-tech-stack}

First, let's take a brief overview of the tools we'll be using:

For the basic typescript project, package manager and javascript-runtime, bun has become my favorite. Bun is blazingly-fast, easy to set up, and just makes coding in TS a joy. If you've never tried it, this is the perfect opportunity to do so. Make sure you have bun installed, then continue reading.

Typescript is the language of choice. It provides the developer experience that Javascript never had. In the beginning the type-syntax may seem daunting, but usually the best Typescript is just sprinkled in and the rest is inferred.

Now to the real MVP of this post is @clack/prompts. Clack enables you to effortlessly build beautiful command-line apps. With Typescript. Check out their npm page. I've taken a liking to their API and general flow.

Lastly, in case our CLI requires some kind of data storage, we'll use lowdb. Lowdb is a very simple database that runs on .json. The benefits are to have the basic database operations (create, read, update, delete), persistent storage, and the database is easily readable for troubleshooting and general checks. This is optional, but often comes to be used in some way for my CLIs.

Setting up the project & installing dependencies {#setting-up-the-project-and-installing-dependencies}

Let's get coding!

Open your favorite code editor and terminal. To start with, we need our basic project:

mkdir simple-ts-cli
cd simple-ts-cli
bun init # run through the bun CLI - for 'entry point' set src/main.ts

We'll use a src/ directory for all our code. This way we keep the project root clean.

Bun already created a tsconfig.json for us with awesome defaults!

Next, we install the dependencies. Since this is a CLI, we don't really care about them being devDependencies. Just run:

bun add @clack/prompts lowdb

Quality of life: Typescript path alias imports with `bun` {#quality-of-life-typescript-path-alias-imports-with-bun}

One thing that's easy to setup and makes development even nicer is having import path aliases for every file. This allows us to always use absolute imports. Whenever you move code from one file to the other, the imports can be copied as well. No more trying to figure out how many directories to .. up!

In the tsconfig.json we just add:

{
  "compilerOptions": {
    // ...
    "paths": {
      "~/*": ["./src/*"]
}
}

Now we can import from the base of our src/ directory with "~/"!

Quality of life: Prettier & package.json scripts {#quality-of-life-prettier-and-package-dot-json-scripts}

I don't like the semicolons at the end of the line, so I use prettier to remove them. This also makes moving lines, cutting and pasting easier. My IDE is already configured to read the prettier file in the root of the project.

Create a .prettierrc in the project root and add this line

semi: false

Last quality of life thing we cannot go without is a simple start script in our package.json to run our CLI.

In the package.json add:

{
  // ...
  "scripts": {
   "start": "bun run src/main.ts"
  },
  // ...
}

Now we can run our CLI with bun start from the root of the project!

File structure and separation of concerns {#file-structure-and-separation-of-concerns}

We'll write a simple typescript CLI: ask the user some questions and execut business logic depending on the answers.

Our CLI will "remember" the last run and default to these choices. For this we'll use lowdb as our database.

The main.ts contains the entry point to our CLI and the main flow. Keep it clean to easily follow the overall flow of the app.

The db.ts contains our database code. The type definition for lowdb and some basic exported functions, like reading the database, updating it or cleaning all the data.

Our user interaction is covered in menu.ts. Here we define the different questions and export a function for each menu - if our CLI ends up being more interactive.

Finally, lib.ts is more of a placeholder for more business logic. Everything else will end up here.

This is not a strict requirement, just some pattern that I've ended up with. Keep it simple, don't abstract, unless you have to.

The CLI menu - `menu.ts` {#the-cli-menu-menu-dot-ts}

Create the file src/menu.ts and add this content:

import { group, outro, select, text } from "@clack/prompts"
import type { LastRunConfig } from "~/db"

// We'll get into the lastRunConfig in the next section
export async function mainMenu(lastRunConfig: LastRunConfig) {
  // group() chains multiple prompts in a row
  const choices = await group(
    {
      username: () =>
        // text() is a basic user input prompt
        text({
          message: "Enter your name: ",
          // if there is a last run, use the value from it
          initialValue: lastRunConfig.username,
          // validate user input before continuing
          validate(value) {
            if (!/[a-z]/.test(value))
              // if we return from validate() the user cannot continue
              return "Username should only contain lowercase characters"
          },
        }),
      // results is an object that contains previous answers!
      environment: ({ result }) =>
        // select() with some types for inferred return types
        select<EnvironmentOption[], EnvironmentValue>({
          message: `Select your environment, ${result.username}`,
          initialValue: lastRunConfig.environment,
          options: [
            // we get auto-complete here from our types
            { value: "dev", label: "Dev" },
            { value: "qa", label: "Staging" },
            {
              value: "prod",
              label: "Prod",
              // hints are only shown when option is hovered
              hint: "⚠ You better know what you are doing",
            },
          ],
        }),
    },
    {
      // in case the user interrupts the menu with CTRL + C
      onCancel: () => {
        outro("K, thx, bye")
        // abort the program, no error
        process.exit(0)
      },
    },
  )

  // we could do more validation or reshaping with the choices here
  return choices
}

// --- Types
// I always use this GenericOption for typing selects
export type GenericOption = {
  label?: string | undefined
  hint?: string | undefined
}

// the actual options of our select
export type EnvironmentValue = "dev" | "qa" | "prod"
// some typescript inferrence magic
export type EnvironmentOption = GenericOption &
  Record<"value", EnvironmentValue>

Study this code and the comments. The group() is a sequence of prompts. In the end choices will be an object containing username and environment. This is just a sample, depending on your needs, create new properties in the group().

The Types are something I just copy & paste from project to project. Notice how we pass EnvironmentOption[] (array!) in the select<EnvironmentOption[], EnvironmentValue>({...}). We're saying: "These are the possible options and in the end I expect one of these Values".

With this setup our choices variable knows which values it contains. Insanely useful for later switch case statements or other conditional logic.

With results in the callback of a prompt, we can access previous answers. Super handy, we could even add optional prompts:

const choices = await group({
  answer1: () => text({ message: "Whats the secret word?" }),
  answer2: ({ results }) => {
    if (results.answer1 === "valar morgulis") {
      // optional answer2
      return text({ message: "A man needs a name: " })
    }
    // otherwise answer2 will be undefined
    return
  }
})

For more detail about using the @clack/prompts, read their examples.

The last run configuration from DB - `db.ts` {#the-last-run-configuration-from-db-db-dot-ts}

Our mainMenu() accepts a lastRunConfig object. It's a nice touch to remember the last time the user ran an app. We'll use a simple JSON structure to store this data.

Create the src/db.ts and input this:

import { JSONFilePreset } from "lowdb/node"

export type LastRunConfig = {
  username: string
  environment: "qa" | "dev" | "prod"
}
type Data = {
  lastRunConfig: LastRunConfig
}

const defaultData: Data = {
  lastRunConfig: {
    username: "",
    environment: "dev",
  },
}
const db = await JSONFilePreset<Data>("db.json", defaultData)

export async function updateLastRunConfig(config: LastRunConfig) {
  db.data.lastRunConfig = config
  await db.write()
}

export async function getLastRunConfig() {
  await db.read()
  return db.data.lastRunConfig
}

This code uses the db.json file as our database. We export a function to add a new lastRunConfig and another to get the lastRunConfig.

Bringing it all together - `main.ts` {#bringing-it-all-together-main-dot-ts}

Let's put these pieces together. In the main.ts we write:

import { mainMenu } from "~/menu"
import { getLastRunConfig } from "~/db"
import { outro } from "@clack/prompts"

const lastRunConfig = await getLastRunConfig()
const choices = await mainMenu(lastRunConfig)
await updateLastRunConfig(choices)

outro(`Great choices:

Username - ${choices.username}
Environment - ${choices.environment}`)

Ahh, how simple and beautiful. This code explains itself!

Run the script twice to see if the lastRunConfig actually works.

outro() is another function from @clack/prompts to say a final word of "Goodbye!" to the user.

Of course in a real world app this would only be the beginning. After asking the user some questions, we would actually do something with it. However, this is not the focus of this post. You got this from here!

Conclusion {#conclusion}

We created a simple typescript CLI with bun, @clack/prompts and lowdb. Our CLI asks the user some question and remembers the answers for the next run.

Hopefully this post gave you an overview of how to approach the topic of CLI with typescript.

Lucia-auth in T3-Stack

Fri, 09 Aug 2024 00:00:00 GMT

<div class="heading">Table of Contents</div>

What is T3 Stack?
Why Lucia-auth?
How to add lucia-auth to NextJS >= 13 (App Router) - Optional: How to setup Prisma on NixOS - Installing lucia-auth dependencies - Editing the schema - Adding the basic lucia-auth functionality - Adding lucia to TRPC - TRPCReactProvider - Adding lucia-auth to TRPC - createTRPCContext - Adding lucia-auth to TRPC - protectedProcedure - Adding lucia-auth to TRPC - the auth router
Conclusion - how to use lucia-auth with TRPC

</div>

Developing web applications is my daily bread and butter. Over the past year or so, I really came to love T3-Stack. This post covers the setup of lucia-auth with a create-t3-app.

What is T3 Stack? {#what-is-t3-stack}

For the uninitiated, T3 stack is the name of a project starter for NextJS. Originally started by Theo GG, T3 focuses on easing the setup of a new project with some very nice packages pre-configured.

When you start your T3 project, you walk through an installation wizard. I usually take all the goodness: Tailwind, TRPC, app router, yes please!

Depending on your needs, you can start with a database with Prisma or Drizzle ORM and even have authentication with NextAuth pre-configured. All super great, but I'm not such a big fan of NextAuth.

The reason is that most of my projects do not use the OAuth Providers from Discord, Google or GitHub. After all, we follow the LandChad ethos here and outsourcing the user authentication and creating this important dependency is just not something I am willing to accept. NextAuth offers a username/password credentials authentication flow, but still...

Why Lucia-auth? {#why-lucia-auth}

What else? Well JoshTriedCoding did a video on an authentication library that according to him has the same, very good level of abstraction as shadcn. I fucking love ShadCN. Building cool user interfaces has never been so easy for me. Naturally, Josh had me immediately hooked and I needed to try out this gem he talked about: Lucia-auth.

<div align="center"> <iframe width="504" height="315" src="https://www.youtube.com/embed/S37uRvBr65k"> frameborder="1px" </iframe> </div>

The documentation of lucia-auth is also not too bad. They have examples for many different variations of authentication. However, they don't have an example for using it with TRPC and having procedures for login, signup and logout.

This is exactly what I'll cover in the rest of the post. We'll setup a basic T3 stack app and then add lucia-auth to it. Ever step will be shown in detail, and you should be able to reproduce.

How to add lucia-auth to NextJS >= 13 (App Router) {#how-to-add-lucia-auth-to-nextjs-13--app-router}

Let's get started. I will use bun as my package manager and runtime. You don't have to; npm, yarn, pnpm will also do just fine. First up, we open the terminal, navigate to a directory that suits as a parent for our project and then execute:

bun create t3-app@latest

Here is how I answered the questions in the wizard:

Then, T3-Stack informs us about the next steps:

Next steps:
  cd lucia-auth-trpc-t3
  bun install
  bun run db:push
  bun run dev
  git commit -m "initial commit"

Optional: How to setup Prisma on NixOS {#optional-how-to-setup-prisma-on-nixos}

Now, since I'm on NixOS (as you may have gathered from My Linux Odyssey), I have to add a dev shell so I can use Prisma. I use the following setup in most of my typescript projects.

As a prerequisite to this step, you need to have devenv setup. I won't go into this here, maybe at a later post in time.

First, we create our shell.nix that houses the project specific packages and configs:

{
  pkgs ? import <nixpkgs> { },
}:

pkgs.mkShell {
  buildInputs = with pkgs; [
    nodejs_20
    nodePackages_latest.prisma
    prisma-engines
  ];
  shellHook = ''
    export PRISMA_QUERY_ENGINE_LIBRARY=${pkgs.prisma-engines}/lib/libquery_engine.node
    export PRISMA_QUERY_ENGINE_BINARY=${pkgs.prisma-engines}/bin/query-engine
    export PRISMA_SCHEMA_ENGINE_BINARY=${pkgs.prisma-engines}/bin/schema-engine
  '';
}

The environment variables are used for our prisma commands to detect the right binary.

Next, we create a flake.nix alongside the shell.nix in our project root.

{
  description = "Run 'nix develop' to have a dev shell that has everything this project needs";

  inputs = {
    nixpkgs.url = "github:NixOS/nixpkgs";
    flake-utils.url = "github:numtide/flake-utils";
  };

  outputs =
    {
      self,
      nixpkgs,
      flake-utils,
    }:
    flake-utils.lib.eachDefaultSystem (
      system:
      let
        pkgs = nixpkgs.legacyPackages.${system};
      in
      {
        devShells.default = import ./shell.nix { inherit pkgs; };
      }
    );
}

This is a generic flake that imports our shell.nix and installs it for the right system.

The final cherry on top is a .envrc file in the project root with this content:

if nix flake show &> /dev/null; then
  use flake
else
  use nix
fi

So, if the developer uses flakes, we use the flake setup, otherwise we just use the vanilla shell.nix.

Make sure these new files are checked into git.

Finally, in the project root run direnv allow to install everything. You should then be able to migrate the Prisma schema and database with prisma migrate dev.

Installing lucia-auth dependencies {#installing-lucia-auth-dependencies}

With the basic project setup out of the way, we can install lucia-auth. So we follow the basic "Getting started".

Install lucia bun add lucia
Add the Prisma adapter for lucia bun add @lucia-auth/adapter-prisma. (If you went with Drizzle in the setup, of course this needs to be the Drizzle ORM adapter)

Editing the schema {#editing-the-schema}

Since we are going for username/password credentials authentication, we have to store users and their sessions in our database. We can achieve this like so:

model User {
  id       String    @id
  username String    @unique
  password String
  sessions Session[]
}

model Session {
  id        String   @id
  userId    String
  expiresAt DateTime

  user      User     @relation(references: [id], fields: [userId], onDelete: Cascade)
}

Migrate the schema with prisma migrate dev (or bun prisma migrate dev if you skipped the NixOS step). Give it a meaningful name like "add user and session".

Adding the basic lucia-auth functionality {#adding-the-basic-lucia-auth-functionality}

Create the file src/server/auth.ts and add the following:

import { PrismaAdapter } from "@lucia-auth/adapter-prisma";
import { PrismaClient } from "@prisma/client";
import { Lucia } from "lucia";

const client = new PrismaClient();

const adapter = new PrismaAdapter(client.session, client.user);

export const lucia = new Lucia(adapter, {
  sessionCookie: {
    attributes: {
      // set to `true` when using HTTPS
      secure: process.env.NODE_ENV === "production",
    },
  },
  getUserAttributes: (attributes) => {
    return {
      // attributes has the type of DatabaseUserAttributes
      username: attributes.username,
    };
  },
});

declare module "lucia" {
  interface Register {
    Lucia: typeof lucia;
    DatabaseUserAttributes: DatabaseUserAttributes;
  }
}

// simply pick some properties from our Prisma User schema
type DatabaseUserAttributes = Pick<User, "username">;

This is our basic setup for lucia. We initialize it with the Prisma adapter, and provide it with some attributes of our user.

However, there is one more function I add to this file: the validateRequest(). It can be called on the server side to check the cookies of the user. We could add it at the top of a page function, or - as we'll see in the next section - add it to the TRPC context.

export const validateRequest = cache(
  async (): Promise<
    { user: User; session: Session } | { user: null; session: null }
  > => {
    const sessionId = cookies().get(lucia.sessionCookieName)?.value ?? null;

    if (!sessionId) {
      return { user: null, session: null };
    }

    const result = await lucia.validateSession(sessionId);

    // next.js throws when you attempt to set cookies while rendering the page
    try {
      if (result.session && result.session.fresh) {
        const sessionCookie = lucia.createSessionCookie(result.session.id);
        cookies().set(
          sessionCookie.name,
          sessionCookie.value,
          sessionCookie.attributes,
        );
      }
      if (!result.session) {
        const sessionCookie = lucia.createBlankSessionCookie();
        cookies().set(
          sessionCookie.name,
          sessionCookie.value,
          sessionCookie.attributes,
        );
      }
    } catch {}
    return result;
  },
);

Adding lucia to TRPC - TRPCReactProvider {#adding-lucia-to-trpc-trpcreactprovider}

In the lucia docs they now go for server actions. With this tutorial though, we will now add the authentication to TRPC. This will allow us to have protectedProcedures that automatically check if a user is logged in. Furthermore, we can add the user and session to the TRPC context. With this, we can always use the logged in userID to get for example only a specific profile from the database.

First up, we have to modify the default TRPC setup to stop using the unstable_httpBatchStreamLink. This is the most critical step that had me struggling for a long time. The reason is that with unstable_httpBatchStreamLink the server responds immediately after request and stream the response. Great and all, but then we can no longer set cookies - which we need for auth!

In the src/trpc/react.tsx the TRPCReactProvider should look as follows:

"use client";

import { loggerLink, httpBatchLink } from "@trpc/client";

export function TRPCReactProvider(props: { children: React.ReactNode }) {
  const queryClient = getQueryClient();

  const [trpcClient] = useState(() =>
    api.createClient({
      links: [
        loggerLink({
          enabled: (op) =>
            process.env.NODE_ENV === "development" ||
            (op.direction === "down" && op.result instanceof Error),
        }),
        // 💡 use this!
        httpBatchLink({
        // instead of this
        // unstable_httpBatchStreamLink({
          transformer: SuperJSON,
          url: getBaseUrl() + "/api/trpc",
          headers: () => {
            const headers = new Headers();
            headers.set("x-trpc-source", "nextjs-react");
            return headers;
          },
        }),
      ],
    })
  );

  return (
    <QueryClientProvider client={queryClient}>
      <api.Provider client={trpcClient} queryClient={queryClient}>
        {props.children}
      </api.Provider>
    </QueryClientProvider>
  );
}

Adding lucia-auth to TRPC - createTRPCContext {#adding-lucia-auth-to-trpc-createtrpccontext}

In the src/server/api/trpc.ts the TRPCContext is created. The Prisma adapter is added to the context for example. Let's add the user and session to the context!

export const createTRPCContext = async (opts: { headers: Headers }) => {
  const { user, session } = await validateRequest();
  return {
    db,
    user,
    session,
    ...opts,
  };
};

That was easy! Now we can access the user and session in every procedure with ctx.user and ctx.session. Nice.

Adding lucia-auth to TRPC - protectedProcedure {#adding-lucia-auth-to-trpc-protectedprocedure}

Since our app features authentication, there are probably some things we only want to allow authenticated users to perform. Luckily TRPC provides a convenient way to re-use this logic.

We simply create a protectedProcedure in src/server/api/trpc.ts:

export const protectedProcedure = t.procedure.use(({ ctx, next }) => {
  if (!ctx.user || !ctx.session) {
    throw new TRPCError({ code: "UNAUTHORIZED" });
  }
  // ensure that session and user are non-nullable for typescript
  return next({
    ctx: { session: { ...ctx.session }, user: { ...ctx.user } },
  });
});

Fantastic. Now we can use this in our routers to automatically protect certain routes.

Adding lucia-auth to TRPC - the auth router {#adding-lucia-auth-to-trpc-the-auth-router}

There is one last thing we actually need to write: a TRPCRouter for our authentication logic.

We'll keep this simple and create these routers:

me - returns the authenticated User from the database
login - authenticate with an existing User
signup - create a User in the database
logout - kill the session for the authenticated User

For the login, signup and logout I simply adopt the example "server action" code from the lucia-auth docs. There is a lot of code below, but if you are reading this far, it may be very instructional.

import {
  createTRPCRouter,
  protectedProcedure,
  publicProcedure,
} from "~/server/api/trpc";
import { z } from "zod";
import { verify, hash } from "@node-rs/argon2";
import { TRPCError } from "@trpc/server";
import { lucia } from "~/server/auth";
import { cookies } from "next/headers";

const LoginSchema = z.object({
  username: z.string(),
  password: z.string(),
});

export const authRouter = createTRPCRouter({
  me: protectedProcedure.query(({ ctx }) => {
    return ctx.db.user.findFirstOrThrow({ where: { id: ctx.user.id } });
  }),
  login: publicProcedure.input(LoginSchema).mutation(async ({ ctx, input }) => {
    const existingUser = await ctx.db.user.findFirst({
      where: { username: input.username },
    });
    if (!existingUser) throw new TRPCError({ code: "UNAUTHORIZED" });

    const validPassword = await verify(existingUser.password, input.password, {
      memoryCost: 19456,
      timeCost: 2,
      outputLen: 32,
      parallelism: 1,
    });

    if (!validPassword) throw new TRPCError({ code: "UNAUTHORIZED" });

    const session = await lucia.createSession(existingUser.id, {});
    const sessionCookie = lucia.createSessionCookie(session.id);
    cookies().set(
      sessionCookie.name,
      sessionCookie.value,
      sessionCookie.attributes,
    );
    return true;
  }),

  signup: publicProcedure
    .input(LoginSchema)
    .mutation(async ({ ctx, input }) => {
      const existingUser = await ctx.db.user.findFirst({
        where: { username: input.username },
      });
      if (existingUser)
        throw new TRPCError({
          code: "FORBIDDEN",
          message: "Username already taken",
        });

      const hashedPassword = await hash(input.password, {
        memoryCost: 19456,
        timeCost: 2,
        outputLen: 32,
        parallelism: 1,
      });

      const { id } = await ctx.db.user.create({
        data: {
          username: input.username,
          password: hashedPassword,
        },
      });

      const session = await lucia.createSession(id, {});
      const sessionCookie = lucia.createSessionCookie(session.id);
      cookies().set(
        sessionCookie.name,
        sessionCookie.value,
        sessionCookie.attributes,
      );
      return true;
    }),

  logout: protectedProcedure.mutation(async ({ ctx }) => {
    await lucia.invalidateSession(ctx.session.id);
    const sessionCookie = lucia.createBlankSessionCookie();
    cookies().set(
      sessionCookie.name,
      sessionCookie.value,
      sessionCookie.attributes,
    );
  }),
});

Conclusion - how to use lucia-auth with TRPC {#conclusion-how-to-use-lucia-auth-with-trpc}

Finally we are done! Well, at least for the basics. Lucia informs us to implement a CSRF token if there are no server actions used. So that's a TODO. Then we also need our front-end components, like the forms and pages.

This post is already way too long, so I won't go into it here. But you will find great resources elsewhere.

Just keep in mind that now we can use our auth router on the server and client by simply using the right import:

// Import this on server pages and in server logic
import { api } from "~/trpc/server";
const me = await api.auth.me()

// Import this on client components (where "use client" is used)
import { api } from "~/trpc/react"
const { data: me } = await api.auth.me.useQuery()

Thanks for following this lengthy guide. I hope you learned something. Make sure to follow my RSS feed to always stay up to date with new posts.

Chiseling dotfiles: The Digital Mason

Sat, 14 Feb 2026 00:00:00 GMT

I declare myself a Digital Mason. Instead of stone, I work with zeros and ones. Find how you can become one, too.

The Rough Ashlar {#the-rough-ashlar}

A concept, heard in passing, deeply resonated with me: The Rough Ashlar from Freemasonry. This has nothing to do with wearing robes, learning secret handshakes or participating in bizarre rituals. Instead that brick is the symbol of continuous improvement.

The Rough Ashlar is a jagged stone straight from the quarry. It is flawed, imperfect, unusable in masonry. It has to be chiseled to become smooth, useful, perfect.

Freemasonry draws the parallel of the stone to human life. A newcomer joining a lodge is the Rough Ashlar. Over their lifetime, they shape themselves into the person they want to become: The Smooth or Perfect Ashlar.

Not only is this metaphor is profound for personal growth, but can be applied to system crafting as well. That's probably why it resonated so strongly with me.

Enter The Quarry {#enter-the-quarry}

Switching from proprietary garbage, like MacOS or Windows, to Linux is like stepping into the quarry: There are countless stones. Some are pre-shaped - like Ubuntu, Manjaro or even Omarchy; some are minimal - like Arch, where you have to install every package yourself.

Picking your first distro feels like picking one of these stones. The endless choice is overwhelming. There is no "just do this"-solution. The first obstacle is getting a grasp of the landscape. Which stone/distro is best really depends on your preferences and goals.

For myself, reconnaissance meant trying out different distros. Starting with Ubuntu, then Kubuntu, then Linux Mint, back to Ubuntu, then Manjaro (read more about my Linux Odyssey here). Those were dark days, since tinkering often lead to a broken system, which meant re-installing everything from scratch and starting over. However, through trial and error, I learned about my own preferences and gained experience in the various flavors.

With understanding, it is possible to determine which packages are bloat - unwanted/unnecessary. Bloat is the enemy of the Perfect Ashlar.

Let The Chiseling Begin {#let-the-chiseling-begin}

I landed on Arch, btw. The beauty was that out of the box, Arch didn't have any bloat!

The meme of Gru from "Despicable Me" comes to mind with the line "no packages installed".

Every package had to be explicitly installed. This meant much more sweat to get things to work, let alone just right for me.

The revelation of that time were <span class="underline">config files</span>. Doom Emacs had already gently introduced me to the concept. All features are adjusted in the config.el (or rather config.org - literal programming FTW). The birth of my .dotfiles repo.

Declaring the configuration for Doom Emacs and having the configuration in a version control system (git) basically translates to "savegames". Like a checkpoint in a video game that you can come back to if you die down the line.

Trying out new stuff became fun! After all, if things didn't pan out git reset --hard origin/main was just a few keystrokes away.

So the appetite for more customization grew. Turns out that having configuration stored in file is actually pretty common. Out with the Gnome and KDE, in with the i3 and qtile. PUT ALL THE THINGS IN CONFIG FILES!

With gnu stow you can even automatically sym-link all your .dotfiles from the repo to their correct location (be it in ~/ or ~/.config/ ). It's an amazing tool and you should give it a try.

It felt like ecstasy installing my setup onto a new computer. Instead of clicking through endless GUIs, it was just a git clone, a stow . and running a bash script to install the right programs. The power.

The lesson: Configure your system once and never lose the progress! Every tweak to the system was a chisel stroke on the stone. Slow and deliberate. My configuration grew with me.

The Stone That Fits {#the-stone-that-fits}

But it all deteriorated.

For work I got another laptop. Installation? Easy peasy lemon squeasy. After all, it was using the same .dotfiles.

But... The work laptop also was different: no dedicated GPU, some different programs (didn't need Steam) and most importantly <span class="underline">different versions</span> of programs, since I ran the installation/update commands at different times.

Two machines, that tried to use the same .dotfiles repo and yet kept drifting apart.

The longing for a new, different stone - a different material to chisel away at - grew. By nature, Arch Linux is imperative. Configuration happens through terminal commands (like the install script) or manually changing /etc/ files. Documenting, let alone remembering, which commands had been done on one system and not the other was futile.

And then came NixOS.

A colleague suggested it to me for my avid use of Doom Emacs. The creator of Doom, Henrik Lissner, turned out to use nix. And the philosophy fits. Instead of interactively instructing a system how to behave, everything is declared. NixOS just does it for the whole system; all system packages & services, all users and their packages & services.

Declaration hits two birds with one stone: The declaration is the documentation and handles configuration.

Great! Nix solves my issue of drifting systems. The perfect stone was discovered. The diamond in the rough. The only problem was learning how to use it.

Shaping The Perfect Ashlar {#shaping-the-perfect-ashlar}

Learning nix is hard! Especially coming from the familiar imperative Linux world. However, my aspiration carried me through the initial skill-issues. If you are at this point right now: Ask for help in the discord channel, read the NixOS wiki & watch every single video of Vimjoyer.

NixOS holds your hand. It won't allow you to rebuild your declared system, if there is a syntax error. And if you still manage to fuck everything up, simply boot into a previous generation! This superpower still shapes my Opensource Odyssey.

Moreover, through a single .dotfiles repo you can declare multiple systems. Let machines share exactly the same packages (as in byte for byte the same package) and the same configuration. The stuff that differs is still declared, but not shared.

There will be less to remember. Configuration is done once, it is done right & it is done forever.

For instance, tools like vim, tealdeer and dust are part of my "terminal toolbelt". This toolbelt is installed <span class="underline">all machines</span> (be it VPS, home machine or work machine).

Moving into new hardware has never been easier. Last year, when a new baremetal miniserver entered my roster, the biggest hurdle was getting ssh and git installed. From there, the rest was a simple nh os switch. Setting up the entire server according to my bespoke preferences took no more than an hour (and most of that time was just looking at the nh output). From what I understand even that can be further optimized so that you can install your distro from a USB stick.

In other words, try Nix. Don't ever look back.

The Digital Mason’s Creed {#the-digital-mason-s-creed}

This brings us back to Digital Masonry. The Digital Mason chisels not stone, but configuration files. This is a lifelong process. With time the system becomes more and more perfect.

While contemplating the concept of Digital Masonry, the Rifleman's Creed from the movie Full Metal Jacket came to mind.

https://youtube.com/watch?v=Hgd2F2QNfEE

Here is the adapted version for the Digital Mason (props to Grok for the adaptation). Repeat after me:

This is my config. There are many like it, but this one is mine.

My config is my best friend. It is my life. I must master it as I must master my machine.

Without me, my config is useless. Without my config, I am useless.

I must declare it true. I must refine it sharper than the defaults that try to own me.

I must chisel it before it chisels me. I will.

Before the terminal, I swear this creed: my config and myself are defenders of my sanity, we are the masters of our bloat, we are the saviors of my workflow.

So be it, until there is no friction, but flow.

Go Forth & Chisel Your Config {#go-forth-and-chisel-your-config}

There you have it. No need for robes or secret handshakes. Only need the mindset of a craftsman. Look at your system like a stone that you adapt to <span class="underline">your preferences</span>. It grows with you. It supports you. It empowers you.

Go build your own temple with one keystroke at a time.

Opensource Odyssey

Building a timeless tech stack

The origin story {#the-origin-story}

Proprietary software vs. open source software {#proprietary-software-vs-dot-open-source-software}

Hard mode: Open source is not enough {#hard-mode-open-source-is-not-enough}

The tech stacks I chose {#the-tech-stacks-i-chose}

Conclusion {#conclusion}

hello world

What to expect in this blog {#what-to-expect-in-this-blog}

An overview of what I'm enthusiastic about {#an-overview-of-what-i-m-enthusiastic-about}

Join the odyssey {#join-the-odyssey}

My Linux Odyssey

Phase I: Discovering Linux {#phase-i-discovering-linux}

Abandoning MacOS {#abandoning-macos}

The first Linux desktop {#the-first-linux-desktop}

Distro hopping {#distro-hopping}

From Debian-base to Manjaro {#from-debian-base-to-manjaro}

Gaming on Linux {#gaming-on-linux}

Phase II: Tiling windows and dotfiles {#phase-ii-tiling-windows-and-dotfiles}

Tiling window managers {#tiling-window-managers}

QTile {#qtile}

Off the beaten path: Arco Linux {#off-the-beaten-path-arco-linux}

Establishing dotfiles {#establishing-dotfiles}

Phase III: Mastering Arch {#phase-iii-mastering-arch}

Daring Arch {#daring-arch}

Learning how to solve problems {#learning-how-to-solve-problems}

Versioning packages {#versioning-packages}

Managing two systems {#managing-two-systems}

Phase IV: Declaring reproducibility {#phase-iv-declaring-reproducibility}

The final distro hop: NixOS {#the-final-distro-hop-nixos}

Settling on NixOS {#settling-on-nixos}

Switching to Flakes {#switching-to-flakes}

Killer feature: Generations {#killer-feature-generations}

Phase V: Nix verstehen {#phase-v-nix-verstehen}

Flexing the nix muscles {#flexing-the-nix-muscles}

MVP: Vimjoyer {#mvp-vimjoyer}

Epilog {#epilog}

Touching base, or: reverting to the default

Dropping everything for the default config {#dropping-everything-for-the-default-config}

Hitchhiking on the backs of masters {#hitchhiking-on-the-backs-of-masters}

Swimming with the swarm {#swimming-with-the-swarm}

Conclusion {#conclusion}

Configuring Doom Emacs to be your Typescript IDE

settings in the init.el {#settings-in-the-init-dot-el}

typescript-mode {#typescript-mode}

typescript-tsx-mode {#typescript-tsx-mode}

Trying it out in a fresh bun project {#trying-it-out-in-a-fresh-bun-project}

Next steps: Debugger {#next-steps-debugger}

How I published this blog post

The basic setup with org-mode {#the-basic-setup-with-org-mode}

Go Hugo! {#go-hugo}

Publishing the post with ox-hugo {#publishing-the-post-with-ox-hugo}

Adding metadata to a post {#adding-metadata-to-a-post}

Hosting the site {#hosting-the-site}

Running an astro blog through org mode

A little hiatus {#a-little-hiatus}

The kindling of a new flame {#the-kindling-of-a-new-flame}

Enter Astro.build {#enter-astro-dot-build}

Scaffolding Astro {#scaffolding-astro}

Using ox-hugo to export markdown to Astro {#using-ox-hugo-to-export-markdown-to-astro}

Summary about this journey {#summary-about-this-journey}

Writing an awesome CLI with typescript

An overview of the tech stack {#an-overview-of-the-tech-stack}

Setting up the project & installing dependencies {#setting-up-the-project-and-installing-dependencies}

Quality of life: Typescript path alias imports with bun {#quality-of-life-typescript-path-alias-imports-with-bun}

Quality of life: Prettier & package.json scripts {#quality-of-life-prettier-and-package-dot-json-scripts}

File structure and separation of concerns {#file-structure-and-separation-of-concerns}

The CLI menu - menu.ts {#the-cli-menu-menu-dot-ts}

The last run configuration from DB - db.ts {#the-last-run-configuration-from-db-db-dot-ts}

Bringing it all together - main.ts {#bringing-it-all-together-main-dot-ts}

Conclusion {#conclusion}

Lucia-auth in T3-Stack

What is T3 Stack? {#what-is-t3-stack}

Why Lucia-auth? {#why-lucia-auth}

How to add lucia-auth to NextJS >= 13 (App Router) {#how-to-add-lucia-auth-to-nextjs-13--app-router}

Optional: How to setup Prisma on NixOS {#optional-how-to-setup-prisma-on-nixos}

Installing lucia-auth dependencies {#installing-lucia-auth-dependencies}

Editing the schema {#editing-the-schema}

Adding the basic lucia-auth functionality {#adding-the-basic-lucia-auth-functionality}

Adding lucia to TRPC - TRPCReactProvider {#adding-lucia-to-trpc-trpcreactprovider}

settings in the `init.el` {#settings-in-the-init-dot-el}

`typescript-mode` {#typescript-mode}

`typescript-tsx-mode` {#typescript-tsx-mode}

Trying it out in a fresh `bun` project {#trying-it-out-in-a-fresh-bun-project}

Publishing the post with `ox-hugo` {#publishing-the-post-with-ox-hugo}

Quality of life: Typescript path alias imports with `bun` {#quality-of-life-typescript-path-alias-imports-with-bun}

The CLI menu - `menu.ts` {#the-cli-menu-menu-dot-ts}

The last run configuration from DB - `db.ts` {#the-last-run-configuration-from-db-db-dot-ts}

Bringing it all together - `main.ts` {#bringing-it-all-together-main-dot-ts}