🎤 Do you have a project?

If you want to share YOUR project with the community, join our Twitter(X) Space on Friday at 4pm UK time.

We will have speakers from GitHub, GitLab, CloudFlare and YOU!

Set a reminder not to miss out https://twitter.com/i/spaces/1vKpPPvrWOmKE

Projects I use daily and recommend

1. Orca ADE. This is my new favourite open source IDE, well ADE. It can run Claude Code, Codex, OpenCode and more, side by side in isolated worktrees.
   Ghostty-inspired terminals, a built-in file editor, and git tracking keep every branch moving. The project and community are super active on Twitter, GitHub and Discord - it is refreshing to be communicating and building with the core team.

2. Playwright e2e testing. Everyone is building, but why is no one testing? I love vibe coding my ideas so they come to life, but I also love knowing that there are end-to-end tests covering the features I have created. This gives me the peace of mind that in future they will continue to work even as I iterate on the project.

3. Supabase is my go to open source backend for any project. It has everything I ever need: a Postgres database, authentication, APIs, Edge Functions, Realtime Data, Storage, and Vector embeddings. It doesn’t have emails, but for that there is Resend - recently I tried this platform and thought it was amazing. The DX was great, it did exactly what was needed and nothing more! As they say “less is more”.

Leave a comment

Projects I am keen to have a play with

1. Matt Pocock (yes, the TypeScript one) opened up his own .agents directory.

   That is the part I want you to notice. Not a tutorial about how to write agent skills. The actual skills he uses on his own work, every day. In a few weeks it has already reached almost 200k stars on GitHub.

2. OmiRoute is An MIT-licensed AI gateway. One endpoint, 290+ providers (90+ of them free), 500+ models, quota-aware auto-fallback, and token compression the project claims saves 15-95%.

   Two reasons I like it as a builder:

   • You stop rewriting your integration every time you switch model.

   • You stop being dead in the water when one provider rate limits you or the provider goes down like Claude did yesterday.

What AI do you use? I use Claude

Claude Code got parallel sub agents. Subagents can now spawn their own subagents up to depth 3, capped at 20 concurrent. If you are nervous about burning too many tokens there is: --max-budget-usd flag which now actually halts background agents when you hit the cap.

Small thing worth knowing: /code-review now runs in the background, so it stops flooding your conversation.

Comment below with 👇

1. What are you building at the moment?

2. What tools/projects are you using daily?

Let me see if I can shift your mindset from:

“I’ll record something later…”
to
“I’ll just record this quickly now.”

There is a moment every creator, educator, developer or indie hacker hits:

• You need to explain something quickly.

• A feature, A bug, A workflow.

• An idea that’s easier to show than write.

Suddenly you are down the rabbit hole of multiple screen recording tools, different editors, each with their own export settings, timelines and way too many configurations. This has happened to me one too many times and it is time to STOP!

The problem with most screen recording and editing tools

Most tools fall into one of two camps:

• Too basic → hit record, export, done (but looks like a rough draft).

• Too complex → multiple timeline editing, effects, rendering… and now you’ve lost an hour.

What you actually want is something in between: fast enough to use daily, but polished enough to share publicly.

Enter: ScreenRecording Pro https://screenrecording.pro

This is why I created ScreenRecording Pro. The big idea is simple:

💡 Record, edit, and export - all in your browser. No downloads. No setup. No friction.

Leave a comment

What makes it different

To me, this is why ScreenRecording Pro stands out:

1. It’s fully browser-based: you can start recording with a single click - no installs, no updates, no “this only works on Mac.” This alone removes a lot of resistance.

2. Editing is built-in (and actually usable): instead of exporting into another tool, you can:

• Zoom in on important areas (also great for the viewer to stay engaged).

• Trim and cut.

• Add text overlays.

• Adjust speed (great for when you are typing, speed it up or slow it down).

• Annotate with arrows and circle to highlight areas of interest.

• Add your camera and audio to personalise your videos.

• Work on a proper timeline all inside the same interface.

• …and more!

3. The zoom effect is the killer feature. If you have ever seen those clean product demo videos where the camera smoothly zooms into the important part of the screen - that is built in. You can add zoom points directly on the timeline and guide attention exactly where you want it. This alone makes recordings feel intentional, not just captured.

4. Designed for sharing, not just recording. Export options include MP4, WebM, or even GIF - with control over quality and resolution up to 4K. So whether you’re posting on Twitter, YouTube, or sending a quick demo to a client - it’s ready.

Why this matters

Especially if you are building in public or if you are:

• Shipping features.

• Writing devlogs.

• Teaching something.

• Growing an audience.

Then screen recordings become part of your daily workflow. The friction matters. Tools like this shift the mindset from: “I’ll record something later…” to “I’ll just record this quickly now.” And that compounds.

Pricing: there is a Free plan with most of the features included - the only tradeoff is a watermark. Or you can upgrade to the Lifetime plan once and that’s it.

Final thought

Most tools try to be powerful. The best tools try to be used. ScreenRecording Pro leans toward the second - and that is why it works. If you are creating tutorials, demos, or just sharing what you are building, it is one of those tools that quietly removes friction from your day. Those are the ones worth keeping around.

Have you found a screen recording setup that actually sticks? I’m always curious what people are using - comment below and let me know, I will reply!

Visit ScreenRecording Pro https://screenrecording.pro
Get it now with a 50% discount for Lifetime access (usually $299, now $149.50 for the first 50 users).

Product Hunt

🎥 Full YouTube video contributing to the Kestra Open Source repo

Do you want to up skill faster?

For me, one of the best ways to up skill is to get real World experience. You can achieve this by contributing to Open Source. No matter where you are in your career, even if you are at the very beginning, or if you have been coding for over 15 years like me, getting involved in Open Source will accelerate your learning and career.

Additionally contributing to Open Source and consistently adding value to a project, makes you more visible to companies who may be looking to hire. When companies are looking to grow their team it is natural that they will look at those who already know the project and their maintainers have collaborated with.

Plus, by contributing to Open Source you will be interacting with contributors and maintainers from around the globe - think: different time zones, different languages and different ways of working. Being exposed to this is a great way to improve written communication skills.

In this blog post I have put together a step-by-step guide on how you can contribute to enterprise Open Source projects.

The project I will use for this guide is Kestra and I would suggest that you take a look at their GitHub repo so that you can follow along: https://github.com/kestra-io/kestra

What will we cover in this blog post

• What is Open Source

• Why you should contribute to Open Source

• How to find projects/repos

• How to validate the project’s repos

• Contributing and getting the Pull Request / Merge request accepted

• What to do next

What is Open Source

Let’s start with “What is Open Source?” Yes, it refers to software where the source code, design, or content is made publicly available for anyone to use.

But to me it is more than this. I like to think of Open Source as Instagram for code, but with a twist. The twist is people can contribute to Open Source projects, make changes, suggestions, improvements and use the project itself.

Why you should contribute to Open Source

Getting involved in Open Source is very beneficial for those in the tech space. Coding is an art and you get to see how other artists create features and their projects - I am not just talking about design, but also architecting the project.

Also you will grow your network within the tech community. Networking can be difficult, but what if it doesn’t have to be? If you are thrown into a room with other people and instructed to “network”, that is difficult for most. But if you are doing an activity with others, like playing sports - then you naturally network and grow the relationship without even trying. That is the same with Open Source.

How to find projects

Not all projects are equal. What I mean by this is that whilst public projects might be available, they don’t always mean they are keen on receiving contributions or they are friendly to contributors. You don’t want to waste your time on these, and it can be a turn off from Open Source if you have a bad experience.

You want to contribute to what I call “real” Open Source projects: those that are friendly, welcoming and professional. Just to be clear, that doesn’t mean they are perfect - no project is - and that is where you come in.

Being new to a project you have a super power (and not a disadvantage as the majority of people think). You know the saying… “with great power comes great responsibility”, so when you are trying to understand the project and get it running you are looking at it with a fresh pair of eyes. If something is not clear, make sure you improve the onboarding documentation.

There are multiple ways to find an Open Source project to contribute to:

1. Social media - people are posting on Twitter (X) about projects, either their own, the company they work for or one that they like. This is a great way to find friendly projects.

2. Your existing network and friends - what projects are your friends using or contributing to?

3. GitHub Trending page - there are super popular repos on GitHub’s trending page. There are some filters for trending duration and also technologies used in the repo. However I don’t think this is a good way to find projects to contribute to, because popular doesn’t always mean better.

4. GitHub Advanced Search with a repo focus - using the advanced search page on https://github.com/search/advanced I recommend firstly selecting the language, then making sure the repo has had activity in the last month with the “Pushed to” filter. Include any others filters you think are suitable for you. Using the Advanced Search with a repo focus is a good approach, but the likelihood is that it will return too many results making it difficult to find good repos.

5. GitHub Advanced Search with an issue search - using the Advanced Search page on https://github.com/search/advanced again, include a language filter like before, then go down to “Issues options”. You definitely want “in the state” to be “open”, in the “With labels” field you can add “good first issue”.

   Caution: most “good first issues” are not good first issues. Either the author wants help or it is a three word issue that makes sense to the person who created it but no one else. So use this label with caution and if you realise that you don’t understand most of those issues, that is ok, it is probably not you.

How to validate the project

Once you have found an issue or project you would like to contribute to, it is important to do some due diligence to make sure it is friendly and welcoming for contributors. I suggest:

1. Check the license - make sure it has an Open Source license. Not having any license does not make it more open, in fact it limits the scope of what is possible. Have a look at a information website created by GitHub with DOs/DONTs of each license with examples https://choosealicense.com

2. Does the project have a README with instructions how to set it up? You don’t need to try this out immediately at this project finding stage. If the README looks detailed that is good enough for now, you can try it out later if other points are all positive.

3. Does the repo have a Contributing Guide? This is a great way for repos to onboard new contributors. If this doesn’t exist, it is not necessarily a blocker, if all the other points are positive.

4. When was the project last active? Look at the latest commit and probably how many commits the repo has had over the last few months.

5. Are Issues and Pull Requests being looked after by maintainers? For example, are they commenting and in a friendly way.

   Bonus tip: go to closed Pull Requests and look for the ones with the red icon, which means they were not accepted. Check these were closed in a friendly way - if some have no comment, take it with a pitch of salt as conversations could have happened elsewhere (such as on Discord). However if most closed PRs don’t have any comments at all, then I would consider this is a warning sign.

How can we contribute

Contribution is not just about writing code. It can be through documentation, automated tests and even project management (for example, highlighting to maintainers where there are duplicate issues). The question you need to think about is “Will this contribution add value?”

There are two directions we can take: creating a new issue because we discovered - for example a bug, or we found an issue we would like to work on.

Here are a few things to keep in mind:

New issue

• Firstly, check the repo that the issue doesn’t already exist. Remember to also check the “closed” issues! If the maintainers have closed a similar issue to what you are thinking of raising, this might be for a specific reason - for example, it doesn’t align with the project’s current roadmap.

• Before you raise the issue, check the Contributing Guide to see if the project has a specific issue template. Following a template will help both you and the project’s maintainers accept the issue as it has all the information needed.

Existing issues

• Filter by labels such as “ready for dev” and “not assigned” - if an issue has recently been assigned to someone, don’t ask for it to be assigned to you.

• Also filter by “not assigned”.

• Another great label to look out for is the “good first issue”. These are well-defined tasks designed for newcomers to get acquainted with a project without needing deep expertise.

• Check the project’s Contributing Guide to see how maintainers would like you to ask for an issue to be assigned to you.

• The maintainers may want you to answer certain questions when asking for an issue to be assigned, so do check the issue description for this. Avoid commenting only with “I want to work on this” when this is the case.

I found a project, Kestra

I found an Issue I am keen to work on in the project Kestra https://github.com/kestra-io/kestra

Kestra is a powerful orchestration tool that simplifies workflows. It uses declarative syntax and has the functionality of multiple Event Based Triggers. What I really like is that it has a great UI and code editor, so I can comfortably stay in the yaml config, see any errors I make immediately as well as seeing the visual result in their diagram. However, it others who don’t want to use YAML and who prefer to only use the UI can stay in that view.

Also Kestra has over 600 plugins which allow you to integrate with other services very easily. For example sending notifications to Slack, creating GitHub Issues and so many more. With these building blocks, just like in Lego, we can create anything we need.

In addition there are over 250 Blueprints which are complete workflows you can easily tweak to suit your situation.

Let me show you an example of how Kestra can be used. Here is a workflow I created that pings my website on a schedule and if my website is down, it will create a GitHub Issue on the repo, how great is that? I still love the visual representation.

The Open Source GitHub Issue that I will solve is this one: https://github.com/kestra-io/kestra/issues/6754 I came across it as I was searching for a “good first issue” as this is my first contribution to this project.

From the issue title and description when disabling a nested workflow only the first child is disabled in the diagram, but all of the children in the disabled workflow should be shown as disabled.

Pre-Pull Request

Before I ask for the issue to be assigned to me, I set up the project locally to get a rough idea of how to tackle the problem. I actually discovered that the bug was not actually in this repo, it was in one of the project’s dependencies https://github.com/kestra-io/ui-libs. So I then proceeded to set up the “ui-libs” project and modified the Kestra repo to use my local version. Once that was done, I was more confident that I could fix the bug as well as see the changes.

