Jonathan Yeong

npmx and the open source mindset

Tue, 03 Mar 2026 22:17:05 GMT

The beauty of open source is that no one is forced to be there. This is what hit me when I first started contributing to npmx. I joined the project after seeing a call to action from patak. I don't particularly know why I joined. I think my fomo got the better of me.

When I entered the Discord, I felt a bit lost. I'm a Ruby, Go, backend developer. What could I contribute to a Nuxt project? And one that builds on top of npm, a package registry I browse only on occasion. Where do I even begin?

So I did what I usually do. I combed through "good first issues" looking for unassigned tickets. But looking around, nobody was asking permission to pick up an issue. Nobody was concerned about multiple people working on the same thing.

Seeing how the community acted empowered me to do the same. I picked up a bug, dug into the code, and pushed a PR. Immediately people jumped in and started commenting. One person was working on something similar. Another had a suggested change to the PR. All of the discussion made my PR better. And every interaction felt like they cared.

This PR along with the Discord interactions blew my corporate mind. In a corporate environment, I would've asked whether this ticket was estimated, or prioritized. I would've asked about aligning the approach before making the PR. I definitely felt like I missed a step having multiple people commenting on the approach of the PR. But this is open source. People do these things because they care.

That's the open source mindset. You decide what to work on. You decide when. Nobody is keeping score, nobody is checking in, nobody is assigning you work. The only thing driving you is wanting to make the project better.

It's a mindset I could only adopt by being a part of this community. Matias (aka patak), Daniel Roe, Salma, and many others created a place of belonging. They showed up every day, in every channel offering suggestions and encouragement. And they put this culture into writing in a Governance doc:

Anyone can become an npmx contributor. Engineering ability is not required

The community is the secret sauce. Something that AI can never replace. The fact that places of belonging and action outside of corporations exist makes me optimistic about the future of open source. I'm incredibly grateful to have been a part of this journey. There's much more to come, since npmx is now in alpha. If you've been wanting to contribute to open source and are looking for a welcoming community, come join us.

Thanks for subscribing to my RSS feed! If you have any thoughts or feedback on this post, send me an email or DM me on Bluesky.

Using Val.town as a webhook middleware

Tue, 13 Jan 2026 22:06:19 GMT

Productive procrastination is one of my favourite pastimes. My latest obsession has been webhook events from Ghost CMS to Netlify. I had event listeners in Ghost that triggered builds whenever the site changed. When this event occurred, and it occurred often, it would trigger a Netlify build by POSTing to a Netlify build hook.

I wanted to optimise these webhook events to run fewer builds on Netlify. This meant using fewer build minutes, which may translate to less money spent. Much productive. You might ask, "how many build minutes are you using?". Well my friend, I'm not even close to the free build minute quota. Nevertheless, we press on.

The first thing I did was listen to different events that fired less often. Instead of site changes, I now listen to post published, updated, and unpublished events. This sends a payload that looks something like this to Netlify:

