DEV Community: Matteo

Making an RSS Feed for a Nuxt Website

Matteo — Mon, 22 Sep 2025 15:11:18 +0000

I recently remade my website (I know, I know) and I got a surprise when getting to reimplement an rss feed because, while Astro has a module that helps with generating an rss feed, Nuxt doesn't - at least not for V3 and consequently V4. But worry not, for making one is easy enough !

What is an RSS Feed ?

An RSS feed is an xml document that allows users to subscribe to updates on a website. It is an xml document that can be easily parsed to retrieve the latest published article, the website's author and more info (wikipedia entry here if you want to learn more).

There are a lot of applications that will allow you to subscribe to an rss feed and even get notified when one is updated.

Although RSS in its xml format is the most well-known way to consume web feeds, there are other formats that are also widely supported:

json feeds
atom feeds

In this article I'll only be talking about RSS - and briefly mentioning atom - but all the things I'm talking about apply to all of them.

The structure of an RSS Feed

Let's take a look at what an rss feed looks like (you can find mine here) - specifically the one for my website

<rss version="2.0">
  <channel>
    <title>Matteo's Log</title>
    <link>https://www.matteogassend.com</link>
    <generator>Nuxt & Feed</generator>
    <language>en</language>
    <atom:link href="https://www.matteogassend.com/rss.xml" rel="self" type="application/rss+xml"/>
    <item>
      <title>T3Chat Cloneathon Postmortem</title>
      <link>
      https://www.matteogassend.com/articles/t3-cloneathon-postmortem
      </link>
      <guid isPermaLink="false">t3-cloneathon-postmortem</guid>
      <pubDate>Mon, 14 Jul 2025 00:00:00 GMT</pubDate>
      <description>
      I participated in the T3Chat cloneathon; here's how it went
      </description>
      <content:encoded>
        ...
      </content:encoded>
    </item>
  </channel>
</rss>

First we have the main tag specifying that this xml document is an rss feed and its implementation version (in this case, version 2.0).
We then get to the channel definition; this is the actual feed that will be consumed and inside of it we can find info such as its name, description, language and more.
Then, for each element we want to add to our channel, we have a item tag. Each item contains a name, description, publication date, unique id and optionally the raw content of the item (in this case, a blog article).

How to build one in Nuxt

Luckily, Nuxt routes can be either Vue components or server endpoints - you could also use tsx, but we'll skip that for now. Server - or API - endpoints are handled by Nitro and use the classic browser Request & Response, meaning we can simply return an xml document with the correct headers and we're good to go! Let's see how to do it in detail

Declaring the API route

Let's start by declaring the Nitro route; in this instance I'll have it match the /rss.xml path, meaning I will create a file here: /server/routes/rss.xml.ts and fill it with the basic Nitro handlers:

export default defineEventHandler(async (event) => {
  //generate the feed
  ...
  //return the actual feed data here
  return {}
})

The RSS Feed enter the game

We could write the xml document by hand, but why bother? There exist the perfect package for this: feed. It allows use to programmatically build a feed and return it in different formats. Let's see how we can integrate it with Nitro.

First things first, let's install the dependency:

npm install feed

And let's start creating the feed itself; we'll begin by setting all the basic info needed for the feed and leave the items for later:

  const feed = new Feed({
    title: "Matteo's Log",
    description: "All the articles from matteogassend.com",
    id: <a unique id>,
    link: <url of your website>,
    language: "en",
    copyright: `All rights reserved ${new Date().getFullYear()}, Matteo Gassend`,
    updated: new Date(),
    generator: "Nuxt & Feed",
    feedLinks: {
      rss: `<url of your website>/rss.xml`,
    },
    author: {
      name: <name of the author>,
    },
  });

With just this, we could generate an xml document and return it with the endpoint we made above. Let's do just that

export default defineEventHandler(async (event) => {
  ... // the feed is here

  return feed.rss2()
})

We only need two other things before we have a fully functional rss feed:

informing the browser of the type of data we're sending
inserting the actual items in the feed

The first step is simple enough, so let's get it out of the way; before returning the generated feed, let's set the content-type header. This header tells the browser how to understand the content we'll send it back; you can see it used mostly when sending back json data - when making an api, for example. Here's how we can do it in Nitro:

setResponseHeader(event, "content-type", "text/xml");

This tells the browser we're sending back an xml document.

Adding Items to the feed

Now that we have our basis covered, let's get to adding actual items to the feed. In my usecase, I needed to fetch items from a Nuxt Content collection and add it to the feed. So let's do just that:

  const articles = await queryCollection(event, "articles")
    .order("publishDate", "DESC")
    .all();

If you don't have a collection, just pretend this is an array of objects.

After that, it's as simple as looping over your data array and calling the addItem method on your feed instance:

  articles.forEach((article) => {
    feed.addItem({
      title: article.title,
      id: article.slug,
      description: article.summary,
      date: new Date(article.publishDate),
      link: `${BASE_URL}/articles/${article.slug}`,
      content: article.rawbody,
    });
  });

And that's all you need to do to generate an RSS feed in your Nuxt app! I also added an atom feed with the exact same logic - I just had to replace rss2 call with atom1 and you're done!

Adding the Feed to the Website

Once you have your server route you just need to add it to your pages and most rss readers should be able to pick it up. Let's say our rss feed lives at /rss.xml: if so, we'll need to add the following link tag to our page's head:

<link rel="alternate" type="application/rss+xml" title="Your feed's title" href=`${BASE_URL}/rss.xml`

If you're using unhead, then this can also be done in a useHead composable hook using something like this:

useHead({
  link: [
    {
      rel: "alternate",
      type: "application/rss+xml",
      title: "Matteo's Log",
      href: "/rss.xml",
    },
    {
      rel: "alternate",
      type: "application/atom+xml",
      title: "Matteo's Log",
      href: "/atom",
    },
  ],
});