Once the issue is assigned to you, get the project running locally if you haven’t done so already. This isn’t always as easy step and can be more difficult than making the code changes. But along this journey you can improve the onboarding documentation for the project - remember your super power - you are new to the project and can look at the documentation. Plus once you have the project running locally you can take on future issues more easily.

As you can see it is not just about changing a few lines of code. There is more to it, which is why I recommend contributing to less projects. That way your investment of setting up the project will benefit you in your next contribution

Once the issued was assigned to me, as the changes I needed to make to fix the bug were on the wrong repo, I created a new issue on the correct repo, detailing what problem and referencing the original Issue.

Here is the Kestra GitHub Issue I created:
https://github.com/kestra-io/ui-libs/issues/561

Leave a comment

Pull Request

Setup the projects locally

Yes projects, because we need to setup the dependency project “ui-libs”. These are the steps:

1. Fork and clone “kestra-io/ui-libs” repo. We need to fork the “ui-libs” repo because we plan to contribute to it.

2. Clone “kestra-io/kestra” repo. We don’t need to fork the “kestra” repo because we only need this to consume the “ui-libs” local repo to check our changes work correctly.

3. Update the npm dependency in the “kestra-io/kestra” repo to use our local “ui-libs” project. We will not commit these changes, as this is only for development and testing purposes. After our changes in the “ui-libs” are accepted we can discard the “kestra” repo changes locally.

Kestra has an overall contributing guide you can follow for different types of contributions https://github.com/kestra-io/kestra/blob/develop/.github/CONTRIBUTING.md

Let me take you through the steps needed for setting up the projects for the changes we are going to make:

1. Fork the Kestra GitHub “ui-libs” repo by clicking the fork button at the top right of the repo, you only need to do this once per repo, not every time you wish to contribute to the project. What this will do is create a copy of the repo under your GitHub account so you can make changes.

Now you have a copy of the “ui-libs” repo in your account, you can clone this forked repo.

To clone you can use your GUI or IDE tool. I still prefer to do it on the CLI but that is up to you. If you use the CLI, here is the command, but do not copy the repo path, as you should clone your fork not mine.

git clone git@github.com:eddiejaoude/kestra-ui-libs.git

2. Clone the “kestra” repo, this you can copy as it is not a forked repo, but the upstream (original) repo.

git clone git@github.com:kestra-io/kestra.git

I suggest having these 2 cloned repos as siblings in the folder structure, this will be more clear to manage relative paths and easier to follow along.

I created an empty “kestra” folder (you can name this anything you wish) and cloned both repos into there:

Leave a comment

Navigate into each project folder in a new terminal and start the projects.

In terminal 1, navigate to the “ui-libs” repo (I called it “kestra-ui-libs”), then run the npm build command:

cd kestra-ui-libs
npm run build

In terminal 2, navigate to the “kestra” repo, I called it “kestra-io” locally, install the local npm package and then run the project:

cd kestra-io
npm install ../../../kestra-ui-libs
make start-standalone-local

Replicate the bug locally

Visit “http://localhost:8080” and create a new Kestra flow. You can use this example YAML to see the bug:

id: example
namespace: company.team

tasks:
  - id: outside
    type: io.kestra.plugin.core.log.Log
    message: Outside message
  - id: nested
    type: io.kestra.plugin.core.flow.Parallel
    disabled: true
    tasks:
      - id: first
        type: io.kestra.plugin.core.log.Log
        message: first child
      - id: second
        type: io.kestra.plugin.core.log.Log
        message: second child

  - id: outside2
    type: io.kestra.plugin.core.log.Log
    message: Outside message

The bug shows the first child disabled but the following children appear to be enabled on the visual diagram called “Topology” shown next to the YAML:

Here is the diagram section zoomed in:

Fix the bug and test locally

I made the following changes to the “ui-libs” repo. This is the git diff:

diff --git a/src/components/nodes/BasicNode.vue b/src/components/nodes/BasicNode.vue
index 48435df..d0a5263 100644
--- a/src/components/nodes/BasicNode.vue
+++ b/src/components/nodes/BasicNode.vue
@@ -183,7 +183,7 @@
                 return {
                     "unused-path": this.data.unused,
                     [`border-${this.borderColor}`]: this.borderColor,
-                    "disabled": this.data.node.task?.disabled,
+                    "disabled": this.data.node.task?.disabled || this.data.parent?.taskNode?.task?.disabled,
                     [this.$attrs.class]: true
                 }
             },