"post": {
    "current": {
      "id": "695d72563020fd0001cb96d6",
      "uuid": "41af1fc2-40e9-43e8-aa47-fbe4de2fd276",
      "title": "Test Newsletter post",
      "slug": "test-newsletter-post",
      "html": "<h1>Some HTML</h1>",
      "tags": [
        {
          ...some fields
        }
      ],

// ...Many other fields

Unfortunately, if the blog post is long it will cause a Netlify build error. I don't see it documented, but I think there's a 140kb limit on payloads sent to Netlify build hooks. I needed a way to process this payload before sending it to Netlify. Enter Val.town.

In Val.town, you create building blocks called Vals that are used to run little http apps, crons, or email handlers all with Javascript/Typescript. I first heard of Val.town from Sam Rose who uses it to power the ping functionality on his website (see his notify Val). I can use a Val as an intermediate service that will do some processing on a webhook payload before sending it off to Netlify.

Here's the code in its entirety. Let's break it down.

export default async function (req: Request): Promise<Response> {
  if (req.method !== "POST") {
    return new Response("Method Not Allowed", { status: 405 });
  }

  try {
    const payload = await req.json();
    console.log("Ghost CMS Webhook Payload:", JSON.stringify(payload, null, 2));

    const post = payload.post?.current;

    // Don't continue if the post has hash-newsletter
    const hasNewsletterTag = post?.tags?.some((tag: any) =>
      tag.slug === "hash-newsletter"
    );

    if (hasNewsletterTag) {
      console.log("Post is meant to be a newsletter, skipping");
      return new Response("Post has hash-newsletter tag", { status: 200 });
    }

    const response = await fetch(
      "<netlify-build-hook-url>",
      {
        method: "POST",
        headers: {
          "Content-Type": "application/json",
        },
        body: JSON.stringify({}),
      },
    );

    if (!response.ok) {
      return new Response("Failed to trigger Netlify build", {
        status: response.status,
      });
    }
  } catch (error) {
    return new Response("Something went wrong", { status: 500 });
  }

  return new Response("OK", { status: 200 });
}

Breaking down webhook Val

First off, I created a Val with a HTTP trigger. This gives me a URL that I can use to trigger the Val from Ghost. It looks like:

https://jonoyeong--50a8ba8ef0c611f0a43942dde27851f2.web.val.run

Next up is the guard clause. When you open a Val it will immediately run a GET request to the above URL. This results in an error since the request is not in the format we expect. The guard clause below returns a nicer response and is easier to parse in the logs.

if (req.method !== "POST") {
  return new Response("Method Not Allowed", { status: 405 });
}

Then we need to process the Ghost payload. We parse the payload data and grab the current post object.

const payload = await req.json();
const post = payload.post?.current

Remember, the payload from Ghost is structured below.

"post": {
    "current": {
      "id": "695d72563020fd0001cb96d6",
      "uuid": "41af1fc2-40e9-43e8-aa47-fbe4de2fd276",
      "title": "Test Newsletter post",
      "slug": "test-newsletter-post",
      "html": "<h1>Some HTML</h1>",
      "tags": [
        {
          ...some fields
        }
      ],

// ...Many other fields

Now you might wonder why we even need that data. Well we can do some more pre-processing here. I want Ghost to be the source of my blog and newsletter content. Anything that's tagged with #newsletter shouldn't be pulled into my blog. The code below will check if any posts have a #newsletter tag, represented as hash-newsletter in the payload. And if it does, it will skip triggering a Netlify build.

// Don't continue if the post has hash-newsletter
const hasNewsletterTag = post?.tags?.some((tag: any) =>
  tag.slug === "hash-newsletter"
);

if (hasNewsletterTag) {
  console.log("Post is meant to be a newsletter, skipping");
  return new Response("Post has hash-newsletter tag", { status: 200 });
}

Finally, we call the Netlify build hook.

const response = await fetch(
  "<netlify-build-hook-url>",
  {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
    },
    body: JSON.stringify({}),
  },
);

if (!response.ok) {
  return new Response("Failed to trigger Netlify build", {
    status: response.status,
  });
}

I POST to Netlify, with an empty body to avoid any payload size errors. And in case something errors, I return a Response with a message and status that will show up in my Val logs.

I found Val.town pretty nifty for deploying small services that manipulate data from 3rd party services you don't have full control over. There's other ways we can achieve build filtering as well. Melanie Richards documented a couple of other methods. Funnily enough, I found out recently that Astro is releasing a live content collection feature. Live content collections will fetch content on-demand, which might make all of the work above obsolete. I'm not mad though. It just means I'll have another reason to productively procrastinate in the future.

Thanks for subscribing to my RSS feed! If you have any thoughts or feedback on this post, send me an email or DM me on Bluesky.

Year in Review: 2025

Wed, 31 Dec 2025 19:44:14 GMT

This was a year of peaks and valleys.

I started strong with a website redesign and a blog post recapping the work. It became my most viewed blog post of the year! I put a lot of effort into it, and I’m chuffed with how well it was received. Following the redesign, I started a newsletter which evolved from writing about the whims of my day to something focused on coding, writing, and design.

Then summer rolled around and I took an unplanned hiatus from being productive. It's the same old story, life and work got in the way. The very same inertia I felt pulling me up the peak, was now keeping me at rest. I stopped sending out newsletters. Stopped working on side projects. And blog posts sat in my drafts folder collecting digital dust.

Thankfully, I ended the year strong by publishing said posts. I'm particularly proud of my post comparing different mobile friendly CMSs. I pushed myself to connect and contribute to digital communities again. Posting on Bluesky and joining the Overcommitted Discord. I read the hundreds of unread articles in my RSS reader, and got back to tinkering with side projects. Essentially, the last bit of the year was focused on building the inertia to create again.

I'm annoyed that I wasn't more consistent in 2025. But I did learn something about myself.

Even if I stop, I'm still able to come back.

I've always wondered why I work on side projects or write. Am I doing it for myself? Or because it's what others tell me I should do? But now I know I do it because I really enjoy it. Even if I take a long break, it'll always be there when I'm ready. And there's something quite forgiving about this thought.

This year in lists

Stuff I wrote

I'm very happy with the four blog posts I published. Even if it's less than last year.

I sent 15 newsletters. My fav was about developing my writing style. Surprisingly I actually achieved my newsletter goal which was to send 12 newsletters.

Fav podcasts

I listened to 9,187 minutes of podcasts this year. And these were my fav podcasts ranked by listen time!

Overcommitted

Fun podcast, with interesting topics and guests. I totally resonate with the developer that's overcommitted as well!

Syntax

My go to podcast to keep up to date with web development.

Growth in reverse

A podcast about newsletter growth strategies. Even though I haven't sent a newsletter in a long time, it's interesting hearing about how newsletters operate behind the scenes.

Fork around and find out

Great tech guests and the main infra focused podcast I listen to.

ShopTalk Show

I came to learn about web dev. But I stayed for the top notch banter.

Fav games

Valheim

It's a nordic open world survival game with deep building and combat mechanics. You play as a viking reborn in Valhalla, either solo or co-op. It's very fun and very addicting with friends. I felt like a viking, travelling the vast ocean to explore new lands.

Hades 2

A rogue like dungeon crawler with beautiful graphics, sound design, and an addictive gameplay loop. The dialog with Gods of Olympus alone is what makes me want to start another run.

Thronefall

A cute tower defense game. I got it recently because I wanted something that was more chill than Valheim and Hades 2. It's perfect if you only have 30 minutes and you want something strategic but low stakes.

Future plans

Next year, I just want to be able to answer this question:

What have you been up to since I've seen you last?

I don't know why, but when someone asks me this question, my mind goes into a panic. What have I been doing? Why can't I remember? Is living an answer?

I'll be theming my year around intentionality. And by doing so I'm hoping to be more aware and present in what I do. To be more intentional with my time and to remember what the hell I've been doing.

I'm grateful for all the connections I've made in 2025. It's been an up and down year and I appreciate all of you who have stayed in touch even after I dropped off the grid for half the year. Sending you all good vibes for 2026.

Thanks for subscribing to my RSS feed! If you have any thoughts or feedback on this post, send me an email or DM me on Bluesky.

Lessons I learnt from my first year of building a DevEx Team

Wed, 03 Dec 2025 23:58:21 GMT

I've been running a DevEx team all of 2025, and I really wished I had some sort of guidebook when I started. And then last week, Nicole Forsgren and Abi Noda published Frictionless. A handbook for starting a DevEx team. Where were you at the start of the year?! At least I can compare notes. Here's my attempt at trying to process everything I learnt about DevEx this year.

The need for DevEx is super clear

Starting the year I knew DevEx was important. I don't think I realised how important. When I started the team, our goal was to reduce developer friction in their day to day workflow. The theory was reducing friction equals happy devs. And happy devs are less burnt out, more satisfied in their role, innovate faster and deliver more.

Now that my company, and seemingly every tech company, has adopted AI the need for good DevEx is even greater. With AI tooling, devs are able to create faster than ever. But this results in problems elsewhere. Sure you can push multiple PRs, but do you have people to review them? Do you have confidence that your changes aren't going to break production? How fast can you even deploy the multiple PRs you're pushing? It's clear that writing code was never the bottleneck in the first place.

My takeaway from the year is that I'm doubling down on the need for DevEx. By improving DevEx we improve so many other parts of the company. As hard as it is to quantify. Forsgren and Noda say it best:

Poor DevEx creates a competitive disadvantage that compounds over time.

Defining what DevEx owns is hard

Even after a year I'm not sure I have a good answer to this question. Reducing friction for a developer could come in many forms. From low level infrastructure changes, like setting up a staging environment. To high level component library to help devs build UI's faster. Where does a DevEx team sit in this range?

The best answer I've come up with is that DevEx should be an organisation. It should have multiple teams specific to certain developer workflows e.g. CI, Monorepo tooling, Language upgrades or tooling, and best practices & learning. It should also build on top of infrastructure tooling created by Platform Engineering teams.

Frictionless also touches on the relationship between platform engineering teams and DevEx. Platform engineering builds the infra, shared tooling, and services that enforce best practice and abstract away complexity. While DevEx teams take a broader view of friction across the entire developer lifecycle. A DevEx team may address problems that no platform solution can solve.

In my experience, I find this boundary not as clear cut. Especially as a growing company, platform or DevEx teams may not have the capacity to take on particular projects. And some projects that should’ve been on one team get started on a different one. This is where the lines get blurred. We do our best, is my current answer around ownership.

DevEx should operate like a product team

Devs are our customers. As an internal team, it feels strange to force product thinking. But I've found that having a strong product roadmap and vision for DevEx gives us more guidance and flexibility into the solutions we build. Instead of fighting fires across multiple dev teams we can think about solutions that work long term. We fix what the dev is really asking us to fix.

Also a note from an Overcommitted podcast episode with Kate Holterhoff. There is a wide range of “developers”. Or more specifically, people that use DevEx solutions. From feature teams, to quality engineering aka quality assurance teams, to even non-technical folks like designers or PMs. Treating DevEx like a product gives us space to think about different personas.

It also means, we need to stay close to our customers. For our team, we focused on talking to devs, observing them use the DevEx tooling, and surveys to gather feedback. I have noticed that if there’s some friction a dev will most likely try to solve it by themselves and move on. So it can be hard to know that something is actually wrong until you go talk to them.

Finally, it should go without saying, but a DevEx team should never adopt an us-versus-them mindset.

Staffing DevEx is an interesting challenge

I started this year thinking that DevEx team should consist of full stack developers. Boy was I wrong. My assumption was that our devs are full stack so we should have a team of full stack devs to support them. But it turns out there's so many parts to DevEx, that we need specialists. And that can be hard to hire for.

Something our team has started doing is offering rotations from feature developers. We work together to come up with a project that they're interested in, and something they can finish during the rotation. The idea is that they're getting to fix a pain point in their workflow, while also being able to affect change across the engineering organisation. And the DevEx team gets to tackle a feature that devs are asking for and can maintain this feature in the long term. Win Win!

There's a lot I'm still figuring out. Like, how much abstraction is too much abstraction? Or what are the right metrics to gather? Or what is the process of telling devs about DevEx changes (Slack sucks for announcements)? Still, it's been a fun year on the DevEx team. Lots of highs and lows and lessons along the way. If I could take one thing away from this experience, it's that I love working with devs. These are my people.

Thanks for subscribing to my RSS feed! If you have any thoughts or feedback on this post, send me an email or DM me on Bluesky.

Loading Ghost CMS posts with Astro Content Collections

Wed, 26 Nov 2025 13:31:07 GMT

I recently made the switch to using Ghost as a headless CMS and I needed to load posts into my Astro site. Along with the Ghost posts, I also wanted to continue loading my existing markdown files. One, because I was too lazy to migrate. And two, because I think it’ll be cool to create more interactive mdx posts in the future.

Thankfully, using Astro's Content Layer API and content collections it was straightforward to load content from various sources. And in this blog post, I'll share how I used content collections to load both Ghost posts and markdown files.

What is a Content Collection

Content collections are a way Astro manages sets of content. And the Content Layer API defines an interface to interact with said content. This lets us plug in multiple sources of content, like a usb stick, for us to interact with.

For example, I'm using the in-built glob loader that Astro provides to load up my markdown files. I can also define a zod schema for typechecking. In src/content.config.ts:

import { defineCollection, z } from 'astro:content';
import { glob } from 'astro/loaders';

const blog = defineCollection({
  loader: glob({ pattern: "*.md", base: "src/content/blog" }),
  schema: z.object({
		title: z.string(),
		description: z.string(),
		// Transform string to Date object
		pubDate: z
			.string()
			.or(z.date())
			.transform((val) => new Date(val)),
		updatedDate: z
			.string()
			.or(z.date())
			.optional()
			.transform((str) => (str ? new Date(str) : undefined)),
		heroImage: z.string().optional(),
		draft: z.boolean().default(false),
		featured: z.boolean(),
		topics: z
			.array(z.string())
			.optional()
			.default([]),
		bskyPostId: z.string().optional()
	}),
});

export const collections = { blog };

I can then fetch content from this collection via the Content Layer API. In my src/pages/writing/[slug].astro file:

---
import { getCollection, render } from 'astro:content';

export async function getStaticPaths() {
    const posts = await getCollection('blog');
	return posts.map((post) => ({
		params: { slug: post.id },
		props: { post },
	}));
}

const { post } = Astro.props;
const { Content } = await render(post);

---

<h1>{post.data.title}</h1>
<Content />

With these two files I'm able to generate static paths based on the files loaded by the glob loader and render their content. This snippet is copied from an Astro guide with some minor tweaks.

To get this working with Ghost, I need add a few more files.

Loading Ghost Posts

Before I dive into my custom Ghost loader, I want to give a shoutout to MatthiesenXYZ for creating the ghostcms-loader. This loader uses ts-ghost under the hood, and contains far more functionality than I introduced in my custom loader. The downside of this package is that it's pinned to Ghost v5 API, and for my usecase it seemed like it was overkill. For example, I only want to load posts right now and not other parts of Ghost.

Secondly, the Ghost + Astro setup guide is very good and I had most things setup except the custom loader after walking through the guide. I'll be building off the foundation that the guide set.

Creating the Ghost loader

Instead of src/lib/ghost.ts from the Ghost + Astro setup guide. I created two files, one named src/lib/api/ghost.ts and the other src/lib/loaders/ghostPosts.ts

The api/ghost.ts file setup a client using the Ghost content api and the file content is similar to the guide except it specifies the v6 API version and points to my production site. I also followed the guide to setup the CONTENT_API_KEY

import GhostContentAPI from '@tryghost/content-api';

export const ghostClient = new GhostContentAPI({
    url: 'https://<YOUR-GHOST-SITE>.ghost.io',
    key: import.meta.env.CONTENT_API_KEY,
    version: 'v6.0',
});

Next up, I created the custom loader that calls ghostClient. In src/lib/loaders/ghostPosts.ts

import type { Loader, LoaderContext } from 'astro/loaders';
import { ghostClient } from '@lib/api/ghost';


function extractBskyPostId(codeInjection: string): string | undefined {
  const match = codeInjection.match(/<!--\s*METADATA:\s*bskyPostId=([a-zA-Z0-9]+)\s*-->/);
  return match?.[1];
}

export function ghostPostLoader(): Loader {
  return {
    name: 'ghostcms-posts',

    load: async ({ store, logger, parseData }: LoaderContext) => {
      try {
        let page = 1;
        let hasMore = true;
        const allPosts = [];

        logger.info('Starting to fetch Ghost posts...');

        while (hasMore) {
          const posts = await ghostClient.posts.browse({
            limit: 100,
            page: page,
            include: ['tags']
          });

          allPosts.push(...posts);

          const nextPage = posts.meta.pagination.next;
          hasMore = nextPage !== null;
          if (nextPage !== null) {
            page = nextPage;
          }

          logger.info(`Fetched page ${posts.meta.pagination.page} of ${posts.meta.pagination.pages}`);
        }

        logger.info(`Loaded ${allPosts.length} posts from Ghost`);


        for (const post of allPosts) {
          const id = post.slug
          const bskyPostId = extractBskyPostId(post.codeinjection_foot || '');
          // Transformation done here to match the schema of our md blog collection.
          const rawData = {
            title: post.title,
            description: post.custom_excerpt || post.excerpt || '',
            pubDate: post.published_at ?  new Date(post.published_at): undefined,
            updatedDate: post.updated_at ? new Date(post.updated_at) : undefined,
            heroImage: post.feature_image || undefined,
            draft: false, // Ghost posts are published by default
            featured: post.featured || false,
            topics: post.tags?.map(tag => tag.name) || [],
            readingTime: post.reading_time,
            bskyPostId,
          };

          const parsedData = await parseData({
            id,
            data: rawData,
          });

          store.set({
            id,
            data: parsedData,
            rendered: {
              html: post.html || '',
            },
          });
        }

        logger.info('Ghost posts loaded successfully');
      } catch (error) {
        logger.error(`Ghost loader error: ${error instanceof Error ? error.message : 'Unknown error'}`);
        throw error;
      }
    },
  };
}

Now that’s a lot of code, so let's break it down.

Satisfying the Loader Interface

Firstly, every Loader has an interface we must meet. It must return a name of the loader, and a load function. Optionally, it can return a schema as well. But for my case, I'll be defining the schema in content.config.ts

Here’s all we need to satisfy the Loader interface:

export function ghostPostLoader(): Loader {
  return {
    name: 'ghostcms-posts',
    load: async ({ store, logger, parseData }: LoaderContext) => {...},
  }
}

The load method takes a LoaderContext which contains various props but the ones I use are store, logger, and parseData.

store is used to store the actual data (which we'll go over below).
logger is logs messages to the console. But the logs also contain the loader name for easier debugging.
parseData validates the data according to the collection schema, which I defined outside the loader in content.config.ts (more on that below).

Calling Ghost client to load posts

Within the load method, I call ghostClient to load the posts:

try {
  let page = 1;
  let hasMore = true;
  const allPosts = [];

  logger.info('Starting to fetch Ghost posts...');

  while (hasMore) {
    const posts = await ghostClient.posts.browse({
      limit: 100,
      page: page,
      include: ['tags']
    });

    allPosts.push(...posts);

    const nextPage = posts.meta.pagination.next;
    hasMore = nextPage !== null;
    if (nextPage !== null) {
      page = nextPage;
    }

    logger.info(`Fetched page ${posts.meta.pagination.page} of ${posts.meta.pagination.pages}`);
  } catch (error) {
    logger.error(`Ghost loader error: ${error instanceof Error ? error.message : 'Unknown error'}`);
    throw error;
  }

In Ghost API v6, they removed limit: all meaning we are forced to paginate over posts. Also, ghostClient.posts fetches posts from the Ghost Content API which will only ever return published posts. Making it impossible to preview draft posts locally. When setting Ghost up, I published a couple of posts so I could see them pulled locally. It's annoying but not the end of the world.

I also include: ['tags'] that I convert into topics which are my blogs representation of tags. For example,

topics: post.tags?.map(tag => tag.name) || [],

Transforming the output

This final step is optional. But in my workflow, I wanted to transform the output of the API call to match what my markdown file frontmatter would return. This meant I could re-use the schema declaration in content.config.ts between my markdown files and ghost posts.

for (const post of allPosts) {
  const id = post.slug
  const bskyPostId = extractBskyPostId(post.codeinjection_foot || '');
  // Transformation done here to match the schema of our md blog collection.
  const rawData = {
    title: post.title,
    description: post.custom_excerpt || post.excerpt || '',
    pubDate: post.published_at ?  new Date(post.published_at): undefined,
    updatedDate: post.updated_at ? new Date(post.updated_at) : undefined,
    heroImage: post.feature_image || undefined,
    draft: false, // Ghost posts are published by default
    featured: post.featured || false,
    topics: post.tags?.map(tag => tag.name) || [],
    readingTime: post.reading_time,
    bskyPostId,
  };

  const parsedData = await parseData({
    id,
    data: rawData,
  });

  store.set({
    id,
    data: parsedData,
    rendered: {
      html: post.html || '',
    },
  });
}

One thing to note is, const id = post.slug. Ghost slugs are unique so it's okay setting this as ID. It also matches what glob loader does, where id is the slug-ified markdown filename.

After transforming the data we save it to the data store:

store.set({
  id,
  data: parsedData,
  rendered: {
    html: post.html || '',
  }
});

The store is a key value store scoped to the collection. Meaning the id must be unique otherwise you'll be returning duplicate entries when you fetch the content collection. That's why it's important that the Ghost slugs are unique.

It sets the id of the post (aka the slug) to the parsedData which matches what is defined in the content schema. It also accepts a rendered prop which is set to the post.html. This will make the render() function available on the post in our Astro pages like this: const { Content } = await render(post);

Bluesky post ID

You might have noticed this reference to bskyPostId. This is how I tie a bluesky post to my blog post. And it's how I load the comments/interactions below! To do so I insert a code injection to the post footer that looks like this:

<!-- METADATA: bskyPostId=3m6g6tkputk2j -->

This will then be extracted and parsed by this extractBskyPostId function. Which takes post.codeinjection_foot which is a field found on the post object from Ghost.

function extractBskyPostId(codeInjection: string): string | undefined {
  const match = codeInjection.match(/<!--\s*METADATA:\s*bskyPostId=([a-zA-Z0-9]+)\s*-->/);
  return match?.[1];
}

...

const bskyPostId = extractBskyPostId(post.codeinjection_foot || '');

At the end, I pass this bskyPostId to the rawData and that field can be used throughout my site. One of the downsides of working with Ghost is the inability to define custom metadata. This is a quick workaround to that problem and something that Astro content collections makes simple.

Content config changes

Now that I've setup the Ghost Post loader. I can modify my content.config.ts to export the new collection, reusing the postSchema across both the existing markdown posts and the new Ghost posts.

import { defineCollection, z } from 'astro:content';
import { glob } from 'astro/loaders';
import { ghostPostLoader } from '@lib/loaders/ghostPosts';

const postSchema =
	z.object({
		title: z.string(),
		description: z.string(),
		// Transform string to Date object
		pubDate: z
			.string()
			.or(z.date())
			.transform((val) => new Date(val)),
		updatedDate: z
			.string()
			.or(z.date())
			.optional()
			.transform((str) => (str ? new Date(str) : undefined)),
		heroImage: z.string().optional(),
		draft: z.boolean().default(false),
		featured: z.boolean(),
		topics: z
			.array(z.string())
			.optional()
			.default([]),
		bskyPostId: z.string().optional(),
		readingTime: z.number().optional()
	})

const blog = defineCollection({
  loader: glob({ pattern: "*.md", base: "src/content/blog" }),
	schema: postSchema
});

const ghostCmsPosts = defineCollection({
  loader: ghostPostLoader(),
	schema: postSchema
});


export const collections = { blog, ghostCmsPosts };

Fetching posts side by side

Finally, how do I actually fetch the posts? I created a utility src/utilities/getAllPosts.ts to load the two content collections side by side.

import { getCollection } from 'astro:content';
import type { CollectionEntry } from 'astro:content';

export type BlogPost = CollectionEntry<'blog'> | CollectionEntry<'ghostCmsPosts'>;

export default async function getAllPosts(): Promise<BlogPost[]> {
  const blogPosts = await getCollection('blog');
  const ghostPosts = await getCollection('ghostCmsPosts');

  const allPosts = [...blogPosts, ...ghostPosts];

  return allPosts.sort((a, b) => {
    const dateA = a.data.pubDate?.getTime() ?? 0;
    const dateB = b.data.pubDate?.getTime() ?? 0;
    return dateB - dateA;
  });
}

And now I can use this utility to fetch all of my posts! Here's the updated src/pages/writing/[slug].astro

---
import { render } from 'astro:content';
import getAllPosts from '@utilities/getAllPosts';
export async function getStaticPaths() {
	const posts = await getAllPosts();

	return posts.map((post) => ({
		params: { slug: post.id },
		props: { post },
	}));
}

const { post } = Astro.props;
const { Content } = await render(post);

---

<h1>{post.data.title}</h1>
<Content />

You made it!

Thanks for making it this far! I hope this tutorial helps you create a custom loader. And more specifically how to set up a Ghost loader. Feel free to check out my PR for the changes in context. And if you have any feedback please let me know!

Thanks for subscribing to my RSS feed! If you have any thoughts or feedback on this post, send me an email or DM me on Bluesky.

Mobile-Friendly Headless CMS's with Astro

Sun, 23 Nov 2025 14:00:00 GMT

A while back, I set up Obsidian for my blog post workflow. There are many great things about it; the editor is minimal and distraction free. My notes and blog posts all lived in one app. And I felt like a hacker setting up GitHub actions, symlinks, and custom plugins to automate git pushes.

But there was one thing I felt missing. A mobile publishing experience. I've been using Day One lately to journal and I've loved writing a quick entry while waiting at the coffee shop. Or while sitting on a bench in the park with my pup. I wanted to bring that to my blog post workflow. Anything to reduce the friction of hitting "publish".

To achieve this, I wanted to use a Headless CMS. I tested four: Sanity, Ghost, TinaCMS, and PagesCMS. I chose based on some loose criteria:

Popular (reddit threads, discussed in blog posts, bluesky mentions)
Open source
Either File-based (TinaCMS, PagesCMS) or DB-based (Sanity, Ghost)

In the end, I decided to go with Ghost. Here's why I chose it over the others.

Why Ghost?

Mobile editing is the dealbreaker

While I still do most of my writing on desktop, I wanted a great mobile friendly user experience for publishing. And I liked Ghost's experience the most out of the CMSs. It has a clean canvas when you load up a new post. It's a distraction free writing experience that lets you focus on the content not the structure of your blog post.

Ghost mobile views (left is editing a post, middle is post settings, right is the Posts view)

In comparison, the other CMSs editors felt clunky.

From left to right; Sanity CMS, Pages CMS, Tina CMS mobile editing experience

At the time of writing, Sanity is experimenting with a Canvas similar to Ghost's editing experience. But to translate the Canvas content you need to use an experimental Content Mapping feature.

Straightforward Ghost CMS setup

Setting up Ghost was straightforward. I followed the Astro + Ghost setup guide with a Ghost trial account and got something working in under an hour. In comparison setting up Sanity felt much longer. And honestly, Sanity felt like overkill for a solo developer blog. Both TinaCMS and PagesCMS were straightforward to setup too. In many ways they matched my workflow better with existing blog posts in markdown files. But when it came to images I needed more work to get them behind a CDN (through cloudinary or aws for example).

Newsletter capabilities ✨

What pushed me over the edge was Ghost's newsletter capabilities. I could have my blog post content and my newsletter being managed by a single platform. I'm currently using Beehiiv to send newsletters. And while I haven't written a newsletter in a while, consolidating content to one platform is very enticing!

Why not Ghost?

There are two reasons why Ghost might not be the right fit for you: cost and CMS limitations.

Ghost Pro is Expensive

Ghost Pro is the hosted version. To use it as a headless CMS, you need to subscribe to the Publisher plan. This plan is $29 USD a month 😱 which is very expensive. Especially, if all you want is to author blog post content. Ghost does offer a self hosted alternative that will bring the cost down. But that brings additional setup and long term maintenance.

CMS limitations

Ghost in comparison to the other three CMSs was more limited in what you could do. For example, with the other three CMSs you could define whatever schema you wanted for your blog post. And with Sanity and TinaCMS you could also enable live preview editing. Not so with Ghost. But I'm okay with Ghost's constraints. It makes setup simpler.

To CMS or not to CMS

That is the question. At the end of the day, I think we can all agree that as a solo dev posting a handful of posts a year I don't need a CMS. You can get far with markdown files.

What about my old Obsidian setup? It's still there. I'm honestly too lazy to migrate those markdown files to Ghost. And at some point might want to author an mdx post that is more customizable than Ghost. Thankfully, with Astro content collections it's easy to load both markdown files and your CMS content. So my advice: give both approaches a try and see what works best.

Thanks for subscribing to my RSS feed! If you have any thoughts or feedback on this post, send me an email or DM me on Bluesky.

Redesigning my site: version 3

Fri, 18 Apr 2025 00:00:00 GMT

After a months-long redesign with some stops and starts, I’m psyched to finally share my new site with you!

I’m a sucker for behind the scenes posts. I love reading them. I love writing them. I was particularly inspired by the Redesigning Piccalilli series. So I thought it would be interesting to go over my goals for the design, the design process, and key moments in the build.

Goals for the design

Before jumping into Figma, I wrote down some goals for the redesign.

The main purpose of this site is a blog. Posts should be easy to read and discover, with a touch of personal curation (recommended or featured posts).
I want a site that’s personal and friendly yet clean and minimal - but not so minimal that it’s boring.
Big type (for my old man eyes), splashes of colour maybe something green.
Newsletter CTA. I’d love to have more people find my newsletter.
A design I can build in a reasonable amount of time, and extensible in the future.

Overall, I’m happy with the result of the redesign. Achieving the second goal is the hardest challenge. Creating something personal and friendly while also being minimal seems like a contradiction. I’m already thinking of changes to the design to bring more personality to it in the future.

Design Phase

During the design phase, I had three design iterations. The first iteration I finished at the end of 2024. The last I finished sometime last month.

In the first iteration, I wanted to display more information so that you could understand who I was at a glance. As well as introduce some sort of post curation. I was tired of the plain old homepage, so I added more colours and photos. I was also really into gradients last year.

The second iteration went a completely different direction. I switched to warmer colours, opting for something more minimal. I also switched out the heading font to Poppins on the homepage. I really love how round and friendly it feels.

Unfortunately, both the first and second iterations were difficult to build. And when I stopped to think about it, neither design checked all my goals.

Which brings us to the final iteration!

I changed out the hero because it just didn’t work when the screen was super wide. Instead, I took inspiration from the original introduction paragraph and turned it into a hero. I also made the About section an actual page. I’d like to extend that page in the future.

One thing I love about Figma is how easy it is to preserve your iteration process. Here’s what it looked like designing from a blank page to the second and final iteration. It’s not the most efficient design process but it looks neat!

Build Phase

During the build phase, I deviated a little from my design. Thankfully, I don’t need to be perfect during design because I’m the one building it.

Before I highlight some key changes in this build, I need to undo my past decisions:

I removed Tailwind and rolled my own CSS. No shade against Tailwind, but I want to learn CSS, not Tailwind.
I reintroduced my blog posts hierarchy with /writing. I thought it looked cool to have a flat hierarchy, but it felt awkward with file based routing.
I retired my logo that I’ve had for years. I felt like it clashed with the new design. Although, it still lives on as a favicon.

Light Dark Theme

It’s been a while since I’ve written CSS. And there’s been so many cool things since I’ve last touched it. The CSS light-dark function is one of those things.

In my stylesheet, I set the :root pseudoclass to use the light dark color scheme along with some light-dark variables:

:root {
	color-scheme: light dark;
	--color-text: light-dark(var(--color-dark-text), var(--color-light-text));
	--color-bg: light-dark(var(--color-light-bg), var(--color-dark-bg));
}

To implement the theme switcher, I first check if there’s a theme in local storage. If there’s not, then I get the browser theme. I toggle the theme, and set color-scheme to the new theme, as well as update the local storage.

const preferredColorScheme = (() => {
	return window.matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light';
});

const handleToggleClick = () => {
	const currentTheme = localStorage.getItem('theme') || preferredColorScheme()
    const newTheme = currentTheme === 'dark' ? 'light' : 'dark'
    document.documentElement.style.setProperty('color-scheme', newTheme)
    localStorage.setItem('theme', newTheme);
}

I also wanted to make sure my code blocks switch between dark and light mode. Under the hood, Astro uses Shiki to parse markdown code blocks. And it has hooks to modify the Shiki config:

// In astro.config.js
shikiConfig: {
  themes: {
	dark: 'everforest-dark',
	light: 'everforest-light',
  },
  defaultColor: false
},

It’s important to set defaultColor to false. This forces Shiki to generate a token with both light and dark variables. Example from Shiki docs:

<span style="--shiki-dark:#D8DEE9;--shiki-light:#2E3440">console</span>

Then in my CSS, I use light-dark function to switch between the two variables:

.astro-code,
.astro-code span {
  color: light-dark(var(--shiki-light), var(--shiki-dark));
  background-color: light-dark(var(--shiki-light-bg), var(--shiki-dark-bg));
}

This way a user can manually toggle the theme, or set their browser appearance and the code blocks will change colours correctly.

Animating the Hero text

I wanted to try my hand at animating some text using only CSS. It’s a small experiment to get myself more comfortable with animations.

First, let’s start with the HTML:

<p>
    <span class="animate-phrase">Hey I'm Jono.</span>
    <span class="animate-phrase">Backend developer.</span>
    <span class="animate-phrase">Learning to build delightful websites.</span>
    <span class="animate-phrase">Telling stories along the way.</span>
    <span class="animate-phrase">Obsessed about developer experience.</span>
</p>

I wanted to have each span slide up on load, staggered from each other. To achieve this animation, my CSS follows these steps:

Setup the initial state of the text.
Define a key frame that transitions from the initial to final state.
For each animate-phrase, add an animation with a slight delay to stagger each phrase.

By setting the animation-fill-mode to forwards my animate-phrase class will retain the properties of the last keyframe.

@media (prefers-reduced-motion: no-preference) {
    .animate-phrase {
	  display: inline-block;
      opacity: 0;
      transform: translateY(50px);
    }

    @keyframes slideUp {
      0% {
        opacity: 0;
        transform: translateY(50px);
      }
      100% {
        opacity: 1;
        transform: translateY(0);
      }
    }

    .animate-phrase:nth-child(1) {
      animation: slideUp 500ms ease-out 0ms 1 forwards;
    }
    .animate-phrase:nth-child(2) {
      animation: slideUp 500ms ease-out 100ms 1 forwards;
    }
    .animate-phrase:nth-child(3) {
      animation: slideUp 500ms ease-out 200ms 1 forwards;
    }
    .animate-phrase:nth-child(4) {
      animation: slideUp 500ms ease-out 300ms 1 forwards;
    }
    .animate-phrase:nth-child(5) {
      animation: slideUp 500ms ease-out 400ms 1 forwards;
    }
}

Writing out the CSS transition wasn’t too bad. But I can see why you would switch to using a JS library.

It’s a pain to manage the delay for the stagger. If I were using a JS animation library like anime.js, it could look like this:

import { createTimeline, stagger } from 'animejs';

document.addEventListener('DOMContentLoaded', () => {
	const timeline = createTimeline();
	timeline
	  .add('.animate-phrase', {
		opacity: [0, 1],
		translateY: [50, 0],
		duration: 500,
		delay: stagger(100)
	  })
});

Subscribing users to my newsletter

Finally, I got to write some backend code 🤩.

Beehiiv has an API you can use to subscribe emails to your newsletter. I needed to create a server side endpoint in Astro to call this API.

First step is to create a pages/api/subscribe.ts file that calls the Beehiiv endpoint.

For brevity, I omitted validations and error checking in the following code blocks.

import type { APIRoute } from 'astro'

export const prerender = false

export const POST: APIRoute = async ({ request }) => {
	const formData = await request.formData();
	const email = formData.get("email");
	const beehiivUrl = `https://api.beehiiv.com/v2/publications/${import.meta.env.BEEHIIV_PUBLICATION_ID}/subscriptions`

	const response = await fetch(beehiivUrl, {
		method: "POST",
		headers: {
		  "Content-Type": "application/json",
		  "Authorization": `Bearer ${import.meta.env.BEEHIIV_API_KEY}`
		},
		body: JSON.stringify({ email }),
	});

	return new Response(
		JSON.stringify({
			message: "Success! Check your email to confirm!"
		}),
		{ status: 200 }
	);
}

Adding export const prerender = false tells Astro that this file should be server side rendered.

Next in my Newsletter.astro component, I set up the client side code to call this backend endpoint.

const formElement = document.getElementById('newsletterForm') as HTMLFormElement;

formElement.onsubmit = async (e) => {
	e.preventDefault();

	try {
		const formData = new FormData(formElement);
		const email = formData.get("email")
		const response = await fetch("/api/subscribe", {
			method: "POST",
			body: formData,
		});

		const result = await response.json();
        formElement.reset();
    } catch (error) {
      console.error('Error:', error);
    }
};

The last thing was to add the corresponding adapter to my Astro config. I’m using Netlify so I added adapter: netlify().

Huge props to Astro for making hybrid rendering relatively easy! I love that I can statically render my Newsletter.astro component but have it call a server side rendered route.

Before and after of the homepage

To wrap everything up, here are some before and after pictures of the homepage. It’s nice to see the difference at a glance!

Before

After

Conclusion

I learnt so much throughout this redesign. It’s given me an appreciation of both design and frontend. That shit is hard! I already have a laundry list of things I want to add and tweak. But for now, the major part is done.

I hope you like the new design! Let me know what you think. Shoot me an email or DM me on Bluesky!

Thanks for subscribing to my RSS feed! If you have any thoughts or feedback on this post, send me an email or DM me on Bluesky.

2024 Recapped

Thu, 26 Dec 2024 00:00:00 GMT

I love seeing people grow and overcome challenges. And at this time of year, I’m eating up all the 2024 wrapped posts I can find! It’s fascinating seeing what people cared about throughout the year.

Without further ado, here’s my year recapped.

2024 Goals and Theme

I started off this year with a theme: Independence.

For context, the past couple of years have been a rollercoaster with work. I survived multiple layoffs at Shopify. Only to have the product, I was working on, sold to another company. Then I survived layoffs at that company. Only to find that the team I was working on being dissolved and moved offshore. Throughout this time, I felt like I had no power over my life.

I wanted to own my own destiny, so I created some goals inspired by the theme. I have a more detailed list, but here are the most important ones:

Get a new job.
Start earning money on the side - freelance, or some other side hustle.
Create content again.

The most challenging part of this year was managing my energy. The first half was spent looking for a job. And in the second half, I had bursts of content (like my 30 day writing challenge), followed by a long lull.

But I was able to accomplish a lot this year. Much more than last year!

Achievements

Got a new job ✅

It was a slog of interviews for the first half of the year. But I landed a position on a Developer Experience (DevX) team. It’s been great so far, I love working with an audience I care deeply about!

Created content ✅

Here are my top three most popular blog posts:

I also started a newsletter, DX Dissected. It’s a forcing function to get deep into the DevX world. And even though I haven’t written as many newsletters as I wanted to, it’s a start.

Finally, I released my first YouTube video in a long while! Snuck it in right before the year-end. The video is about using Dev containers to prototype without needing to worry about managing dependencies! Check it out.

Start earning money on the side ❌

Big fat X for this goal. I have some ideas, but I also have a mental blocker. What value am I providing? And can I provide that value consistently? I haven’t proven to myself that I can be consistent this year. So I’m focusing my energy on answering those questions first.

New hobbies

I started journaling my side hustle journey on pen and paper. It’s a nice way to slow down and process my thoughts. I’ve also noticed my handwriting becoming more readable over the entries.

I also picked up pottery! I made a few pieces that are actually usable, which I’m happily surprised about. Here’s a pic of some pots I made.

What’s to come in 2025

After this year, I have more clarity with what I want my life to look like. Communities gave me a lot of energy this year. And I’m starting to find my place on Bluesky as well. Which brings me to my 2025 theme:

Connection

Building connection with people through communities. Both IRL and virtual. But also connection, in the form of building value for others. With this theme, I have some plans:

Invest more time building and taking part of communities (IRL and virtual)
Consume more content for ideas (not only for entertainment)
- Read technical books - 2 (baseline goal) to 4 (stretch goal).
Build and release production-grade apps - 1 (baseline goal) to 3 (stretch goal).
Create more content (as much as possible)
- I don’t know what amount is sustainable. I would like to create 12 videos and release 12 newsletters, but that seems high.
Pie in the sky goal: Speak at a conference!
- Step one: figure out what to speak about.

Thanks for subscribing to my RSS feed! If you have any thoughts or feedback on this post, send me an email or DM me on Bluesky.

Building Design Gut Instinct

Sat, 07 Dec 2024 00:00:00 GMT

Ever looked at a website and thought “wow, that’s beautiful” but couldn’t explain why? That’s where design gut instinct comes in.

This is a tip from Learn UI Design, a design course I’m taking. To be clear, I most definitely am not a UI design expert! There’s always something lacking in my own designs that I can’t quite put my finger on.

Sure, I could use a UI library like Bootstrap to quickly create a good-looking site and save countless hours of learning what’s basically a new career. But sites that use these libraries have a template-y “smell”.

I want to design rad sites that make someone go “ooohhh pretty”. And to do that, I’m working to improve my gut instinct.

Here’s how you can do it too:

Find a website with a banging design. If you’re not sure where to find these sites, I’ll link to some resources at the end.
Open up your tool of choice to store notes. I’ve found Figma to be the best tool for this exercise. Here’s what my Gut Instinct Figma File looks like. You’re welcome to clone it, and modify!
Write down what you liked about the website, take screenshots as well.
Explain why you liked certain elements. Try to be as specific as you can. It’s okay to not know the terminology. But dig deeper than “cool font”.
Observe elements that you might want to repeat in your own designs. And if there’s an element that, by changing, would make the design look worse. Note that down.

Having done this process for a handful of sites, I can tell I know more about design today than I did a week ago. Each analysis takes me about 10-15 minutes, and after a few sites I start seeing patterns emerge. And even though I don’t know all the design-y words, I write down what I feel when I see something I like.

Let me share a concrete example.

While looking at Fly.io, I loved the header font. It was a serif font (Mackinac) that, for me, evoked a sense of trustworthiness but also whimsy.

Now that I know about this font, I can use a tool like Typewolf to see what other sites are using it, and if they evoke the same emotion.

Our goal is to build a library of patterns that we can draw from. We want to know what patterns work well, and why they work. The other benefit of documenting these patterns is to build an inspo board. When you start designing your own site, you’ll have a well of inspiration.

If you’re wanting to build your design gut instinct, give the above steps a try and let me know what you come up with! You can tag me with your notes / Figma file on Bluesky.

Resources

Here’s a list of aggregators that share beautifully designed sites. Note: beautifully designed, sometimes not great UX.

To more easily figure out what font a site uses, I use What font browser extension.

Thanks for subscribing to my RSS feed! If you have any thoughts or feedback on this post, send me an email or DM me on Bluesky.

(Re)Building a reading habit

Fri, 06 Dec 2024 00:00:00 GMT

I’m an atrocious reader of non-fiction articles or books. First off, I find myself constantly zoning out when reading a technical article. Secondly, I’m a sucker for instant gratification. I would rather clean the house for an hour then sit in a chair reading. For context, I do neither and watch YouTube instead. Those pottery videos aren’t going to watch themselves.

In the past few weeks, I committed to reading more. To quote a toddler, “why”?

Reading is a superpower. And it was one that I was missing out on. It unlocks new ideas, challenges preconceptions, and it helps me find my voice when writing. Also, by reading more I can finally complete the Goodreads reading challenge.

Here’s what I’ve been doing to help me (re)build my reading habit.

Make reading a priority

The first step, and the only step that matters, is consistently making the time to read. Or more concretely, make reading a priority.

When I have a busy day, reading used to get bumped into the “I don’t have time for this” bucket. No more! I now carve out 10 minutes, non-negotiable, reading time in the morning. I do this after I wake up, and after I make coffee. For those habit nerds, I make reading part of a habit chain.

10 minutes doesn’t sound like much, but it’s more then what I was doing a month ago. And the goal is to slowly up this amount of time.

Figure out your reading vibe

Since 10 minutes isn’t a long time to read. I’ve found doing a vibe check at the start of a session a good way to get the most out of it. It sets myself up for a win and after the session I felt like I accomplished what I wanted.

These are my reading vibes:

Reading to be entertained
Reading to be informed
Reading to understand

Most of the time I want to be entertained or informed. If that’s what I’m feeling for the session, I’ll focus on those types of articles first. If there are more technical posts that seem interesting, I’ll save it for later.

In the past, I’ve felt the pressure of taking notes, or always having to takeaway something when reading. It doesn’t have to be this way. I’m becoming comfortable with reading an article, saying “huh, interesting”, and forgetting about it the next day. It’s a muscle, and as we read more, we’ll get better at digesting information.

But there are days when I want to fully understand a concept. Or I have a technical article that I want to read. On these days, I normally spend a bit more time in my reading session. The next tip helps me digest information in these articles.

Prep your brain, then check your brain

Before diving into a deeply technical article. I prep my brain for learning. I’m basically telling my brain “hey dude, it’s not that bad, don’t zone out”.

To prep, I skim over the article to get the general gist of what is happening before I start reading it. After skimming, I write down everything I know (or think I know) about the concept.

Then after I’m done with the reading session, I write down at least one thing that I learnt from the article. If I have time to write more, I’ll write about new concepts I found out, how they relate to my existing knowledge, or if they challenge what I currently know.

I’ll rinse and repeat this process until I’ve finished with the article. The end result are notes I can look back on, and an article that I fully comprehend.

(Bonus) Curate your reading list

My final tip is to be selective about what you read. There’s so much content out there and not all content is the same. Daily.dev is a good place to find new content. But it can get overwhelming if you don’t follow the tags or collections you care about.

Nothing has beaten an RSS feed for getting new content. My RSS reader is my best friend. And it helps me keep up to date with the people I look up to most. If you’re curious, here’s my blogroll.

My reading habit is still a work in progress, these tips have been helping, but I have a ways to go before I complete the Goodreads Challenge. I hope these tips have been helpful. Happy reading!

Thanks for subscribing to my RSS feed! If you have any thoughts or feedback on this post, send me an email or DM me on Bluesky.

Articles I Enjoyed #1

Thu, 05 Dec 2024 00:00:00 GMT

I’m trying to read more these days, and I wanted to share some posts that I enjoyed recently. If there’s an article you think I should read or a blog I should follow, leave a comment or find me on Bluesky.

Why I write

Brittany Ellich

A lot of the reasons why Brittany writes resonate with me. Brittany’s also on a posting spree this month with the #blogvent challenge.

I write because it helps me to connect dots between the different things that I am reading, watching, and learning. Taking a topic and trying to form coherent sentences so that other folks can understand your thinking around it is a great way to synthesize your ideas.

Redesign: Version 7.0: Sidebars, light-dark, and Bluesky

Tania Rascia

I’m a huge fan of redesign posts. Reading about the thought process behind design decisions is fascinating. Go check out Tania’s redesign if you haven’t. It’s really well done!

It also led me to another of Tania’s posts Tending to My Digital Garden that comes back to why I write, even if I forget my why sometimes.:

There are a lot of reasons contributing to less activity from me, but I think one of the major ones is that I’ve been treating all my blog posts like they have to be precious. They’re not posts, I’ll think, they’re articles.

It’s weird that I feel weird about that, considering it’s my blog, so what else could or should it consist of aside from whatever I want to put on it? … it’s just whatever I find interesting and whatever I’m working on

So I’m writing this post to give myself permission to put whatever I want on the site.

Why pipes sometimes get “stuck”: buffering

Julia Evans

I never thought I needed to know about why pipes get stuck. But it’s happened to me before, and now I know why! Julia’s posts are the perfect example of I had a problem, I figured out why it was a problem, and now I’ll share it with everyone.

TIL how grep decides to buffer its output

Here’s how grep (and many other programs) decides to buffer its output:

Check if stdout is a terminal or not using the isatty function

If it’s a terminal, use line buffering (print every line immediately as soon as you have it)

Otherwise, use “block buffering” – only print data if you have at least 8KB or so of data to print

Thanks for subscribing to my RSS feed! If you have any thoughts or feedback on this post, send me an email or DM me on Bluesky.

Personal Productivity Handbook

Tue, 27 Aug 2024 00:00:00 GMT

Lately, I’ve been feeling extra energy to pursue my goals. If my motivation were a season, it would be summer right now. Sun is shining. High energy. Happy days. From experience, this energy doesn’t always stay, and I want to make the most of it now. In this post, I want to share a lesson I learnt about productivity and motivation. As well as walk through my current productivity system.

I’ve realised what drains my energy most is decision fatigue. Especially, decisions on how to be more productive. It sounds great on paper. If I can organise my systems and workflows, then I can 10x the amount of work I output.

However, if I spend all my energy organising, how much energy do I have left to create? If I create nothing, then what will 10x the amount of work equal? This lesson seems so obvious in retrospect, but I’ve fallen into the trap of working on my productivity efficiency over doing the actual work.

So here’s a message for future me:

Don’t prematurely optimise your productivity

You don’t need to time block every minute, streamline your note-taking workflow, or invent a new way to track your projects.

Focus on putting in the work, above all else.

Spending time optimising productivity feels good. It feels like I’m making progress towards goals. But after all the decision-making, I end up with a system that takes too much effort to maintain. And eventually the energy to keep the system up dissipates along with my motivation to do the work.

I want the productivity system I have to be dead simple. I need it to do these things:

Tell me what I should do now.
Capture thoughts wherever I am.
Help me focus.
Give me a way to process my thoughts.

I’m going to share what my system is below. But even as I’m writing it out, I realise there are things that I can improve! It’s taking me a lot of self-control to not change it, but what I have written down is something that I don’t want to change for a while.

Productivity Tools & System

Here are the tools I use and how they fit into my productivity system.

Things (Apple only)

Things Website

My to-do app of choice. Every morning, I’ll spend 5 minutes going over any tasks in my “Anytime” section and move things I need to do to “Today”. There’s a handy shortcut cmd + t that will move things without me needing to drag and drop. Any tasks that come up during the day, I’ll note in my inbox and forget about them until the next day. Tasks that I don’t complete roll over to the next day. I try to keep my projects sparse, so I don’t spend too much time deciding where a task should go.

The killer feature I’ve been using is Templates projects. From a template, you can use Apple Shortcuts/automation to have a recurring project. It’s how to set up my weekly reset and review.

Logseq (cross-platform)

Logseq website

Logseq is where I capture thoughts. Thoughts that come into my head naturally fit a bullet point outliner format that Logseq provides. I don’t spend too much time categorising my thoughts. I just dump everything into today’s Daily Note. Being able to capture thoughts and learning is more important to me than organisation (for now). I also have my Logseq vault saved on iCloud, which means I can access Logseq on the go.

Obsidian (cross-platform)

Obsidian website

I published a post about writing blog posts with Obsidian. It’s my tool of choice when I want to synthesise thoughts.

Physical Journal (most recent addition)

Leuchtturm1917 ruled A5

Lately, I’ve taken up writing in a physical journal. I’ve been documenting my entrepreneur / multi-hyphenate journey. I write in the mornings, usually for 25 minutes. Although my handwriting is atrocious, I’ve found it helpful to get a thought out of my head and into the real world. Especially around self-doubt. As I write, I’m able to process that thought more deeply. And reading back over what I wrote, I can see it in a different light. I’m also forcing myself to write neatly, which slows me down. It makes me process my thoughts, and not just word vomit.

Pomodoro timer (Flow.app)

Flow.app website

My final tool is a Pomodoro timer. I use Flow.app, which is free. But there are many other options out there. I stick with the standard 25-minute block with a 5-minute break. A pomodoro has been the best option I found (so far) to give me a short feedback loop. I’ve started measuring project progress in terms of pomodoros. It tells me that I’ve been putting the work in. And tells me when I’ve probably spent too long on a project.

I’ve been using this system for a couple of months now, and it has largely gotten out of my way in terms of creating. I don’t need to think about this system. Most things have a place, and while it might not be the most efficient. It allows me to get thoughts out of my head and into the world. I want to stick with this system until I see a real problem. Maybe I’m taking so many notes that I need to organise it. But that’s a good problem to have, and something I’m not facing right now.

Thanks for subscribing to my RSS feed! If you have any thoughts or feedback on this post, send me an email or DM me on Bluesky.

Setting up dev containers in Rails

Sun, 30 Jun 2024 00:00:00 GMT

Development containers, aka dev containers, have been around since 2019. Made by Microsoft, they allow you to use a container as a development environment. If you’ve used GitHub Codespaces, you’ve loaded a dev container. In Rails 7.2, there will be a new devcontainer flag that will generate a dev container folder for you. Ever since I found out about Rails devcontainers at a local Ruby meetup, I’ve been eager to try them. If you also want to be an early adopter, here are a few issues I ran into.

Installing libraries

Before I can get dev containers working locally, I need to install a few libraries and extensions.

VSCode dev container extension, which will run my application as a dev container inside VSCode.

A docker runtime, that will run my devcontainer. If you’re on a personal machine, Orbstack (which I use) or Docker Desktop is a simple way to get started. Or if you’re on a work machine, Colima is another option.

If you were to use Colima, you’ll have to follow these steps:

brew install colima

Docker to run my containers.

brew install docker

Docker compose, which is needed to run the dev container compose.yaml file.

brew install docker-compose

I also updated my ~/.docker/config.json to add the plugin

"cliPluginsExtraDirs": [
	"/opt/homebrew/lib/docker/cli-plugins"
]

Setting up a Rails dev container

If you have Rails 7.2+ installed, you can create create a new Rails app with a devcontainer:

rails new dev-containers-app --devcontainer

After opening the project in VSCode, you should get a popup asking if you want to Reopen in container. If you don’t, you can use command palette (cmd+shift+p for mac) and type dev container: Reopen in Container.

If you have a Rails 7.2+ project created and you want to add devcontainers

rails devcontainer

Which creates the devcontainer files for you:

Initial thoughts

Here’s what I loved:

Modifying files in the container also modified the files on my local machine. And vice versa! It’s a fast development workflow
Git just works! It pulled my gitconfig from my machine, and I could push verified commits from the container.
Since the app runs in a container, I don’t need to worry about dependency management any more. If I need a new dependency, I can pull it into my docker image.
It works out of the box with VSCode dev container extension.

Here’s what I didn’t like:

You can’t run --skip-bundle and generate a .devcontainer folder. Maybe someone can correct me if I’m wrong. I would like to not have to install anything locally if possible!
The best dev experience is with VSCode. If you don’t use that editor, your workflow would be more involved. You would want to use the devcontainers/cli.
If you have an underpowered machine, dev containers might not be for you. If your container run time isn’t beefy enough with RAM & CPU a-plenty, then your dev container might be sluggish.

GitHub repo for reference.

Troubleshooting

Unable to connect to DB through a DB management tool

I’m seeing an issue with Rails 8 and the default devcontainer setup. When I try to connect to my devcontainer DB using Sequel Ace or DBeaver. Then I get a timeout error:

Unable to connect to host localhost, or the request timed out.
Be sure that the address is correct and that you have the necessary privileges, or try increasing the connection timeout (currently 10 seconds).
MySQL said: Can't connect to local MySQL server through socket '/tmp/mysql.sock' (2)

To fix this issue remove 3306 from forwardPorts section in devcontainer.json. And add in compose.yaml add this line under the mysql block:

ports:
  - '3306:3306'

So the mysql block should now look like:

mysql:
  image: mysql/mysql-server:8.0
  restart: unless-stopped
  environment:
    MYSQL_ALLOW_EMPTY_PASSWORD: 'true'
	MYSQL_ROOT_HOST: "%"
  volumes:
  - mysql-data:/var/lib/mysql
  networks:
  - default
  ports:
	- '3306:3306'

Rebuild your devcontainer and you should be able to connect to your DB using sequel ace or DBeaver.

Can’t connect to local server through socket

Update: It looks like with the latest Rails release, these issues have been fixed. When I first ran the dev container, the bin/setup step errored:

ActiveRecord::ConnectionNotEstablished: Can't connect to local server through socket '/tmp/mysql.sock'

The issue is that config/database.yaml is trying to read a mysql.sock file that doesn’t exist in the container. The easiest fix is to connect to the DB through the network. Modify your config/database.yaml file with:

default: &default
  adapter: mysql2
  encoding: utf8mb4
  pool: <%= ENV.fetch("RAILS_MAX_THREADS") { 5 } %>
  username: root
  password:
  host: mysql
  port: 3306

After this change, I was able to get my dev container up and running. However, when I tried to do Git things like git status, I got an error:

fatal: detected dubious ownership in repository at '/workspaces/dev-containers-app'
To add an exception for this directory, call:
    git config --global --add safe.directory /workspaces/dev-containers-app

To resolve this issue, I updated the devcontainer.json file. Adding a postStartCommand.

{
	... // Rest of config
	"postStartCommand": "git config --global --add safe.directory ${containerWorkspaceFolder}"
}

Thanks for subscribing to my RSS feed! If you have any thoughts or feedback on this post, send me an email or DM me on Bluesky.

30 Days of Posts Retrospective

Sun, 23 Jun 2024 00:00:00 GMT

Today marks the end of my 30 days of posts challenge. Phew, it’s been a journey. I did miss two days of posts. But I was also able to get back to posting after I had broken my streak. I honestly thought I would run out of things to say after the first week. So I’m happy that I made it through the 30 days.

What did I enjoy about the challenge?

The little voice in my head that tells me my posts are dumb was drowned out because of the time constraints. I wonder if that voice will be louder now.
Having my blog become a playground of ideas and exploration was really fun. No idea was too small to write about. And making mistakes was okay!
Finding ways to optimise my posting workflow. I doubled down on Obsidian, introduced some GitHub actions, and found faster ways to write.
I also loved not “marketing” my posts. I didn’t post on social media, and I didn’t think about SEO at all. I wanted to optimise writing rather than views.

Some struggles during the challenge:

Writing quality posts was difficult. I often ran out of time to edit. I didn’t feel like I was becoming a better writer. But a faster writer.
There were some topics I couldn’t explore because they would take too much time.
Coming back after breaking my streak was so hard. I was close to giving up at that point.

What’s next? I want to move to a more chill posting cadence. Maybe once or twice a week. And there’s some other content ideas that I intend to explore. I’m also going to dabble more into marketing my posts, so I can see what resonates with people. Overall, it was a fun challenge. I now know I have ideas to write about!

Thanks for subscribing to my RSS feed! If you have any thoughts or feedback on this post, send me an email or DM me on Bluesky.

Reframing Imposter Syndrome

Fri, 21 Jun 2024 00:00:00 GMT

I had a bad bout of imposter syndrome last week. I felt like I didn’t belong in my role, and that I was a fraud. Starting the day was anxiety inducing. I was expecting to be told that I was doing a terrible job. I needed help from someone. Thankfully, my company offers a few free coaching sessions, and I went to my first session this week. Here’s how my coach helped reframe my anxiety.

Not all anxiety is bad. There’s a bell curve, like with stress. Too little anxiety, you’re bored or coasting. Too much anxiety and you can’t function. Having just enough anxiety lights a fire in your belly. This feeling of anxiety was kicking my ass into gear. It was pushing me to learn.

Think of the opposite scenarios. I talked about not feeling like I knew enough to be called a staff. But my coach posed this question, what if you knew everything? Bored, was the answer I gave her. If I knew everything, I’d go looking for a new challenge. Talking about the opposite scenarios helped get my head out of the negative story I was telling myself.

What did the company see in me? This question was asked by my coach in the session. She went on to ask about my experiences when I first joined a company. What was my learning curve like? These questions helped me see that I had some valuable experience to bring to my role. It might not be technical skills, at least not yet, but I had non-tangible skills to bring to the table.

Working on imposter syndrome is a work in progress. And reframing my anxiety this way doesn’t magically make it disappear. But now I have these questions in the back of my mind when I start to think I’m a fraud. I hope they help you.

Thanks for subscribing to my RSS feed! If you have any thoughts or feedback on this post, send me an email or DM me on Bluesky.

Dynamic Nested Forms with Rails and Stimulus

Wed, 19 Jun 2024 00:00:00 GMT

I’ve been away from Ruby on Rails for a couple of years. And in that time, Rails introduced Hotwire, and Stimulus. In this post, I extend my Rails nested from tutorial by adding a button to dynamically add new nested form elements using a Stimulus Nested Form component.

We’re going all in on Rails, so I’ll be using the default importmap JS package manager.

Set up

Let’s first install the Stimulus nested form component

bin/importmap pin @stimulus-components/rails-nested-form

Update app/javascript/controllers/application.js to register the stimulus component.

import { Application } from "@hotwired/stimulus" // Should exist already
import RailsNestedForm from '@stimulus-components/rails-nested-form'

const application = Application.start() // Should exist already
application.register('nested-form', RailsNestedForm)
...

Let’s modify our previous form by moving our nested fields into a partial. First create the partial app/views/training_sessions/_training_step_fields.html.erb and add the following code:

# app/views/training_sessions/_training_step_fields.html.erb
<%= f.label :description %>
<%= f.text_field :description %>

After we create our partial, we can modify the form in new.html.erb:

# app/views/training_sessions/new.html.erb
<%= form_with model: @training_session do |form| %>
  Session Steps:

  <%= form.fields_for :training_steps do |training_steps_form| %>
    <%= render partial: "training_step_fields", locals: { f: training_steps_form } %>
  <% end %>

  <%= form.submit "Create New Session" %>
<% end %>

At this point, when we go to training_sessions/new we should see the same behaviour as before.

Implementing Stimulus Nested Form Component

Let’s implement the Stimulus component. Modify your new.html.erb to add a Stimulus target:

<%= form_with model: @training_session do |form| %>
  Session Steps:
  <template data-nested-form-target="template">
    <%= form.fields_for :training_steps, TrainingStep.new, child_index: 'NEW_RECORD' do |training_steps_form| %>
      <%= render partial: "training_step_fields", locals: { f: training_steps_form }%>
    <% end %>
  </template>


  <%= form.fields_for :training_steps do |training_steps_form| %>
    <%= render partial: "training_step_fields", locals: { f: training_steps_form } %>
  <% end %>

  <div data-nested-form-target="target"></div>

  <button type="button" data-action="nested-form#add">Add Training Step</button>

  <%= form.submit "Create New Session" %>
<% end %>

Now if we reload our app there’s now a button that lets you add more training steps 🎉.

Breaking down the changes

Let’s break down the changes.

<template data-nested-form-target="template">
...
</template>

<div data-nested-form-target="target"></div>

We register two targets with Stimulus, template and target. The template target, which in Stimulus, gets referred to as this.templateTarget is inserted into this.targetTarget via insertAdjacentHTML. The template is defined similar to our original definition of the training_step fields. But it has two additional params: TrainingSteps.new and child_index: 'NEW_RECORD'

<%= form.fields_for :training_steps, TrainingStep.new, child_index: 'NEW_RECORD' do |training_steps_form| %>
  ...
<% end %>

Rails requires the index of nested fields to be unique. It enforces uniqueness via a child_index. See the Rails docs. We must keep the NEW_RECORD value. Stimulus nested form component will replace the term NEW_RECORD with Date.getTime().toString().

TrainingStep.new is used to build a new instance of the Training Step model. Without this model, we’ll see some odd behaviour where we add two fields every time we press the “Add Training Step” button. Note: the two comes from our controller: 2.times { @training_session.training_steps.build }.

Fun fact: even though two form elements get added, only one element get saved. Can you guess why? That’s right! It’s because the child index for those elements are the same. Rails will only save the last of the two values.

For reference, here’s the component source code.

At the time of writing:

Rails 7.1
Ruby 3.3.2
Stimulus Nested Form Component 5.0.0
Stimulus 3.2.2

Thanks for subscribing to my RSS feed! If you have any thoughts or feedback on this post, send me an email or DM me on Bluesky.

Infrastructure 101: What is a server?

Tue, 18 Jun 2024 00:00:00 GMT

You’ve been working hard on a Rails application. It’s living on your local machine, but now you’re ready to show the world. What’s next?

We need a server! A piece of hardware which can download your Rails app, run it, and allow people to access it. There are many kinds of servers. When I was doing research, the term “server” was losing all meaning.

Cloud Servers
- A virtual server hosted on a cloud computing environment like AWS, GCP, Azure etc. Examples include, AWS EC2 or Digital Ocean Droplets.
- Server is managed by the provider.
- Pricing is on demand, can be dynamically scaled up or down.
Virtual Private Servers (VPS)
- A virtual server that runs on top of a physical server. The physical server may have multiple virtual servers running on it. It can be hosted on on-premises physical servers or within data centres.
- Server managed by you.
On-premise (on-prem) Servers
- Physical machines in a data centre (or even a dedicated machine at home) that will run your application.

We’ll focus on cloud servers, since that’s what most hobby projects would use. You can spin up a cloud server through the provider UI, or through an Infrastructure as Code tool like Terraform. Once the server is up and running, the next steps will be to load your application. I’ll leave that for the next post!

P.S. In most cases, especially if you’re a solo dev trying to get something running quickly, I’d recommend Fly.io. Fly.io is an infrastructure as a service (IaaS) platform. It has a simple deploy process, fly launch && fly deploy, and is cheaper than Heroku. Here’s the guide to getting Rails up and running with Fly.io.

Thanks for subscribing to my RSS feed! If you have any thoughts or feedback on this post, send me an email or DM me on Bluesky.

How to Effectively Pair Program

Mon, 17 Jun 2024 00:00:00 GMT

For me, pair programming is the best way to solve complex problems. I’ve had my fair share of poor pairing sessions. Ones where I was zoning out, or falling asleep, and that left me drained at the end of the session. But I’ve also felt the power of a good pair programming session. I could bounce ideas back and forth with my partner. I felt confident about the feature we released. And I learnt something new. Pairing leads to safer code, and reduces the knowledge silos on a team. The positives outweigh the negatives.

Pairing might not be for everyone, but I wanted to share some tips that have helped me in my pairing sessions. Hopefully, it’ll help make your next pairing session more pleasant.

Come with a topic to pair on - the problem matters

It’s important to have the right topic when pairing. Here’s what you shouldn’t pair on:

Tasks that require a lot of research up front.
Topics where one person doesn’t know the domain at all.

Pairing sessions where both participants are reading documentation is no fun. It’s much better to have read documentation beforehand and come with ideas. And if one of the participants doesn’t know the domain at all, it’s much better to spend that time context sharing. When pairing, you want both participants contributing to the conversation.

Everything else is fair game.

Know when to stop

Both participants should discuss when to stop or to take breaks ahead of time. They don’t need to be set in stone. If it’s a complex issue, I’d suggest taking the entire day to pair. The agreed times can change throughout the session. Maybe at the start, you take breaks every one or one and a half hours. But then later, you take breaks for longer and more frequently.

Use the right tools

This point is specifically about remote pairing. Find a tool that lets you interact with your partners screen. Both with a pointer, and also the ability to type. It’s a much better pairing experience when you can jump in to type out a missing command. Instead of saying it aloud or sending it over in a message. Here are my favourite tools:

Tuple - high definition, low latency, you can draw on the screen, and typing on your partner’s screen is seamless.
VSCode Live Share - Live share is a VSCode plugin that allows participants to join and see your VSCode session. They retain their editor settings, which is a neat feature. You can have people follow you, and they can type in your window. I would use this plugin with video conferencing, or even Tuple.

Don’t get locked into the driver & navigator dynamic

There’s a “best practice” when pairing to define two roles clearly: a driver and a navigator. The driver is doing all the typing. While the navigator is offering suggestions, catching errors, and guiding the driver. Participants each get a turn driving and navigating.

In my experience, these roles aren’t so clearly defined. As a driver, you’re still navigating. And as a navigator, you could step in to drive at any point. The point is to make pairing interactive and engaging. You want there to be a feedback loop for both participants. Don’t get hung up on who’s driving and who’s navigating. Make sure both participants get a chance to type.

Check in at the end of the session

At the end of pairing, check in with your partner. How did they feel about the session? What did we learn? What should we do next? It doesn’t need to be super formal, just a conversation. But it closes the loop and sets you up for future pairing sessions.

Thanks for subscribing to my RSS feed! If you have any thoughts or feedback on this post, send me an email or DM me on Bluesky.

Moving Slow to Move Fast

Fri, 14 Jun 2024 00:00:00 GMT

I’ll always be a Kelsey Hightower fan. He was on a recent Changelog podcast “Retired not Tired” and he said a lot of things that resonated. One piece of knowledge he dropped was around these electrical installer competitions. He talks about how the person whose winning is methodical.

He moving slow…and he’s done 30% faster then everybody else. He is methodical.

Contrast it to the people who are moving fast:

Everybody else is picking it up, moving the ladder, picking it up, moving the ladder

They continue to talk about moving slow to move fast which I agree with. Most of my screw ups happen because I’m moving fast. It feels like I’m moving the ladder repeatedly. Except instead of a ladder it’s push a PR, find a bug, push a PR.

Then Kelsey adds the missing piece. That to be methodical, you have to be good at what you do. You have to put in the work.

It’s the people that don’t quite have the skills down and they have to compensate for the lack of skills by doing stuff seven times

The entire podcast episode was full of great stuff. Give it a listen if you haven’t already!

Thanks for subscribing to my RSS feed! If you have any thoughts or feedback on this post, send me an email or DM me on Bluesky.

Terraform magic

Thu, 13 Jun 2024 00:00:00 GMT

I’m learning about Terraform, and it’s all magic to me right now. I know that Terraform is an Infrastructure as Code (IaC) tool. The alternative to IaC is clicking around GUIs to create your infrastructure. I’m not going to lie, the AWS UI is overwhelming. Also, it’s basically all acronyms, and I hate acronyms.

I fully support Infrastructure as Code (IaC). It’s safe, consistent, and repeatable. You can version your infrastructure, share it, and reuse it. Now back to Terraform. How does it work?

Here’s my best guess with the little research I’ve done so far.

Terraform has a provider registry that you can reference in your tf file. A provider is a plugin for a specific infrastructure service, a service like AWS or Digital Ocean, for example. When you run terraform apply, the tool will read your configuration and call some APIs in the provider, which in turn hook into APIs on the infrastructure service that will create / modify / delete the infrastructure. Your Terraform configuration goes into main.tf, which is a naming convention, or it can go into any other *.tf file.

The next step is to use Terraform to set up some infrastructure for a Rails application. I’m planning on going through the Core Terraform Workflow for guidance.

Thanks for subscribing to my RSS feed! If you have any thoughts or feedback on this post, send me an email or DM me on Bluesky.

Beginning my Developer Experience journey

Wed, 12 Jun 2024 00:00:00 GMT

For once, I’m excited about my job. I’m working on the Developer Experience (DevEx) team. I get to help other developers for a living! One of my first tasks is to understand the vibes with our current developer experience through a survey. But before I could start the survey, I had to learn some things.

What is good DevEx

I know a good developer experience when I see it. But I’ve never defined it. Here’s my stab:

Good DevEx reduces friction on a developer’s daily tasks.

It can look like better tooling, CI/CD, build time improvements, apps to help with pairing etc. A good developer experience makes for a productive developer.

How do we measure DevEx

We can measure DevEx both qualitatively and quantitatively. It’s important to have both. For example, we can pull objective data about build time. However, that account for any flaky test reruns, or merge queue times. It’s easier and faster to get a measure of DevEx through qualitative data (i.e. surveys).

What do we measure?

The two metric frameworks I found were DORA (DevOps Research and Assessment) and SPACE. SPACE stands for:

Satisfaction and well-being
Performance
Activity
Communication and collaboration
Efficiency and flow

DORA is focused on DevOps measures like deployment frequency, lead time for changes, change failure rate, and time to restore services. SPACE is all encompassing. DORA can be considered an instance of SPACE.

From a recent Engineering Enablement, podcast episode,

“DORA presents at least a starting point… I see DORA metrics having been really successful is for organizations that are focused on DevOps transformation or who are going from batched releases to continuous delivery”

For my DevEx measures, I’d rather not focus on DORA. There were other functions at my company that had these metrics. Instead, I wanted to answer these set of questions, inspired by SPACE.

What is the engineering onboarding experience like? Can we reduce errors with setup?
What does collaboration look like to you? Is it pairing, mentorship, both, or none?
How do you test your changes? Are you confident that what goes into production will work as expected?
How long does it take for a change to get pushed to production? How long is the feedback loop for you?
What is the experience working in a monolith? Have you started committing changes to other teams domains?
What tooling are you missing? What prevents you from answering positively to the above questions?

Building the survey

The survey is segmented out by team, function (front end or back end), tenure, and level. I expanded the questions I shared above and gave them options based on the Likert Scale. Here’s an example:

I have the tools necessary to get my work done 1 - strongly disagree, 2 - disagree, 3 - neither agree nor disagree, 4 - agree, 5 - strongly agree

Something I didn’t realise about surveys was how hard they are to write. I want the result of the survey to help answer the questions I have in mind, that will be actionable, but also not be biased due to leading questions. I found CultureAmp’s Guide to Designing a Survey a great resource.

I’m only beginning my DevEx journey, so there’s a lot to learn. If you have any resources, please share! Here’s a list of all the resources in this post and more:

Thanks for subscribing to my RSS feed! If you have any thoughts or feedback on this post, send me an email or DM me on Bluesky.

Tools I use daily as a solo dev

Tue, 11 Jun 2024 00:00:00 GMT

I was inspired by Nick Taylor’s post “Tools that keep me productive”, to document tools I use daily. These tools help me build and showcase projects, stay organised, and keep me productive. Most of these tools are cross-platform, at least between macOS and Linux.

Editor + Terminal

VSCode is my main editor. I’ve been playing around with Zed, but it doesn’t have the plugin ecosystem (yet) for me to switch over. I’m using the Dracula theme, and SF Mono Powerline font.

Bonus tip: if you’re livestreaming, you can enable screencast mode in VSCode to have it show keystrokes. If you want to turn off all keystrokes, go to settings, search for keyboardOptions, and uncheck show raw keys. After that setting is turned off, it will only display modifier keys.

iTerm2 is my terminal of choice. I use zsh as my shell, with oh-my-zsh installed to manage plugins for zsh. Starship is my prompt, it shows valuable information on a project out of the box. Finally, I added z to jump around to different folders from anywhere.

asdf is my plugin manager. It can manage versions of multiple different languages.

Screen capturing

CleanShotX (paid) is what I use to capture screenshots, videos, and GIFs. It’s a new tool in my workflow, so I haven’t had a chance to fully use it yet.

QuickTime player was what I was using to screen record before CleanShotX. It’s a free tool that comes with macOS. The screen recording feature displays mouse clicks and allows you to select a window or area to record.

Design

Figma is my go-to design tool. It has a free plan that gives you a limited number of projects and pages. It also has powerful features like auto-layout, and components which make building designs faster. The only downside is that you have to pay monthly for multiple projects.

Penpot is a free, open-source Figma alternative that I’ve been playing around with. I don’t have the same muscle memory as Figma, and it’s browser only. But it seems like a promising free alternative.

Excalidraw is my whiteboarding / brainstorming tool of choice. I love Excalidraw. I have a whole post about it! Figma is a too heavy for rough wireframing or brainstorming. That’s where Excalidraw shines.

Note-Taking

Logseq for learning new concepts, or taking quick notes. I dump all my knowledge into Logseq and let references between those notes form over time. There’s no real concept of folder structures, which means I don’t need to spend a lot of time figuring out where notes should go. It also comes with a built-in query language, which can help you find information. My favourite part about Logseq is its unlinked references. Meaning you don’t need to explicitly add references to things, Logseq can do it for you.

Obsidian for long form writing, like blog posts. I have a blog post workflow in Obsidian. It’s also where I write journal entries or do my goal setting. Both Obsidian and Logseq store notes locally, so I can write offline.

Notion for documentation that needs some kind of UI (like a table of contents), that I won’t need if I’m offline. It’s where my brag doc lives.

Project management

GitHub Projects is how I manage all my projects. I’ve set up a single GitHub Project that pulls in issues from various GitHub repos. It gives me an overview of all the things that I want to do, and then lets me drill down into what I should do next.

Thanks for subscribing to my RSS feed! If you have any thoughts or feedback on this post, send me an email or DM me on Bluesky.

Slow productivity framework

Mon, 10 Jun 2024 00:00:00 GMT

Years ago, I was fully hooked to the world of productivity. At the time, I was getting up at the crack of dawn to get as much done. I used time blocking to try to maximise every hour of my day. Working a full-time job, then spending 4–5 hours outside the job working on various side projects. I would cut out any activity that I deemed “unproductive”. And when something unexpected came along that interrupted my time block, it caused anxiety.

Only recently did I realise that this productivity mindset was toxic. Yes, it took me a pandemic and also burning out to realise that toxic productivity exists. Gaslighting myself is my forte. To this day, I’m still battling with the feeling of not doing enough. That there aren’t enough hours in the day to be “productive”.

To have a healthier mindset, I needed a new “productivity” framework. I wanted a framework that would help me prioritise what to do outside my 9-5 job. Something that would let me roll with the punches when the unexpected came up. And would help me feel good about what I chose to spend time on. So I present to you my “slow productivity” framework.

When I’m trying to decide what to do. I have to answer three questions:

Will I have fun?
Will I learn something?
Will I regret it if I didn’t do it?

If I say yes to any one of these questions, I should do the thing and not feel guilty about doing it. Some activities are more worth doing than others, I can tell if it’s a yes to multiple questions. But if it’s a no to all questions, then I won’t do the activity.

Here’s an example of how I applied the framework this morning.

I woke up feeling refreshed, which rarely happens. I wanted to immediately start working on a side project before work. It’s something that I would have fun with and learn something. Ticking two of the three questions. This task is something that I would consider productive.

Now I sit at my desk, turn on my laptop, and get ready to code. But my cat jumps up on my table and wanted pets. She was far too cute, and demanding, to ignore. There went my productive morning time. In the past, I would’ve been annoyed and felt guilty that I was doing something unproductive. But today, I ran through the three questions. Am I having fun? Yes. Will I regret it if I didn’t do it? 100% yes. Always pet the cat if it offers.

Sometimes unexpected events happen that interrupt your productive task. With this framework, I feel less anxiety and guilt around these events. It might not work for everyone, but I hope it helps you feel better about doing the “unproductive” activities.

Thanks for subscribing to my RSS feed! If you have any thoughts or feedback on this post, send me an email or DM me on Bluesky.

Nested forms in Rails

Sun, 09 Jun 2024 00:00:00 GMT

What I’m trying to achieve

I have two models:

Training Steps
Training Session which has many Training Steps

When a user creates a Training Session, I want a form that contains fields for Training Steps inside the Training Session form. When I submit the form, I will create a Training Session object along with the related Training Steps.

1. Accepting nested attributes

First, I added accepts_nested_attributes_for to my Training Session model.

class TrainingStep < ApplicationRecord
  belongs_to :training_session
end

class TrainingSession < ApplicationRecord
  has_many :training_steps
  accepts_nested_attributes_for :training_steps, reject_if: lambda { |attributes| attributes['description'].blank? }
end

By default, nested attribute updating is turned off. With accepts_nested_attributes_for I’m able to create a Training Session and the Training Steps in one go. With this method, TrainingSession will now accept a key training_steps_attributes as a value. With reject_if, it will also silently ignore any records that don’t pass the lambda.

2. Adding the controller `new` method

class TrainingSessionsController < ApplicationController
  def new
    @training_session = TrainingSession.new
    2.times { @training_session.training_steps.build }
  end
end

In my new method, I’ll initialise a new Training Session model assigned to @training_session, and build two training_steps models along with it. @training_session will be used in the view.

3. Adding a nested form in the view

<%= form_with model: @training_session do |form| %>
  Session Steps:
  <ul>
    <%= form.fields_for :training_steps do |training_steps_form| %>
      <li>
        <%= training_steps_form.label :description %>
        <%= training_steps_form.text_field :description %>
      </li>
    <% end %>
  </ul>
  <%= form.submit "Create New Session" %>
<% end %>

In the view, new.html.erb, we’re using form_with to build a form that routes to the correct create path. Rails will infer the correct routes based on the resource, in this case @training_session. fields_for is then used to refer to the nested training_steps objects. This method is used to refer to a specific model object, training_steps in this case, but it yields to the form_with element. In other words, you would use fields_for inside a form_with.

TIL - form_with is the new way to build forms. I used form_for in the past but that’s now obselete (here’s the PR with the change to form_with).

4. Creating a nested object

class TrainingSessionsController < ApplicationController
  def new
    @training_session = TrainingSession.new
    2.times { @training_session.training_steps.build }
  end

  def create
    training_session = TrainingSession.new(training_session_params)
    if training_session.save
      training_session.save
      redirect_to training_sessions_path
    else
      render "new"
    end
  end

  private

  def training_session_params
    params.require(:training_session).permit(training_steps_attributes: [:id, :description])
  end
end

In the controller, we can add the create method to handle creating the Training Session object. Notice that we use the training_steps_attributes in training_session_params. We’ll pass these parameters directly into TrainingSession.new and when we save Rails will create both the TrainingSession object and the associated Training Steps objects.

Thanks for subscribing to my RSS feed! If you have any thoughts or feedback on this post, send me an email or DM me on Bluesky.

Tina CMS: a retrospective

Sat, 08 Jun 2024 00:00:00 GMT

I decided to try TinaCMS (aka Tina). It’s another headless CMS that supports Git. Perfect for my workflow! It has built in media management, it can validate metadata fields on a post, and it can push directly to your Git repo. Unfortunately, it didn’t fit with my flow, as much as I wanted it to. Here are the challenges I faced, and why I ultimately decided not to use Tina.

Separate content repo woes

This blog consists of two repos; a website repo, and a content repo. The content repo is a flat folder with all my blog posts in Markdown. Luckily, TinaCMS works with a separate content repo. When you set up Tina, you add a tina folder that contains configuration for Tina cloud to read. This configuration is where you specify the metadata of your blog posts, the path to your content, among a few other settings.

Something that the docs don’t mention is the requirement to have a tina folder in both the website repo, and the content repo. When you run tinacms build it will generate some files in your tina folder in the content repo. Unfortunately, this folder does not play nicely with AstroJS if you’re using content collections. Including this folder caused the following error:

I was able to get around this issue by removing the folder during my Netlify build step. But it was major pain point. With a hacky solution.

Failing build on deploy previews

I didn’t realise at the time, but out of the box, Tina doesn’t support multiple branches. It comes as a feature for the paid editorial workflow. It wasn’t a dealbreaker, but it was an inconvenience. Anytime I wanted to push a new feature, I couldn’t test it out in a deploy preview. I would have to test in production.

Flat file structure issues

After the separate content repo woes, and failed deploy previews, I was finally able to get Tina up and running. I could see, and edit my posts! But then I faced another blocker. I couldn’t create posts. Whenever I pressed save, I would get the following error:

The reason was because I set my path in Tina config to an empty string. I needed to set it as an empty string, so I could display my posts in the flat folder. However, Tina will add a / when saving a post, which will cause the call to GitHub to fail.

This blocker was the final nail in the coffin. I opened an issue for it.. I’m hoping they’ll accept my suggestion, or come up with a better approach in the future!

Deciding not to use TinaCMS

The culmination of all the issues above, made me realise that Tina wasn’t for me. I really wanted to get TinaCMS to work. I had a few back and forth’s on Tina Discord in an attempt to resolve my issues. But last week, I decided to not continue with it. I doubled down on Obsidian as I started writing more. And I found the Obsidian Cloudinary plugin, which solved my media management problems. I had many learnings during this process. And I’m pretty confident saying, if you have an AstroJS site with a separate content repo, TinaCMS might not be for you.

Thanks for subscribing to my RSS feed! If you have any thoughts or feedback on this post, send me an email or DM me on Bluesky.

Fixing missing Ruby versions in asdf

Fri, 07 Jun 2024 00:00:00 GMT

I use asdf to manage my Ruby versions. It’s a version manager that can manage multiple languages. Meaning I don’t need to install a separate Ruby version manager with a Node version manager, for example.

I ran into an issue today where asdf wasn’t showing the latest Ruby version. To fix it I ran:

asdf plugin update ruby

Then to install the latest ruby version, and set it as the default Ruby version:

asdf install ruby latest
asdf global ruby latest

You can also use .tool-versions to specify which Ruby version you want at the project level (see asdf docs for more info).

Thanks for subscribing to my RSS feed! If you have any thoughts or feedback on this post, send me an email or DM me on Bluesky.

Advice for Effective Developers

Thu, 06 Jun 2024 00:00:00 GMT

Syntax FM released a podcast episode 11 habits of highly effective developers yesterday, it’s filled with anecdotes, and great advice. If you haven’t already, give it a listen! Scott Tolinksi and Wes Bos shared these 11 habits:

Understand stakeholders and business goals
Have an open mind about new tech
Help others with problems
Understand work-life balance
Pay attention to details
Be curious and always learning
Ask for help when needed
Have fun with development
Be empathetic to users and coworkers
Be part of the developer community

While listening, I made a mental note to keep practising these habits, I loved them! Especially, having fun with development. Usually, I see programming as a way to solve business problems. I forget that it can also be used to make fun things!

After the podcast ended, I thought about what advice would I have given my past self to be a more effective developer? So I made a list! I’ll add to it over time, and I hope you’ll find the advice useful.

Naming is hard. Understanding the domain of your application can help. If possible, err on being specific with your name rather than generic.

Build your pattern matching muscle. Not regex (although that can be useful), but patterns with solving problems. Watch how others solve problems, debug, and write code. Go through the same process yourself over and over again.

Pair frequently and with different people. The benefits of pairing greatly outweigh working solo on complex issues.

“For each desired change, make the change easy (warning: this may be hard), then make the easy change” - Kent Beck

Find the most straightforward path to solve a problem. If this path doesn’t exist, can you make it happen? Only when you’ve exhausted your options should you look at more complicated solutions. I find this advice the hardest to follow.

Introspect often and stay away from autopilot mode. After finishing a tutorial, take the time to understand what you’ve learnt and how you could use that knowledge in other ways.

Pursue what is interesting to you. Drown out the hubbub, the trends, the absolutists. If you don’t know what fascinates you yet; experiment.

Go broad on a topic before going deep. This advice ties in with the one above. Experiment until you find something, then go deep on it. Going broad diversifies your mental models. Going deep strengthens your models.

Have a career document aka brag document. Use it to show your impact at your role. Save all the good stuff people say about you or things that you’re proud of. Look at it whenever you’re feeling down or feeling like an imposter.

Practice saying no. Overcommitting is stressful. Burnout is real, take the time to care for yourself.

You don’t need to write blog posts, produce content, or commit to open source to be a successful developer. But it can be a nice way to give back to the community.

Thanks for subscribing to my RSS feed! If you have any thoughts or feedback on this post, send me an email or DM me on Bluesky.

Using Github Actions to fetch content

Wed, 05 Jun 2024 00:00:00 GMT

I recently added more automation around my blog post publishing workflow. Previously, I shared how I use Obsidian to write blog posts. In this post, I want to show you what automation I’ve added to help publish a post.

Before I dive in, I need to provide some context. This site is separated into two repos. A website repo, that’s where all the AstroJS goodness lives. And then a content repo, that’s where all my posts live. The content repo is a Git submodule inside the website repo. These two are separated for a few reasons:

I can keep my content commits separate from my website commits.
I have dedicated version control over my content.
I have visibility controls over my content. Meaning, I can set my content to provide if I ever wanted to.

Unfortunately, with two separate repos, I have a few extra steps to publish. I need to push the new post to the content repo. Then pull in those changes to the website repo, before pushing again.

Automation introduced

I used two Github Action scripts to automate fetching the latest content changes, and pushing to main.

In my content repo, I have a script that runs whenever I push to main:

name: Trigger deploy
on:
  push:
    branches: [ main ]
  pull_request:
    branches: [ main ]
  workflow_dispatch:
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Trigger parent repository update
        run: |
          curl -XPOST https://api.github.com/repos/jonathanyeong/personal-website/dispatches \
          -H 'Accept: application/vnd.github+json' \
          -u jonathanyeong:${{ secrets.ACCESS_TOKEN }} \
          --data '{"event_type": "deploy content changes"}'

This script will dispatch an event to my website repository whenever there’s a push to main. The data field doesn’t matter, and could be whatever event type you want. GitHub has more docs on creating a repository dispatch event.

In my website repo, I have a script that listens to dispatch events and runs when it receives one.

name: "Fetch Content Updates"
on: [repository_dispatch, workflow_dispatch]
jobs:
  pull_content_updates:
    name: pull_content_updates
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repository
        uses: actions/checkout@v4
        with:
          token: ${{ secrets.ACCESS_TOKEN }}
          submodules: true
      - name: Pull submodule
        run: |
          git pull --recurse-submodules
          git submodule update --init --recursive --remote
      - name: Push changes
        run: |
          git config --global user.email "hey@jonathanyeong.com"
          git config --global user.name "Jonathan Yeong"
          git add .
          git commit -m "[Workflow] Updating website content"
          git push

The repository_dispatch handler will watch for dispatch events. When it gets one, it will pull down the latest changes from the submodule, and then push the updates to main. Here are the GitHub docs on repository_dispatch. After pushing to main branch on my website repo, Netlify will build my site and publish it.

Note: I included workflow_dispatch so I can manually trigger a content fetch, and push for testing.

What’s next?

These GitHub Actions were my first foray into automating my workflow. And I’d love to do more. It’d be great to have a linter that would catch any markdown issues before I pushed. I also want to automate pushing posts to the content repo. It would be cool if I had a “publish” button in Obsidian that would do a commit and push for me.

Thanks for subscribing to my RSS feed! If you have any thoughts or feedback on this post, send me an email or DM me on Bluesky.

Scheduling Posts with AstroJS

Mon, 03 Jun 2024 00:00:00 GMT

Before going on a trip this weekend, I wrote multiple posts so I didn’t need to write on my trip. However, to keep my writing streak, I had to manually release posts by setting their draft property to false. That sucked. Today I released scheduling posts so I don’t need to go through this pain again. Here’s how I did it.

Implementing scheduled posts

A scheduled post on my site is any post that is NOT in draft, with a pubDate that is in the future. I want to display a scheduled post when the pubDate is in the past. With the previous sentence in mind, I created a file that exported a method hasPubDatePassed.

import type { CollectionEntry } from 'astro:content';
import { formatInTimeZone } from 'date-fns-tz'

const formatDate = (date: Date): string => {
	return formatInTimeZone(date, 'Etc/UTC', 'yyyy-MM-dd');
}

const hasPubDatePassed = (post: CollectionEntry<"blog">) => {
	let todaysDate = new Date()
	todaysDate.setHours(0, 0, 0, 0)
	return formatDate(todaysDate) >= formatDate(post.data.pubDate);
};

export default hasPubDatePassed

I used this method in my filterPublishPosts helper (source)

const filterPublishedPosts = (allPosts: CollectionEntry<"blog">[]): CollectionEntry<"blog">[] => {
  return allPosts.sort(
    (a, b) => b.data.pubDate.valueOf() - a.data.pubDate.valueOf()
  ).filter((post) => import.meta.env.DEV || !isDraftPost(post) && hasPubDatePassed(post));
}

Where this filterPublishedPosts method sorts the posts and then displays only those that are not in draft and who’s pubDate is in the past.

Note: import.meta.env.DEV is used to display all posts in local development.

Timezone Gotcha’s

After a bug with timezones sometime last year, I knew it wasn’t enough to do a date comparison like below. todaysDate would have a timestamp but pubDate doesn’t have a timestamp. If we applied timezones to these two dates we could publish a post earlier then expected.

// ❌: 🕛 Timezone issues
const hasPubDatePassed = (post: CollectionEntry<"blog">) => {
	let todaysDate = new Date()
	return todaysDate >= post.data.pubDate;
};

To avoid dealing with timezones, I set the time of today’s date to 00:00. This time matches the time of pubDate. After setting the time, I convert both dates into UTC timezone, and output strings in a format like 2024-05-30. Finally, I do a string comparison that will return all posts with pubDate today or in the past.

// ✅: 🕛 Sets both times to UTC
const hasPubDatePassed = (post: CollectionEntry<"blog">) => {
	let todaysDate = new Date()
	todaysDate.setHours(0, 0, 0, 0)
	return formatDate(todaysDate) >= formatDate(post.data.pubDate);
};

I have a scheduled post for tomorrow to test this feature 🤞 it all works. Note to self: automated tests would be nice.

Update: GitHub Action to trigger a build

After I finished writing this post, I realised I missed one big thing. When AstroJS builds, it’s building as a static site. Which means at the time of the build, only those posts will exist. So scheduling a post in the future will never work because it will never exist in the AstroJS build step 🤦🏻.

To resolve this issue, I introduced a GitHub Action that would trigger daily at 6am UTC (around 2am EST). The GitHub Action will call a Netlify build hook , which will build the site and pull in the scheduled post. It’s important to keep the build hook a secret because it’s not authed, meaning anyone can curl the URL and trigger a build.

name: "Scheduled Build"
on:
  schedule:
    - cron: "0 6 * * *"
jobs:
  trigger_netlify_build:
    name: trigger_netlify_build
    runs-on: ubuntu-latest
    steps:
      - name: Call netlify build
        run: |
          curl -X POST -d {} ${{ secrets.NETLIFY_BUILD_HOOK }}

Thanks for subscribing to my RSS feed! If you have any thoughts or feedback on this post, send me an email or DM me on Bluesky.

Writing blog posts with Obsidian

Sun, 02 Jun 2024 00:00:00 GMT

I’ve been writing a lot of Markdown lately. And I have two thoughts:

I love writing Markdown
I hate looking at Markdown

When I write pure Markdown, I feel like it’s too noisy. I’ve tried some editors that mirror Markdown like VSCode with the Markdown preview, or using an online Markdown editor like StackEdit. I couldn’t deal with the split, my eyes didn’t know what to look at! There’s probably live Markdown previews online as well. But copy-and-pasting content from the browser to a file was too many steps.

Then I found Obsidian. It’s a writing app that’s popular in the PKM (personal knowledge management) space. You can use it to organise your thoughts and link together different concepts. It fits perfectly in my workflow because it provides a distraction-free environment, live preview, and page templates.

Setting up the blog post workflow

To set up the workflow, I needed to symlink two folders. One was to my content folder in my Astro project. And the other was to the folder I created for blog posts in Obsidian.

Opening up my terminal, I first got the path to my content folder. Then cd into my Obsidian folder. This folder was set up when I created a new “Vault” (see Obsidian Manage Vaults doc for more information). I then created a new folder, and symlinked the two.

cd <path-to-obsidian-vault>
mkdir BlogPosts
ln -s <path-to-content-folder> BlogPosts

Now, any new posts created in the BlogPosts folder in Obsidian will also appear in my path-to-content-folder.

Setting up a template

Obsidian has a built-in Template plugin that I use for all my posts. Learn more in the Obsidian Template documentation.

I have a folder named Templates that contains a file blog-post-template. The template is common front matter I use for all my posts:

---
pubDate: {{date}}
updatedDate: {{date}}
title: "template"
description: "A template"
featured: false
draft: true
topics: []
---

Adding images to posts

Initially, I added image by dropping the file into my Astro project than referencing the file in Obsidian. This is clunky for a couple of reasons.

My content is separate from my website. Meaning I have to sync git pushes to ensure my images aren’t breaking on publish.
I have to jump back and forth between apps to get the image details.

A better alternative is to drop a link to an image. Cloudinary is a popular tool to manage media, and there’s a Cloudinary Uploader plugin that will upload your image to cloudinary and return a link in one step.

You do need a Cloudinary account and an API key, but after some setup it’s been working flawlessly.

Pushing posts to Git

After writing a post, I would switch to my terminal and run a few commands to push the post to the Git repository. Running these commands became anonying quickly. So I built a small Obsidian plugin that would run the git push for me!

What’s next?

I’ve tried using Tina CMS but unfortunately it didn’t fit with my workflow. But moving to a CMS would be a logical next step. Media management is still a pain point. I also want to start building components to use in MDX files, and I know Obsidian won’t handle that out of the box.

Thanks for subscribing to my RSS feed! If you have any thoughts or feedback on this post, send me an email or DM me on Bluesky.

Making a custom kebab case method for pretty URLs

Sat, 01 Jun 2024 00:00:00 GMT

Recently, I was working on a Rails app where I wanted to make some pretty URLs for it. I have a route where you can view a Dog resource GET /dog/1. Having an ID in the URL is not what I want. People could increment the ID to potentially see other dogs. But more importantly, it’s not personal! I wanted the URL to show your dog name instead, like /dog/albie or /dog/st-george-bernard-the-3rd. I needed a way to make pretty kebab case URLs.

Pretty kebab case URLs

To get a URL that’s not the default id, I added the to_param method to my model. Where slug was a column on my Model:

def to_param
  slug
end

Since I wanted the slug to be auto-generated, I had to transform the name column to kebab case (see below). Much to my surprise, there wasn’t a Ruby / Rails kebabcase method:

class Dog < ApplicationRecord
  before_create ->(dog) { dog.slug = dog.name.kebabcase } # .kebabcase doesn't exist

  def to_param
    slug
  end
end

Looking at the docs, I found .underscore and .dasherize. Unfortunately, they only work for camel case names:

"DogName".underscore.dasherize
# => "dog-name"

But who names their dog in camel case? Maybe people do, but I’m assuming most people use spaces. Unfortunately, .underscore only works on camel case strings.

"Dog Name".underscore.dasherize
# => "dog name"

Searching for a Gem

If Ruby and Rails didn’t have a kebab case method. I’m sure there’s a gem out there that does. In comes Strings::Case to the rescue:

strings.kebabcase("PostgreSQL adapter")
# => "postgre-sql-adapter"

I could’ve called it a day here, but looking at the gem, it has so many other methods that I wouldn’t use. Honestly, it seems like overkill for my tiny side project. It’s also another library I would have to maintain and make security updates to. In the end, I decided to roll a custom kebab case method.

Rolling a custom kebab case method

Before jumping into a solution, I wanted some inspiration from Strings::Case.

Under the hood, the gem scans through a string, building words determined by whether there is a specific delimiter or if there’s an uppercase. “DogName” would be two words “Dog” and “Name” since there’s an upper case in the middle. And “Dog Name” would be two words, since there’s a space in the middle. These words get put into an array, and after the string has been scanned, a .join method is called with a separator. In kebab case, the separator would be -. I’m oversimplifying this approach. If you’re curious, about the source code, you can view it here.

For the gem, this process makes total sense. It handles many use cases as well as includes multiple string manipulation functions. Since I only wanted kebab case, I decided to go with a regex approach:

dog.name.downcase.gsub(/[^\w\d\s]/, "").gsub(/\s/u, "-")

Let’s break down what this is doing:

.downcase - A built-in function that makes the string lowercase.
.gsub(/[^\w\d\s]/, "") - Regex that matches anything that’s not a character, digit or space, i.e. any special characters and removes it.
.gsub(/\s/u, "-") - Regex that matches a space and replaces with a dash

"St. George Bernard the 3rd".downcase.gsub(/[^\w\d\s]/, "").gsub(/\s/u, "-")
# => st-george-bernard-the-3rd

The biggest limitation with my approach is the regex. I make plenty of assumptions with what I think names should be, and it’s focused primarily on English. But what if someone uses a character language like Japanese?

"餅".downcase.gsub(/[^\w\d\s]/, "").gsub(/\s/u, "-")
# => ""

If I wanted to make this more robust, I should handle non-English characters properly. If I can, I could transliterate it. Like é becomes e. If it’s in a character language, I could leave it because non-English characters can be used in URLs.

However, for a small side project, what I have is enough. And I didn’t need to pull in a new gem to achieve it.

Using Ruby 3.2.0 and Rails 7.1.3.3 at time of writing

Thanks for subscribing to my RSS feed! If you have any thoughts or feedback on this post, send me an email or DM me on Bluesky.

30 Days of Posts

Fri, 31 May 2024 00:00:00 GMT

I came across this blog post by Rach Smith where they talk about Weblog Posting month. A challenge in May where you post on your blog every day. I love this idea. I haven’t posted on my blog very consistently, mostly due to feeling burnt out. So the challenge of posting every day is inspiring! I loved reading through Rach’s posts because they range from technical content to personal thoughts or anecdotes. It makes me feel better about posting whatever.

Unfortunately, I can’t join the #WeblogPoMo2024 challenge because I’m super late to the party. But I’m going to challenge myself to post every day for the next 30 days. And you might have noticed already that I have a few posts under my belt. I wanted to see if I could get through a week before committing. Under promise, overdeliver.

You might ask why am I doing this?

Firstly, I like a challenge. And I need that extra motivation to start posting again.

Secondly, I want to get better at writing and find my voice. The only way to get better is to force myself to write in public.

Thirdly, I’m hoping to build a “post brain” (relevant Rach Smith post). I’d like to flex that muscle that tells me when I should write about an experience.

Finally, I tend to have countless notes in draft which I don’t post because I think they’re stupid, and no one will read them. I’m working really hard to quiet that voice in my head.

I hope you’ll enjoy the random thoughts that come out of my head!

Thanks for subscribing to my RSS feed! If you have any thoughts or feedback on this post, send me an email or DM me on Bluesky.

You know what they say about assumptions

Thu, 30 May 2024 00:00:00 GMT

Last year, I added a comments feature to my blog. During development, I verified the change by checking that the comments section existed on a post. It did, #shipit. After almost a year, someone told me that their comments and reactions weren’t showing. It turns out that I had set up Giscus incorrectly from the start 😫! And if that person hadn’t said anything, I would’ve been clueless.

The fix was trivial, I changed data-categories in my Giscus setup to point to the correct discussion category "Blog Post Discussions", not "Announcements" (here’s the commit).

I took one lesson away from this experience. Something I probably should’ve already known.

Just because it’s a personal project doesn’t mean I should take shortcuts with testing

Here’s the test cases I should’ve run through:

Does the comment section load when I view a blog post?
Can I post a comment?
- Does the comment section show the new comment?
- Can I put images/gifs in the comment?
Can I add a reaction?
- Does the reaction show?
If a comment is posted, do I get a notification?
Can I reply to a comment?
- Does the reply show up with the comment?

Writing out the test cases, it feels obvious that I should’ve gone through them. I shouldn’t release something that’s untested. But these things happen. Especially for projects where I’m rushing, tired, or overconfident. Maybe a combination of all three. At least now the comments work, I manually verified the test cases. Happy days.

Thanks for subscribing to my RSS feed! If you have any thoughts or feedback on this post, send me an email or DM me on Bluesky.

What I missed about Ruby

Wed, 29 May 2024 00:00:00 GMT

I’m back in Ruby on Rails land after two years using only Node/TS. And I’m thrilled to be back! I feel like I missed so much progress with Rails 7 over the last 2 years. But now that I’m back, I can finally use all the things I missed. Here’s all the things that I took for granted before my break:

Convention is enforced in Rails. Organization is much easier in a rails project, and I’m able to hop into any Rails project and find my way around.
Some magic is nice. Such as auto-loading files!
Rails console!!! Omg being able to run code snippets is amazing. I downloaded RunJSto be able to achieve the same thing. But it’s not a replacement for being able to play around with the data along with your code.
Mocking with RSpec is way easier than Jest. In Node/TS, we used dependency injection to be able to mock classes and methods. But it was annoying to use dependency injection when it was only used in testing. Please let me know if there’s a better way to do it.
Having Rails routes to get an overview of all the entry points to the app is so underrated.

One thing that I took away from the last two years, is typing. I’m not going to lie. I like it. It’s nice to be able to hover over an object and know what fields exist in it. I would love with Ruby to be able to hover over a hash and see all the keys that exist. I added Sorbet and RBS to my things to learn list.

Thanks for subscribing to my RSS feed! If you have any thoughts or feedback on this post, send me an email or DM me on Bluesky.

Taking charge of my onboarding: my personal checklist

Tue, 28 May 2024 00:00:00 GMT

When I first join a company, I need some sort of structure. I feel like there’s an ocean of information, and I’m told to start rowing. It’s overwhelming to know where to start.

Thankfully, most companies have some sort of onboarding when you first join. It gives you some sort of foundation, maybe even helps you get the application setup on your machine. But often times I find company onboarding lacking guidance beyond the first couple of weeks.

To help me feel like I’m progressing, I’ve made my own personal onboarding checklist that I’ve used and tweaked over the past few companies I’ve worked at. I try to tick these items off during my first month of onboarding.

Join all the fun and team related Slack channels
Set up 1-1s with my entire team.
- Get to know them; topics include where are they based, how long have they been on the team, any surprises or challenges they’ve faced so far
Set up a recurring 1-1 with my onboarding buddy (hopefully done earlier, and hopefully, I’m assigned one)
Set up a recurring 1-1 with my manager (hopefully they do it)
Read through the company career ladder, understand what’s required from me. Summarise these points and share it with my manager in our first 1-1.
- Understand what my manager thinks success looks like
Set up the application locally, run it, and click around the interface.
Have someone take me through the application. At a high level, happy path flow, understand how a user uses the application.
- Perform user actions myself, after the meeting. I wish to see what are the critical classes, any logging, and what the data looks like in the database.
Get access to staging and production data. I want to see what real-world data looks like.
- Get access to any other tools required for my role (hopefully done during general company onboarding)
Understand the coding workflow, either have someone take me through it or find some docs. What are the company conventions?
Pair on a feature / bug
Complete a feature / bug solo.

Hopefully, some of these tasks are included during onboarding. Is there anything I should add?

Thanks for subscribing to my RSS feed! If you have any thoughts or feedback on this post, send me an email or DM me on Bluesky.

Tools I Use: Excalidraw

Mon, 27 May 2024 00:00:00 GMT

My brain is terrible at visualizing and tracking how various concepts fit together. Excalidraw helps make my brain be better. It’s a free low-fidelity whiteboarding tool that I’ve been using for system design interviews, brainstorming, flow diagrams, wireframe/mockups. Anything that I used to draw on a piece of paper is now being done in Excalidraw. It has basically everything you need to diagram, and if you need more, there is a plugin library to get extra shapes.

The low fidelity look and feel reduces the friction of creating diagrams. I don’t need to worry about perfection, I can slap together a few shapes add some text, and I’ve mapped out what was in my head.

Here are a couple of random things I’ve made in Excalidraw:

Flow chart of how my personal website is structured

Brainstorming a side project I’m working on

Thanks for subscribing to my RSS feed! If you have any thoughts or feedback on this post, send me an email or DM me on Bluesky.

What is Zeitwerk?

Sun, 26 May 2024 00:00:00 GMT

Zeitwerk is a gem that loads Ruby files. From Rails 6, Zeitwerk is the default loader. Loading a Ruby file means making that file available in your code. There are a few ways to do this with Ruby, require, require_relative, load. Zeitwerk removes the need to add these special keywords and does the loading for you. It can load files on demand (autoloading) or upfront (eager loading).

Zeitwerk works by following naming conventions. The idea is that file paths match the constant name. From Zeitwerk’s README:

lib/my_gem.rb         -> MyGem
lib/my_gem/foo.rb     -> MyGem::Foo
lib/my_gem/bar_baz.rb -> MyGem::BarBaz
lib/my_gem/woo/zoo.rb -> MyGem::Woo::Zoo

One reason you would use Zeitwerk in your Ruby projects is to get rid of using require. Manually loading files is brittle because you might forget to load certain files or load files in an incorrect order. Zeitwerk also removes the need for require_dependency since Zeitwerk also supports code reloading.

Thanks for subscribing to my RSS feed! If you have any thoughts or feedback on this post, send me an email or DM me on Bluesky.

What I look for in a company

Sat, 25 May 2024 00:00:00 GMT

I went through months of interviews recently. And one question that I got asked repeatedly was “what do you look for in a company?” or “what are you looking for in your next role?”. For some of these interviews, I gave some pretty generic answers:

“I’d like to work on challenging problems” “I’m looking for a company with an inclusive culture” “I want a team where I can learn and grow”

A few times I had to stop myself saying:

“I dunno, money I guess?”

Of course, I want to work in an inclusive company, where I’m growing and working on fun, challenging problems. And of course I want to get paid but reflecting on this question. I’m realizing I had more answers to that question.

I have green flags, what will make me say yes to more interviews or yes to an offer. And red flags, what will make me say hell no!

Red Flags

Messy, unorganized recruiting process
Recruiters that take weeks to respond to your emails. Or send you roles that don’t match at all with your skill set.
Interviewers show up uninterested, late, derail you from completing the interview, or are taking Slack messages during your interview.
When recruiters / interviewers don’t know the answer to questions about the company like with profitability, market fit, road map, cash runway, etc. Approximate answers are okay, but if they won’t tell you outright or don’t know the answer to these questions, then red flag.
Microservices IF the dev tooling is subpar or non-existent. Also, cookie cutter answers to why use microservices.
Long deployment cycle. I want to deploy at any time of the day every day.
If they don’t support fully remote work, ESPECIALLY if their team is distributed
If the team doesn’t have a spread of developer levels, is mainly top (senior+) heavy, and doesn’t have a plan for hiring devs across levels.
Crypto companies
Non-AI companies talking about integrating some AI being the next big thing they’re working on.

Green Flags

When salary ranges are shared ahead of time before recruiter calls. I.e. in the job posting.
Coding questions aren’t hacker rank / leet code style questions. And they feel more like pair programming.
When developers talk about the product with excitement. And are proud of what they’ve released.
When recruiters send you tips and what to expect before an interview. Or hop on a call to prep you for that interview.
Humour. If I can joke with my interviewer, and we share a laugh, green flag.
If the company has contributed to open source or open sources their own projects. If they give developers time to contribute to open source as well.
If benefits like learning and development exist. Is it formalized and part of company culture (green flag)? Or is it an afterthought (red flag)?

These flags are pretty personal to me. What do you agree or disagree with? What are your red / green flags?

Thanks for subscribing to my RSS feed! If you have any thoughts or feedback on this post, send me an email or DM me on Bluesky.

Burnout is a sneaky bugger

Fri, 24 May 2024 00:00:00 GMT

Burnout really sneaked up on me. Would not recommend 0/10.

It took me a week into my 5-week break between jobs to realise that I was actually burnt out. And it took almost the entire break to feel energised again.

I had always read about burnout, and I had seen my peers go through it. I get it now. It totally freaking sucks. All I could do after work was stumble over to the couch and watch easy-to-digest TV. Side note: I’m pretty good at picking out the killer in crime shows now.

In hindsight, the signs were pretty obvious. But when you’re in it, it’s hard to tell what’s burnout or what’s fatigue. There are some great resources on burnout, this one on CodeSubmit is my fav.

I’m starting to feel more energised these days, and with that brings a whole lot of excitement about learning new things and engaging with my communities. I’m lucky that I had a chance to take a long break to recover. If you have that time, I recommend it. Especially, if you’re able to get out of a toxic work environment in the process. My goal is to take more time out of the day to be kind to oneself. I hope you’ll join me!

Thanks for subscribing to my RSS feed! If you have any thoughts or feedback on this post, send me an email or DM me on Bluesky.

Fixing a Timezone bug on my blog

Mon, 17 Jul 2023 00:00:00 GMT

I noticed a weird bug on my blog the other day. The dates that I set in my blog post metadata didn’t line up with the dates that I saw on the page. It was always a day off. For example, the front matter for my blog post showed days:

---
pubDate: 2023-07-11
updatedDate: 2023-07-10
---

But the dates displayed on my blog post was:

Published Jul 10, 2023 | Updated Jul 9, 2023

This bug felt like a timezone error. It’s weird that it was off by one day. But I wasn’t sure, so I went through my debug steps.

I console logged pubDate and updatedDate everywhere and I got these values:

updatedDate is: 2023-07-10T00:00:00.000Z
pubDate is: 2023-07-11T00:00:00.000Z

Which meant I wasn’t doing some weird conversion when pulling out the metadata from my blog post.

The only place where it was changing the date was in this snippet:

{
  date.toLocaleDateString('en-us', {
    year: 'numeric',
    month: 'short',
    day: 'numeric',
  })
}

So I dug into the toLocalDateString docs. It turns out toLocaleDateString was using my local timezone. I had totally missed this line from the MDN docs:

The toLocaleDateString() method returns a string with a language-sensitive representation of the date portion of the specified date in the user agent’s timezone

Unfortunately, there didn’t seem like an easy way to keep the UTC timezone when displaying the dates with toLocaleDateString(). Since my date formatting needs were pretty basic, I could use toUTCString() instead:

const formatDate = (date: Date) => {
  const dateParts = date.toUTCString().split(" ");
  const monthIndex = 2;
  const dayIndex = 1;
  const yearIndex = 3;

  return `${dateParts[monthIndex]} ${dateParts[dayIndex]}, ${dateParts[yearIndex]}`
}

It’s not pretty but it works without needing to pull in another library. If I wanted to have fancier date formatting I could use something like date-fns. But I found a gotcha with date-fns

Since date-fns always returns a plain JS Date, which implicitly has the current system’s time zone, helper functions are needed for handling common time zone related use cases. (source)

So if I wanted to display a UTC time on my current system which is set to EST. Then I would need to pull in date-fns-tz instead. This library lets me specify which IANA timezone and uses the Intl API. Here’s what that change would look like:

import { formatInTimeZone } from 'date-fns-tz'

const formatDate = (date: Date) => {
  return formatInTimeZone(date, 'Etc/UTC', 'MMM dd, yyyy');
}

This bug was a reminder that timezones are the worst.

P.S: I had this post sitting in draft for about a year, and I have no idea why.

Thanks for subscribing to my RSS feed! If you have any thoughts or feedback on this post, send me an email or DM me on Bluesky.

Adding Topics (aka tags) in Astro

Tue, 11 Jul 2023 00:00:00 GMT

This month’s Virtual Coffee challenge is Build in Public. And I wanted to kick things off with some website updates. I’ve been meaning to add tags to my site for a long time. After poking around at other people’s sites, I decided to switch from the concept of tagging to the concept of topics. While the naming is different the process to adding topics was the same. In this post I want to share how I added topics, what I learnt, and what’s next.

How I added topics to my site

I mainly followed the Astro guide on building a tag index page.

Firstly, I created this structure in my project:

pages/
  topics/
    [topic].astro
    index.astro

index.astro is rendered when you go to /topics (example link).

[topic].astro is rendered when you go to /topics/:topic. Where :topic is something I define in my blog posts. Example, topics/api%20design/ (example link).

I then added the topics field to my front matter yml in my blog posts:

---
pubDate: 2023-04-05
updatedDate: 2023-04-05
title: "template"
description: "A template"
draft: true
topics: []
---

Added topics key in my config.ts file (source code)

topics: z
  .array(z.string())
  .optional()
  .default([])

Finally, to display the topics on my blog post, I made a component that is pulled into the Blog Post Layout:

BlogPost.astro

...
{topics && topics.length > 0 && <TopicList topics={topics} />}
...

TopicList.astro

---
const { topics } = Astro.props;
---

<p class="flex space-x-3">
{topics.map((topic: string) => (
  <a href={`/topics/${topic}`}>{topic}</a>
))}
</p>

Deep dive (aka what did I learn)

Digging into the index.astro and [topic].astro files a bit more.

index.astro

The way we get a list of topics to display on the /topic page is through this code (source code):

const posts = (await getCollection('blog'))
const topics = [...new Set(posts.flatMap((post) => post.data.topics))];

This line will get all my posts from my blog folder, pull out all of the topics, and return an array of topics with no duplicates.

[topic].astro

To generate the corresponding topic endpoints like /topic/api%20design/ I needed to modify the getStaticPaths() function in the [topic].astro. (source code). I forgot to modify it originally, and I was very confused when I kept getting a 404 not found error when trying to navigate to a topic page 🤦🏻!

export async function getStaticPaths() {
  const posts = (await getCollection('blog'))
  const topics = [...new Set(posts.flatMap((post) => post.data.topics))];
  return topics.map((topic) => ({
    params: { topic }
  }));
}

getStaticPaths() is an Astro function that Astro uses to generate each page at build time. It returns an array that looks something like this:

[
  { params: {topic: "API Design"} },
  { params: {topic: "Productivity"} }
]

What’s next

I’m not super happy with how my topics are styled. But I’m also not sure how I would style them - I’m open to suggestions! Next up for me is writing an About me page. I don’t know why but I find it incredibly hard to write! I’ll be chugging away at it while trying to come up with a better styling in the meantime.

Thanks for subscribing to my RSS feed! If you have any thoughts or feedback on this post, send me an email or DM me on Bluesky.

What is the right amount of testing?

Sun, 11 Jun 2023 00:00:00 GMT

What is the right amount of testing?

Over the years my answer to this question has changed drastically. From fully embracing integration testing and requiring code coverage numbers on Pull Requests (PRs). To writing only unit tests covering the critical paths of the application. Leaving much of code untested.

Of course there’s no definitive answer for the right amount of testing. If there was, everyone would be doing it. Instead, I’d like to share what I consider a good default amount of testing. But before diving into that, let’s discuss the problem we’re trying to solve.

The primary goal of testing is to prevent bugs from reaching production. Too little testing leads to a brittle application. As more features get pushed out, more fires need to be fought. And eventually you’re worried that any change might cause something unrelated to break.

In response, we swing the pendulum to the other side. We write extensive suites of integration tests that get run on every PR. Code coverage numbers need to be met before a PR can be approved. We aim to test every possible path, leaving no room for bugs to slip through. Unfortunately, our feedback loops begins to slow down. And meaningful features take longer to be released.

Both of these are extreme ends of the spectrum. Too little testing leads to brittle applications. Exhaustive integration tests slow down feedback loops and delay feature releases. So what is a happy middle ground? Here’s what I think we should default to.

Write unit tests for all your changes. Testing error paths but not every combination of errors/inputs. Pick your edge cases that cover critical aspects of your code. Here’s some examples:
- Test paths that have a complex outcome and/or an error you display to the user.
```
if condition
  complex_outcome
else
  error_to_user
end
```
- In general, you don’t need to test well-established, trusted libraries. But you should manually validate library calls (see more on manual testing below).
```
# Don't test that Rails will save a model to the database.
model = Model.create
# Don't test S3 library will delete the bucket
s3Client.delete_bucket({  bucket: "bucketName", })
```
- Test for public not private methods. Unexpected changes to private methods should be caught in the public method tests.
```
# Test this method
def public_method
  something = do_something
  do_something_with(something)
end

private

# Don't test these methods
def do_something
  ...
end

def do_something_with
  ...
end
```
Test suites should run fast enough that by the time you make a coffee your build is complete (faster is better). That means unit tests over integration tests.
If possible, always manually test your change. Keep the process lightweight and repeatable by writing down your steps. Don’t test the entire app behaviour on every change. But allow someone on your team to vet your change by running through the testing steps you wrote down. If you find yourself testing the same thing over and over again, look to automate it (i.e. write a unit test).
Manually testing is especially important if testing a third party service/api. Mocking in unit tests is needed for fast tests but you need to validate your mocks in the real world. Validating third party services/api is the purpose of integration tests. But arguably, a quick manual test may be all that’s needed along with good observability.
Bonus points if you have a cloud developer environment or a developer preview on your PR that allows someone to validate your changes without having to run your code on their machine. This approach also promotes collaboration between your team!
Finally, have a robust CI/CD pipeline that lets you rollback bad builds, or feature flags to quickly turn off a breaking change. Having the right monitors in place will tell you if something is broken before it causes too much damage. Expect that bugs will happen even with a proper amount of testing.

While there’s no one size fits all solution for the right amount of testing. I’ve found that these defaults have worked well in the past. They strike a balance between maintaining healthy developer feedback loops while minimizing game breaking bugs that make it to production.

Thanks for subscribing to my RSS feed! If you have any thoughts or feedback on this post, send me an email or DM me on Bluesky.

Developer productivity with Github Codespaces

Fri, 19 May 2023 00:00:00 GMT

During my time at Shopify, I had the opportunity to work with a cloud development environment - and I was sold. Since then, I set out trying to recreate a similar experience for my personal development. Enter, Github Codespaces. I’d like to share my thoughts on using Codespaces and why I believe it will greatly benefit developer productivity.

Exploring Codespaces: My Motivations

There are a couple of reasons why I decided to explore GitHub Codespaces:

Escape from Bare Metal Setup: I’m tired of installing and managing specific versions of Ruby, Node, Postgresql across my various projects.
Onboarding Developers: one of my aspirations is to run my own company, I wanted to explore how cloud development environments like Codespaces could facilitate the smooth onboarding of new engineers.

The Github Codespaces Workflow

Firstly, install the Github CLI tool. Being able to use the terminal over the browser has significantly streamlined my experience. Once authenticated with the Github CLI, my workflow is as follows:

Creating a Codespace: Initially, I needed to create a Codespace. Note that if you cloned a project and you’re in that folder, the Github CLI tool will use that project as the default

gh codespace create

Getting to Work: To start working on my application, I ran the following command, selecting the Codespace I had just created. There’s a short delay as the environment is being set up:

gh codespace code

Astro Aside: Since I’m running the Codespace for my Astro site, I made an update to the dev command in the package.json file:

astro dev --host

This configuration binds the Astro local server to any IP, allowing proper connection when Codespace forwards the localhost port.

Codespace Logging: I also experimented with Dotfiles for my Codespace, which customize the Codespace developer environment. The Codespace logs proved invaluable for debugging my changes as the Codespace started:

gh codespace logs

Initial Considerations

Based on my early experience, here are a few considerations regarding Codespaces:

Overkill for Simple Projects: Codespaces is overkill for simple projects like my Astro blog. Given the minimal version dependencies and longer startup time compared to setting up my Astro project directly, it doesn’t give that much benefit.
Treat Codespaces as Ephemeral: It’s important to treat Codespaces as ephemeral environments. That means commit often! Any uncommitted changes will be lost when the Codespace is destroyed (which occurs by default every 30 days).

The Untapped Potential

I’m totally bought into the idea of cloud development environments. Github Codespace is one option there’s also others such as Gitpod.

Imagine this situation, you’re starting a new job, excitedly setting up a fresh codebase, only to encounter a mysterious, undocumented error. You turn to your onboarding buddy for help. They speak the dreaded words, “weird - works on my machine”. A response that leaves you navigating a labyrinth of debugging all by your lonesome. Okay I’m being a little dramatic, but we’ve all experienced these “works on my machine” moments that can send you spiraling.

With a cloud developer environment like Codespaces, someone can get their project up and running in minutes rather then days. Think about the time and headache saved! These environments can be used for more then onboarding too. You could use them as developer previews, sharing a URL of your app running in the Codespace so anyone can test your changes.

While I haven’t found a project to fully utilize Codespaces yet, I’m psyched to keep exploring it. Stay tuned, I’ll keep this post updated.

Thanks for subscribing to my RSS feed! If you have any thoughts or feedback on this post, send me an email or DM me on Bluesky.

Learning about API First Design

Mon, 08 Aug 2022 00:00:00 GMT

Building an API using an API first approach means that the API is the core deliverable. The API is treated like a core product that other products build on top of. Rather then products being built first then an API is slapped on top of them. There’s another term - API design first which is focused on how you design your API. Whereas with API-first you focus on both design and building the API first.

I think of it like a restaurant. With API First you define exactly how the wait staff will send orders to the kitchen. In this case, we could say that wait staff will only use numbers and then the kitchen will have some mapping on their end to figure out what dish to cook. With API design first, the wait staff and kitchen will come together and figure out what the language is around an order. They may come up with a set of rules:

These set of abbreviations will mean this (e.g. bf = beef)
Numbers are okay or not. The kitchen will have some mapping on their end.

In API design first, it’s all about communication. While API first is more rigid in how the API is defined in the first place. In both examples, building and API was about defining a contract - there are overlaps between the two approaches.

It feels like API first and API design first really go hand in hand. Building an API that interfaces with other teams means you need to discuss design even if you’re building API first. I would love some examples where this isn’t the case!

Finally, one way to describe your API/create a contract is through a specification language like OpenAPI.

Resources

Thanks for subscribing to my RSS feed! If you have any thoughts or feedback on this post, send me an email or DM me on Bluesky.

Redesigning my Blog: 2023

Wed, 06 Apr 2022 00:00:00 GMT

If you’ve been here before you might have noticed a few things have changed. That’s right, I blew up my blog and rebuilt it from ground up! Two years ago I wrote this line in a previous blog redesign post:

I heard of this new Static site generator, Astro that looks very interesting… Nope. Not going down that path.

Well my friend, I moved from SvelteKit to Astro 😅. On top of a framework change, I also changed my design to embrace minimalism. I wanted to focus on content and nothing else, being heaviy inspired by Irrational Exuberance. In my previous site, I fell into the trap of spending my energy building features that weren’t the core reason of why someone would come to my site. With the stage set, let’s talk through some of my thoughts so far on the rewrite:

Moving fast with Astro & Tailwind

Getting up and running with Astro was a really nice experience. For the first time, I feel like I have a static site generator that is straightforward to use. But offers the additional flexibility to add more reactive features using Astro islands. No shade to SvelteKit though! I loved it but I felt like it was too much for my needs. I’m trying to embrace minimalism in all aspects, including framework features.

Another thing that Astro gives is typing on my Markdown frontmatter. I love this feature! It means that I can have build time errors if I have a typo or if I’m missing a frontmatter key. You can read more about defining collection schemas on the Astro docs.

I also moved to Tailwind for this rewrite and deleted most of my CSS in the process. Tailwind is a utility first CSS framework that allows you to style an element through class names. For example, here’s how my links are styled:

<a href="" class="no-underline font-semibold dark:text-teal-400 text-logo-green before:bg-teal-600 before:dark:bg-teal-300 before:rounded-lg hover:before:opacity-100 hover:dark:text-teal-300 hover:text-teal-600 relative">
  Link
</a>

Honestly, the upside of not having to maintain my css far outweighs the downside of poor readibility on elements with lots of classes. Getting Astro setup with Tailwind was a breeze with the @astrojs/tailwind integration.

Changing URL namespacing

I moved away from the /garden/<blog-title> hierarchy and flattened it to /<blog-title>. Swyx writes:

Personal sites of frequent speakers often opt for TWO namespaces: /writing and /speaking. My current site (as of Sept 2020) uses this, but I have grown to dislike it: I will often speak about what I write, and write about related things I speak about. Why separate them? It is more effort to make my talks discoverable to my readers and vice versa.

In his article Against Namespacing Personal Sites. And while I agree with this idea, I tried to overcome that by having a garden/ namespace. But I’ll admit, the naming is horrible. If you don’t know what a digital garden is then a garden/ namespace makes no sense. You can set this up in Astro by adding a [...slug].astro file at the root of src/pages folder.

Generating OpenGraph (OG) Images on the fly

Honestly, this is my favourite part of the redesign. I’m using Netlify Edge functions to generate OG images on the fly. This image will show up when you share this post on Twitter (or Facebook but who still uses that). Shoutout to Kevin Zuniga Cuellar, whoe wrote about og images on the edge. The annoying parts of building this were:

Debugging was painful because there wasn’t great error messages when something broke. And every change took a second of build time so the feedback loop was pretty longer then I wanted.
You can’t access folders with Netlify Edge functions which meant that I can’t use custom fonts unless they’re loaded on some CDN.

I’m trying to get better at building in public so this site is far from finished. I want to focus on content next. Over time, I’ll be adding pages for tags, featured and an about page. If you’re curious, here’s a screenshot of the old homepage and you can still play with the old site here.

Thanks for subscribing to my RSS feed! If you have any thoughts or feedback on this post, send me an email or DM me on Bluesky.

Learning about Open API

Tue, 05 Apr 2022 00:00:00 GMT

OpenAPI is a specification (OpenAPI Specification (OAS)) that is a way to define how you interact with an API without needing to understand implementation logic. You describe the capabilities of the service and someone can understand what it does without needing to look at source code, documentation, or network traffic inspection. The OpenAPI definition can then be used by documentation tools or code gen tools to display the docs or generate servers and clients respectively.

In other words, OAS is a standardized way of describing your API that isn’t tied to any programming language. A reason you would write an OAS document is to help during the API design lifecycle (reference). You can use this document with a tool such as Optic to prevent things like breaking changes from your implementation versus the design.

Backlinks

Learning about API First Design

Thanks for subscribing to my RSS feed! If you have any thoughts or feedback on this post, send me an email or DM me on Bluesky.

Redesigning my Blog: 2021

Tue, 09 Nov 2021 00:00:00 GMT

What will you learn:

What technology can be used to build a blog
The process I have when building a site

TL;DR - This site is built with SvelteKit and hosted on Netlify. It’s open sourced, take a gander!

Some time ago, I embarked on a journey to redesign my website. I convinced myself that I needed a fresh, clean, minimalistic, snazzy, whimsical, <insert adjective> site to be able to write content.

While this reasoning is flawed. Rebuilding my site allowed me to play with SvelteKit. A framework for Svelte that was fresh out of beta when I first started the rebuild. It was also an opportunity to practice my design skills. Opting this time around to design most of my screens in Figma before building.

Throughout this entire process I made heaps of mistakes and discovered what worked and what didn’t. All the lessons that I’m excited to share!

Designing upfront

Tools: Figma

Resources:

Refactoring UI
Figma Youtube Channel
Level Up Tuts: Design Systems in Figma (Paid)
Design + Code: UI Design for Developers (Paid)

I’m no design guru so I can’t speak too much to colour theory, typography and other design-y stuff. But here’s what worked for me.

Start with the layout

I focused initially on building the layout of my site (both mobile and desktop) using grayscale and blocks. I went around to all the sites that I found aesthetically pleasing and took inspiration of their layouts. Then I used these blocks to play around with how my content would be structured.

This was focused only on the homepage since I thought that would be the most visually complex page. But I would have found value doing it for the posts page as well.

What I was looking for was:

Visual hierarchy - do the blocks flow and fit together.
Spacing - Is there room for the blocks to breathe or does it feel cramped?
Focus - Is there too much information presented at once?

Setting up a design system

The next thing I set up was a design system. This system standardized the colours and the fonts that I would be using across my design. Building this upfront saved a bunch of time later on. Changes to font sizing or colour could be done in one place and it would adjust throughout all my design files. During this phase, I used Type Scale to define my font sizes and line heights. And then a Figma plugin, A11y - Color Contrast Checker, helped me find accessible font colours for light and dark backgrounds.

Going from grey blocks to pretty colours

After picking a layout, it was only a matter of replacing those gray blocks with actual content. I used components in Figma to standardize what a Post card would look like. You can also give properties to components. This means you can define components in different active states or theme options, like my post cards which have both a dark and a light theme property.

The goal at this stage was to have my site look as close as possible to the finished product. This step took time. A shit ton of time. Much of it was spent figuring out how to use Figma. But there was also time spent second guessing my design and tinkering with different layouts. Ultimately, these making these decisions up front meant that I could spend more time working on the build.

The Tech Stack

Resources:

I have a tendency to get distracted by shiny things. And this blog is no exception. When I found out that SvelteKit was coming into public beta, I jumped on the bandwagon. This involved a full rewrite of my site. I was coming from 11ty and nothing survived the transition.

If you’re familiar with React and Next.js - SvelteKit offers similar sensibilities. It offers both server side and client side rendering. A built in router. Developer environment optimizations. And Svelte, which has been a joy to use.

Styling is done using SCSS, a css preprocessor. Out of the box, styles in Svelte are scoped per component. Posts are processed using Mdsvex. This package is similar to MDX for React. It lets me define components and import them into my markdown. For example, this alert box is a Svelte component! I just moved my site to Astro so this won’t work anymore.

I can then import the Alert box into any of my markdown files:

<script>
  import AlertBox from "$lib/AlertBox.svelte";
</script>

# Markdown header
Some paragraph text

<AlertBox content="Hiii I'm a Svelte component!" />

For the search, I use Fuse.js to do the fuzzy search matching. The search and tag filtering probably warrants it’s own post. If you’re interested bug me. But I’ll give a quick rundown of it. Fuse.js takes in all my posts, and keys off my post titles and tags. In other words, you can search for both titles and tags. Svelte will then react to typing, by using a reactive declaration $:, and it will call Fuse to return results based on the current search. This search should also be scoped to the currently selected tags (or all tags if none are selected). To be honest, I’m not entirely happy with how I built this. It works but it feels… wrong. I’m currently in the process of refactoring my search, but if you want to see it in it’s current state - the code lives here.

Finally, the site is deployed on Netlify which has been the hosting platform I’ve used since my 11ty days. It’s been great (and free) for my use case. SvelteKit has a Netlify Adapter that creates a Netlify function for dynamic server side rendering. Along with hooking into Netlify fun-ness like Netlify redirect rules and forms.

Retrospective

Decisions made

Other than the search and tagging functionality, this build was pretty straightforward. But even so, there are decisions that I made that are hard to reverse. I wanted to share these in case you’re facing a similar decision!

I was thinking about using TailwindCSS and decided against it. Instead, I rolled my own plain SCSS. The main reason behind this was speed. Both in terms of reducing package load during development or production. And also the time it would take to learn Tailwind. Scoped styles in Svelte makes maintaining CSS less cognitively demanding. You don’t need to think about the cascades in terms of the application. Only the component.
Choosing SvelteKit was done out of passion (or FOMO). But one reason I wanted to move off 11ty in the first place was to have greater interactivity. I was inspired by Josh Comeau’s site which is full of whimsy. That is something that I wanted to strive for with SvelteKit. It’s a work in progress for my site.
I spent a little time researching other hosting platforms (Vercel, Render, Begin), but went with Netlify in the end. It was what I was used to. And I was happy with it’s free tier. Another reason why I decided to stick with Netlify was DNS records. DNS is a pain to manage, and I don’t really want to deal with it.

Challenges Faced

Documentation, documentation, documentation. SvelteKit was newly public when I started using it. And I spent a lot of time being stuck. I was grateful for the Svelte community for answering my questions. But working on this project made me appreciate the importance of docs.
It took my a very long time to ingest the Markdown files. Specifically, it was how to load them and where I should be loading them. I can chalk this up to not understanding how SvelteKit & Svelte works.
Battling Flash of Unstyled text (FOUT). FOUT is the default text that appears for a moment while your site loads in the css files. I still haven’t fixed this. Initially, I attempted to not load the site until the css files were loaded. However, this fix ended up causing an issue where I never server side rendered my website. In other words, if you didn’t have javascript loaded, all you would see is a blank page!
The search & tag functionality. I was pretty happy with myself when I got this working. I think it’s overly complex and in need of a refactor. But I spent a lot of time playing around with stores and tinkering with Fuse.js.
Metatags were surprisngly hard to add! I think I was spoilt coming from 11ty with Nunjucks. What I really wanted was a default set of metatags that I could override within individual pages. In the end, I duplicated the metatag information across multiple files. Thinking about it now, there has to be a better way to do this.

Surprises

Writing Svelte is a joy. Most of it is plain HTML and CSS, and the components are structured similar to Vue. Having scoped CSS out of the box is also incredible. Some of my favourite Svelte features are built in stores and reactive declarations. They’re a little weird at first but they cut down on so much boilerplate code!
How much SvelteKit gets out of your way when developing. From the project setup prompts, to adding new packages and features, to the build times, it all feels… svelte.
The weirdness of having two script tags in a single component. Also, how quickly I got used to it. If you have two script tags, one (denoted by context='module') is executed during server side rendering, while the other is executed during client side. If you have one script tag, that code is executed both in server side rendering and client side.
Time it took for the build. Estimating is hard and it will always be a perpetual surprise. Over time, I’ve gotten better at it. Like sometimes I can tell when someone is about to surprise me because they have this look in their eyes. But I still can’t predict what they’re going to do.

What’s next?

I heard of this new Static site generator, Astro that looks very interesting…

Nope. Not going down that path.

What’s next is to populate this site with more content. I’m also working on a better flow to get my posts from draft to publish. Doing some refactoring, lots of polishing. And more whimsy, because you can never have enough. If you’re curious you can view my project roadmap and you can see the source code for my site here.

Thanks for subscribing to my RSS feed! If you have any thoughts or feedback on this post, send me an email or DM me on Bluesky.

Excerpts with Eleventy

Fri, 28 Aug 2020 00:00:00 GMT

Update: I opened a Github issue for this all the way back in Aug 2020. Here’s a better approach then mine (linked comment):

In .eleventy.js:

eleventyConfig.setFrontMatterParsingOptions({ excerpt: true });

In the template:

{{ article.data.page.excerpt | md | safe }}

The md filter looks like:

// .eleventy.js
const markdownIt = require("markdown-it");
// ...
eleventyConfig.addFilter("md", function (content = "") {
  return markdownIt({ html: true }).render(content);
});

I 100% struggled with getting excerpts in Eleventy (11ty). It seems so simple, but I couldn’t figure it out.

I had two issues. Firstly, I got excerpts working using 11ty’s custom frontmatter data, unfortunately the excerpt did not render markdown. Which resulted in something that looked like this:

Secondly, I found a great blog post: Creating a blog with Eleventy that detailed how to create an excerpt shortcode. This shortcode defaulted to taking the first paragraph as an excerpt. Or whatever custom excerpt tag you wanted. However, the shortcode ended up rendering the HTML tags. The opposite problem to 11ty’s excerpt. Rendering HTML resulted in some weird looking excerpts:

I could not find a happy medium! Here’s what I really wanted out of an excerpt:

Cap at 200 characters
Strip any HTML tags.
Add an ellipses at the end of the excerpt
Automatically pull the excerpt, no need for specific tags.

Thankfully, the blog post above gave me all the code I needed. I just had to make a few modifications.

The modifications to extractExcerpt

First, install striptags. We will be using this library to get rid of the HTML tags:

npm install striptags

Now, we want to require striptags in .eleventy.js. At the top of the file:

const striptags = require("striptags");

Next, add the extractExcerpt method at the bottom of the .eleventy.js file. This method is a modified version from the blog post to fit the criteria I wanted:

function extractExcerpt(article) {
  if (!article.hasOwnProperty("templateContent")) {
    console.warn(
      'Failed to extract excerpt: Document has no property "templateContent".'
    );
    return null;
  }

  let excerpt = null;
  const content = article.templateContent;

  excerpt = striptags(content)
    .substring(0, 200) // Cap at 200 characters
    .replace(/^\\s+|\\s+$|\\s+(?=\\s)/g, "")
    .trim()
    .concat("...");
  return excerpt;
}

Add this line in the eleventyConfig block. This step is also from the blog post:

module.exports = function(eleventyConfig) {

  eleventyConfig.addShortcode("excerpt", (article) => extractExcerpt(article));

  ...

}

Finally, we can see our results.

Hooray! Nothing looks too off. I do see Addendum # which is caused by markdownIt adding an anchor permalink to the header. I can live with it though.

Looking back on this problem, the solution seems so easy. But I spent almost a week trying to figure out how to do this properly. I think it’s a combination of being stubborn with wanting the 11ty custom frontmatter solution to work, and my inability to Google. Really need to Google or ask for help sooner. I don’t know about you, but knowing when to ask for help is an endless struggle for me. Bar this one issue, I’m loving 11ty so far! Hopefully, this post will solve your excerpt woes.

Thanks for subscribing to my RSS feed! If you have any thoughts or feedback on this post, send me an email or DM me on Bluesky.

How to setup CI with Phoenix and Github Actions

Fri, 24 Jul 2020 00:00:00 GMT

⚠️ This post may contain outdated content

Continuous Integration (CI) is the act of automating the build and testing of your code when it’s committed to version control. For a small app like my blog, I wanted to setup CI without needing to create accounts with TravisCI or CircleCI. This is where Github Actions comes to the rescue. Actions is a workflow automation tool and has a variety of different uses. You could send an SMS, build and push a docker image, run code coverage, and much more. Today, I want to show you how to use Github Actions to setup a CI pipeline for your Phoenix app.

Create the Workflow

This tutorial assumes, you already have a Phoenix app and you’re using Github as your repository. In your project, create a file under <your-phoenix-app>/.github/workflows. Choose any name for your file and save it with the the yaml (.yml) extension e.g. phoenix_test.yml. Add the code below to the file. Before we commit and push let’s understand what’s actually happening.

# <your-phoenix-app>/.github/workflows/phoenix_text.yml
name: Elixir CI

on:
  push:
    branches: [ master ]
  pull_request:
    branches: [ master ]
  workflow_dispatch:

jobs:
  run-tests:
    runs-on: ubuntu-latest
    container: node:10.18-jessie
    services:
      postgres:
        image: postgres:12
        ports: ['5432:5432']
        env:
          POSTGRES_PASSWORD: postgres
        options: >-
          --health-cmd pg_isready
          --health-interval 10s
          --health-timeout 5s
          --health-retries 5
    steps:
      - uses: actions/checkout@v2
      - uses: actions/setup-elixir@v1
        with:
          elixir-version: '1.10.3'
          otp-version: '22.3'
      - run: mix deps.get
      - run: mix deps.compile
      - run: cd assets && yarn install --frozen-lockfile
      - run: mix test
        env:
          DB_PASSWORD: postgres
          DB_HOST: postgres

Code Breakdown

Before we dive in, let’s quickly touch on the basic structure of an Action. A Github Action consists of a workflow. A workflow has many jobs. And a job is made up of steps. In the code above, our workflow is the entire yml file. We’ve named our workflow Elixir CI. Inside our workflow we have one job, run-tests. If we had multiple jobs, they would run in parallel. Inside a job we have many steps. Each step will run sequentially. Once all the steps have finished our job will be complete. Once all the jobs have finished our workflow will be complete. And once our workflow is done Github will report the results. Now that we know the structure, let’s move on.

name: Elixir CI

on:
  push:
    branches: [ master ]
  pull_request:
    branches: [ master ]
  workflow_dispatch:

...

name defines the name of our workflow. You will see this name when you view your action on Github.

on defines the events that trigger your workflow. In this case, we will run our workflow when we push to master. Or when a pull request is opened against master.

workflow_dispatch allows us to manually trigger our builds. This key is optional. Since we have a pretty simple workflow, we don’t really need this. But it can be helpful for debugging. Note, that there’s no value. If the key exists, Github will configure everything properly.

...
jobs:
  run-tests:
    runs-on: ubuntu-latest
    container: node:10.18-jessie
...

jobs defines the jobs that your workflow runs. We only have one job and it’s called run-tests. You could name your jobs anything.

runs-on declares what virtual machine your Github Action runs on. Your options are Mac, Windows, or Linux. Most of the time you would run on Linux. But for some cases you might want to run Windows or Mac. For example, if you needed to convert a Microsoft powerpoint to a PDF, you would have to run your Action on windows. An important concept to remember is that every Github Action runs on a virtual machine.

container declares containers for our VM. A Github Action will spin up a virtual machine (VM). Whatever you run will be run on that machine. In this case, we are adding node to our VM via a container.

services:
  postgres:
    image: postgres:12
    ports: ['5432:5432']
    env:
      POSTGRES_PASSWORD: postgres
    options: >-
      --health-cmd pg_isready
      --health-interval 10s
      --health-timeout 5s
      --health-retries 5

services declares the tools needed to run our task. These tools are installed via a container, with networking already configured. In our case we want to setup Postgres for our tests to run on. We do this by pulling in the postgres:12 container. We expose the port 5432 and set our password to postgres. Finally, we do a health-check on the database to make sure it’s started correctly by passing in some options. pg_isready is a utility command found in Postgres that checks the connection status of the server. Note: >- is a special yml syntax. It means anything after >- is combined as one line with no newline character (\\n).

steps:
  - uses: actions/checkout@v2
  - uses: actions/setup-elixir@v1
    with:
      elixir-version: '1.10.3'
      otp-version: '22.3'
  - run: mix deps.get
  - run: mix deps.compile
  - run: cd assets && yarn install --frozen-lockfile
  - run: mix test
    env:
      DB_PASSWORD: postgres
      DB_HOST: postgres

Finally to the fun part! Everything before steps was needed to set up our environment. Now we can actually do things. You’ll notice 4 keywords here: uses, with, run, env. Let’s go through each one.

uses selects an action to run as a step. Github has a rich ecosystem of actions. And we can reuse these actions in our own workflow. An example of this is the actions/checkout@v2. The checkout action pulls our code down from Github onto the VM.

with passes input parameters to the external Action. In the case of actions/setup-elixir@v1 we are passing in the elixir version and the Erlang OTP version. Note: setup-elixir works best if you specify the exact versions.

run executes a command line command.

env sets environment variables on that command. For example, when running mix test we will set the DB_PASSWORD and the DB_HOST environment variables.

Knowing these keywords, we can read our steps like this:

Pull down our codebase using a checkout action.
Install Elixir v1.10.3 and Erlang OTP v22.3 using the setup-elixir action.
Get the dependencies for our Phoenix app.
Compile the dependencies.
Install the frontend assets using yarn.
Run our tests with two environment variables DB_PASSWORD and DB_HOST.

Gotcha

Since we’re running everything inside the docker container, the Postgres service will need a postgres hostname. If you’re like me, you may have configured test.exs to connect to your local database with different credentials. To get the mix test step working you can edit your test.exs to include the System.get_env command. Where app is your Phoenix application name.

config :app, App.Repo,
  username: "postgres",
  password: System.get_env("DB_PASSWORD") || "localhost",
  database: "app_test#{System.get_env("MIX_TEST_PARTITION")}",
  hostname: System.get_env("DB_HOST") || "localhost",
  pool: Ecto.Adapters.SQL.Sandbox

Running the Workflow

Commit your changes and push to Github. Now go to Github and navigate to the Actions tab. Here, you will see any current or past workflow runs. Every run will have a commit, the branch the commit was on, and some other metadata.

If you wanted to manually run your workflow you will have to click into the workflow. My workflow name is Elixir CI so clicking into it gives me the following page. On this page, you can run your workflow by clicking the button.

What’s next

Now every time you commit your code your tests will run and you will be notified if anything broke! The next evolution would be to automatically deploy our application to production (continuous deployment).

Thanks for subscribing to my RSS feed! If you have any thoughts or feedback on this post, send me an email or DM me on Bluesky.

Building a blog with Phoenix: Getting started

Thu, 09 Jul 2020 00:00:00 GMT

Today, I want to show you how to start building a blog using Phoenix. You can find the source code here: https://github.com/jonathanyeong/phoenix_blog/tree/v0.0.1. We are using Phoenix version 1.5.3 and Elixir version 1.10.3. We will cover:

Project Setup
Generate migration
Add Routes
Add the Post Controller
- Breakdown
Add Post View & Templates
- Breakdown
Conclusion

Project Setup

After installing Phoenix and Elixir (see Phoenix docs). Setup your new blog application.

  mix phx.new phoenix_blog
  cd phoenix_blog/
  mix ecto.create

Generate migration

Firstly, we need to create the Post table. We can use the mix task phx.gen.schema to generate a schema and a migration file (see the docs for more info). The schema is how we represent information from the database within our application. While, the migration contains the commands that run on the database itself.

    mix phx.gen.schema Post posts content:text title:string
    mix ecto.migrate

Add Routes

Now that we’ve run the migration, we need to add routes to our app so that we can view and create posts on the front-end. We will be using resources to generate resourceful routes for us.

In lib/phoenix_blog_web/router.ex

  scope "/", PhoenixBlogWeb do
    resources "/posts", PostController
  end

If you run mix phx.routes. You should see:

  post_path  GET     /                                      PhoenixBlogWeb.PostController :index
  post_path  GET     /posts                                 PhoenixBlogWeb.PostController :index
  post_path  GET     /posts/:id/edit                        PhoenixBlogWeb.PostController :edit
  post_path  GET     /posts/new                             PhoenixBlogWeb.PostController :new
  post_path  GET     /posts/:id                             PhoenixBlogWeb.PostController :show
  post_path  POST    /posts                                 PhoenixBlogWeb.PostController :create
  post_path  PATCH   /posts/:id                             PhoenixBlogWeb.PostController :update
              PUT     /posts/:id                             PhoenixBlogWeb.PostController :update
  post_path  DELETE  /posts/:id                             PhoenixBlogWeb.PostController :delete

Now if you start the Phoenix server

  mix phx.server

And navigate to localhost:4000/posts you will get an error. Let’s fix this.

Add the Post Controller

All of these routes point to a nonexistent Post Controller. Lets create one and add the following code.

  # lib/phoenix_blog_web/controllers/post_controller.ex
  defmodule PhoenixBlogWeb.PostController do
    use PhoenixBlogWeb, :controller

    alias PhoenixBlog.{
      Post,
      Repo
    }

    def index(conn, _params) do
    posts = Post |> Post.ordered() |> Repo.all()
      render(conn, "index.html", posts: posts)
    end

    def new(conn, _params) do
      changeset = Post.changeset(%Post{}, %{})
      render(conn, "new.html", changeset: changeset)
    end

    def create(conn, %{"post" => post_params} = _params) do
    changeset = Post.changeset(%Post{}, post_params)
    case Repo.insert(changeset) do
      {:ok, _log} ->
        conn
        |> put_flash(:info, "Success - created a Post!")
        |> redirect(to: Routes.post_path(conn, :index))
      {:error, changeset} ->
        conn
        |> put_flash(:error, "failure couldn't create post")
        |> render(:new, changeset: changeset)
    end
    end
  end

Jump to Post View & Templates.

Breakdown

  defmodule PhoenixBlogWeb.PostController do
    ...
  end

Controllers are just modules in Elixir. The module name (PostController) needs to match the filename post_controller.ex.

    use PhoenixBlogWeb, :controller

use will require and inject the Phoenix.Controller code and the Plug.Conn into our Post Controller. It does this by calling the macro __using()__ . You can see the code injected here.

    alias PhoenixBlog.{
      Post,
      Repo
    }

Alias is used to define shortcuts. Instead of writing PhoenixBlog.Post we can instead write Post.

    def index(conn, _params) do
      posts = Repo.all(Post)
      render(conn, "index.html", posts: posts)
    end

The index method takes in a conn and a params argument. conn comes from Plug.Conn. Which was injected above via use. conn is a module that defines low level functions such as request information. Next is params, we will prepend it with _ to signify that we aren’t using it. We then call Repo.all(Post) to pull all the posts from the database. These posts are assigned to a variable which we can access in the index view via @posts.

    def new(conn, _params) do
      changeset = Post.changeset(%Post{}, %{})
      render(conn, "new.html", changeset: changeset)
    end

The new method creates a changeset that is passed to the new view. A changeset in Elixir will only allow data with specific information to go through. It will also complain if it expects data but doesn’t receive it. Post.changeset/2 method takes in a Post struct and some attributes. Since we’re creating a new Post, there are no attributes so instead we’ll pass in an empty map.

    def create(conn, %{"post" => post_params} = _params) do
      changeset = Post.changeset(%Post{}, post_params)
      case Repo.insert(changeset) do
        {:ok, _log} ->
          conn
          |> put_flash(:info, "Success - created a Post!")
          |> redirect(to: Routes.post_path(conn, :index))
        {:error, changeset} ->
          conn
          |> put_flash(:error, "failure couldn't create post")
          |> render(:new, changeset: changeset)
      end
    end

The create method is pretty big so let’s break this down to smaller parts.

    ...%{"post" => post_params} = _params

The first line of the method uses Elixir’s pattern matching to assign anything found in params["post"] to post_params.

    changeset = Post.changeset(%Post{}, post_params)

We’ve seen changeset being used for the new route. In the create route we’re passing in the post_params instead of an empty map. This creates a changeset that is populated by the form data. Which we’ll save to the database via:

    Repo.insert(changeset)

Repo.insert/1 will return one of two tuples.

    {:ok, _log} ->
      conn
      |> put_flash(:info, "Success - created a Post!")
      |> redirect(to: Routes.post_path(conn, :index))

On a successful insert into the database, it will display a success flash message and redirect to the index page where all the posts will be displayed.

    {:error, changeset} ->
      conn
      |> put_flash(:error, "failure couldn't create post")
      |> render(:new, changeset: changeset)

On an error inserting into the database, it will display an error flash message and re-render new.html.eex.

Add Post View & Templates

Phoenix’s has a strong naming convention, which will link templates in the post directory and the view, post_view, to the Post Controller.

Templates in Phoenix are written in eex which stands for Embedded Elixir. They are the building blocks to a webpage. When we start the Phoenix server, templates get rendered into the view and displayed as html.

    # lib/phoenix_blog_web/views/post_view.ex
    defmodule PhoenixBlogWeb.PostView do
      use PhoenixBlogWeb, :view
    end

    # lib/phoenix_blog_web/templates/index.html.eex.
    <h1>Blog Post</h1>
    <%= link "+ Add new post", to: Routes.post_path(@conn, :new) %>
    <%= for post <- @posts do %>
    <h2><%= post.title %></h2>
    <p><%= post.content%></p>
    <% end %>

    # lib/phoenix_blog_web/templates/post/new.html.eex
    <h1>New Blog Post</h1>

    <%= form_for @changeset, Routes.post_path(@conn, :create), fn f -> %>
      <label>
        title:
      </label>
      <%= text_input f, :title %>

      <label>
        Content:
      </label>
      <%= textarea f, :content %>

      <%= submit "Submit!" %>
    <% end %>

Breakdown

    # lib/phoenix_blog_web/views/post_view.ex
    defmodule PhoenixBlogWeb.PostView do
      use PhoenixBlogWeb, :view
    end

The Post view has a similar structure to the Post controller. use will inject the Phoenix.View code.

    # lib/phoenix_blog_web/templates/index.html.eex.
    <h1>Blog Post</h1>
    <%= link "+ Add new post", to: Routes.post_path(@conn, :new) %>
    <%= for post <- @posts do %>
    <h2><%= post.title %></h2>
    <p><%= post.content%></p>
    <% end %>

The index view will add a link that routes to the new Post path. It will also loop through all the posts and display the title and content. The @posts variable was set in the PostController index method.

    # lib/phoenix_blog_web/templates/post/new.html.eex
    <h1>New Blog Post</h1>

    <%= form_for @changeset, Routes.post_path(@conn, :create), fn f -> %>
      <label>
        title:
      </label>
      <%= text_input f, :title %>

      <label>
        Content:
      </label>
      <%= textarea f, :content %>

      <%= submit "Submit!" %>
    <% end %>

The form inside new.html will use the changeset variable we set in the PostController new method. If you want more information on the types of input fields, see the Phoenix docs. When the user clicks on submit, the form data gets sent to the PostController create method via Routes.post_path(@conn, :create).

Conclusion

Phew, we finally made it! Now if you start your webserver:

    mix phx.server

Navigate to localhost:4000/posts you should see Blog Post as a header. If you click on the link or go to localhost:4000/posts/new you should see a form to create a post.

Try implementing the update and edit route next! You can apply the patterns in new and create to help guide you. I hope this tutorial has highlighted how easy it is to get started with Phoenix. If you enjoyed this article please leave a comment below. Happy coding!

Thanks for subscribing to my RSS feed! If you have any thoughts or feedback on this post, send me an email or DM me on Bluesky.