And you're officially done!

Developing and Compiling Webapps with Vite and Go

Matteo — Sat, 10 May 2025 00:00:00 +0000

this article uses custom markdown components. Expect some of them to break in places other than my blog

I've recently been playing around with Go (and RPC) and have stumbled upon the embed package, which allows us to specify files and directory to be embedded (hence the name) into the final binary. You would usually use this to embed something like the db schema / migrations, but there's also a world where this can be used for a vite bundle so that we can embed a SPA (single page app) into the final executable; neat right ?

Bundling the assets

Let's consider that we already have a Vite application and that we have already run an npm run build to generate its bundle and so we have a dist folder where all our front assets are.

If we have a standard http mux, we could simply add a Handle function. Let's see what that would look like:

// this file could be called front_prod.go

//go:embed dist/*
var embedFS embed.FS

func Front(mux *http.ServeMux) {
    staticFiles, err := fs.Sub(embedFS, "dist")
    if err != nil {
        log.Fatal(err)
    }
    fileServer := http.FileServer(http.FS(staticFiles))
    mux.Handle("/", fileServer)
    log.Println("Serving static files from embedded filesystem")
}

Let's break this down: most of the magic happens on these lines:

//go:embed dist/*
var embedFS embed.FS

These lines tell go to get the dist folder and all its subfolders (and files) into a structure that matches the standard library's FS interface and stores it in a variable called embedFS. Inside the Front function we simply target the dist folder (with a bit of error handling ) and we add the FileServer as a route to our mux.

Caveats

This is a simple and pretty "dumb" implementation of the "production assets"; if using something like React, you might need to write some logic to redirect the requests to the index.html file if no matching asset is found.

What about during development ?

Well, I think having to build a Vite app every time you make a change during development is not the best DX, right ? What if I told you there was a way that you could have all the power of the Vite dev server (i.e. hot reload) from within your go app ?

Writing the Vite Proxy

This is the (mostly) the whole code we'll need to do this:

// this file could be called front_dev.go

func createViteProxy(target string) http.Handler {
    url, err := url.Parse(target)
    if err != nil {
        log.Fatal(err)
    }
    proxy := httputil.NewSingleHostReverseProxy(url)
    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        // Update the request to point to the Vite server
        r.Host = url.Host
        r.URL.Scheme = url.Scheme
        r.URL.Host = url.Host
        proxy.ServeHTTP(w, r)
    })
}

func Front(mux *http.ServeMux) {
    viteProxy := createViteProxy("http://localhost:5173")
    mux.Handle("/", viteProxy)
    log.Info("proxying requests to vite dev server")
}

Let's break it down!

We have the same function signature for the Front function
:::callout
Remember this, it will be important later on
:::
The magic happens with the createViteProxy function, where we return a new http.HandlerFunc that sends the request through a SingleHostReverseProxy that points to the Vite dev server. This means that all requests the Front function handles will be sent to the Vite server; this allows all the hot reload goodness that Vite provides to work out of the box.

How Do You Switch Between the Two ?

Here's the fun part: you let the compiler do it!

On its latest versions, Go supports a feature called build constraints. These are values that you can pass your go build command and that can influence which files the compiler will include.
When I shared the whole code file, I might have lied; there are actually three more lines you might need to have at the top of the file:

//go:build dev
//+build dev

// the rest of the code goes here

The two comments above are the two syntaxes for build constraints. These tell the compiler to only include this file if this constraint is passed to the build function: here's how you would run this:

go build -tags dev

Once you add the reverse condition on the "production" logic, you're done!
:::callout
you can just add a ! before the constraint you're checking
:::

This is why I said it would be important to name the Front function the same in both files; if both files are in the same package, the rest of the program is completely oblivious to this switcharoo happening in dev or prod!

Should you do this ?

While this might almost look like magic, there are cases in which this might not be the ideal choice:

If you need more complex routing that just redirecting to index.html

While I have addressed this a bit in the related section, I just want to point this out again.

separation of concerns and scalability

This setup will obviously not work if you want to deploy your frontend code to a dedicated service (Vercel, Netflify etc), this will obviously not work.

Still, there are some cases where you might want this:

offline-first