diff --git a/src/utils/VueFlowUtils.ts b/src/utils/VueFlowUtils.ts
index 9d90b7e..afd5536 100644
--- a/src/utils/VueFlowUtils.ts
+++ b/src/utils/VueFlowUtils.ts
@@ -587,6 +587,7 @@ export default {
           draggable: nodeType === "task" ? !isReadOnlyTask : false,
           data: {
             node: node,
+            parent: clusterByNodeUid[node.uid] ? clusterByNodeUid[node.uid] : undefined,
             namespace:
               clusterByNodeUid[node.uid]?.taskNode?.task?.namespace ??
               namespace,

Before making any changes in your fork make sure to create a branch, you can do this in a single git command:

git checkout -b name-of-branch

I usually name my branch related to what I am doing, for example “issue-123”.

If you are following along, you can apply these changes manually to this commit https://github.com/kestra-io/ui-libs/commit/7bb08eef9cec1140174c5379afca3855b8aa772a (but it will not work for the latest changes in the repo). Apply it by saving the code above to a local file, for example “fix-561.patch” and use the git command:

git apply fix-561.patch

Run both project commands again and let’s see the result.

Here is the diagram section zoomed in and I have highlighted the children nodes in red that should be disabled and green for the nodes that should remain enabled:

Creating the GitHub Pull Request

Now I have made my changes and they are tested locally, I can submit a Pull Request to be reviewed by the repo maintainers.

When creating a Pull Request, the title and description are just as important as the changes you are suggestion. This means the title needs to be clear and concise, plus the description needs to have all the relevant information for anyone to follow why you made the changes.

I also include in the PR a before and after screenshot of the result. I don’t need to include the changes as these are visible on the other tab already. You should also include how to test the changes.

Markdown helps improve the layout of the Pull Request description. No one likes to see a wall of text, so making use of lists and tables for example, will really help keep the reader engaged.

View the GitHub Kestra Pull Request here https://github.com/kestra-io/ui-libs/pull/562

Post-Pull Request

Keep an eye on your GitHub notifications, this might be emails if you set it up this way or the way I recommend is using the GitHub inbox for notifications.

Be patient, the team on the projects have their own work to do as well as review GitHub issues and pull requests. Do not chase across platforms 5 minutes after raising a GitHub issue or pull request. If after 1 week you haven’t heard anything, maybe send a polite message in their Slack or Discord, but don’t DM people.

Do not merge your changes in your repo

You are probably thinking, “My changes are in a branch in my repo, how do I get them in the default branch?” Your default branch should be identical to the original (upstream) repo. So your changes will be in the default branch after your Pull Request is merged by the maintainers on the original (upstream) repo. Then there is one more step you need to do to keep your default branch in your fork in sync with the original (upstream) repo.

Add upstream remote to your local git

Your local git repo will have a git remote for “origin” which will be the url of your forked repo. Remotes can have any name you wish and you can have as many git remotes as you want. However, when adding the original (upstream) repo, it is recommended to use the name “upstream” and I highly recommend using the standard naming conventions.

To add a remote, you can check what you already have with the following command:

git remote -v

origin	git@github.com:eddiejaoude/kestra-ui-libs.git (fetch)
origin	git@github.com:eddiejaoude/kestra-ui-libs.git (push)

Now we can add the “upstream” git remote with the command (yours will be identical to this including the url because it is the original repo location):

git remote add upstream git@github.com:kestra-io/ui-libs.git

Now when you list all the remotes you will see the following:

git remote -v

origin	git@github.com:eddiejaoude/kestra-ui-libs.git (fetch)
origin	git@github.com:eddiejaoude/kestra-ui-libs.git (push)
upstream	git@github.com:kestra-io/ui-libs.git (fetch)
upstream	git@github.com:kestra-io/ui-libs.git (push)

Note: your “origin” will be your fork not mine.

The last step is to fetch the changes in the default branch in the upstream repo and then merge it into your default branch of your local git. You can then push this to your fork. This is how your changes and others will end up in your default branch in your forked repo. As this should mirror the upstream repo and you never make changes to it directly, you should never have conflicts in this branch. If you do, then something has gone wrong and you could delete your default branch and fetch it again.

Fetching and merging the upstream

Make sure you change back to the default branch with:

# git checkout <branch-name>
git checkout master
git fetch upstream
git merge upstream/master

# push these commits to your fork on GitHub
git push origin master

Now if you do a git log, the commit history will match the upstream repo.

What next?

Don’t stop there, now you have the project set up locally and have a better understanding of the project, keep going!

Contributing is not just about Pull Requests, it is also about review other Pull Requests and issues. However don’t blindly approve Pull Requests as this is the fastest way to get banned from a project!

Remember it is about adding value not noise. Each time you do something (even if it is leaving a comment) many people get notified. So avoid leaving multiple comments with a single line in each - this is not a DM! (in fact, I wouldn’t even recommend you do this for DMs…)

Conclusion

I hope this post has inspired you to contribute to Open Source.

Most projects in tech involve multiple people, so in addition to improving our tech skills we need to also continually improve our communication skills. Both take practice.

So what are you waiting for? Go and get involved and contribute to Open Source.

Leave a comment

Watch the full YouTube video here:

Note: you might have signed up a long time ago on another platform, so if you wish to unsubscribe there is a link you can click at the end of this email 👇

Don’t worry I won’t be too upset (maybe a little 🥲).

This is my first newsletter on Substack! 🎉 I renamed my Substack publication from “Open Source Expert” to “Eddie’s Log“. You might be thinking, why? Open Source is still my focus but not everything I want to make my blogs and newsletters more personal and authentic.

As developers we need to write code, think about performance, security and accessibility, write automated tests, also deploy our projects, be a technical writer to document the project, communicate with the team, collaborate on code reviews, and that is only part of it. Plus on top of all that we need to make sure we get enough rest, exercise and eat healthy - wow I am exhausted just writing that! I believe that with my 15+ years as a Fullstack developer and my recent focus on work life balance as a Digital Nomad, I can share what has and hasn't worked for me to save you the trouble of figuring it out.

What to expect from my monthly newsletter

1. Technical tips - I share tips that might seem small but have a big impact on what we can use daily to make our developer lives more efficient and better.

2. SaaS projects - As I build more frequently, I want to share with you the tools and resources I have found helpful, plus highlight your projects as I come across them.

3. Behind the scenes - Sharing my Digital Nomad adventures, solo entrepreneur advice and how I try to get a work life balance.

My newsletter is over 10k+ subscribers strong 🎉 but I would like to get to know YOU more. REPLY to this email and let me know something about YOU, you can include these also:

💡 What content you would like to see next?
🧱 What projects are you building?

This is my first newsletter post. The intention is not to commit to a set and rigid schedule, and most certainly not “spam” any of my subscribers on this platform. Instead, my aim is to publish a newsletter post as and when I feel I have collected information which I think you as a reader, will value.

Tips

This month’s tips focus on debugging and communication with clients, team members and people in your network.

Rubber Ducking

Are you stuck? Try explaining the problem to an item on your desk (usually known as a rubber duck, I have a rabbit 🐰). This process and method often highlights the bug to us and we figure it out ourselves faster than searching google or using AI - it is not magic or using the Jedi force, just Dev Life. This works because it forces us to break down the problem into little step-by-step chucks that we might have missed before.

Client work

When freelancing, most include the services and deliverables BUT don't forget to mention what you don’t include - this will leave no unexpected surprises for you or your client.

Technical skills are not enough

Hard skills alone are not enough! No matter your job title or how many years experience you have, you need to be able to communicate, this is know as soft skills but better know as core skills as they are difficult also. Most often we work in teams and we need to efficiently and effectively community with then, this takes practice. Whichever platform you use (GitHub, Discord, Slack etc), you can most likely use markdown to help communicate your message better - no one likes a big wall of text. Learn the 12 or so markdown styles and use them appropriately in your messages, the person reading will really appreciate it.

Here is a GitHub specific markdown tip to help your content stand out…

GitHub Markdown tip (alerts)

Use alerts in GitHub Markdown to highlight important information like: note, tip, important, warning, caution.

> [!NOTE]  
> Highlights information that users should take into account, even when skimming.

> [!TIP]
> Optional information to help a user be more successful.

> [!IMPORTANT]  
> Crucial information necessary for users to succeed.

> [!WARNING]  
> Critical content demanding immediate user attention due to potential risks.

> [!CAUTION]
> Negative potential consequences of an action.

If you would like to read an article on Markdown (which includes a video), here it is:

This newsletter is sponsored by my own project MakeTheList.io

Build a comprehensive directory of information that helps others discover your product. Perfect for curating a directory of SaaS tools, learning resources, or industry knowledge.

Behind the scenes

I have been a Digital Nomad since 2021 and yes I take my laptop with me everywhere. You never know when you get that super cool idea that you want to code, or need to fix a bug, or merge that pull request. So a photo of my laptop around the world near some water is fairly standard for me 🌴 But before this change in lifestyle, I used to be locked in my “command centre” almost 24/7. Let me show you…

Before being a Digital Nomad

Before becoming a Digital Nomad, I used to live in my “command centre” and this is what it looked liked 👇 Looks great right? But with more tech there is more distractions and more to go wrong - yet I kept adding more and more tech to my home office without any real need for it or value to my production.

After being a Digital Nomad

Realising that sun and touching grass (or water in my case) was good for my health and actually helped me write better code, this now this is my preferred style of working. Simple and clear, I find it super creative and it helps me focus. Yes I do miss my second screen sometimes.

Here is one of my favourite laptop photos from my recent travels … 📸

Q. Which do you prefer, the before or after office photo? Leave your preference in the comments below:

Leave a comment

My recent content

Here are some of my recent and favourite content that I think would be interesting and useful to you.

As a developer is security important?

Developers need to be involved in so many areas of the project, but security is often left out, why? Maybe because it is not interesting or fun, or maybe because it is difficult and scary! However, there are great libraries and tools out there that remove this pain and solve the problem. Let more about my experience at the Okta (Auth0) event at McLaren UK.

Building a SaaS from idea to deployment

My biggest blog and video ever! 🎉 I wanted to show the process from idea to user, so I have created a blog and video, the projects themselves are similar but not exactly the same in each project, so check out both:

If you like my content and would like to support me, then you can share my free publication with your friends or even a friend.

Share The Open Source Expert

Your content

Here are some great content I think you would like from the tech community.

12 month challenge

has created a challenge for himself, 12 projects in 12 months. Do you want to understand why and see how it is going after a few months in? Read below and follow Razvan Muntian for latest updates:

Razvan Muntian

The Reason Behind My 12 Startups in 12 Months Challenge

Hello friend…

Read more

a year ago · 1 like · 1 comment · Razvan Muntian

Open Source

I was part of the first cohort of the GitHub Accelerator in 2023 and one of the projects there Mockoon is still moving forwards as a business years later. I have kept in contact with Guillaume, the founder, and seen the project’s journey. I really respect the consistent push forwards even with the challenges that Open Source projects face with time and money.

Mockoon is the easiest and quickest way to run mock APIs locally. No remote deployment, no account required, open source.

Visit the Mockoon GitHub repo https://github.com/mockoon/mockoon

If you have got this far, thank you for taking the time to read this newsletter! See you in the next one.

What are we building and why?

We are going to build a multi-tenancy fullstack monitoring platform that pings web page URLs on a scheduler (cron) every X minutes and records the results. This will include the status code, the size of the response and how long it took to make the request, allowing us to show to the user the status of the web page at any given time, as well as their uptime for a select period. For example; 7 days or 1 month. In addition we will store the time it took to make the request, so that the user can see how fast or slow their platform is performing over time.

Why is a platform like this important? When we build a website or web app, we trust that it is always up, but we cannot be sure. There are many moving parts, from the database to the domain. Having an independent regular check that stores the results if we need to refer back to them and notifies us if something goes wrong, means you can take immediate action to solve any issues that arise.

Tools needed for this project

To follow along with this blog, here is the list of tools which I used.

• GitLab

• Cursor AI

• NextJS + Tailwind (TailwindCSS) + Shadcn

• Prisma + Postgres (PostgreSQL)

• Clerk

• Sevalla cloud hosting

Why these tools?

The tools I list in this post are my personal favourites, but feel free to swap out any for your preferred ones.

GitLab

GitLab will give you not only a git repository (“repo”), but also has all the project management tools to make your life easier; such as Issues, Issue Boards, as well as CI/CD and a Service Desk where a user’s message will end up straight to your GitLab project - very cool!

CursorAI

There are many AI development tools out there. Cursor has a great dedicated IDE which makes the whole process much more streamlined. For example, you can use AI in the terminal to explain or even fix an error.

NextJS (Typescript) + Tailwind (TailwindCSS) + Shadcn

These frameworks and libraries are a great combination to build a fullstack app. There are a lot of content and examples out there using them, which means AI loves these tools also. Just be careful with the version you are using and the code AI generates, as it can often get the version wrong - Typescript and the Linter can help with this which comes out of the box with NextJS.

Prisma + Postgres (PostgreSQL)

Prisma and Postgres have great DX (Developer Experience) as well as being mature products, making them super reliable.

Clerk

There are many authentication options out there - I know I have tried out many over the years - and they all have their pros/cons. Clerk works out of the box within minutes and has many useful features. Plus it also has a generous free tier.

Sevalla Cloud Hosting

This has all the cloud features you need to launch your app fast from your GitLab/GitHub/Bitbucket projects and scale to millions. However it is still super affordable with straightforward and clear pricing. Sevalla is a great choice to host your fullstack app and database. I especially love the architecture diagram they generate of your setup, as it gives a clear picture of your setup and allows you make any changes you need.

Chapter 1: Setting up the GitLab project

Many people skip this step thinking it will slow them down and it is not as important as the code. However I feel it is super important to create good foundations so that we can keep track of the code changes and plan the tasks we need to do. Plus having CI (Continuous Integration) and CD (Continuous Deployment) brings many efficiencies and improves quality. It doesn’t take long to set up and will help you think throughout the duration of the project and beyond.

Create the GitLab Project

You need to create a unique name within your GitLab group. I am creating the PingIt project under my username.

Once the GitLab project is successfully created you will see the following page:

Create Issues for the project's features

This first pass at creating Issues does not need to be perfect. I suggest you see this as a good way to make a note of the initial tasks that come to mind. You can always split larger tasks later on when you get to them and create more as you discover that you need them.

At this stage I create only the tasks that I need for the MVP (“Minimal Viable Product”), so I can keep a clear focus. Any ideas that would fall under a version 5 stage could be a distraction at this point and also clutter the Issue Board. You could opt to add these could go under a single issue called “future ideas” to ensure you don’t forget about them.

I prefer to create Issues directly on the Issue Board so I can visually see the progress, plus I love dragging them over to the “done” column! Before we can do that on GitLab we need to create some Labels as these will become the board’s columns.

Create Labels

Under “Manage” click “Labels”. You will be presented with “generate” labels: I did this as well as adding one new label “In progress”. These are useful for filtering Issues as well as creating buckets (columns) in the next step.

Issue Board

Now under the “Plan” section:

1. Click on “Issue boards“ (I have it pinned on my side navigation).

2. Click “New list”.

3. Select the “In progress” Label we created earlier.

Then you will see the following board. We will probably add more columns later but for now, let’s keep things simple and focus on the MVP.

Create specific Issues

I have created the high level Issues and the board looks like this:

For each Issue I will have a task list of things I need to do. If a task is too big, it will have it’s own specific Issue, which I can then break down further into sub-tasks.

Here is an example of what a sub-task with checkboxes looks like in the Issue:

I check each task off as I go. The feeling is almost as good as moving the card over to the “done” column!

In Markdown you can create a checklist using the following (the blank spacing around the square brackets is important):

- [x] Item 1 completed and checked
- [ ] Item 2 not complete and not checked

Chapter 2: Creating the NextJS project

1. Using the NextJS CLI command to create a new project:

npx create-next-app@latest ping-it
Need to install the following packages:
create-next-app@15.1.7
Ok to proceed? (y) 

✔ Would you like to use TypeScript? … No / Yes
✔ Would you like to use ESLint? … No / Yes
✔ Would you like to use Tailwind CSS? … No / Yes
✔ Would you like your code inside a `src/` directory? … No / Yes
✔ Would you like to use App Router? (recommended) … No / Yes
✔ Would you like to use Turbopack for `next dev`? … No / Yes
✔ Would you like to customize the import alias (`@/*` by default)? … No / Yes
Creating a new Next.js app ping-it.

Using npm.

Initializing project with template: app-tw 


Installing dependencies:
- react
- react-dom
- next

Installing devDependencies:
- typescript
- @types/node
- @types/react
- @types/react-dom
- postcss
- tailwindcss
- eslint
- eslint-config-next
- @eslint/eslintrc


added 376 packages, and audited 377 packages in 28s

143 packages are looking for funding
  run `npm fund` for details

found 0 vulnerabilities
Initialized a git repository.

Success! Created ping-it

2. Navigate into the new directory:

cd ping-it

3. Connect GitLab Repo with our local git repo, using the git remote command:

git remote add origin git@gitlab.com:eddiejaoude/ping-it.git

4. Now push the local changes to the git Repo on GitLab:

git push origin main

5. If you refresh the GitLab project page, you will see the code files:

Chapter 3: Generating a static landing page

SEO discovery takes time and is out of our control so we want to make sure that we start this process immediately and without delay. It is recommended to create a landing page with high level important information about the project and get this out on the internet as soon as possible. With NextJS and Sevalla I can do this quickly, easily and for free. Plus it gives me content for social media as I enjoy posting about “building in public”.

To start building a static landing page for our project, I get CursorAI to help:

1. Open the project in Cursor AI:

cursor .

2. Use the right panel Composer with “agent” mode to describe what we want CursorAI to do: which is create a static landing page for our app.

Here is my discussion with Cursor AI:

Which generated the following result:

I suggest removing the payment buttons for now. I won’t be covering how to integrate payment into the project as part of this blog - but please do let me know in the comments if this is something you would like to learn more about. The objective of having a static landing page is to be able to deploy as quickly as possible so that SEO can start (plus there is nothing to pay for at this stage!). Remember, it takes time for the project to be indexed by Google and other places so ideally you do not want to leave this until the last minute.

It is necessary to change the output of the NextJS project to be static files and disable image optimisation. This can be achieved by adding 2 lines to the NextJS config, but as this is a new project we can make the following changes to the `next.config.ts` file:

const nextConfig: NextConfig = {
  output: "export",
  // Disable image optimization, it's not supported in static exports
  images: {
    unoptimized: true,
  },
};

Now run `npm run build` and it will create the directory `out` where the static files will be generated.

To test it out locally you can install the dev dependency `server`. These are the steps:

1. `npm install serve —save-dev`

2. `npm run build`

3. `npx serve@latest out` which will output useful information

4. Visit http://localhost:3000 to see your static web page.

Leave a comment

Chapter 4: Deploying the static landing page to Sevalla Cloud Hosting

I decided to use Sevalla for this project because it is very straightforward to set up. It is fast and affordable to get started and as I need to scale up. You will see the UX/DX is great with some extra visual architectural features of your set up, which I really love. I will show it to you later, but here is a teaser:

Let me know what you think by leaving a comment.

Leave a comment

Hosting on Sevalla cloud provider

1. Sign up to Sevalla. I use my GitHub with Oauth, but you can select the login method you prefer.

2. Under the My Account section, connect your GitLab.

3. Go to the `Static sites` section on Sevalla and click `Add a static site`.

4. Select your repo and branch. I checked `Automatic deployment on commit` as each time I push to GitLab I want to deploy the latest changes.

5. Sevalla detected my project is NextJS and has preselected the recommended settings, so I will keep those.

6. The first deployment will automatically happen, and future deployments will happen after a new commit is pushed to GitLab.

7. Sevalla will create a temporary sub-domain for you, which you can see by clicking the button `Visit site`. This saves me so much time because I want to focus on finalising the end-to-end workflow/pipeline, which we will build on later.

   The format will be your project name then some random characters appended with `.kinsta.page`. Mine at the time of writing is https://ping-it-zv7bk.kinsta.page

Your Dashboard will now look more interesting and something like this:

Domain setup on Sevalla

Now we have our project running on Sevalla with a temporary domain that Sevalla created, we can check everything works fine, but we want to build SEO domain authority on our custom domain.

Firstly you need to buy the available domain you want from your favourite registrar. I don’t have a favourite - quite the opposite - the ones I have tried are not great. I do hear people recommending CloudFlare but I haven’t tried it yet myself, I will soon though. Let me know in the comments which domain registrars you have tried and if you would recommend them.

Leave a comment

In your app, go to “Domains” on your side navigation, then click “Add domain”:

Enter the full domain you purchased, mine is pings.sh, what do you think?

Follow the wizard’s step-by-step instructions to add `TXT` to your domain’s DNS records with the provided values to your domain to prove ownership. Then Sevalla will verify the DNS records.

The verification can take some time as it is waiting for DNS to propagate. While you are waiting Sevalla will show that the verification process is pending:

Once verified, it will give you the IP you need to point your DNS `A` record to on your domain, then shortly after you make these changes and they propagate through the internet you are ready!

Chapter 5: Build the project

Now the fun really begins, well for me at least! Creating the fullstack SaaS application.

Before we get started we now to need to remove the static NextJS export we configured earlier in the `next.config.ts` file.

The diff in Cursor will look like this:

Authentication with Clerk

I always recommend starting with authentication. It may not be considered the most “fun”, but it is required and it will be the foundation for the application. What I mean by “foundation” is that almost every database query in this application will be authenticated.

I will ask Cursor AI to “add authentication user Clerk with GitHub OAuth”. I find AI is very good at this because there are so many examples out there. It even gives the steps to set up the account and what secrets are needed to get from the GitHub OAuth provider.

Clerk has great documentation, so if you follow the steps for Clerk with NextJS you will have GitHub OAuth set up in a few minutes. Then you can click login and you will be presented with the following OAuth GitHub page to log in:

Also Clerk and your GitHub OAuth app will now show 1 user has authenticated, which you can check this on their dashboards:

Clerk’s Dashboard

GitHub’s Dashboard

Now I have logged in, I am presented with my GitHub name, which is a good indication that all is working well. Your own page will probably look different as the point is to let AI have a bit of freedom here, but you should have a similar result. If not chat with AI to resolve and move forward. I find this is often needed with AI, so don’t be concerned if things do not turn out exactly as you envisioned first time round, as it can often surprise you with a different result.

Make sure to check the secure pages that require authentication are protected as AI often forgets things like this. If you do find this is the case, then ask AI to implement a solution. As an extra check remember to test this in your browser as well as private browsing as a guest, and make sure the secure pages are not reachable and you are redirected accordingly usually to the login page.

Prisma (Postgres)

The next step is to save data in my database and I will start with the Monitor data. This will be the foundation of our app and we will need to have the field `userId` for each monitor, so the user can only see and manage their own data. I asked Cursor AI to do this for me and I will review the diff from the changes it creates.

CRUD monitors

Here is what I asked Cursor AI to do:

create a new page for the authenticated user to CRUD their monitor. The monitor form should include a name and url, include client side and server side validation using zod. Use Prisma with postgres to save the monitor data and include the userId field from Clerk.

It had the “create new monitor” form on the Monitors list page, which I didn’t like so I went back and asked AI to move this to its own page. That way the edit Monitor could reuse the same code or even page.

This is the result:

Monitor list page

Monitor create / edit page

Monitor Postgres database table

The database table Monitor has the column `userId` and all database SQL queries include the following parameter which comes from Clerk’s unique identifier for each user:

Scheduler to run ping for each monitor

Now I have the ability to create, edit and delete monitors, I need to have these run on a scheduler (cron) and save the relevant results. I asked AI to create this for me and it got it right first time - yes I am surprised! Now I have a Typescript script that can be called from npm, which collects the information needed for every monitor. This is not protected per user as it will be a system call only which runs for every monitor on the platform regardless of the user.

Collect data for all the monitors by running the command:

npm run monitor

Your command might be named differently. This makes the http request and collects the data in the database for each monitor:

List of ping results for each monitor

After the previous section of the scheduler and collecting data for each monitor, I need a way to display the results to the user of their own monitors - yes only their own data. I always start with asking AI but purposely keep my instructions a bit vague to see what it generates. Why? It might generate something I didn’t think of as well as giving me some ideas!

After a few iterations, I ended up with the following dashboard that shows the total statistics at the top and the latest results for each monitor:

There is a dropdown to select a specific monitor, then the graphs are shown for the history of that specific monitor:

There are some UI improvements to be made, but I will get this deploying to the end user now. Then I can go back and make further tweaks to improve the UI while I wait for user feedback.

Chapter 6: Deploy full stack project to Sevalla

To get the fullstack app to the end user, we need to deploy 3 parts: the database with Prisma migrations, the NextJS app itself and the scheduler (cron). This is not as scary as it sounds, you will see we are almost complete.

Create database on Sevalla

Firstly click on “Databases” on the left navigation menu on Sevalla, then click “add database”. You will be presented with a small form where you can select the database type (Postgres, MySQL, MariaDB, Redis, Valley), version, name and location:

Sevalla auto generates the username and password, which I don’t change. There is also the resource size:

After clicking “create” you will be taken to the overview page of your database, which will look something like this:

I will connect the app to the database in the next step, so it has an internal database connection that is fast and secure. It is possible to enable the external connection if required, but I wouldn’t recommend doing this by default, but only if you have a specific requirement.

Create an app on Sevalla

From your Sevalla Dashboard you can click “Add service” and select “Application”. Or in the same way as to how the Postgresql database was created, alternatively you can click on “Applications” on the left menu then “Add application”. Either way you will be presented with the following page:

I have filled in the Sevalla application creation with the following details (but you would change them to match your project requirements):

1. Git repository.

2. Private repository.

3. GitLab tab.

4. `ping-it` repository in the dropdown.

5. The `main` branch is automatically selected for me.

6. I checked “Automatic deployment on commit”.

7. The name is pre-populated with the name of the repo which is great, but I appended `-app` to it. This is not required, just my personal preference.

8. I selected `London` for my location, but you have many options around the globe.

9. As to the size of your pod there are a variety of options, which clearly show the price. Plus you can increase/decrease these later as your project requires.

Next you will be taken to the “Applications Dashboard” page, which will show you a great diagram of the architecture overview: from the client through to your web process (and more later as I connect more services). There is the temptation to click the “Deploy now” button for the first deploy immediately, but I need to connect the database first otherwise the application will not work properly.

Connect the app to the database on Sevalla

Connecting the database and web process together can be done in two ways: either from the application or from the database. Whichever one you pick you will achieve the same result.

Connecting the app to the database via the database

In the database overview, scroll down to “Add connection” and select the application you wish to have a connection to the database.

The dropdown will list your applications:

Connecting the app to the database via the app

In the application dashboard, on the left navigation click “Networking” and then scroll down to connected service and click “Add connection”. Similarly to before the dropdown will show you the databases you can connect and I will look for the Postgresql database I created earlier.

Once the database is selected Sevalla does ask with a toggle whether I want to “Add environment variables to the application”. This is super convenient but I prefer to do this myself manually. Now the connection will show in the “Connected services” list.

Add environment variables Sevalla

I will then click on “Environment variables” in the app’s side menu and add my application’s environment variables. For the app I built we need 4: I can get the database environments from database overview page.

Migration command

For ease let’s add the Prisma migration commands to our `package.json` file:

"db:migrate": "prisma generate && prisma migrate deploy"

• generate: creates the Prisma client

• migrate deploy: apply pending migrations to environment

We have combined both commands into a reusable npm command.

We want the `db:migrate` npm command to run after the npm dependencies have been installed and we can do it with the following command using the `postinstall` npm hook:

"postinstall": "npm run db:migrate"

First deployment

I am now ready to deploy, so I click the “Deploy now” button. After a few minutes you should see 2 things:

1. A successful deployment with a green check.

2. The “Visit app” button at the top right will take you to your live app on the internet.

I have one step left to do, which is the scheduler / cron to run the checks for each monitor. Before I do that though, I am going to log in in and create some monitors.

I have created 2 monitors:

1. Monitor my own project Ping It.

2. Monitor my other project MakeTheList.io homepage.

Add the scheduler / cron on Sevalla

Earlier with the help of AI I created a script to run using npm that collected data using the URL from the user’s Monitor, but now I need to run it frequently on a scheduler (cron). With Sevalla this is really straight forward to do with a couple of clicks.

In the app page on the side navigation click “Processes”, then at the top right of the page click “Create process“, where you will be presented with a form. Fill in the details: the important fields are the “command” which we will use the npm command created earlier and the “cron expression” which determines how often this command should run (if you are unsure click the `?` and it will give examples).

Here is what I have used:

After clicking “create”, these changes will be deployed and the app dashboard will show a visual representation of the projects architecture as before, but this time with the scheduler / cron added:

I love this Sevalla view of my project, it shows me the status of the project and also reminds me how the architecture setup is - which is very important when we have multiple projects plus super helpful when onboarding new team members.

Results

By leaving the app running with the Sevalla process that has the scheduler (cron) there are now results on the dashboard:

What I really like about Sevalla is that it is user friendly but also feature rich. The Sevalla cloud hosting platform has all the features needed to support our SaaS products as they grow, as well as controlling spending and no hidden surprises.

Chapter 7: Other SaaS considerations

As the blog is about how to build and deploy a SaaS, I am keen to also mention what other considerations you need to think about if you want make it a serious project with paying users.

Payment provider

You will need to add a payment integration. There are many options out there, like Stripe or Paddle. They both have a quick way to integrate which can be more generic, or a more advanced option if you wish to have this look consistent with your existing design. In my opinion, I highly recommend going down the simplest route so you can get your product out as soon as possible and get user feedback.

User notifications

With our monitoring platform, if there is an unexpected error when the app makes a ping to the user’s Monitor URL, we need some way to notify them as they only log into the platform to check the results and statistics once per week. This way they can be proactive if their website goes down.

Automation with CI

Iterating fast is great but we need to make sure we are not breaking anything. So it is important to run commands like: tests, linters etc on every push. This can be achieved with GitLab CI and some YAML config files.

Scaling

With Sevalla you can manually or automatically scale your app horizontally or vertically as required. This is super useful for when your app receives unexpected traiffic or during a marketing campaign. This way you only pay for what you need to use. Sevalla’s official documentation covers this here: https://docs.sevalla.com/application-hosting/scale-application-resources.

On your Sevalla dashboard you can see your spending over the month as well as go into each app or database and see the usage. For example: memory, cpu, requests etc https://docs.sevalla.com/application-hosting/application-analytics.

Chapter 8: Conclusion

I hope that I have showed you that building your own SaaS doesn't have to be a pipe dream and doesn't have to cost you a lot of money. My advice is to use tools and platforms that are recommended and proven - don’t select those which are just hype or “in” right now, as this could come back to haunt you later on.

Let's be honest. When deploying your shiny new project your main objective is to get users and customers. The last thing you want to be worrying about is whether your app is still running, especially when you are not working or sleeping. You just want it to work so your users can use your app confidently and consistently.

I hope this post has inspired you to start your project today. Please let me know in the comments what project you decide to build and keep me updated on your progress.

Watch the full YouTube video here:

Thank you to Okta for sponsoring this blog post. The content and opinions are my own.

Do developers need to worry about security?

As developers we want to build exciting features. Not be security experts. Regardless of this, security is important to me as a fullstack developer and it is important to have a good understanding and awareness of security. How? We can use tools and platforms that allow us to be secure without needing to go into all the intricacies of how we got to that point. It’s a bit like being able to drive a car but not having to be a mechanic to do so.

Judging by one of my recent tweets though….I might be part of a small group of developers who feels this way.

However as it turns out, companies do want to hear what developers think about this topic!

Leave a comment

Okta Showcase

I was invited to report on Okta’s Showcase which took place on April 9 here in England, in what is perhaps one of the best (if not the best) venue for an event that I have ever been to…McLaren’s R&D facility! It is like the Apple Park but in the UK.

For those of you who don’t know, Okta is a cloud-based identity management service that helps organisations manage and secure user access to applications and resources as well as having an authentication providing through their platform Auth0. They recently announced a partnership with McLaren Racing to identify new ways to secure and improve the digital experience for not only the McLaren employees but also the millions of fans who love watching the Formula 1, IndyCar and Le Mans races around the world.

So when I had the opportunity to participate in a roundtable with journalists in the tech space as well as leading key figures at Okta, I …raced at the chance (get it?). As a developer it was super interesting to hear how leading voices in tech news perceive security and AI, and to ask the type of questions I don’t always get a chance to when attending a developer conference or online on social media. So I wanted to share my thoughts and findings with you.

“Identity is security”

These were the thoughts of Todd McKinnon, CEO and Co-Founder of Okta during his Showcase talk. What does he mean by this? There is a need for the tech industry to be more standardised so that we can get to the point where all identity based attacks are eliminated.

There are already authentication standards, for example OAuth and Open ID. Most people, whether they are developers or not, will be familiar with accessing a web app securely through social login without sharing their credentials with said web app. Plus in my experience of working with teams of developers, my opinion is that the vast majority of us are keen to comply with existing standards. Standards lead to a more secure outcome: not only does the end user only have to be identified and authenticated once by an identity provider, standards will contribute towards privacy compliance.

However it would be impossible to ignore that some still try to circumvent this or “roll their own”, under the misguided impression that this will be faster.

"You cannot secure what you cannot see"

Harish Peri, SVP for Product Marketing at Okta highlighted how securing NHIs (Non-hHuman Identities) is a very difficult task during his talk. These cannot be taken lightly as they have become silent attack vectors and over privileged. Without realising perhaps, owners are unknowingly giving NHIs greater power than required, for the sake of convenience.

Even the smallest project requires multiple tokens or API keys (which are the equivalent of passwords) to function effectively. I recently created a small SaaS and that had three tokens for multiple platforms. Now think about this on a larger scale.

The likelihood is that when a developer or sys-admin creates tokens, API keys or service accounts these are usually forgotten: either because the author has moved on or the reality is, if the integration is working why would you give the tokens or API keys are second thought about what permissions they have? What’s worse is that even when the project has moved to a new integration, the likelihood is that no one will think to revoke the tokens or keys. Plus, upon a system being deprecated the privileges it has from tokens or API keys are not automatically revoked - they still remain.

“AI agents must be built securely right from the start”

It is no surprise that AI is evolving faster than any other technology shift. What is surprising and even a little scary is that in the opinion of Shiv Ramji President of Auth0 Okta, “security is getting left behind”.

A staggering 82% of organisations plan to integrate AI agents in the next three years, not only for assistance but also to take actions on behalf of the user. Once these AI agents are online without the correct security, it is too late. They can have access to sensitive data and potentially allow an attacker to take control.

During his talk I was excited to hear from Shiv that “Auth for GenAI” was built for developers! As a fullstack developer myself, I don’t want to get into the intricacies and details of security but I know it is important. That is why tools and platforms like Auth0 are great as they allow me to be secure without worrying about the details of the security at the same time. That way I can focus on building the business value for my users and still keeping them secure.

The main features of Auth for GenAI are:

• Authentication for GenAI - tailored made login experience for AI agents.

• Token Vault - AI agents can call APIs on the user’s behalf using secure standards, therefore allowing the AI agents to securely connect to platforms like Gmail, Slack etc to automatically handle token refreshes and exchanges.

• Asynchronous Authorisation - from interactive chatbots to background workers, AI agents can perform tasks on behalf of the user and have the user notified to provide consent for critical actions.

• Fine Grained Authorisation of RAGs - only retrieve data or documents the user has access to.

This is available for developers to start using Auth for GenAI today, and I am excited to have a play! What about you?

Okta’s private tour of McLaren

After hearing the talks those attending the event had an amazing private tour of the McLaren facilities. I got to see the most amazing cars but also the workshops with the engineers in action (what struck me was how clean and tidy the work stations were - not what I was expecting). But as there is proprietary information and work going on 🤫 I wasn’t able to take any photos of this area… you will just have to use your imagination!

This blog post only really scratches the surface of what Okta and Auth0 are doing in the security space. If you want to learn more I would recommending taking a look at “A blueprint for Identity Security in the era of AI and NHIs”.

Online directories are not a new invention, but they have recently increased in popularity as an effective way to connect with businesses and review products and services.

There are several articles out there which explain why a fully fledged business should create a directory: it is low cost and low risk, great for SEO traffic, building consumer trust…the list goes on.

We wanted to focus this post on why individuals should consider compiling their own directories.

Traditional long form content is not the only avenue

When 280 characters is not enough to share our thoughts, most of us turn to longer form content avenues such as blogging or videos.

However there could be several reasons why these are not for you. Blogging can be considered a high effort endeavour which can discourage some people from starting one. You might find that you feel you do not have enough to “fill” a blog post or you simply do not want the commitment to publishing your opinions on a regular basis. Making videos - particularly the speaking on camera part - and the work that follows with editing and publishing, is just not everyone’s cup of tea.

Putting together a directory is a great way to create long form evergreen content with lasting SEO benefits, where you can still share your opinions on products and services. There is no reason why you can’t start small (with only a few items in your directory) and build on this as and when new experiences arise, particularly as populating a directory is a straightforward thing to do. Rather than committing to spending hours on a piece of content, with a directory you can get started and add value within minutes.

Become a community resource

One of the reasons for a business to build a directory is that they provide high-quality backlinks to the businesses listed as they are considered reliable and well-known sources by search engines. This eliminates a consumer’s concern that the business might be a fake company hiding behind a website.

Yes, directories can be a great marketing tool for a business. More so, they can be genuinely useful to their users.

Sharing your experiences and knowledge with the community through a carefully curated set of resources provides more value than an “opinion-less” list of services. More often than not when looking for a service or a product, potential users want to hear from real-life users - rather than the promises and tag lines on a company’s website.

Given how quickly a directory can be populated and scaled, your curated list can become an authority on that particular topic and the go-to resource for the community.

It is not just about the list itself: make sure your authentic voice comes across. MakeTheList can help you with this as it will populate the directory item from the URL as a first pass, and you can then use the rich text editor to really make your opinion stand out.

A boost to your online presence and credibility

In the same way as your social media account is a good tool to solidify your online presence and personal brand, so is having your own directory.

As we mentioned above creating a list of curated resources while sharing your opinions and reviews, helps establish you as a voice in that space. As your directory gets more and more visitors this will bring traffic to you and what you want to promote. For example:

• If you have a SaaS, why not create a directory for that niche? The likelihood is that you will have researched your competitors so populating your directory will be easy. Plus, some online directories give you the functionality to pin or feature your product at the top of the directory list.

• Have you done a deep dive on one of your directory items? Why not link that blog or YouTube video for those who want to learn more.

• Have you used one of your directory items on a real use case or as part of your portfolio? Bring this to the visitor’s attention so they can find out about your work and other projects.

• Use your directory as a way to get the users to discover your content on other platforms.

Sponsorship and affiliate opportunities

Once you have set up your directory consider adding it to a business directory, many of which offer a free listing. Having your directory showcased on a business listing (for examples, check out the Explore Directories tab on MakeTheList), brings you exposure at zero or low cost.

As your directory accumulates more listings with reviews providing good value, your profit potential increases. When you consider that platforms such as MakeTheList make it straightforward to create a directory and populate it, growing your list of directory items doesn’t seem so daunting.

One of the main sources of income from a directory comes from businesses paying to be in the directory and also being featured at the top. By having a directory you are creating another source where the supplier can connect to the consumer, the product to the user. The higher the traffic to your directory will translate to higher premiums for listings.

If your directory attracts significant traffic, additional revenue streams such as advertising (in the form of banners on your directory website, for example) and affiliate programs (earning a commission for each new user who signs up to a product or service listed in your directory), become viable.

Last Thoughts on Directories

Having your own directory is a great way to share your knowledge, create SEO friendly evergreen content and potentially have an additional income stream. We hope that you will consider choosing MakeTheList as the platform to create your directory.

Why?

There are times when you want to expose your local services temporarily to the internet for the outside World to reach. For example, you might be adding a payment integration to your app with Stripe or LemonSqueezy and you need the test webhooks. These would need to be sent to your local development server because you don’t want to deploy to your staging environment for every test or code change.

How? Quickstart

There are various tools out there to do this, the most famous being Ngrok. But I really like the simplicity of the alternative LocalTunnel.

localtunnel exposes your localhost to the world for easy testing and sharing! No need to mess with DNS or deploy just to have others test out your changes.

Installation

Note: you need Nodejs installed.

Install the npm package globally:

npm install -g localtunnel

Running

If you are running a project or service locally like NextJS on port 3000, you can run the command in your terminal with the port flag:

lt --port 3000

In your terminal this will output a domain you can use to route external traffic on the internet to your local services:

your url is: https://dull-readers-call.loca.lt

Note: this url will change every time. Here I will stop the command and run it again and you will notice the url has changed:

Leave a comment

Extra settings

Run the help command to get all available options:

lt --help

Here is the output from the help command:

Usage: lt --port [num] <options>

Options:
  -p, --port                Internal HTTP server port                 [required]
  -h, --host                Upstream server providing forwarding
                                             [default: "https://localtunnel.me"]
  -s, --subdomain           Request this subdomain
  -l, --local-host          Tunnel traffic to this host instead of localhost,
                            override Host header to this host
      --local-https         Tunnel traffic to a local HTTPS server     [boolean]
      --local-cert          Path to certificate PEM file for local HTTPS server
      --local-key           Path to certificate key file for local HTTPS server
      --local-ca            Path to certificate authority file for self-signed
                            certificates
      --allow-invalid-cert  Disable certificate checks for your local HTTPS
                            server (ignore cert/key/ca options)        [boolean]
  -o, --open                Opens the tunnel URL in your browser
      --print-requests      Print basic request info                   [boolean]
      --help                Show this help and exit                    [boolean]
      --version             Show version number                        [boolean]

You can also use LocalTunnel programmatically if you need, see the API section in their docs.

Conclusion

Yes there are more advanced alternatives but if you don’t need a specific feature (for example, custom domains or sub domains), then I think the LocalTunnel library is perfect for what we require as developers 99% of the time.

It is:

• simple

• open source

• free

• npm package https://www.npmjs.com/package/localtunnel

Let me know in the comments which tools you have tried and what you liked and didn’t like about them below. 👇

If you prefer to watch a video on this topic:

Here is an example from GitHub’s API to get my repo JSON:

When I was working with the GitHub API a lot of JSON was returned, so I was keen to find a way to automate this process of creating the Typescript interfaces. I came across various tools, but the one that caught my eye was quicktype.

quicktype generates strongly-typed models and serializers from JSON, JSON Schema, TypeScript, and GraphQL queries, making it a breeze to work with JSON type-safely in many programming languages.

Whilst it is easy to use it does create more code than I need for now, although I think it will be useful in the future. Let me show you:

1. Install the npm package globally:

npm install -g quicktype

2. Save the JSON response from the API, in my case GitHub to a JSON file. As you do not need this for your project, it can be saved to a temporary location.

   I suggest not committing this JSON file as it will not be used and might cause some confusion on what these extra files are for (unless you need the example data for mocking, but that is another story). I add to the filename `*.tmp.json`, and in my global git ignore. I ignore any of these “tmp” files so they are not accidentally committed.

3. Using the command:

quicktype -s json -o <DESTINATION-TS-FILE> --lang ts <JSON-FILE>

The actual command looks like this:

quicktype -s json -o src/models/github/repo.ts --lang ts tests/mocks/repo.json

Two required parameters:

• output/destination of the typescript file

• input/source of the JSON file

These are the Typescript Interfaces that will be generated:

You don’t need to use all of the generated code. You can remove any Interfaces or items you will never use. In fact additional helper functions are included, but for now I have removed these from my code and from the image above.

Conclusion

You should create types/interfaces for your project, but please do not use “any”! Being strict and saving your self pain later on doesn’t have to be difficult or time consuming, when we have tools that help us create them.

If you prefer to watch a video on this topic:

There is another alternative, the external trigger! You can create an API endpoint on your app that does what it needs to do. Then you can test this by visiting the URL in your browser. If all is working well, the next step is to automate it with something, rather than visit it manually. I think this “something” could be a GitHub Action. Yes a GitHub Action is usually triggered by an event on GitHub, but they do have scheduling functionality just a like Cron job on Linux.

on:
  workflow_dispatch:
  schedule:
    - cron: 0 1 * * *

I won’t go into a lot of detail about the Cron functionality and how to configure the scheduled time because there is already a lot of great content out there on that - so note that it is super customisable.

As a brief overview:

1. The first value is the minute

2. The second is hour

3. The third is day

4. The forth is month

5. The firth is day of the week

The `*` is for any value on that item, so the Cron in the above example will run at 1am every day.

Then in the GitHub Action, you can make a http request. There are various ways to do this, such as Curl, Javascript and more, in the GitHub Marketplace. After testing a few, I actually decided on an Action in the Marketplace `tyrrrz/action-http-request`.

With all this added together this is what the whole GitHub Action looks like:

name: Run checks
permissions: read-all
on:
  workflow_dispatch:
  schedule:
    - cron: 0 3 * * *
jobs:
  api:
    runs-on: ubuntu-latest
    steps:
      - name: hit api
        uses: tyrrrz/action-http-request@master
        with:
          url: "https://healthcheck.eddiehubcommunity.org/api/system/checks?token=${{ secrets.API_TOKEN }}"

You will notice that the URL has a token param appended to it. This is how I secure the API endpoint in my application. The first step my app does for this API endpoint is to check that the token sent in matches the token my app is expecting. That way the API endpoint can’t be used by anyone.

In my NextJS code I have the following:

if (request.nextUrl.searchParams.get("token") !== process.env.API_TOKEN) {
    return Response.json({ error: "denied" }, { status: 401 });
}

That’s it, you now have a scheduler/crontab for your app. You can also add more at different frequencies if required.

Here is a real world example on GitHub:

https://github.com/EddieHubCommunity/HealthCheck/blob/main/.github/workflows/checks.yml

If you prefer to watch a video on this topic then take a look at:

Here are a few reasons why we may want to mock these:

• work offline;

• not worry about 3rd party rate limits while developing;

• boundary conditions for automated testing, we need different responses;

• control OAuth providers when authenticating.

Leave a comment

Despite all these reasons and benefits, it was difficult to find examples of how to achieve mocking out server-side API requests. There were examples that were specific to a library, for example Octokit - but this would leave the project with having many different implementations of trying to solve the same problem for each library being used.

Is there a way I can intercept all server-side RESTful API requests without my app knowing so it thinks it is real?

TL;DR

Yes it is possible! I will create an example NextJS app, that queries GitHub’s API on the server-side for real data. Then I will introduce the library MswJS that will allow me to create a JSON file to return a customised response for the GitHub API request. Yes my app will think it is making a real API request to GitHub’s API.

You might be surprised to hear there isn’t much code required to make this happen, there is actually more JSON as part of the response. But there is a small tricky part, which is integrating the MswJS code with the NextJS project. This is possible with an experimental feature in NextJS called “instrumentation”, which I will talk about later in this blog.

NextJS

Firstly I will create a standard NextJS app using the npx create command:

npx create-next-app@latest

I answer the CLI prompt questions with the type of NextJS project I wish to create. For example `javascript/typescript`.

Then I navigate into the new project directory and start the application in dev mode with the NextJS command:

npm run dev

Then I visit `http://localhost:3000` to see the web app.

GitHub Repo API

The next step is to make a server-side 3rd party API request. I will use GitHub’s API , but you can use any other API you prefer.

For the GitHub API request, we can make a request using NodeJS’s fetch or a library like Octokit, as both will be making the same http RESTful API call to GitHub.

To save installing an npm dependency, l will use NodeJS’s fetch.

I start by removing all the generated example content in `src/app/page.js` and make the fetch request to GitHub’s API with:

const res = await fetch("https://api.github.com/users/eddiejaoude");
const data = await res.json();

The file now looks like this, with some data displayed with help from GitLab Duo autocomplete:

export default async function Home() {
  const res = await fetch("https://api.github.com/users/eddiejaoude");
  const data = await res.json();
  console.log(data);

  return (
    <ul>
      <li>Name: {data.name}</li>
      <li>Location: {data.location}</li>
      <li>Bio: {data.bio}</li>
    </ul>
  );
}

As I still don’t like the look of the output, I asked GitLab Duo to refactor the output by highlighting the `return` section and asking GitLab Duo Chat to refactor using Tailwind:

That immediately looks a lot better:

Above I am making a real API request, but what if:

• We don’t have internet?

• We are running automated tests and we don’t want to hit the API rate limit of GitHub? or

• We want to test different results from GitHub, no data, lots of data etc?

This is where the library MswJS comes in to save the day!

MswJS

Mock Service Worker (MSW) is an API mocking library for browser and NodeJS. With MSW, you can intercept outgoing requests, observe them, and respond to them using mocked responses.

Installing MswJS

Firstly, I run the npm command:

npm install msw@latest --save-dev

Then I create the folder `mocks` in the folder `src` (path will be `src/mocks`).

This is followed by creating a file `handlers.js` in the new mocks folder. In this file I list all the requests I want to intercept and the response I want to return. Later on these can be split out into separate files as it grows.

Here is a simplified example:

http.get(
  "https://api.github.com/users/eddiejaoude",
  ({ request, params, cookies }) => HttpResponse.json(user)
),

This will watch for a GET request to the url https://api.github.com/users/eddiejaoude and will return a json response of my choice. We are able to use wildcards and regular expressions (regex) - for example https://api.github.com/users/* - these would watch and listen for any user to the GitHub API url and always return the same response. However, we could have a smarter function that manipulated the data, but for this example it is not needed.

The whole contents of the `handlers.js` file will be:

import { http, HttpResponse } from "msw";

import user from "./user";

export const handlers = [
  http.get(
    "https://api.github.com/users/eddiejaoude",
    ({ request, params, cookies }) => HttpResponse.json(user)
  ),
];

It is possible to mock the status codes and headers also. The full official documentation can be found here https://mswjs.io/docs/basics/mocking-responses.

Next I need to create a JSON file for the data I want to respond and I can edit this manually. To get the JSON file contents, I visited the url https://api.github.com/users/eddiejaoude in my browser and saved it to a new directory `data` in the `mocks` directory (full path `src/mocks/data`).

If you are following along, here is the contents for the JSON file:

{
  "login": "eddiejaoude",
  "id": 624760,
  "node_id": "MDQ6VXNlcjYyNDc2MA==",
  "avatar_url": "https://avatars.githubusercontent.com/u/624760?v=4",
  "gravatar_id": "",
  "url": "https://api.github.com/users/eddiejaoude",
  "html_url": "https://github.com/eddiejaoude",
  "followers_url": "https://api.github.com/users/eddiejaoude/followers",
  "following_url": "https://api.github.com/users/eddiejaoude/following{/other_user}",
  "gists_url": "https://api.github.com/users/eddiejaoude/gists{/gist_id}",
  "starred_url": "https://api.github.com/users/eddiejaoude/starred{/owner}{/repo}",
  "subscriptions_url": "https://api.github.com/users/eddiejaoude/subscriptions",
  "organizations_url": "https://api.github.com/users/eddiejaoude/orgs",
  "repos_url": "https://api.github.com/users/eddiejaoude/repos",
  "events_url": "https://api.github.com/users/eddiejaoude/events{/privacy}",
  "received_events_url": "https://api.github.com/users/eddiejaoude/received_events",
  "type": "User",
  "site_admin": false,
  "name": "Eddie Jaoude",
  "company": "Open Source Engineer",
  "blog": "https://eddiejaoude.substack.com/p/links",
  "location": "London, UK",
  "email": null,
  "hireable": true,
  "bio": "Open Source DevRel!\r\nGitHub Star ⭐ program + GitHub Star of the Year 🤓 + GitHub Accelerator with BioDrop (aka LinkFree)... let's GEEK out together!",
  "twitter_username": "eddiejaoude",
  "public_repos": 268,
  "public_gists": 24,
  "followers": 8251,
  "following": 67,
  "created_at": "2011-02-18T06:56:22Z",
  "updated_at": "2024-08-10T16:36:56Z"
}

The last file I need to create is for node (if you want this to work in the browser, you will have to add an additional file). Create the file `node.js` in the path `src/mocks` and the contents will be:

import { setupServer } from 'msw/node'
import { handlers } from './handlers'
 
export const server = setupServer(...handlers)

I then need to enable MswJS in our NextJS app with the code:

import { server } from './mocks/node'
 
server.listen()

Don’t worry we will cover how to do this in the next section.

NextJS’s experimental feature Instrumentation

After researching I found the best recommended way to integrate MswJS into an AppRouter NextJS app is with the `instrumentation.js` file. If you have not heard of before, don’t worry, neither had I! This file is a new experimental feature that needs enabling in order to be used.

Instrumentation is the process of using code to integrate monitoring and logging tools into your application. This allows you to track the performance and behavior of your application, and to debug issues in production.

In the `next.config.js` file I enabled the feature with:

module.exports = {
  experimental: {
    instrumentationHook: true,
  },
}

In the `instrumentation.js` file, I can start the mock server as follows:

export async function register() {
  if (process.env.NEXT_RUNTIME === "nodejs") {
    const { mockServer } = await import("./mocks/node");
    mockServer.listen();
  }
}

Note that we check the enviroment is “nodejs” then we import the mock server. Otherwise the app will throw an error if not in the correct runtime.

The next step is to restart NextJS to get the same data displayed in the browser. So how do we know it’s working? The easiest way is to go and change some data in the JSON file.

To illustrate this, I have changed the “name” field from “Eddie Jaoude” to “Eddie Jaoude (mock)”, and this is the result:

Next Steps

Now you have full control to intercept and mock out everything you need in your app! But one more change to the `instrumentation.js` file is needed, as when you deploy you will not want to use mock data but instead real data.

After looking into this, I learnt that the best way is to use an additional environment variable `APP_ENV` and add it to the condition in the `intrumentation.js` file, resulting in:

export async function register() {
  if (process.env.NEXT_RUNTIME === "nodejs" && process.env.APP_ENV === "test") {
    const { mockServer } = await import("./mocks/node");
    mockServer.listen();
  }
}

This way the mocking server can be enabled for local development and also automated testing.

Don’t forget to add `APP_ENV` to your `.env` and `.env.example` files

# APP_ENV=test

Conclusion

We can setup our projects for success and make our development workflow better because we have great Open Source tools available to us. However with so many tools, it is impossible to know them all, let alone try them all out. I hope this post will help you become aware and understand the best way to achieve server-side API mocking with NextJS, so you can use this functionality in your projects.

I will have more blog posts and YouTube videos on this topic coming out soon. I will be covering areas such as how we can use what we just learnt to mock out authentication that is using an OAuth provider like GitHub OAuth.

If you would prefer to watch a video on this subject:

1. it is too late to test then

2. the users are testing it also and might have a bad experience

3. it could break production for the users

However, sometimes we need production data to test our changes properly, and testing in production would be super useful and a much more of a thorough test. Is this possible and if yes, how can this be achieved?

TL;DR

Yes, this is possible and can be achieved by decoupling deployments and releases. This is best done using a feature flag tool. My feature flag project of choice is the Open Source project Flagsmith. By wrapping your new feature in a feature flag, and only showing it to a certain users or groups of users like maintainers, you can confidently and safely test it in production as it won’t be visible or affect any other user on the platform.

Prerequisites

Using NextJS (AppRouter) and Flagsmith, you can self-host Flagsmith or use their cloud platform for free. I have a full guide on how to set this up in a previous blog post:

Hiding features

In the Open Source HealthCheck project we have a new feature where we show stats from the platform. This has been tested locally with example data, but it is not the same as testing with real production data. Therefore we would like to deploy the feature to test with real data. However we don’t want users to use it yet, just in case there is a bug. This can be achieved using Flagsmith by wrapping the feature in a feature flag that we can only enable for certain users, like maintainers for example.

There are two steps to this process: 1. Adding the feature flag to Flagsmith’s dashboard and 2. Adding the code to our new feature.

Leave a comment

Flagsmith dashboard

I would recommend starting with Flagsmith’s dashboard. That way we will have some actionable results when we move on to the next step of coding.

At this stage you will already have a free Flagsmith account, possibly with some existing feature flags (please see my blog post mentioned at the beginning on how to set this up if you have not already).

1. Click “Create Feature”.

2. Give the new feature a unique name, I will use `platform_stats`.

3. I will not enable it by default and also not give it a value - this is different to what I usually do, especially compared to the banner text example.

Why am I giving it no value and not enabling the feature? For everyone, I want the feature to be disabled rather than enabled (similar to a default state in a database) and I will only enable it for a specific users or groups of users later on.

Segments

For groups of users there are segment overrides. I already have admin and maintainers in my dashboard, which I pass to Flagsmith when initialising their client and in Flagsmith for this segment I check for the trait `isMaintainer`.

initialise.traits = {
  isMaintainer: user.isMaintainer,
};

Identity

I decided for this feature flag to override the feature flag to being enabled for my user only. I can easily change this as any time to include more users or groups (aka Segements), as mentioned above.

Code changes

This is even easier, so this section will probably be the shortest - probably not what you expected?

1. In your code import Flagsmith:

import { useFlags } from "flagsmith/react";

2. Then use the flag that matches the name you created in the dashboard - another reason why naming is so important.

const { platform_stats } = useFlags(["platform_stats"]);

3. Near the top of your component check if the feature flag is enabled:

if (!platform_stats.enabled) {
  return;
}

Identity

Depending on how you set this up using Identity or Segments, you will probably need to add more information to the Flagsmith initialisation.

What I have done is send to Flagsmith on intialisation the user id and also if they are a maintainer. Then in the Flagsmith dashboard I can select the appropriate method to enable the feature flag.

if (session) {
  initialise.identity = session.user.id;
  const user = await prisma.user.findUnique({
    where: { id: session.user.id },
  });
  initialise.traits = {
    isMaintainer: user.isMaintainer,
  };
}

Conclusion

You can test in production safely! Previously this was used a negative term but with modern development practices, it is actually safe and positive.

You can see this fully implemented in the Open Source HealthCheck repo
https://github.com/EddieHubCommunity/HealthCheck

If you would prefer to watch a video on this topic:

I think most people are aware of the repo’s git ignore file, particularly when they clone a repo or create a new project with a framework like NextJS, as the git ignore file in the root of the git repo will be there and work its magic 🪄.

Using the git ignore feature is great but it has limitations, which is why I think this file is overused and often incorrectly.

Problem

Most projects in the repo’s git ignore will include almost every possible IDE and dev tools. I believe this is wrong, because:

• Everyone uses different operating systems, IDEs and dev tools.

• This list will only keep growing, it will never end

• Is the “.gitignore” file competing with the “README.md” for the most updated file in the git repo? I hope not 😰

Examples of folders included in the git ignore file are generated files like “.next” from NextJS or “test-results” from Playwright. These will be generated for every developer on the project regardless of their OS, IDE etc.

Yes I am saying this is wrong… (let me know if you agree/disagree below)

# .gitignore

.DS_Store
.vscode
.idea

Leave a comment

Solution

Global git ignore to the rescue! Adding this file to your system might sound like extra work. However it is actually quite straightforward and will save you from making mistakes that will cause a lot of extra work down the road.

The global git ignore is the same type of file and format as the repo’s git ignore you are familiar with. It is just in a special place on your computer that will affect all your local repos, yes ALL. This means that adding this file just once will benefit all your repos - that sounds great, right? So if you are on a Mac and it generates “.DS_Store” files, there is no need to add this to every git repo you work on and you can remove the risk of accidentally committing this file.

How

I know you are excited to get started, so let’s jump straight in, it will only take a few minutes:

1. In your home directory, create the file “.gitignore”:

touch ~/.gitignore

2. Add the contents you would need, for example:

.DS_Store
.vscode

3. Then tell your git about the new global git ignore file:

git config --global core.excludesfile ~/.gitignore

Then that’s it. Yes, that’s it! 🥳

Maintainers

For those maintainers out there reading this, I know what you are thinking: “But people don’t set this up properly so if I don’t have this in my repo’s git ignore all the Pull Requests come in with these files. So I add them to the repo’s git ignore to make contributors and maintainers lives easier.”

I understand this and I have done this before myself. What I noticed though was that this led to some people taking advantage of this project strategy by making it become a “green square game”. This resulted in Pull Requests containing new items being added to the git ignore file, just to cover every possibility - making the git ignore file many pages long 🤦.

Conclusion

The contents of the repo’s git ignore is for the project only files and folders. Developers can customise their own global git ignore with extra exclusions they need.

As a maintainer, don’t fall into the trap of putting every possible exclusion into the repo’s git ignore. This really is a “sticky plaster” approach in my view. What we should try to do is up-skill and educate the community, so it benefits everyone in the long run.

Here is a short description of this project from their website:

Wireshark is a network traffic analyzer, or "sniffer", for Linux, macOS, *BSD and other Unix and Unix-like operating systems and for Windows. It uses Qt, a graphical user interface library, and libpcap and npcap as packet capture and filtering libraries.

First impressions

My eyes are first drawn to these 4 pieces of information:

• 1k+ Star: this not an important metric, but for some reason this is something that naturally most people always look out for.

• Almost 100k of git commits: seems like a very active and long standing project.

• Uses the “master” branch not “main”: the project has probably been around for a while and has not changed the default branch.

• Badges: I am used to seeing these in the README, so to see them hoisted up I think is great as I don’t need to scroll down to see the Badges that the project wants to highlight.

Leave a comment

My next step is to scroll down to the README; maybe I can get a screenshot of the software? Unfortunately, there isn’t one. My suggestion here would be to add a screenshot, even if there is a risk that this would get out of date (although I feel this is unlikely on such a mature project). The benefit of having a screenshot is that it will attract more people to look into the project further.

Issues

There are many Issues, but most do not have Labels. I know this takes a lot of time for the maintainers, but it definitely would help the project and contributors filter through Issues.

The Issues on the Issue Board seem to have Labels, so I am not sure if they only get Labels once added to the board? To do it in this way might be the project strategy, however I didn’t see anything about it in their Contributing Guide - maybe it is an unspoken rule?

Wiki

Wireshark seems to make extensive use of the Wiki which is great! Their docs seem to be well organised and fully featured.

I really like that in their Wiki they even have a page on “Presentations” which is really awesome to see. I think other projects need to adopt this idea so that people can easily find talks given about the project and different perspectives. Plus the speakers can get some visibilty also - I see this as a two way street.

Empty sections

There are two sections in “Plan” on the left: “Iterations” and “Requirements” that are empty. Personally I would like to see these hidden so that I am not distracted by unused sections. What do you think?

Leave a comment

Merge Requests (MRs)

This looks very active, with recent MRs open and also multiple comments on each - great to see the collaboration in the community.

Build (CI)

I love this section, it is the heart of any project, where all the automation magic happens. Tasks like linters, automated tests, releases and then finally deployment. Seeing the various repo events trigger jobs and pipelines for the project, and the badges changing state. For me this section brings the project to life.

From the screenshot you can see the different state of the Badges and their colours: skipped, running, passed - and there are more. Is it only me who enjoys to watch these change state? Maybe because I always hope there are no red badges…

Releases / Tags

Git Tags are being used in this project. I personally prefer to see Releases being used, as this can present additional information about the Release/Tag. They are basically the same (so there are no disadvantages), but I feel the Developer Experience (DX) is better with Releases.

Environments

Another empty section, so my suggestion here would be to hide it if possible.

Incidents / Service Desk

Currently this doesn’t seem to be used on this project, but OH MY, this is the first time I am seeing these features and I love this idea! The Service Desk connects the users with the maintainers, and one of the reasons I think this is great is because the users (potentially customers) may not have GitLab accounts, but are still able to give feedback via email. Plus it all still appears in a single place for the maintainers. Information is kept transparent and doesn’t interfere with the Issue section.

With Service Desk, your customers can email you bug reports, feature requests, or general feedback. Service Desk provides a unique email address, so they don’t need their own GitLab accounts.

This is something I need to look further into for my next SaaS product, more on that later, subscribe for free to my publication not to miss out…

Conclusion

The Wireshark project is super active and well organised. My constructive feedback would be:

• Use Releases

• Hide the following sections as they are not used (if possible):

  • Iterations

  • Requirements

  • Environments

I hope you enjoyed my first review of a GitLab project, it was super fun and interesting for me to see how other projects manage their repo, but also how it compares to GitHub (which I have so far used much more).

The way in which GitLab have set up a repo is super interesting and something I am looking forward to delving into more in the coming months. If you are curious about GitLab let me know what areas you would like me to explore.

If you prefer to watch a video on this review here it is:

• Mathematical expressions

• Diagrams

• 3D models

• Maps

• Center align

• Comments

• Collapsable Content

• Subscript

• Superscript

Other Possibilities

In addition to your daily Markdown usage, there are other exciting features that GitHub Markdown can do.

In this section I will give you a brief overview of these.

Mathematical Expressions

When GitHub is rendering Mathematical Expressions in Markdown it uses MathJax . Inline single backtics are used with the $ for Mathematical Expressions.

Add $` at the start of the Mathematical Expression and close it with `$:

$`\sqrt{4x-1}+(1+x)^3`$

This will render the result:

Diagrams

GitHub Markdown, like the tool AsciiDoctor, support diagrams directly in Markdown. Why is this important? Diagrams are great, but there are some challenges:

• Everyone uses a different tool to create diagrams;

• Binary files in the git repo are terrible to be tracked by version control - one pixel change and the whole file is re-tracked (plus no one knows what the actually change is);

• It can be unclear who in the team might have the original file to edit the diagram.

This is where Mermaid comes in. It allows us to generate different types of diagrams with code and is very similar to Markdown. The benefit of this is that the diagram content is in the Markdown file in a code block with the type mermaid. Therefore anyone can change it and the changes can be diffed, then this is rendered just like the rest of the Markdown file.

Here is an example of a branching diagram:

NOTE: remember to add the code block with 3 backticks and the type Mermaid.

```mermaid

```

gitGraph:
    commit "Ashish"
    branch newbranch
    checkout newbranch
    commit id:"1111"
    commit tag:"test"
    checkout main
    commit type: HIGHLIGHT
    commit
    merge newbranch
    commit
    branch b2
    commit

Which will render to:

Here is another example for a Sequence Diagram:

sequenceDiagram
    Alice->>John: Hello John, how are you?
    John-->>Alice: Great!
    Alice-)John: See you later!

This will render to:

The Mermaid project keeps adding more diagram types all the time, here is what they currently support:

• Flowchart

• Sequence Diagram

• Class Diagram

• State Diagram

• Entity Relationship Diagram

• User Journey

• Gantt

• Pie Chart

• Quadrant Chart

• Requirement Diagram

• Gitgraph (Git) Diagram

• C4 Diagram

• Mindmaps

• Timeline

• Zenuml

• Sankey

• XYChart

• Block Diagram

Learn more on the official Mermaid documentation.

Read more

• Table

• Code

• Color

• Alerts

• Reference

• Footnotes

Table

Tabular data is a great way to lay out the information.

A Table in Markdown always has the title row followed by the alignment row, then your content can follow from the third row.

Here is how you can create a Table and in this example, it will have three columns but you can create as many as you require:

• The 1st column is using :--- which will make the whole column left aligned

• The 2nd column is using :---: which will make the whole column centred

• The 3rd column is using ---: which will make the whole column right aligned

| Column 1 | Column 2 | Column 3 |
| :--- | :---: | ---: |
| Row 1a | Row 1b | Row 1c |
| Row 2a | Row 2b | Row 2c |

The rendered Table will look like this:

Using the Styling covered previously, you can create emphasis in the Table with bold or italic:

| Column 1 | Column 2 | Column 3 |
| :--- | :---: | ---: |
| Row 1a | Row 1b | Row 1c *italic* |
| Row 2a | Row 2b **bold** | Row 2c |

Read more

• Introduction

• Example

• Headings

• Styling

• Link (internal, external)

• Image

• Lists (unordered, ordered, tasks)

• Horizontal rule

• Quote

Introduction

Markdown is used all over the Web; from GitHub to documentation to blogs.

It is an important skill to have as it allows you to communicate your message more clearly.

On GitHub alone, you will use Markdown for:

• README file

• Issue description

• Issue comments

• Pull Request description

• Pull Request comments

• Pull Request reviews

• Pull Request inline comments

• Release description

In this course you will learn how you can confidently use Markdown so that you can apply it to the above and more.

Before/After Example

Do you find your Issues, Comments, Pull Requests get ignored? It is highly likely that the DX (Developer Experience) for the user is not good as it could be making it difficult for them to digest.

Q. Which Issue would you rather read?

Without Markdown:

With Markdown:

This is how the above was created using Markdown only (no images were used). At first glance it might look a bit complicated to create, but by the end of the course, you will be able to create this yourself with confidence.

Leave a comment

## Authentication

> Product owner
> Users wish to use their existing authentication

Login with GitHub OAuth with NextAuth library.

```mermaid
sequenceDiagram
    Guest->>User: Login?
    User-->>Guest: Yes!
    Guest-)User: Authenticated
```

### Prerequisites 

These are the subtasks required:
- [x] install library
- [ ] look into https://github.com/eddiejaoude/eddiejaoude/issues/99
- [ ] setup OAuth app
...

We must also include the login hook:

```js
// create the new user a Stripe account
const user = getUser();
const stripe = createNewStripeUser(user);
```

### After

Use feature flags to hide login button until fully tested

> [!CAUTION]
> Do not run in production until after migration

Headings

Headings create the structure of our content. In Markdown a heading is started with a #. The number of # determines what type of Heading it is.

Here are the six Headings available in Markdown and how to achieve them:

# heading 1
## heading 2
### heading 3
#### heading 4
##### heading 5
###### heading 6

This is what the rendered output looks like:

Markdown content is converted to html for the browser to understand. In the above example the tags are converted from <h1> through to <h6>.

IMPORTANT: Remember to have a space between the # and your heading text.

Styling

When having paragraphs of text, we can add emphasis to help the reader digest the content. Examples of how we can make the text stand out are bold or italic.

This is how different Styling is created:

This is **bold** text

This is also __bold__ text

This is *italic* text

This is also _italic_ text

This is ~~strikethrough~~ text

We can mix the styles ***bold and italic*** with ~~***strikethrough***~~

This is what the rendered output will look like:

IMPORTANT: do not have a space between the styling and the text on either ends

These will both not work * italic text* or *italic text *

Read more

What are we going to build?

In this post I am going to show you how to do this and as an example, I will add badges (which can also be known as Shields) to the EddieHub project “The Open Source HealthCheck” https://github.com/EddieHubCommunity/HealthCheck

The feature will enable people to proudly show off that their Open Source project is friendly.

If you prefer, you can watch this tutorial - the video is at the end of this post.

What are we going to use?

• NextJS (app router)

• Badge Maker https://github.com/badges/shields

Pre-requisites

• Existing NextJS project

• Npm

Installation

1. Install the npm dependency.

npm install badge-maker

2. Import the dependency in your API file in NextJS.

// src/app/api/badges/report/[id]/route.js
import { makeBadge } from "badge-maker";

3. The default badge config will be used if no data exists for the GitHub repo yet in "The Open Source HealthCheck” project.

let config = {
  message: "No checks",
  label: "HealthCheck",
  style: "flat",
};

4. Get the checks from the database using the uid (we are using Prisma but you can use any tool you prefer to manage your data).

const check = await prisma.check.findUnique({
  where: { id },
});

5. Customise the badge color and message depending on “The Open Source HealthCheck” results.

config = {
  ...config,
  message:
    check.red > 0
      ? `Error (${check.red})`
      : check.amber > 0
      ? `Warning (${check.amber})`
      : `Success (${check.green})`,
  color: check.red > 0 ? "red" : check.amber > 0 ? "orange" : "green",
};

let svg = "";
try {
  svg = makeBadge(config);
} catch (e) {
  console.log(e);
  // TODO: return error badge
}

return new Response(svg, {
  headers: {
    "Content-Type": "image/svg+xml",
  },
});

Why the nested ternary on message and color? We check for the worst situation first, which is error (red), then work our way through warning (amber) to success (green). If any results exist along this journey, that is the color and message that will be shown.

Then we create the SVG badge with “makeBadge” and return the response body to have the SVG string as well as the content type of “image/svg+xml”.

The result

Using an example Repo, we get the following badge locally

import { makeBadge } from "badge-maker";

import prisma from "@/models/db";
import { worstCheck } from "@/utils/checks";

export const dynamic = "force-dynamic";

export async function GET(request, { params }) {
  const { id } = params;

  // get repo data
  const check = await prisma.check.findUnique({
    where: { id },
  });

  // default badge settings
  let config = {
    message: "No checks",
    label: "HealthCheck",
    style: "flat",
  };

  if (check) {
    // if check report found
    config = {
      ...config,
      message: worstCheck(
        check,
        `Error (${check.red})`,
        `Warning (${check.amber})`,
        `Success (${check.green})`
      ),
      color: worstCheck(check, "red", "orange", "green"),
    };
  } else {
    // if check report not found
    config = {
      ...config,
      message: "Not found",
      color: "lightgrey",
    };
  }

  let svg = "";
  try {
    svg = makeBadge(config);
  } catch (e) {
    console.log(e);
    // TODO: return error badge
  }

  return new Response(svg, {
    headers: {
      "Content-Type": "image/svg+xml",
    },
  });
}

Future tasks

Now that was not so scary! I know when I first created a badge it was challenging, even though there was not much code involved.

You may notice that this will be re-generated on every visit which is not efficient. This can be improved with caching. Especially as the data does not change often, therefore caching the data for a short period of time would make the app more efficient.

So why would we archive the project and give it all up?

This blog post is about BioDrop (formerly LinkFree). But it’s also about why sometimes, no matter how much you will something to succeed and you put your all into it, the “it” just doesn’t work.

Where it all began

If you watch Eddie’s YouTube channel, then you’ll know that Open Source is one of its biggest themes. The idea for BioDrop came from a livestream, where together with the EddieHub community, the objective was to create an Open Source alternative to the link sharing platform Linktree. If you are part of the amazing EddieHub community or you have seen it “in action”, then it probably won’t surprise you that the next day there were many Pull Requests for the project.

What followed were months of creating with the community what BioDrop was eventually going to become. Yes a platform where you could add your social links, but also a place where you could also connect with other users, check out and add what tech events you would be attending - an extension of the EddieHub community we would say. And the green square icing on the cake for the contributors? An opportunity to create your profile through a JSON file and a GitHub Repo where you could contribute and collaborate with others.

We saw such amazing uptake from the EddieHub community: we absolutely loved all the profiles which were being created and the fun the community was having playing with different tools and coming up with new features. Amazingly this was going beyond the EddieHub community. One day we woke up to several pages of new Pull Requests on our GitHub Repo of people wanting to set up their BioDrop Profile. Turns out our documentation on “How to create your BioDrop Profile with a JSON file” had been used as a case study and assignment for a lecture in a university in Asia!

Getting serious

After a year of approaching BioDrop entirely as a community project, we thought “What if there is scope to take this further?”

Whilst consulting and content creation are the bread and butter of our business, we had for a while been thinking how we would like to have a SaaS product which we turned into a lifestyle business. Could BioDrop be it?

To explore whether this was a possibility we thought it would be a good idea to apply for an accelerator program and the GitHub Accelerator seemed perfect: it focused on Open Source projects (✅ check) and guiding its owners and maintainers on making these sustainable (yes please).

We absorbed as much as we could during the ten week program. From that, as well as the chats we had with successful founders (we are so grateful for their time and advice) and consuming tonnes of content on the subject, we felt ready to turn BioDrop into a SaaS.

In addition to moving the project along and dealing with the community contributions - which were coming in thick and fast - we spent our time and personal financial resources on a rebranding exercise, logos, domains, social media accounts and most importantly for a SaaS - thinking about what type of paid product our users would find value from and what that price point would be.

Could this be “it”?

The intention for BioDrop was that there would:

1. always be a generous free tier and

2. a place where the community could contribute, develop their skills and collaborate.

Having spent thousands of hours over the years dedicated to the community, not only through EddieHub community projects, but through YouTube videos and livestreams as well as the EddieHub Discord, we did not see a reason why a part of the BioDrop project could not be turned into a SaaS. One thing was not going to change: we did not want to make money from the community, but in our view recognised that there could be some users who would see value in paying for a premium tier of BioDrop.

In hindsight we took way too long to get the premium tier out. Every example of a successful SaaS that we saw was telling us the same thing: “Get something out, it doesn’t have to be perfect.” But as that wasn’t really the decision why we archived the project, this is probably the subject for another blog. What we will say is, the speed at which we were able to work on the premium features and also the community’s response to it did have an impact.

We appreciate the there are countless projects where contributors are keen to contribute for free, when the project itself produces an entirely commercial product. But MongoDB and Elastic we were not. In retrospect we were perhaps a bit too over zealous on this front. We were so worried that we could be perceived as “exploiting” the community in some way by asking them to contribute towards what would be a premium feature. As a result premium features were labelled accordingly and Eddie took on 99% of the work required to get these features done - only asking our maintainers for help on this if he was absolutely stuck. Added to this the notifications on the community contributions were completely getting out of hand.

Turns out we didn’t need to worry about being perceived to ask the community to “work for free”. Any Issue or Pull Request with the label “Premium” might as well have read as “Radioactive”.

We would never be the ones to advocate for hustle culture, although we fully appreciate that hard work is necessary to achieve what you aim to do. But when you are completely burnt out from juggling the community and trying to run a business, and you are in perpetual survival mode - then it’s time to revaluate things.

And the noise kept getting louder

The effect of notifications for maintainers is a topic which is not talked about enough. Whilst we feel the aim of a community project is to encourage contributions and collaborations, what happens when you are dealing with notifications 24-7 and you are trying to build a SaaS at the same time?

During the GitHub Accelerator a cohort member had shared a blog by a maintainer who had decided to lock Issues until they were ready to be worked on. This was in no way gatekeeping, but had helped with managing notifications.

Have you ever come across an Issue where you scroll through the comments and all you see are contributors commenting “assign this to me” on repeat, over and over again? Often times the Issue had already been assigned. Or duplicate Issues were being raised and worked on causing conflicts for the maintainers to resolve. Plus there were the instances where Issues were raised that were just not in line with the project. This can be a little annoying right? Imagine this happening multiple times a day for months on end and as maintainers, feeling like resolving this is all you are doing (and in the meantime, those premium features you would like to work on are sidelined). So we made the decision to lock Issues until they were appropriately triaged. This was in a great part to save Eddie’s sanity and when explained to the community, taken on board. We were however not expecting this to be the catalyst for some of the project’s maintainers leaving.

A big part of what Eddie advocates is encouraging people to get into Open Source and particularly not being apprehensive about making their first contribution. It’s great when someone makes their first contribution as a result of this encouragement and maybe even on one of the livestreams! However in hindsight the BioDrop experience has changed our perception of pushing the “get your daily green square” approach.

Particularly in the last few years we are seeing a trend (if that’s the right word) of people making contributions for - in our opinion - the wrong reasons (such as swag or a green square only). This is not a criticism of competitions with prizes or that nice feeling of seeing a dark green grid on your GitHub Profile. But that should not be the only reason a contribution is made. Those types of contributions tend not to be thought out in terms of whether it will benefit the project and also how the community can collaborate.

Have multiple contributions made “for the sake of a green square” in the hundreds and you will have a maintainer who cannot cope. An example of this is the number of times the BioDrop footer moved - from left, to right, to the middle, then back to left then…you guessed it - back to the right again. Was there a reason for it? No.

Whilst some may consider this an unpopular opinion, we know that we are not alone in thinking this. Take a global event such as Hacktoberfest. They have modified their requirements and also their prizes to avoid these types contributions, and have as a result seen a downturn in participation.

Realising hard work isn’t everything

We realise that a product is not going to take off overnight and we are also not the type to make snap decisions. However, as months passed it was clear that BioDrop as a SaaS was not making a profit. When you consider the hosting costs of the web app and the database - we weren’t close to breaking even.

Maybe we got too caught up in the community’s support at the start? Maybe we had incorrectly interpreted our careful market research?

Plus it can be demoralising to run a community project which also has a SaaS element. It is free for the community to use but it is costing you money. Your premium tier does not have near enough paid subscribers to cover those costs. Then there are the mounting notifications a lot of which were - let’s face it, noise - making it hard for you to come up for air. If these elements were not enough, you wake up one morning and someone had decided to write a script to keep refreshing their BioDrop Profile page so they would appear in the “Most Popular Profiles” list, which effectively load tested the app and double our costs. And this was not an isolated incident.

This makes you think: “What am I doing here?”

After much deliberation (and probably way too much of that too…) we decided to archive the project as of June 2024. We considered turning this back into a 100% community project: we disabled the premium tier and gave all these features for all users - but ultimately we felt the project could not continue.

We want to emphasise that we had had the most amazing maintainers, but it is important to remember they have a day job too and interests in other projects. Plus the reality had set in: having spent 99% of our time on this project, taking on minimal client work to contribute (not cover) living costs and going through our savings - this was no longer sustainable. It may seem like an all or nothing attitude but we needed to move on from the project and also start making money to live.

So what are the lessons?

Ah hindsight.

We have thought whether, if BioDrop was generating an income, would we have sucked it up with the level of notifications? Probably yes for a while - but we recognise that in the long run this would not have been healthy.

There are certainly elements that we feel we spent too long thinking about; such as the name and branding. Additionally we took too much time to deliberate whether we should archive the project and move on. In the meantime costs were mounting and we felt we didn't have the necessary closure to move on to the next project.

Then there is what many who will probably feel this is the most “controversial” lesson of all. We have worked with many clients who want to build a community around their product, after the product has been created - and this is not always an easy task. We thought “Well we already have the community, so support will be there right?”

The truth is the mindset needed to run a community and to run a business such as a SaaS, is completely different. Running a community which is just that - a community - requires a level of realisation that whilst many of its members are there to collaborate, there will be several instances where the green square, swag and “I’m going to use this as a place to test the new technology I learnt” and “This will look great on my resume” mentalities will be prevalent. Some will say that those things are what a community should provide. But this is not financially sustainable for an individual to run on their own. And as a founder is that the place to run a business? Our conclusion, probably not.

Leave a comment

What if you could get near instant feedback before your commit? Yes, before - well- during the commit process, and the commit is prevented if the checks fail.

TIP: Local git hooks do not replace your CI checks, because the user can skip these local git hooks. The way I think about it is: git hooks are better Developer Experience (DX). They are similar to client-side validation, but client-side validation is no replacement for server-side validation because client-side validation can also be skipped.

TL;DR

If it is not automated, we will forget to run it. As you will see in this blog post, we have a lint command but we have been forgetting to run it. So when we install Husky and add the lint command to run on a pre-commit hook, we will be made aware we have some code issues to fix before we can complete the commit.

Install

I will be using npm, but they also have docs for pnpm, yarn and bun.

npm install --save-dev husky

The output will look something like this:

➜  healthcheck git:(main) npm install --save-dev husky

added 1 package, and audited 387 packages in 749ms

142 packages are looking for funding
  run `npm fund` for details

found 0 vulnerabilities

This will change the package and lock file. Doing a git status will show the files changed:

➜  healthcheck git:(main) ✗ git status -s
 M package-lock.json
 M package.json

Setup

You can do the setup manually, but I recommend using the “init” command to do this automatically for you:

npx husky init

This command will have no output but will create a “.husky” folder and update the “package.json” with a new command “prepare”.

We can check again with git status; it will contain the previous changes and the new:

➜  healthcheck git:(main) ✗ git status -s
 M package-lock.json
 M package.json
?? .husky/

But before we dive into the new folder “.husky”, let’s look at the “package.json” file. We can do this with a “git diff package.json”:

diff --git a/package.json b/package.json
index b1c59ba..e58f6a3 100644
--- a/package.json
+++ b/package.json
@@ -7,7 +7,8 @@
     "build": "next build",
     "start": "next start",
     "lint": "next lint",
-    "test": "npx playwright test"
+    "test": "npx playwright test",
+    "prepare": "husky"
   },
   "dependencies": {
     "@headlessui/react": "^2.1.2",
@@ -26,6 +27,7 @@
     "@types/node": "^20.14.10",
     "eslint": "^8",
     "eslint-config-next": "14.2.4",
+    "husky": "^9.0.11",
     "postcss": "^8",
     "tailwindcss": "^3.4.1"
   }
