Build In Public Journal #3

Let's get technical - I'm picking the tech stack, preparing some wireframes and being a bit said for leaving Porto 🇵🇹

Hello friend,

This is a more technical newsletter, since I've started the implementation of my project.

Before going into all the details, let me give you a short summary of my previous posts:

I've started the 12 startups in 12 months challenge. I'm building a product every month. The one I'm working on right now is a glossary app. I want to help people understand difficult tech terms through this open source project. I hope I can lower the bar for newcomers entering the tech industry.

You can follow the progress of the app on Github: https://github.com/techterms

Deciding the tech stack

I'm trying to find some good candidates for my static website. I mean, it can be implemented directly in HTML, or implement some Javascript app from scratch, but I'd like to take this chance and learn some new frameworks.

This is the first framework I'm testing out: Astro. I've started reading the documentation and they point out really early that there are multiple templates I could start using right away: https://astro.new/ .

The install process seems easy. I ran npm create astro@latest and Astro got installed.

Running npm run dev starts the development server. But what interested me more is the build: `npm run build` builds the static HTML site. I'll dig dipper into all the build configurations, but for now, I like it.

After about an hour or research, it seems to be a good fit. It generates HTML with a simple command (which I'll next use in Github Actions). Some features I've encountered so far that I really enjoyed are:

• file-based routing - it really speeds things up, especially when you want something small

• generating pages using markdown - I really enjoy writing markdown. The fact that it's supported by default by Astro is a plus for me

• dynamic routing is interesting - maybe there are more ways to configure that, but it was quite simple to run their examples and get a sense of the feature

• building the website where you added dynamic routing makes you feel like a wizard 🧙 for some reason

Try Astro on your own: https://docs.astro.build/en/getting-started/

Now that I've chosen the main framework, I'm trying to slowly build around it.

Firstly, I'll add Typescript (I believe Astro comes with Typescript by default). The reason for adding Typescript is because I believe it's more welcoming for new users who are willing to contribute to the project. They might have a better understanding of the data models used across the project.

Tailwind CSS is also a library I'm willing to try. It seems to be a popular one. Also if you generate code with AI, Tailwind seems to be preferred by the LLMs. I'd like to give it a try, since I tried in the past and I couldn't successfully integrate it into a project. Maybe it's a good time to slow down and really understand how Tailwind works.

Since I'm storing my code on Github, I considered Github Actions as well. In my past projects, we've used other CI/CD providers, and I didn't really have a chance to try this one out. The app will be deployed to Github Pages.

For code formatting and linting, I think I'll be using Prettier and ESLint. At least this is my initial plan. I hope those work well with Astro. We'll decide later if we have to choose a different tool.

It seems we have a plan. This is the tech stack:

• Astro

• Typescript

• Tailwind CSS

• Github Actions

• Github Pages

• Prettier

• ESLint

I've created Github issues for all the topics and I'm starting writing some code. Even though initially I thought about using only Features and Bugs types of issues, it made sense to use Tasks as well. I don't think it makes any difference, other than being a bit more organized.

Adding Astro and Tailwind CSS

I've created a Github feature issue https://github.com/techterms/techterms/issues/10 and multiple tasks. I managed to install Astro and to easily integrate Tailwind. It was a seamless process. While adding Astro, I also fixed the Github Actions workflow. Now, once the changes made with Astro make it to the main branch, they're deployed to https://techterms.io

To keep things consistent and formatted the same way across the project, I'll add ESLint and Prettier. I'm using Cursor as my main editor. So let's see how it goes.

ESLint, Prettier and Husky

It didn't go as smoothly as I would have liked. To give you some context: I'm using latest versions of all the packages:

• Node v24.2.0

• eslint ^9.29.0

• husky ^9.1.7

• prettier ^3.5.3

Initially I configured .eslintrc.json, but I found out that it won't be supported much longer. Now I need to migrate the changes to eslint.config.mjs. And that's what I did: https://eslint.org/docs/latest/use/configure/migration-guide

Now when trying to commit, eslint --fix fails. The good news is that husky and lint-staged seem to work. The bad news, tough, is that the Astro file format seems to be wrong (even though it's exactly as in the documentation):

---
import '../styles/global.css'
---
<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Tech Terms</title>
</head>
<body>
    <h1>Tech Terms</h1>
    <p>A collection of tech terms and their definitions</p>
</body>
</html>

At this point, I believe there are three ways to fix this:

• Maybe I'm missing something, and I could keep digging for a solution.

• I could disable linting for the Astro files (not the preferred way).

• I could use a different file type. Just because we have default Astro files, doesn't mean I have use them. I could use Markdown or HTML, so there's probably no point in fixing this if I end up using HTML in the end.

After a couple of minutes of investigating, I added this line:

...astroPlugin.configs['flat/recommended']

It seemed to work. Running the individual commands in the terminal seems to work. Also, committing the changes triggers Husky pre-hook and the commands seem to work. I think we're good for now. I'll review the code and clean up the pull request. This time, I'll pay some extra attention to the code since I've used ChatGPT and Cursor to generate the configuration.

I've noticed that ChatGPT gave me better responses compared to Cursor. Cursor seemed to make up some configurations. I believe Cursor's training data contains more entries with the older version of the ESLint configuration, rather than the new one.

Execution passed the Lint and Format Check, and the new version will be deployed soon! 🚀

A bit of planning for short and long term

Now that the tech stack is in place and CI/CD is working, let me list out some plans I have for the website. The purpose of this app is to help newcomers understand the difficult tech terms. In order to achieve that, there's still a lot of work to be done.

There are some aspects I need to brainstorm initially:

• What are the main pages and sections?

• How will we add the definitions (either me, or other devs involved)?

• How are we listing the definitions?

• How will we store the definitions? In what format, what DB?

• How do we market the app?

• Logo and branding

I'm thinking of the following marketing channels:

• SEO - I want my app to be easily discovered

• App directories - promote the app in multiple product directories

• Sharable definitions - I want the definitions to be easily sharable on social media so we should include some share buttons

• Embeddable - just as Youtube videos, I want to have the ability to include the definitions in articles or blog posts using HTML scripts

• Generate images - I'm still thinking about this one. I believe it would be a nice to have feature to be able to generate images with definitions that are easily sharable on social media compared to text. Text can be shared to X and Bluesky, but images can also be shared on Instagram or other places

With all these ideas, I've started trying to split the tasks into Github issues. I've created some of them and prioritized them somehow. I'll start by creating some homepage wireframes, defining the blocks we'll be using on home page and start from there.

Working on the wireframes

I've started working on the wireframes: https://github.com/techterms/techterms/issues/21

After some research, I tought, why not let ChatGPT generate the wireframes? I wrote a generic prompt (probably I should've given more details):

Help me generate wireframes for my web glossary app. It’s a free, open source app designed to help users understand difficult tech terms and enter the tech industry with ease. The app is called techtrends.io.

I want a menu and heading section. Below the heading, I’d like some blocks containing definitions and a search bar (similar to the strategies page from the Passport.js library: https://www.passportjs.org/packages)

Please also include what’s relevant for a landing page. The app is free and open source, so don’t add a pricing section.

Also, include a version number and links to social media somewhere. Please generate some wireframes.

And this is what I got 🤮.

So there's no shortcut. I'll have to figure out on my own what I want to build 😁

Finally, I came up with this wireframe for the home page:

How I came up with this layout

• Home is the main page of the app. Users should be able to access definitions directly - no login or extra steps required.

• Searching and filtering should give users the ability to browse existing categories of terms and explore what we already have on the site.

• The Contributing to the Project section encourages the community to contribute to the project.

• Users can get some info at a glance with the project stats section.

As we’re used to - a brief personal update

When I’m writing this, I’m still in Porto, but when you’ll receive it, I’ll be back home. This is our second time here, and we really enjoyed our stay.

When you visit a place for the first time everything is new, you’re excited, but you don’t get a chance to really explore the place. This time, being our second visit, it felt way different. We weren’t in a hurry.

Being in Porto for two weeks helped us find a rhythm. We could both work and enjoy our vacation. I think there’s a word for that: workation. I think I’ll write a newsletter describing our whole experience, so I don’t want to give you too much spoilers right now.

The only hint I’m giving you is that we’ll be missing Porto so much until next year, when we hope to get here again for some time. 😉

That being said, thank you for reading my newsletter and for your support. It means a lot to me, and I hope I’ve inspired you to build your own open source projects.

See you soon!