Weirdly, this could work really well with an offline-first approach; download the binary, run it on your system and just browse to localhost:3000 (or any other port) and you have your whole application running, no internet required (except if you're connecting to external services, obviously)

simple deploy

It's a binary.

great DX

With this setup, you have a backend and frontend living on the same port (and/or domain), meaning you don't need to worry about CORS, proxy rules and whatever else causes mental breakdowns to developers nowadays.

Custom markdown components with remark and web components

Matteo — Fri, 21 Feb 2025 00:00:00 +0000

this article uses custom markdown components. Expect some of them to break in places other than my blog

Recently, I ported my portfolio (again) to Astro from Hugo. While I really liked Hugo, I missed the choice JS gave me (plus, I was bored) so here we go!

Porting Data

Everything is markdown in Hugo (mostly), so transitioning to and from was pretty simple; just import the data, build the collections and we're off to the races! The one thing I had to deal with was importing the cover images for the opengraph images, but that wasn't hard and went on without many issues.

Where are my shortcodes ?

One thing that I really like about Hugo is how it handles shortcodes. This is how I could generate a stackblitz embed using Hugo: {{<stackblitz url goes here>}} That line right there would then be mapped to a component called stackblitz where I could describe the html element and I was done! But unfortunately, Astro does not handle shortcodes (or similar) natively, so I had to get creative.

Astro uses remark and rehype to transform your markdown collections into html.

:::callout{type="info"}
I've already written about the unified ecosystem, you can checkout that article here
:::

That means that we can hopefully build something within this pipeline and recreate the feeling of shortcodes.

Enter Remark Directive

Turns out we (kind of) can! There's a remark plugin called remark-directive that enables remark to parse directives (basically shortcodes, but maybe more powerful). With this plugin, we can then write a custom function that looks for these directives and "does something with them".

What do we do with a remark directive ?

Let's take a small look at the source of one of my articles:

Astro uses [remark](https://github.com/remarkjs/remark) and [rehype](https://github.com/rehypejs/rehype) to transform your markdown collections into html.

:::callout(type="info")
I've already written about the unified ecosystem, you can checkout that article [here](/blog/markdown-editor)
:::

The thing with the 3 : is a remark directive. When I traverse the tree of the article (an abstract syntax tree describing the repo), I can check whether the node I'm looking at is a directive. If I find one, I can then check the type of directive (there are 3) and finally get its attributes.

For example, the following snippet

::stackblitz{#mg-fbr-express}

Contains a node that is a leafDirective with an id of mg-fbr-express

:::callout{type="info"}
the attributes section of the directive supports multiple elements separated by a whitespace like this: ::codesandbox{projectType="devbox" projectid="cwmtww"}
:::

Getting the node's attributes is pretty straightforward from there: they're in

node.attributes

And now we have everything we need to create our custom elements!

Web Components

Web Components are not new (they have been baseline available since 2021) but I don't think I've ever seen them much out in the wild. They have lots of advantages and will work pretty well in this use case, but they also come with some drawbacks.

The Good

Web components, as stated above, are pretty easy to get up and running and put in a page. Here's the code for my youtube embed web component:

class Youtube extends HTMLElement {
    constructor() {
        super();
    }

    connectedCallback() {
        this.render()
    }

    render() {
        const iframe = document.createElement('iframe');
        iframe.src = `https://www.youtube.com/embed/${this.getAttribute('videoid')}`;
        this.innerHTML = `<div style="width: 100%; min-height: 500px;"><iframe class="w-full min-h-[500px]" src="https://www.youtube.com/embed/${this.getAttribute('videoId')}" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" allowfullscreen></iframe></div>`;
    }   
}

customElements.define('wc-youtube', Youtube)

This little snippet does all the heavy lifting to generate an iframe tag with the provided videoid and all the necessary styles and (potentially) logic.

Notice the last line; that's where we tell the browser that there's a new valid tag (called wc-youtube) that is represented by the Youtube class.

The Bad

Well, if web components are so nice, why is everyone bothering with frontend frameworks ?

Well, because it’s not all roses. There are some design principles that you need to take into account if you want to use web components. If I had to choose one thing that "grinds my gears" about web components is that they are encapsulated; while this has some benefits in my use case this caused quite some headaches.

I tried for quite some time to have TailwindCSS (which I'm using to style this whole website) pick up and generate the styling required by the web components. Because of this encapsulation (called the shadow DOM, by the way) this proved pretty hard - I probably would have needed to spend too much time looking into it (maybe next time?).

The Compromise

So, what did I do ? I simply rewrote the styles in plain css. I didn't need that much styling to begin with, so why bother ?

Should you do this?

Honestly I don't know; this "stack" fit my use case pretty well and is, by definition, portable (I could use these web components on basically any website). Could I have found another solution? Probably. Was this fun? Kind of. Was this interesting? Definitely.

How to rebuilt a personal website

Matteo — Sun, 15 Dec 2024 00:00:00 +0000

The first website I ever had was built on wordpress; it was a way for my friends and me to write small articles in things we liked at the time (like the Lavender Town Syndrome - yes, it was a long time ago) and share it with one another. Since then, said website has changed and evolved. Through it all it at some point became my professional portfolio and, as such, changed what was required of it. It became a place to showcase all I did (and help me land a job); and so wordpress was left behind. Throughout the last 4 years it went through some major rewrites; this article is a way to log those rewrites and what I've learned along the way.

Timeline

I think there are mainly 3 major releases:

Astro
Laravel
Hugo (the current one)

Astro

Astro is an awesome web framework that works really well with static content (which is baiscally all of my content). It worked pretty well with all my content collections and had pretty much all the extensions I needed, but I still needed to add custom extensions to remark to have it handle some iframe elements I needed in some articles (codesandbox and stackblitz embeds, basically). This ultimately led me to look for a more customizable solution (where I could easily build some more custom stuff). This leads us to the first rewrite of this version.

Laravel

Now, I hear you asking:

The honest answer to that is: why not? I believe that if you want to try new technologies (and can afford to - meaning probably don't do this in a work production app), you probably should. I had been hearing of Laravel for a while and finally gave it a shot.

It was a really nice experience and it was really easy to add some more integrations like automatically adding photoswipe tags to each image in an article (I even made an extension for it). It also allowed me extra space to add some more quality of life stuff, like a search function using meilisearch and its laravel scout interface. Plus, Livewire is pretty cool to use (though I have my issues with it - to be discussed in a later post).

Ultimately, though, it was probably too much for a personal website; it had too much overhead to simply publishing content, mainly just updating the website (without using Forge or Vapor); containerising the application definitely helped, but in my opinion it still took too long and, after some more reflections, it was needlessly overcomplicated for a blog/portfolio.

Hugo

And thus we get to Hugo. I had heard of it in passing but had never really looked into it - so I finally did; it's pretty cool. It:

supports md files natively
can handle tags and series automatically (taxonomies FTW) And best of all, it just produces a public folder with all static html that I can send off to a cloudflare pages project and call it a day. This allows me to do as much (or as little) customization to the output as I want (more on that in the next section). I believe it is (for my use case, obviously) the most compelling solution at this time (as proven in this article, I'm not against rewriting all of this at some point)

Overengineering simplicity

But it's not over yet! You know how I said above that you should be able to experiment and have fun, right ? Well, let's say I managed to find some fun stuff to do with this new setup. I'll just list them here, because some of this stuff is interesting enough to get its own articles:

client-only search using Lunr and AlpineJS
automatic og (opengraph) image generation
automatic photoswipe image rendering

And these are the potential things I might add later:

newsletter subscription section
automatic bluesky post with the new article
and so much more

I will also look into having a self-hosted Github Runner if I end up reaching the limits of the free plan (though that should hopefully not happen)

Dotfiles, the nix way

Matteo — Wed, 30 Oct 2024 08:55:50 +0000

I've recently started exploring the Nix ecosystem (I got hooked by Vimjoyer's videos) and decided to give it a try (I even installed NixOS on my laptop, but that will come in a later article).

Dotfiles

First things first, what are dotfiles ? They are basically configuration files that are usually preceded by a .. or that are usually kept inside a folder called .config in your home directory. They are used to configure per user settings for apps that support it. For example, you could use it to change the keybindings in your i3 configuration, or pimp your neovim config or just change the color scheme for your favorite terminal. Why would you want to do that, I hear you ask? Why not, I would answer...

Ok, let's be serious for a second; if you went through the (kind of) trouble that installing Linux is (though that obviously depends on the distro you choose), then you'd probably want to customize to be more "you" or to better fit your needs. Here's an example: I have pretty bad eyesight and tend to prefer some specific colors for windows, text and stuff; after a while, I found out that the Catppuccin Mocha theme is not as hard on my eyes than some other (or even the Gnome or KDE default dark mode, for that matter), so I like for as many of the applciations as I daily drive to use that same theme (plus, I think it looks pretty).

Here's how you would configure rofi to use Catppuccin Mocha:

create a mocha.rasi file that will contain all the theme customization rule
create a config.rasi file in .config/rofi/ that will contain the import rule for the theme you want: @theme "catppuccin-mocha" You might have noticed what my problem is with these kind of configuration files; most of them are custom file formats! This might be fine if you have one or two configuration files, but it gets old really quick if you have more than that.

My Journey with Dotfiles

Step 1: files ending in dots

I started playing with dotfiles when I first installed Arch (btw), and the first approach I had was to just write my files directly in the .config directory. That phase ended quickly once I mistakenly wiped my OS and lost all said files...

Happens to the best of us, right?

Step 2: version control for the win

Once I got my system up and running again, I decided to version control those files (you live you learn, right?)
Here's the problem with that approach: you either version control the whole .config directory, or you can create many small repos for each program because, spoiler alert, anything can write stuff in that directory.

Step 3: Stowing

So now you have a git repo containing all your dotfiles but cannot directly clone into to replace your .config folder, what do you do? You find out there's a tool that could fix all these problems: GNU Stow!

This tool allows you to create symlinks to anywhere and keep all your original files in a single folder (sound familiar?)

I'd been on this step for a long time and kind of liked it, to be honest. But then I started hearing about Nix more and more often and so decided to take a look at it.

Step 4: Manage your home

I'd read about Nix a while ago but had never explored it correctly. That changed when I got some time off work to tinker with some stuff. That's when I heard about home-manager and decided to give it a try.

Home Manager

Home-manager is a tool that allows you to declare your config files and put them wherever they need to be. You can declare almost anything directly using the Nix DSL, but you can also simply copy files into their correct directory and even clone directly a repo from Github (this is the method I use to get my neovim configuration instead of rewriting it to use Nix).

Let's take a look at a simple home-manager home.nix file:

{config, pkgs, ...}
{
    home.stateVersion = "24.05";
    home.packages = [
        pkgs.fzf
        pkgs.tmuxifier
    ];
    home.file = [
        ".config/waybar/mocha.css".source= ./styles/mocha.css;
    ];
}

This little configuration will ensure that both fzf and tmuxifier are on your user's $PATH and copies over a css file from your directory into the appropriate .config directory.

But this is not all we can do with home-manager (again, I highly encourage you to read the documentation); let's see how we can configure some more stuff.
This is how you can configure kitty, a tty:

  programs.kitty = {
    enable = true;
    settings = {
      "tab_bar_min_tabs" = 1;
      "tab_bar_edge" = "bottom";
      "tab_bar_style" = "powerline";
      "tab_powerline_style" = "slanted";
      "tab_title_template"= "{title}{' :{}:'.format(num_windows) if num_windows > 1 else ''}";
    };
    font = {
    name = "JetBrainsMono Nerd Font";
    };
    themeFile = "Catppuccin-Mocha";
  };

This enables kitty, sets some configuration stuff, like the topbar style title template string, but ti also sets up the font to use in the terminal and the theme the terminal will use.

How about writing configs when home-manager does not have a module for it (or you can't find it)? Well, here is how I configure tmux using home-manager:

programs.tmux = {
    enable = true;
    plugins = with pkgs.tmuxPlugins; [
      catppuccin
    ];
    extraConfig = ''
      set -g prefix C-s
      set -g mouse on
      set-option -g status-position top

      set -g @plugin 'tmux-plugins/tpm'
      set -g @catppuccin_flavour 'macchiato'
      set -g @plugin 'kenos1/tmux-cht-sh'
      set -g @plugin 'jimeh/tmuxifier'
      set -g @catppuccin_window_left_separator ""
      set -g @catppuccin_window_right_separator " "
      set -g @catppuccin_window_middle_separator " █"
      set -g @catppuccin_window_number_position "right"

      set -g @catppuccin_window_default_fill "number"
      set -g @catppuccin_window_default_text "#W"

      set -g @catppuccin_window_current_fill "number"
      set -g @catppuccin_window_current_text "#W"

      set -g @catppuccin_status_modules_right "directory user host session"
      set -g @catppuccin_status_left_separator  " "
      set -g @catppuccin_status_right_separator ""
      set -g @catppuccin_status_right_separator_inverse "no"
      set -g @catppuccin_status_fill "icon"
      set -g @catppuccin_status_connect_separator "no"

      set -g @catppuccin_directory_text "#{pane_current_path}"
      run '~/.tmux/plugins/tpm/tpm'
    '';
  };

This configuration here allows you to see how you can pass "raw" configuration values via extraConfig and how to setup plugins taken directly from nixpackages.

The last example I want to show you, is how to retrieve configuration files from a github repository and copy it over to the correct .config folder. This goes in a bit deeper in the Nix DSL, but I think it still keeps pretty readable:

let
  neovim_config = pkgs.fetchFromGitHub {
    owner = "matfire";
    repo = "config.nvim";
    rev = "044cb8670307bb3195607b90229f26ffcb61d46d";
    sha256 = "sha256-tzWcYrRGX82kBmPc50LjQmXfNjBoT/sLNanH470NuAE=";
  };
in
{
    home.file = {
        ".config/nvim".source = neovim_config;
    };
}

This will automatically clone and verify (with the sha256 you provide) the right repository and commit, and then clone (or copy) it over to the right place.

The best of both worlds ?

Personally, I really like doing configs like this; it lets me keep it all in one format (with the occasional exception, obviously) and be sure that whatever OS I use this on, I'll get the same programs & configs each time.

But it still requires you to learn a new language (or the basics of it, at least) and it's a functional language, which may be a blocker for some. The first experience I ever had with a functional programming language was Haskell back in university, so I can understand the animosity with this principle.

Still, I believe it worthwhile if you daily drive Linux and have a lot of config files to learn and use this kind of system.

Build a reverse ssh tunnel reverse proxy for (not) fun and (not) profit

Matteo — Mon, 03 Jun 2024 14:58:51 +0000

A few years ago, a team I was part of was working on vivi, our master thesis's project. You can read more about it in the link above if you'd like, but the gist of it is; we were trying to build a solution to handle internet traffic and routing for ephemeral events (think something like comic-con etc) with lots of features and a user interface non-technical users could use and understand.

Where does a reverse ssh tunnel reverse proxy fit into this

Context

When the time came to built the box that would live between the router and the rest of the network, we went (al least for the POC - proof of concept) with a RaspberryPi 4. We tried different solutions to handle communications between our backend server and all the machines, including using balena os - which would have worked fine had we not needed to work with the network stack of the device.

Build it yourself

So that's why we ended up building this kind of Frankenstein monster of a service. We needed a way to remotely connect to the device to check its status and perform maintenance operations (i.e. reboots, firmware updates etc). And before you ask:

couldn't you have just used the ip address of the machine or exposed a port on the network to connect to it?

NAT and local ip addresses

Fasterthanlime has an excellent video describing how the internet works, you should check it out

A (forward) ssh tunnel

A normal (or forward) SSH tunnel allows you to securely access a remote service over an encrypted SSH connection.

For example, let's say you want to access a web service running on a remote server's port 8000, but that port is blocked by a firewall. You can create an SSH tunnel by connecting to the remote server (assuming port 22 is open) and forwarding a local port, say 9000, to the remote port 8000:
you can run the command:

ssh -L 9000:localhost:8000 user@remote_server

with this command, you can then open the address localhost:9000 and the request will then be forwarded to the remote machine's ssh port and then finally reach the destination port (8000 in this case). This is also called Tcp Forwarding.

Let's reverse that

Now, what happens if the machine I need to connect to is behind a firewall and/or a NAT? It would most likely not work because:

I don't know the machine's actual IP address
I cannot (usually) initiate a connection from outside the local network without an exposed port or something similar

And so, enters the reverse ssh tunnel.
A reverse ssh tunnel is based on the same principle as the normal ssh tunnel, except it contains an additional step, with the remote machine using the initial connection from the other host to create a new "tunnel" toward the initiating machine. This allows to bypass the issues with firewalls and NATs listed above.

For example, to tunnel the SSH port (22) of a remote machine to port 8022 on your local machine, the command would be:

ssh -R 8022:localhost:22 user@local_host -N

How we built it (attention: do not try this at home, there are easier ways to do this)

There are a couple of part to this setup:

The http server onboard each device
The systemd service responsible for the ssh tunnel on each device
The Server handling all of these connections and all the reverse proxy logic

Http Server

The Http server is the API we built to manage the device; it allowed us to remotely restart the device, update the dependencies, retrieve its logs etc...

It was a simple NestJS application.

Systemd Service

The systemd service was responsible for receiving a port from the server and configuring the reverse ssh-tunnel to connect to said port.

Remote Server

The remote server was the one receiving all the connections and handling the domain name registration for each device and its corresponding reverse proxy configuration.

The code is available here if you want to take a look at it (though I would not recommend it)

The steps were:

A device would upload its ssh public key to the remote server
The remote server would then generate an nginx config and associate a domain name to a port number
The port number would be sent to the device to configure its service
THe connection was then started on boot

Why you shouldn't do it this way

The main issue with the way we did this is security; there really is no central authority managing this.

The device uploads its ssh key and registers itself with the server
The server never verifies that the request it coming to a legitimate source.
The server also doesn't check to see if the ssh connection for a specific host is aiming for the right port

Alternatives

A simpler way to handle this, given the infrastructure requirements, would probably have been a mesh vpn like tailscale or zerotier - or even plain old wireguard. This would still allow all reverse proxy goodies, but would provide a central authority to handle authentication (the server provides and checks for correct credentials on a new connection).

Really, a vpn would probably have simplified a lot of things for this use case

Using Shadcn-ui with Inertia and AdonisJS

Matteo — Tue, 26 Mar 2024 14:01:34 +0000

Since AdonisJS V6 has experimental support for Inertia, I thought it might be a good idea to see if I could configure shadcn/ui to run with the aforementioned stack.

Configuring Inertia with AdonisJS

Since support is experimental, I'll refer you to Adonis's documentation on this procedure. If you're starting from scratch, it may be as simple as installing their inertia starter kit.

Installing Shadcn/ui

To install shadcn/ui, you can follow the basic instructions for Vite-based projects, but we'll need to adapt a few steps.
The one thing to keep in mind is that you need to specifiy inertia's css file as the global CSS file during setup.

Where to store components and libs

I would personally advice (also, this is what I tested) to store all shadcn related files inside the inertia folder; i personally created a lib folder and had shadcn install everything in there.

tsconfig

The documentation asks us to create aliases in both the tsconfig file and the vite.config.{js|ts} file. If you only change those in the root directory, shadcn will work fine, but your inertia pages will not be able to resolve the imports using those aliases.
You can definitely stop here for this step and modify the imported components to use a normal path instead of the aliases it includes.

But if you want to avoid that headache, there is one more tsconfig file you'll need to modify; the one inside the inertia folder. Just copy the same aliases you just set up in the root project.

Here's, for example, my root project tsconfig:

{
  compilerOptions: {
    paths: {
      //other paths can go here
      "@/*": ["./inertia/lib/*"]
    }
  }
}

which then translates inside the inertia folder to:

compilerOptions: {
  paths: {
    // other paths here
    "@/*": ["./lib/*"]
  }
}

as for the vite config, here's the interesting bit:

{
  resolve: {
    alias: {
      // other aliases can go here
      '@': `${getDirname(import.meta.url)}/inertia/lib`
    }
  }
}

Tailwind Config

After running the installation commands, we need to change a few settings from those created by default in our tailwind config file. This is because shadcn makes certain assumptions regarding the location of all our components and files.
The only thing to modify is the content array. If you're only using inertia (with React, in this case), you can probably use something like this:

{
  content: [
    "./inertia/**/*.{js,ts,jsx,tsx}"
  ]
}

Conclusion

There you go! Now you can enjoy using shadcn/ui with Inertia and AdonisJS. To demonstrate this, I built a small example you can find below:

Building a dynamic form with Svelte and Typescript

Matteo — Fri, 23 Feb 2024 13:48:57 +0000

In the quest to make magiedit always better, I figured out that people may want to publish to multiple "accounts" on the same platform. So, the goal for the next feature was to allow just that. A user should be able to select the platform they want to create a Publisher for, fill in the required data, and be able to publish to it.
The problem was in the second to last step; the form. How do you handle the fact that different platforms require different authenticating elements to send requests?

Generating a form from a class

As mentioned in a previous article, all the platforms have a decorator that adds them to a list that can be imported in other files, meaning I could get a list of supported platforms and generate a select, allowing the user to select the platform they wanted to configure. The next step consisted of having a way for the class to describe the input it needs to handle publishing an article.

Describing form elements

After some deliberation, I settled on the following structure:

interface IPlatformSetting {
    type: string;
    name: string;
    label: { htmlFor: string; value: string };
    settings: Record<string, unknown>;
}

type defines what form element will be rendered (i.e. input)
name: the name of the element (pretty self explanatory, I know)
label: the settings for the label (both the for attribute and the actual text inside it)
settings: an object of settings for the html element; as an example, here's what the Dev.to platform settings look like:

{
    type: 'input',
    name: 'api_token',
    label: { htmlFor: 'api_key', value: 'API Key' },
    settings: { type: 'text', required: true }
}

There still is a bit of information duplication, but for now it works pretty well.

Displaying the form elements

Once the user has selected the platforms they want to publish on, the next step is to display all the fields necessary for that specific platform. Remember how we had a method that described precisely this? This is where we get to use it.
With Sveltekit, this could look somthing like this:

{#if setting.type === 'input'}
  <Label for={setting.label.htmlFor}>{setting.label.value}</Label>
  <Input id={setting.name} name={setting.name} {...setting.settings} />
{/if}

If you ever need to do more field types, just add them as available types for each setting element and modify the if condition (hoping someday to have a switch statement in svelte - or pattern matching).

Handling submission

This next step is probably the easiest. Since you're also sending the select platform template, you can reference that to determine if the data is valid (why not try superforms? I made an adapter for it).

With no validation whatsoever, it could look something like this:

const formData = await request.formData();
const { publisher_id, publisher_name, ...args } = Object.fromEntries(formData);
await db.insert(userPublications).values({
    publisherName: publisher_id,
    publisherData: args,
    name: publisher_name,
    userId: user.id
});
return { message: 'ok' };

How filesystem-based routers work: building one for express

Matteo — Sun, 22 Oct 2023 09:55:45 +0000

Have you ever wondered how Next, Sveltekit, Nuxt (even Expo now) do their routing? What's the magic that makes it so when you create a file called +page.svelte in a directory called routes, just for it to magically works? Well, wonder no more! I'll show you how to build your own file-based router for express in Javascript, though the concepts we'll see are usable in other frameworks and other languages. This article will focus on parsing files, ignoring folders (because that is a whole of grenades I'm not yet ready to step - and write - on). Let's get to it!

How file routing works

First, let's start by saying what file-based routing is and how it works.
Usually, a function will loop through the routes folder (ever noticed how you always have a single place where you place your pages? this avoid crawling the whole project directory every time your app starts), getting all the files matching a certain pattern (for svelte, that will be +page.svelte) and, based on their location in the folder, determines what requests should be sent to it. The first part of this series, as specified above, will not be handling folders; instead, we will just do a basic file router; here's how it'll work:

This means that when we'll call our function, it will step through our route directory and generate a separate route for each filename: user.js will create /user for example.

Building a file-based router

Initial Setup

First of all, we should setup our base structure. For this example, I'll have an index.js file at the root of my project that will instanciate the express application and call the function to generate the routing. Then I'll have a routes folder that will contain - you guessed it - our routing files. The only dependency you should need is the express package; if you haven't already done so, you should install it in a new project using:

npm install --save express

and let's initialize the express application in index.js

const express = require("express");

const app = express();

app.listen(4000, () => {
    console.log("listening");
});

This should be enough to have a basic http server listening on port 4000 (btw, you should probably use an environment variable here instead of hardcoding it like this). Next, let's see how we should define our route file; inside our routes folder, let's create a user.route.js file; this suffix (.route) allows us to filter only the files we are sure belong to our application thanks to the power of regex (oh yes, we'll be writing a regex - just one, I promise)!

Making a route

Let's start by defining a simple rule: every route file should have a Router instance as its main export. This will allow us to do simple programmatic requires to load our route files (we'll look at how to do more specific filtering and imports in a following article, don't worry).

So, let's say we have a user.route.js file containing the following:

const router = require("express").Router();

router.get("/", (req, res) => {
  res.send("test");
});

router.get("/:id", (req, res) => {
  res.send(`test ${req.params.id}`);
});

module.exports = router;

When our loader will be finished, this should generate two routes:

/user
/user/:id (this one will match /user/1, /user/2 etc)

Making the loader

Now it's time to make the actual loader:

Let's recap what our loader needs to do:

walk the routes folder
for each file matching the pattern (routeName).route.js, add a route to our express app that looks like /routeName

So, i'll make a new file called router.js which exports an asynchronous function. This function will take as an argument the express application and define a regex we will use to match our route name and save it as a group.

module.exports = async (app) => {
  const fileNameRegex = /(.*).routes.js$/;
};

And in this function we'll begin by walking the whole routes folder

/* add this at the top of the file */ const fs = require("node:fs/promises");

  const folders = await fs.readdir("./routes");

And then check each file to see if it matches the regex we defined earlier:

  folders.forEach((file) => {
    const regexName = fileNameRegex.exec(file);
    if (!regexName) return;
  });

And finally, we add the route to our application with a little log line:

    console.log(`[+] Router file ${file} loaded under /${regexName[1]}`);
    app.use(`/${regexName[1]}`, require(`./routes/${file}`));

The last step is to use our loader function: your index.js should look something like this:

const express = require("express");
const loadRoutes = require("./router");
const app = express();
loadRoutes(app).then(() => {
  app.listen(4000, () => {
    console.log("listening");
  });
});

This is the simplest way to make a file-based router in express js. This logic can obviously be translated to be used in other framework, like this plugin for fastify

You can see a working example below:

test everywhere with dagger.io

Matteo — Sun, 15 Oct 2023 09:28:43 +0000

Have you ever had to implement a CI/CD pipeline and then proceed to push to a repository 10/20 times just to see if the pipeline works correctly? Well, this ends today!

Dagger (not the stabby kind)

Dagger's tagline is

CI/CD as Code that Runs Anywhere

It is a way for developers to create pipelines that run everywhere, be it locally, as Github Actions or anywhere where you can spawn containers; it is what I use to do a test build on magiedit and what I'll use when I eventually write unit tests (it'll come one day, I promise.)

How do you use it?

Dagger provides different sdks (for Javascript, Python, Go etc) and they also have an HTTP and GraphQL api, so you can use with whatever coding language you prefer. Then you just run it wherever your pipelines run.

Creating a Pipeline

In this article I'll be using the Javascript sdk, because that is the one I know better (and because it is my article, after all). We'll be looking at how to create a simple pipeline script with some extra configuration like setting some env variables.

Prerequisites

Container engine

Dagger requires a container engine for it run wherever it needs to run (at this stage, at least, locally); the recommended one is Docker (I have an article on the basics of Docker here), but other runtimes are compatible (podman, containerd etc): here's an article detailing how to use them, though I would still recommend Docker.

Install Dagger CLI

You can find the installation instructions here, but the gist is (for Linux / WSL) to execute this line:

cd /usr/local
curl -L https://dl.dagger.io/dagger/install.sh | sh

Install Dagger SDK

For this example I'll be using the NodeJS sdk which you can install like this:

npm install @dagger.io/dagger --save-dev

Writing the actual pipeline

The main thing to do is import the connect function from the Dagger sdk, because everything will happen in there:

import { connect } from '@dagger.io/dagger';

Once we call this function, we can pass it a callback that gets as its argument the client instance; this is what we will use to define our pipeline:

connect(
    async (client) => {
    },
    { LogOutput: process.stdout }
);

As you can see from the snippet above, you can also specify where the output logs will be sent; in this case, the standard output is good enough, but you could also sent them to a file that could, for example, be uploaded as an artifact for the pipeline run.

Then you can declare a runner with a base image and run all the commands you need with it;

        const node = await client
            .container()
            .from('node:18')
            .withDirectory('/app', client.host().directory('.'), {
                exclude: ['node_modules', 'ci']
            })
        const runner = node.withWorkdir('/app').withExec(['npm', 'install']);

In the above snippet, we declare a container based on node 18 and we copy the contents of the current directory (excluding the folders called node_modules and ci), then set the working directory to /app (the directory we copied our project to) and execute npm install inside it.

Now, how about running a build script and getting the error output (if any)? Simple, we just continue adding calls to our connect callback:

await runner
    .withExec(['npm', 'run', 'build'])
    .stderr();

Running the pipeline

To run pipeline, you simply execute it like any other NodeJS script; assuming you have saved your script as build.mjs in a ci folder, you can just run:

node ci/build.mjs

And that's how you can create and run a basic pipeline; note that you can create multi-stage builds, publish images, using existing Dockerfiles and much more!

Bonus Round: Github Actions

Running a Dagger pipeline in Github Actions is pretty straightforward; you need to setup your environment to be able to run Dagger, which means basically installing nodejs js and installing dependencies:

name: build
on:
  push:
    branches:
      - master
      - feature/*

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - uses: pnpm/action-setup@v2
        with:
          version: 8
      - uses: actions/setup-node@v3
        with:
          node-version: 18
      - name: Install dependencies
        run: pnpm install
      - name: Build
        run: node ci/build.mjs

In this example, I'm using pnpm to install my dependencies, and then simply execute the pipeline.

If you want to learn more about Dagger, check out their website; they have some very nice real case articles on how to use Dagger to build more complex pipelines.

building a basic markdown editor: unified, trees and data

Matteo — Mon, 02 Oct 2023 12:06:54 +0000

As you have probably guessed from the previous articles in this series (go read them if you haven't, btw), the main thing when building a markdown publishing webapp, is the markdown editor itself.

But not all editors are born equal; there are many ways of building one, with benefits and tradeoffs. In this article I'll try to explain what led me to my current solution (not yet completed, but still I'd say it's about 80% done).

Markdown

if you don't know what markdown is, think of it as kind of like html; it is a type of text with special characters or combination of characters that get interpreted and displayed according to a determined specification; for instance, an html <h2> tag would be translated in markdown with ## and vice versa. It is especially useful if you want to quickly write a README, some documentation or, turns out, articles for certain platforms. You can find a more complete introduction that I can provide here

What I needed to build

I needed to build a markdown editor with a live preview. The first part is not that difficult; put down a textarea on a page and you have your editor! The problem was with the live preview; turns out Markdown is not natively supported by browsers...

But you know what is? HTML! So I just needed to build (or find, in this case) a tool that allowed me to convert Markdown to HTML!

Unified

To build the Markdown editor (and the preview, mostly), I decided to use unified, an ecosystem of tools allowing the developer to parse a format into an abstract tree and back into another format (for example, markdown to html) and modify said tree (for example, to add specific classes to certain html elements before they are converted to an actual html string. The basics of how to do so can be found in this article, but they mostly consist of:

reading the markdown content (from the textarea in this case)
using remarkParse to convert the markdown into a syntax tree
using remarkRehype to convert the markdown syntax tree to an html syntax tree
using rehypeStringify to convert the html syntax tree to an html string

The real magic is what happens once you generate the syntax trees; at that point, you can modify them with the existing plugins (or make you own, if you really want to). For instance, I use a plugin to add specific css classes to certain elements so they integrate better with the visual design of the website another to add code highlighting with highlight.js and some others for generating a js object from the frontmatter of a Markdown file and to add support for Github flavored Markdown. I could do a lot more with these, like add support for videos, embeds and more, but for now this is enough for a simple preview.

NB: remark and rehype are also used by astro to render the collection's markdown content, so any plugins you use there can also be used here

Putting it all together

Now that we have a basic understanding of how unified works, let's practice! I have already created a stackblitz example you can see just below this paragraph: try writing something in the textarea and it should be parsed and displayed in the preview next to it!

end-to-end encryption with sveltekit

Matteo — Mon, 25 Sep 2023 12:49:36 +0000

Introduction

Now that Magiedit is kind of done (except for user experience, I guess), I figured I had to tackle the security / sync of notes; at the beginning of this project, I thought I could store everything locally (first versions did not even have authentication), and later on implement a solution to sync back and forth with a remote server using something like couchdb and pouchdb. When I tried implementing things like those, however, I ran into all kinds of problems, namely making it play nice with sveltekit (and vite) and syncing different models (articles and settings for each user). And so I decided, at least for now, to ditch storing articles locally, and simply store them on a remote db (right now turso, btw). The thing is, I didn't want to store raw article data for reasons like data privacy and privacy in general (I don't want to know what you write using Magiedit). To solve this problem, I started looking into cryptography, specifically the web-cryptography api.

How this all works

Genering a master password

When a user creates an account, it is now required to create a master password; this will then be stored (hashed, obviously) on the server and at each new session they will need to enter it again. This master password is the origin for every cryptographic key used to encrypt and decrypt the articles.

NB: except for the master password creation and unlocking, the clear password is never sent to the server and is instead stored in the browser's session storage

How and where things happen

How it works (algorithms and stuff)

DISCLAIMER: I'm not an expert in cryptography, so take everything I say with a grain of salt

The key is based on a hash of the master password using SHA-256
The algorithm used for encryption is AES-CBC, since it is symmetric and does not make me manage private and public keys (they would work better, but let's be honest; they are just articles, after all)

Where it works

Let's first take a look at this schema:

When a user creates, loads (from a file) or saves an article, the same steps happen:

A cryptographic key is generated using the master password hashed using SHA-256

const keyBytes = await crypto.subtle.digest('SHA-256', new TextEncoder().encode(keyData));
const key = await crypto.subtle.importKey('raw', keyBytes, 'AES-CBC', false, ['encrypt']);

We generate an iv (initialization vector, kind of like a seed)

function generateIv() {
    const data = new Uint8Array(16);
    crypto.getRandomValues(data);
    return data;
}

The text is then encrypted using the key and the iv

const encodedContent = await crypto.subtle.encrypt({ name: 'AES-CBC', iv }, key, new TextEncoder().encode('write here'));

It is then converted to base64

const base64 = btoa(String.fromCharCode(...new Uint8Array(encodedContent)));

and finally sent to the server (along with its iv) to get it stored securely

As for decrypting, it is the same process, but in reverse:

get the article from the db
convert the base64 string to a buffer
generate a key from the master password
decrypt the buffer
convert the buffer back to a string

I really like this gif, you know?

Why end to end encryption ?

Because I wanted users to know that even if I wanted to (and I don't) read what they wrote before publishing, I couldn't, because I wanted to be in line with current regulations about data privacy and, most of all, because it looked like it could be fun!