~

Here we see the new command “"prepare": "husky". Unlike the other “npm” we will not run this command ourselves, but will run as a hook on “npm install” - so you don’t need to worry about it. This command will run when the project is being installed locally and will setup the git hook(s).

The directory we are interested in is “.husky” and the file “pre-commit”. This will already contain a command which will run when we do a commit:

npm test

If this command fails, then the commit will not succeed. In this file “.husky/pre-commit” we can add additional commands to also run (for example, the linter) making the file look like this:

npm run lint
npm test

Now next time you run “git commit”, these commands will run as a pre git commit hook.

Let’s test it out, but first I always do a git status check:

➜  healthcheck git:(main) ✗ git status -s
 M package-lock.json
 M package.json
?? .husky/

➜  healthcheck git:(main) ✗ git add .husky/

➜  healthcheck git:(main) ✗ git status -s
A  .husky/pre-commit
 M package-lock.json
 M package.json

Now I am happy with that, let me do a commit:

➜  healthcheck git:(main) ✗ git commit -m "feat: setup husky" .husky/ package*

> healthcheck@0.6.0 lint
> next lint


./src/components/Header.js
113:21  Warning: Using `<img>` could result in slower LCP and higher bandwidth. Consider using `<Image />` from `next/image` to automatically optimize images. This may incur additional usage or cost from your provider. See: https://nextjs.org/docs/messages/no-img-element  @next/next/no-img-element
184:17  Warning: Using `<img>` could result in slower LCP and higher bandwidth. Consider using `<Image />` from `next/image` to automatically optimize images. This may incur additional usage or cost from your provider. See: https://nextjs.org/docs/messages/no-img-element  @next/next/no-img-element

