Build In Public Journal #5

TechTerms is starting to take shape. Filtering remains a technical challenge, and the project now has 4 contributors.

Hello friend,

As time passes by, I can see that techterms.io is starting to take shape. There are still many tasks to tackle, but I'm glad I'm slowly moving forward. So far, it's been an incredible journey and I'm grateful for that. While talking to other indie makers or developers in general, they said that this is an interesting initiative and that they think it's useful for the community. This brings me joy.

At the moment I'm writing these lines, the repository has 8 stars on Github (which is like a follow or subscribe on other platforms) and there are 4 contributors who have done some work on the repository. 🙌

https://techterms.io - A glossary app designed to help newcomers and tech enthusiasts understand difficult tech terms

Now let's dive deeper into what happened since my last newsletter:

Adding analytics

When you think of analytics, you might immediately think about Google Analytics and maybe Google Tag Manager. When I initially started building my own apps I checked if Google Analytics is a viable option. It seemed a bit too much for what my needs. I wanted something easy to understand, GDPR free, a cost-free solution since my apps didn't make any money.

I also considered implementing my own platform or a rudimentary way of tracking the user interaction. So, nothing fancy or advanced, just a simple way of seeing how many visitors and pageviews I have over time. It was quite challenging and I had other priorities. Maybe in the future I'll take some time to build this, since it's a fun project, but for now I'll stick to something else.

After some research, I found https://www.simpleanalytics.com. It is a simple solution with a free tier, privacy-oriented, easy to integrate and has a clean UI. It was the perfect fit for me.

I checked https://umami.is, but there was a limit on the free plan at 100k events per month. Simple Analytics doesn't have that (or I didn't find this specified).

The only potential downside of the Simple Analytics free plan is that it keeps only one month of data history. That's not an issue for me.

So I decided to go with Simple Analytics. Maybe later I'll consider replacing it, but for now I wanted to have some analytics in place.

• Check the analytics in real time: https://dashboard.simpleanalytics.com/techterms.io

• Github issue: https://github.com/techterms/techterms/issues/9

Implementing the filtering

One important feature for this type of app is the ability to search and filter for a specific definition or term. The user should get to the term as fast as possible, either by typing the name of the term, or filtering by category.

When we think of searching or filtering from a technical point of view, it can be either client-side or server-side filtering.

What's the difference? A short (and boring and incomplete) explanation:

When you access a website (let's say https://techterms.io) you ask a server (in this case Github Pages server) to give you some files that the browser then reads and renders on your screen.

Filtering means you want a specific group of resources (in this case terms).

Server-side filtering

Server-side filtering means the server does the filtering. You pass the filtering criteria to the server and the server returns only the requested data.

Client-side filtering

Client-side filtering means the server returns the full set of data, and the browser (using Javascript logic) filters out some fields that don't match the criteria.

Let me give you an example

Server-side rendering on Github: If you search for "techterms" on Github, you end up on a URL that looks like this:

https://github.com/search?q=techterms&type=repositories

The q=techterms and type=repositories are called query parameters.

When you access the page, Github's servers return the results - only the resources that are repositories and contain the value techterms. You don't get the full list of repositories (which could be millions) and then filter out in the browser.

Client-side rendering on lucide.dev: If you go to https://lucide.dev/icons/ you'll see a list of +1600 icons. There's a search bar. While typing, some icons are filtered out. That means all icons are loaded once when the page opens, and the browser hides the once that don't match your search.

Why is the distinction so important: One of the main reasons I want server-side rendering is because this type of filtering is better for SEO. The crawlers are not always executing the Javascript code. That's also an issue when using several frontend frameworks or libraries (like Angular or React). For each of them there are workarounds.

Astro generates static HTML files. That's one of the reasons I chose Astro in the first place. But what I didn't know initially was that I cannot implement server-side rendering in Astro. Technically, you can do that, but it's done by enabling the Astro's server-side rendering. (More on this: https://docs.astro.build/en/guides/on-demand-rendering/).

This is what I initially considered: there should be a specific route for category filtering, and a parameter should be passed, so I tried to build a page with a URL that looks like this one: techterms.io/?category=web-development.

// Version 1
const categoryParam = Astro.url.searchParams.get('category') || 'all';

// Version 2
const url = new URL(Astro.request.url);
const searchParams = url.searchParams;
const category = searchParams.get('category');

Neither version 1 nor version 2 works properly. It returns "all" every time. After spending more time researching input search filtering, I got a bit more clarity on the server-side rendering. The default behaviour of Astro is to generate static HTML files.

If server-side rendering is enabled, that means it's going to start a server that renders the HTML, so it's not static. Generating static files means everything needs to be ready at the build time (upfront). Because we use Github Pages, we need static HTML files, so server-side rendering is not an option.

What's even worse is that we cannot do any sort of backend side filtering for the search. We have to do it on the frontend side, get all the definitions in a JSON file on the frontend side and do the filtering there. I don't really like this method, but for now we might stick to it. There's no issue with 10 or maybe 100-200 terms. But in case we grow to thousands, we definitely need to improve the performance. Probably that's a topic we need to handle a bit later.

For client side filtering behaviour, I got the inspiration from https://www.passportjs.org. If you search the available strategies, there's a popup that appears and all the 500 strategies are listed there. While you start typing, strategies that don't match the input are hidden.

I've implemented the search functionality, and this is what we currently have (at the moment I'm writing this section).

And yes, I've introduced a bug because I didn't closely review my code. There's a ; added to the sidebar.

Some small but important topics

Having a separate Github Action for code analysis speeds up the process. Initially, we had the check only on main. So the flow executed only after the PR got merged. But if there was a format error, build would fail. In order to fix that, you'd open another PR, fix the formatting and merge that PR to retrigger the flow. The common solution: add another Github Action that runs on PRs to check code format and linting: https://github.com/techterms/techterms/issues/40

Because the flows got changed, I thought it should be the right time to create a separate account that's used only for deployments. So I created techterms-bot. Whenever a PR is merged, there's a version bump logic that's executed. One challenging task was to properly extract the release information, more specifically the commit messages to be posted to release notes. That's done with the use of our new account.

I've also enabled wiki pages. I found out that I can benefit from using more Github features. I don't plan to update wiki pages that often or over complicate things, but the purpose for that is to add all the documentation and diagrams that might be useful in the future, things that otherwise get lost in the closed issues.

As I said previously, sharing the terms is the main feature of the app. That's why I added buttons to share the definitions on X and Bluesky. There's something called an intent URL. You open a specific URL for X or Bluesky containing a query param and it automatically populates the post message with the term value. I've used this for the first time in https://typoquiz.com

It's time to celebrate 🎊

While posting online, more people said that this is an interesting project, and that it can be helpful for the community. And this is the main purpose of the app. I knew from the beginning that I'm not able to create a good product only on my own, and community involvement is crucial.

This came up earlier than I expected, but we had our first contributors. At the moment I'm writing this section, we have 4 contributors who raised PRs and helped improve the app.

I'm very thankful for your contributions folks. Let's keep it going and build a platform that'll be useful for the community! 🎉👏

What's next

• Even though initially I thought we should only have main and feature branches, I'm still thinking if we should also have some release branches. Let's say I work on multiple small issues in one work session, like fixing some typos in documentation, refactoring a couple of lines of code, or changing some spacing. And I don't want to build the app for each individual fix. I want to build it only when there's a relevant pull request. That's why I think I could either skip the CI/CD by adding a prefix to commit message, or create release branches. I'm still thinking what to do.

• I've been trying to address the critical issues and core features before promoting the app. There are many nice-to-have features, but some that I believe should be done before promoting the app on social or on ProductHunt and other directories. I've been planning these features and postponing the release for some time, but we'll get there soon.

In conclusion

If you like what you've read, make sure to follow the progress on Github and social media. I'm sharing some links below that you can check out:

• https://techterms.io - this is the app

• https://github.com/techterms/techterms - you can find the source code here

• https://github.com/techterms/techterms/blob/main/CONTRIBUTING.md - want to contribute code to TechTerms? start here

• https://github.com/techterms/techterms/issues - found a bug or want to suggest a term? this is your link

• https://x.com/razvanmuntian/status/1930203176466092409 - I'm regularly posting in this thread 🧵 about the progress I'm making

Looking for suggestions. If you think I can improve the newsletter in one way or another, feel free to get in touch.

Thank you for reading this post.

See you soon!