./src/components/Heading.js
13:15  Error: Missing "key" prop for element in iterator  react/jsx-key
27:13  Error: Missing "key" prop for element in iterator  react/jsx-key

info  - Need to disable some ESLint rules? Learn more here: https://nextjs.org/docs/basic-features/eslint#disabling-rules
husky - pre-commit script failed (code 1)

Straight away we can see there are some errors, not with Husky or the setup of Husky but with my project! We have a linter setup in our project, but it is not running locally or on CI. So now we have tried to commit, it has highlighted problems with our project’s code. Hopefully, you can see the benefit of automating everything!

TIP: if you want to skip these git pre-commit hook checks, you can with the flag “-n” but please use this with extreme caution. You don’t want to jump ahead and think all is working fine, only to encounter a bigger problem later on.

Once I have fixed these lint issues with my project, I can try to commit again. This time if the lint command is successful then it will move on to the test command because that is the order we have in our Husky pre-commit config file.

This looks better, both git pre-hook commands run successfully and the commit is made:

➜  healthcheck git:(main) ✗ git commit -m "feat: setup husky" .husky/ package*

> healthcheck@0.6.0 lint
> next lint

✔ No ESLint warnings or errors

> healthcheck@0.6.0 test
> npx playwright test


Running 12 tests using 4 workers
  12 passed (11.5s)

To open last HTML report run:

  npx playwright show-report

[main f447eec] feat: setup husky
 3 files changed, 21 insertions(+), 1 deletion(-)
 create mode 100644 .husky/pre-commit

Now you can confidently push your code to the remote repo. The CI checks should also pass: these are still needed as they are independent and will do a fresh setup of the project and re-run these checks.