DEV Community: Billy Le

Common Errors for New Flutter Developers: Tips and Fixes

Billy Le — Thu, 16 May 2024 00:00:00 +0000

I started learning Flutter this year to expand into different areas of development.

Because I'm new, I don't know my way around the ecosystem yet. Some minor setbacks are not unusual whenever I'm coming to a new technology or programming language.

Flutter can be frustrating in the beginning, but once you're around the bend, it becomes easier to work with.

I'm here to share with you some common errors that kept popping up and how I was able to fix them.

Installation problems and fixes

I found that installing manually by downloading a zip file gave me fewer errors than doing the installation via VSCode.

I don't remember all the details but somehow the PATH didn't register correctly. Whenever I ran, dart run build_runner build -d, to generate code, I received errors and I couldn't figure it out even though flutter doctor -v gave me all green check marks.

Somewhere along the way, the dart executable wasn't in my path and unsure where it exists.

So if you're starting your journey with Flutter, I suggest installing by downloading the zip file and carefully following the instructions.

Clean and repair cache

When I find that something goes wrong with Flutter, this is usually my first approach. I run these commands in order before I start researching for a solution.

Usually, it's a hit or miss but it gives me peace-of-mind that Flutter might not be the culprit and it could be something else like Xcode or a misconfigured setting.

If you don't have a build_runner, you can skip steps 3 & 4.

flutter clean
flutter pub cache repair
dart run build_runner clean
dart run build_runner build -d
flutter pub get
flutter doctor

Cocoapods errors

Cocoapods is a dependency manager used by Xcode and it's a requirement if you plan to build any apps for Apple.

This section is dedicated to some issues I ran into when working with Flutter.

Cocoapods not installed error

This one was quite frustrating and recurring.

Launching lib/main.dart on iPhone 15 Pro Max in debug mode...

Warning: CocoaPods not installed. Skipping pod install.

CocoaPods is used to retrieve the iOS and macOS platform side's plugin code that responds to your plugin usage on the Dart side.

Without CocoaPods, plugins will not work on iOS or macOS.

For more info, see https://flutter.dev/platform-plugins

To install see https://guides.cocoapods.org/using/getting-started.html#installation for instructions.

CocoaPods not installed or not in valid state.

Error launching application on iPhone 15 Pro Max.

Exited (1).

You can check if Cocoapods is installed by running gem list | grep cocoapods.

cocoapods (1.15.2)
cocoapods-core (1.15.2)
cocoapods-deintegrate (1.0.5)
cocoapods-downloader (2.1)
cocoapods-plugins (1.0.0)
cocoapods-search (1.0.1)
cocoapods-trunk (1.6.0)
cocoapods-try (1.2.0)

If you see Cocoapods listed there then the issue is not with the installation.

Here are some possible fixes:

Restart VSCode. You need to completely close all VSCode instances before opening the text editor again.
Reinstall Cocoapods:
- run sudo gem uninstall cocoapods. Select all versions.
- after uninstall is complete, run sudo gem install -n /usr/local/bin cocoapods
If using a Ruby Version Manager like rbenv:
- list all available Ruby version rbenv install -l
- install the latest Ruby version: rbenv install 3.3.0
- set global to 3.3.0 with rbenv global 3.3.0
- make sure the .rbenv/bin and .rbenv/shims are available to your PATH
- run gem install bundler
- perform option 2 again

Cocoapods base configuration

[!] CocoaPods did not set the base configuration of your project because your project already has a custom config set. In order for CocoaPods integration to work at all, please either set the base configurations of the target `Runner` to `Target Support Files/Pods-Runner/Pods-Runner.profile.xcconfig` or include the `Target Support Files/Pods-Runner/Pods-Runner.profile.xcconfig` in your build configuration (`Flutter/Release.xcconfig`).

To fix this issue, you'll need to modify two files where you'll remove the ? from #include? statement.

In ios/Flutter/Debug.xcconfig:

#include "Pods/Target Support Files/Pods-Runner/Pods-Runner.debug.xcconfig"
#include "Generated.xcconfig"

In ios/Flutter/Release.xcconfig:

You're going to add an extra #include here for the profile.xcconfig

#include "Pods/Target Support Files/Pods-Runner/Pods-Runner.release.xcconfig"
#include "Pods/Target Support Files/Pods-Runner/Pods-Runner.profile.xcconfig"
#include "Generated.xcconfig"

Target versions not supported

You might run into this issue when the version of your target platform isn't supported by a 3rd-party library that you've installed.

Here are some examples of what that might look like:

uses-sdk:minSdkVersion 16 cannot be smaller than version 23 declared in library [:audioplayers]

warning: The iOS Simulator deployment target 'IPHONEOS_DEPLOYMENT_TARGET' is set to 11.0, but the range of supported deployment target versions is 16.0 to 17.0. (in target 'firebase_core' from project 'Pods')

What you need to do is modify your targets for each platform you're deploying to. In my case, for Android and iOS, I edited these two files to set the minSdkVersion and the platform :ios.

In android/local.properties file, add the flutter.minSdkVersion on a new line and set it to the version you need.

flutter.minSdkVersion=21

For iOS, go to ios/Podfile file and uncomment where it says, platform :ios, '<version>' and specify the version.

# Uncomment this line to define a global platform for your project
platform :ios, '16.0'

If you're deploying to other platforms, say Windows or macOS, you will need to search the internet on how to update those values.

Launch the simulator from VS Code

This one was a bit tricky. When developing for Flutter in VSCode, you'll be using the debugger tool. When you start the debugging tool to launch your Flutter app, the device will often change.

Sometimes it will launch on my physical iPhone. Sometimes it will launch for my macOS. Neither of which I want since I only want to run an iOS simulator.

My approach to this is to use the Flutter: Launch Emulator from the Command Palette to launch the simulator separately, and then run the debug tool.

To do this, open the Command Palette by using the shortcut, (⌘ + Shift + P).

Begin typing Flutter and you'll see a list of options you can choose from. When you select Flutter: Launch Emulator, it will show you all the available simulators that you've installed on your machine.

Select one and it should open.

If not, then you may have these next set of issues.

Unable to boot the simulator

This pops up for whatever reason. Maybe I tried to do something with Xcode and broke my simulator.

But no matter what I did, restarting VSCode, uninstalling/reinstalling the simulator, nothing would work.

That is until I found a solution by deleting the Xcode caches.

You need to go to your "System Settings > General > Storage > Developer" and click on the "i" icon button. You should see the following page.

Select "Xcode Caches", click "Delete..." and continue with the prompt.

From there you should be able to boot your simulator again.

But you might encounter another error when the simulator has booted.

Springboard quit unexpectedly

Another popup that might show up that something went wrong. This time it has something to do with Springboard.

Maybe this issue stemmed from deleting the Xcode cache but I would never know.

A quick internet search tells me that Springboard is the application that manages the home screen for iOS devices.

Not liking the sound of that, I searched for a fix and the only thing that worked for me was to delete Xcode entirely and install it fresh.

It was a hassle but it worked and was something I could do easily since every conversation about the error was way above my technical knowledge.

Rename App ID / Bundle ID

Every app deployed to a platform has a unique App ID. In iOS terms, it's called the Bundle ID. These unique names are usually reversed in the manner of a domain name.

These App IDs must be unique because this is how the platform identifies your app in their App Store. Whether that be the App Store, Google Play Store, etc. you'll need to keep them unique and that's why reversed domain names are standard practice.

For example, billyle.dev becomes dev.billyle as my App ID.

When you create a new Flutter project either by the command line or by VSCode, it will default the name of your App ID to be com.example.<YOUR_PROJECT_NAME>.

I don't like seeing the "example" in there and it's not a real representation of what I'm creating.

Instead, when starting a new Flutter project use this command and replace com.yourdomain and app_name to your liking.

flutter create --org com.yourdomain app_name

This will then create the App ID for you with com.yourdomain.app_name.

A thing I am starting to do is replace app_name with specific platform names like ios and android to keep things organized but you don't need to do this.

If you find that you're knee-deep in an existing project but your App ID still contains the com.example name, you can use this rename-cli to rename your App ID.

The instructions are straightforward to use.

Keeping this updated

There you have it. This is my current list of common errors and tips when developing in Flutter.

I hope it helps you on your journey to becoming a Flutter Developer.

With that, thanks for reading and I hope you have a good one.

Adding RSS Feed Content and Fixing Markdown Image Paths in Astro

Billy Le — Sat, 04 May 2024 00:00:00 +0000

Having an RSS feed is a nice way to notify your readers when your new content has been published.

I have a yellow "Subscribe" button at the end of every blog post which points to my rss.xml file where anyone could subscribe using an RSS reader.

To do this, AstroJS makes it easy for you to create an RSS feed by using their official plugin @astrojs/rss.

However, when it comes to adding feed content, there was one little problem...

The RSS content image issue

When I first integrated it, I tried adding the full contents of my post to the RSS feed.

I realized the output image src were all using a relative path that didn't exist because of how Astro works with local images.

I couldn't find a direct fix for this initially so I put it off.

With that said, I excluded using the post content and simply used the title and description for my RSS feed.

Now, when I visit an RSS reader like Feedly and look for my website, I get a list of feeds.

It's exactly what I want, but it looks pretty bare-bones.

All a user can do at this point is to follow the link to visit the blog to read it.

But what if I want users to read from their preferred source?

Wouldn't it be nice if someone wanted to read on Medium, dev.to, or their own RSS reader?

That's why I found the want to add the post content and begin cross-posting to other platforms so that my blog has more reach.

Cross-posting on dev.to

More recently, I wanted to cross-post over to dev.to to get more visibility on my writings.

You can connect your RSS feed to dev.to under "Settings -> Extensions".

If you want, you can specify to dev.to that you want your RSS feed to be the canonical URL. Be sure to check the box if this is your desire.

From there, you can click the "Fetch feed now" button and it will pull all your feed items into your dashboard as draft posts.

Everything works as expected but the contents of the blog weren't included because the RSS feed item didn't have any content that dev.to can use.

Before I get to the solution, I want to talk about how AstroJS outputs the image files.

AstroJS image optimization

Let's understand a bit what is happening with the images in your markdown.

In this photo, you can see I have an _images folder alongside my markdowns that map to a relative path in a blog post.

If you're using an import alias or relative path that is not the public directory in your markdowns, Astro will copy and optimize the images and place them in a static folder called _astro/ at build time.

When AstroJS is transforming your markdowns to HTML, it will then replace all the image paths with the one found in the _astro folder.

Here is an example of what that folder looks like.

By default, AstroJS will give the file names a hash and also convert it to webp for a smaller footprint.

Pretty simple, right?

Okay, it's time to revisit adding the RSS feed content.

Building the RSS feed content

Using the AstroJS RSS tutorial as a base, we'll add onto it to make sure our images correctly point to a URL.

This is the basic code to compile your RSS feed.

import rss from '@astrojs/rss';
import { getCollection } from 'astro:content';
import sanitizeHtml from 'sanitize-html';
import MarkdownIt from 'markdown-it';
const parser = new MarkdownIt();

export async function GET(context) {
  const blog = await getCollection('blog');
  return rss({
    title: 'Buzz’s Blog',
    description: 'A humble Astronaut’s guide to the stars',
    site: context.site,
    items: blog.map((post) => ({
      link: `/blog/${post.slug}/`,
      // Note: this will not process components or JSX expressions in MDX files.
      content: sanitizeHtml(parser.render(post.body), {
        allowedTags: sanitizeHtml.defaults.allowedTags.concat(['img'])
      }),
      ...post.data,
    })),
  });
}

In the parser.render(post.body), we are passing in the contents of our markdown into render which includes the relative image paths.

That is why in our final output for our rss.xml, we get those incorrect URLs.

At this point, I had an idea to fix this. What if before I pass the HTML string into sanitizeHtml(), I modify the markdown or HTML image paths myself, would that work?

Let's see...

Add dependency node-html-parser

We're going to need an HTML parser so we can easily manipulate objects instead of strings.

Install node-html-parser.

The Node HTML parser will convert the string output from the rendered markdown from markdown-it and create a DOM-like HTML structure.

We can query against this structure like how we would use the DOM API for browsers.

Install it with your preferred package manager.

I use pnpm so that command would be pnpm add node-html-parser.

The image relative path fix

Here is my solution to this problem.

import rss from "@astrojs/rss";
import sanitizeHtml from "sanitize-html";
import MarkdownIt from "markdown-it";
import { allPosts } from "@utils/getCollection";
import { parse as htmlParser } from "node-html-parser";
import { getImage } from "astro:assets";

import type { AstroGlobal } from "astro";
import type { RSSFeedItem } from "@astrojs/rss";
const markdownParser = new MarkdownIt();

// get dynamic import of images as a map collection
const imagesGlob = import.meta.glob<{ default: ImageMetadata }>(
  "/src/content/posts/_images/**/*.{jpeg,jpg,png,gif}", // add more image formats if needed
);

export async function GET(context: AstroGlobal) {
  if (!context.site) {
    throw Error("site not set");
  }

  const feed: RSSFeedItem[] = [];

  for (const post of allPosts) {
    // convert markdown to html string
    const body = markdownParser.render(post.body);
    // convert html string to DOM-like structure
    const html = htmlParser.parse(body);
    // hold all img tags in variable images
    const images = html.querySelectorAll("img");

    for (const img of images) {
      const src = img.getAttribute("src")!;

      // Relative paths that are optimized by Astro build
      if (src.startsWith("./")) {
        // remove prefix of `./`
        const prefixRemoved = src.replace("./", "");
        // create prefix absolute path from root dir
        const imagePathPrefix = `/src/content/posts/${prefixRemoved}`;

        // call the dynamic import and return the module
        const imagePath = await imagesGlob[imagePathPrefix]?.()?.then(
          (res) => res.default,
        );

        if (imagePath) {
          const optimizedImg = await getImage({ src: imagePath });
          // set the correct path
          img.setAttribute(
            "src",
            context.site + optimizedImg.src.replace("/", ""),
          );
        }
      } else if (src.startsWith("/images")) {
        // images starting with `/images/` is the public dir
        img.setAttribute("src", context.site + src.replace("/", ""));
      } else {
        throw Error("src unknown");
      }
    }

    feed.push({
      title: post.data.title,
      description: post.data.description,
      author: `${post.data.author.email} (${post.data.author.name})`,
      pubDate: post.data.pubDate,
      categories: post.data.tags,
      link: `/posts/${post.slug}`,
      // sanitize the new html string with corrected image paths
      content: sanitizeHtml(html.toString(), {
        allowedTags: sanitizeHtml.defaults.allowedTags.concat(["img"]),
      }),
    });
  }

  return rss({
    title: "Billy Le | Blog",
    description:
      "My creative outlet is a reflection of the experiences I've encountered—whether in learning, facing setbacks, or achieving success—as a software developer.",
    site: context.site,
    items: feed,
    stylesheet: "/pretty-feed-v3.xsl",
    xmlns: {
      atom: "http://www.w3.org/2005/Atom",
    },
    customData: [
      "<language>en-us</language>",
      `<atom:link href="${new URL("rss.xml", context.site)}" rel="self" type="application/rss+xml" />`,
    ].join(""),
    trailingSlash: false,
  });
}

I littered the code with comments but I'll try to break this down to make more sense of it.

The most important thing part is the import.meta.glob().

Thanks to Henri Fournier, from the Astro Lounge Discord Support Channel, for this tip.

You can read more about dynamically importing your images and the import.meta.glob() in more detail.

The imagesGlob variable holds an object that holds the key as the path, and the value as a dynamic import function.

const imagesGlob = {
  '/src/content/posts/_images/content-collection-in-sync/types-to-any.png': [Function: /src/content/posts/_images/content-collection-in-sync/types-to-any.png],
  '/src/content/posts/_images/creating-toc/remark-toc-md.png': [Function: /src/content/posts/_images/creating-toc/remark-toc-md.png],
  '/src/content/posts/_images/creating-toc/remark-toc-static.png': [Function: /src/content/posts/_images/creating-toc/remark-toc-static.png],
  ...
}

Each dynamic import contains the ImageMetadata object which looks like this:

export interface ImageMetadata {
    src: string;
    width: number;
    height: number;
    format: ImageInputFormat;
    orientation?: number;
}

With that ready to go, I loop over all my blog posts and convert them to HTML using the node-html-parser.

const body = markdownParser.render(post.body);
const html = htmlParser.parse(body);
const images = html.querySelectorAll("img");

From there, I loop through the images and use the dynamic imports from imagesGlob to get the correct path from the ImageMetadata.

And that looks like this:

const src = img.getAttribute("src")!;

if (src.startsWith("./")) {
  // remove prefix of `./`
  const prefixRemoved = src.replace("./", "");
  // create prefix absolute path from root dir
  const imagePathPrefix = `/src/content/posts/${prefixRemoved}`;

  // call the dynamic import and return the module
  const imagePath = await imagesGlob[imagePathPrefix]?.()?.then(
    (res) => res.default,
  );

  if (imagePath) {
    const optimizedImg = await getImage({ src: imagePath });
    // set the correct path
    img.setAttribute(
      "src",
      context.site + optimizedImg.src.replace("/", ""),
    );
  }
}

The rest of the else if/else statements check if the image is from my public/images directory or if it's an unknown source, I throw an error.

Finally, I push the feed item into an array and when we sanitize our HTML, we call html.toString() which is passed into sanitizeHtml().

Check RSS output fix

Now it's time to see if everything works.

Run the build command, I'm using pnpm build.

Check the contents of your _dist folder and look for your RSS XML file.

🥳 Yes! It's looking good and seems to be pointing the the path correctly.

Okay, time to push it live and test Feedly and dev.to.

Verifying fix on supported platforms

If you had an RSS feed on Feedly before adding content, they won't update as the date is encoded on their servers.

Only new content will be updated with the new RSS changes or you change your feed URL.

Viewing from Feedly, I only have one item that correctly shows the contents of my blog post.

And the images are working!

That's awesome!

Over on dev.to, I deleted all my drafts with no content.

I kind of wish they added a multi-select action on this part but it is what it is.

Once I removed all my old draft posts, I fetched my updated RSS feed using the "Fetch feed now" button.

And now, I see that all the contents are there ready to be published!

Conclusion and improvements

With the RSS feed content in place, we can now grab our blog posts into platforms that support fetching RSS feeds.

This is great because we can benefit by sharing our blog with platforms and give our readers a choice where they get updates and read new content.

In this post, I've gone over the issue of the incorrect image path when creating an RSS feed from markdown to XML with AstroJS.

To fix this, we had to convert the markdown to HTML and modify the image src to use the correct path. That's all thanks to the import.meta.glob(), a useful Vite utility function.

After verifying our fix, we can view places like Feedly and dev.to, to continue sharing our posts.

If you want to see how you can add a featured image per blog post for your RSS. Check out Web Reaper's blog post on how you can do that.

Well, that's all I can think of. Let me know what you think and if there is anything I can add.

Thanks for reading, and as always, have a good one! 😊

How Docker Breathes New Life into My Workflow

Billy Le — Tue, 30 Apr 2024 00:00:00 +0000

Have you ever come across a tool and were so impressed by it that you tried to integrate it into your daily workflow? First was TailwindCSS and now I can say that about Docker.

As a frontend developer first, I haven't considered learning Docker at all since there wasn't a reason for me to do so.

That is until I launched my self-hosted Coolify which uses Docker itself to deploy my applications.

Ever since then, I've been practicing and learning Docker on all my new projects.

And I wished I started sooner.

Understanding how to use Docker benefits me greatly as it is being used everywhere. Especially in the cloud.

What is Docker 🐳?

From what I understand, Docker offers containerization products that allow you to package your application as images with all its dependencies and run them as containers.

Each container is an instance of that image and you can run nearly infinite amounts if you had the resources.

That's why companies choose to build their infrastructure with containers; they scale well and meet the demands of their business.

Docker has many different products from CLI tools to desktop applications that help manage your images and containers.

There is also a Docker Hub, a cloud repository for images that can be hosted publicly or privately and where you can find official images.

How do I use Docker?

There are several ways I'm using Docker at the moment. These include:

Using Docker Desktop
Interacting with the Docker Client CLI
Docker as a Version Manager

Of these three listed, I primarily use #2. Usually, I run docker compose commands to build and run my images in one go.

I'll briefly describe how I use them below.

Docker Desktop - a must

Docker Desktop is super neat. It does all the Docker things in one single beautiful UI.

And it's easy to get around and inspect every aspect of it too.

With Docker Desktop, you can view your images, containers, and volumes. You can also pull in new images or push your own to Docker Hub.

Once you have your containers running, you can inspect the container's contents, the logs, and some analytics like CPU and RAM usage.

You can launch VS Code from here by accessing the dropdown menu of a container.

I like using Docker Desktop to monitor all my images, containers, volumes, and build history. I also use it to pull one-off images to play with by using the search tools.

You can easily access this by ⌘K if you're coming from a MacOS device.

In VS Code, I can download the Docker extension that features running docker commands by the right-click menu and inspect container files.

This is super helpful when you're troubleshooting why the Docker build is missing some dependencies.

There's so much you can do and I have yet to touch Docker Scout, Docker Swarm, and extensions.

Dockering through Docker CLI

I like using the CLI since I don't have to leave VS Code to interact with my containers.

Normally, I run docker compose up --watch and docker compose down.

The --watch flag watches for any changes you've specified in the docker-compose.yaml file.

services:
  app:
      container_name: my_app
      build: .
      develop:
        watch:
          - path: .
            action: sync
            target: /app
            ignore:
              - node_modules/
          - path: package.json
            action: rebuild

This configuration will watch any changes in my project using the watch fields.

There are three actions, sync, rebuild, and restart.

I'm using sync to sync any changes done on the host machine, to also reflect in the container. This makes a seamless experience like you're developing locally.

And if I ever need to install new dependencies, the action rebuild watches the package.json file, rebuilds the image, and launches new containers.

Learning the CLI commands to start, stop, list, and remove images and containers is pretty helpful too.

When I start using the CLI more frequently, I find myself not having to access the documentation as much anymore.

Like if I want to run a container with an exposed port, I know that's -p.

If there are environment variables that I want to use, that would be -e.

Once I got the hang of it all, I was spinning up and down containers fairly easily.

My new version manager

I use Docker as a way to manage different versions of technologies like PostgreSQL, Redis, etc.

The reason for this is that I don't have to worry about anything breaking if I'm working on an old project.

For example, there were some breaking changes with Node when I was using the latest version and working on an old project.

I would try to run the server and it would spit out some cryptic error.

A few minutes later, I realized that the project was using an earlier version of Node. 😓

So I would switch to the correct version of Node to get it working.

While I can add some assistance for Node by updating the package.json with an engines field, it doesn't entirely solve the issue.

I had to manually switch my Node version and some time was wasted. I don't like that.

This is why having Docker as a version manager is advantageous. All I needed to do was build the image and run a container. That's all!

I haven't been using Docker for long so I don't know what all the pros and cons are but I think one downside of this approach is that you're using up more disk space by doing it this way.

Using Docker in Development

I initially started using docker init. It's a command that quickly initializes your project with some Docker files.

However, after a while, I stopped using it since I didn't quite fully understand the generated output.

That's why I find myself writing the Dockerfile or docker-compose.yaml by hand because it gives me a lot of practice and get a grasp of how Docker works.

I make sure my Dockerfile can correctly build an image before I start working inside the compose file.

Here is a simple Dockerfile which uses Node:

# Run as a non-privileged user
FROM node:18-alpine
RUN useradd -ms /bin/sh -u 1001 app
USER app

# Install dependencies
WORKDIR /app
COPY package.json package.lock .
RUN npm install

# Copy source files into application directory
COPY --chown=app:app . /app

CMD ["node", "server.js"]

In the docker-compose.yaml I list out all my apps and services in my project.

So if I'm on Redis v6 and PostgreSQL v14, I can list those out and add a volume to each.

Then in my main service app, I add a watch field, which syncs the changes between the host and the container environment.

This is how it would look like:

services:
  redis:
    image: redis:6-alpine
    port:
      - 6379:6379
    volumes:
      - node_app:/data

  db:
    image: postgres:14-alpine
    environment:
      - POSTGRES_USER=${POSTGRES_USER}
      - POSTGRES_PASSWORD=${POSTGRES_PASSWORD}
      - POSTGRES_DB=${POSTGRES_DB}
    port:
      - 5432:5432
    volumes:
      - node_app:/var/lib/postgresql/data

  app:
    container_name: node_app
    build:
      context: .
    environment:
      - POSTGRES_URL=postgres://${POSTGRES_USER}:${POSTGRES_PASSWORD}@db:5432/${POSTGRES_DB}
      - REDIS_URL=redis:6379
    develop:
      watch:
        - action: sync
          path: .
          target: /app
          ignore:
            - node_modules/
    ports:
      - 8000:8000
volumes:
  node_app:
    external: false

From here, I would run the docker compose --watch command and start coding on my app.

The different containers will all be on one network, all talking to each other by the service name reference.

All the data is stored in a separate volume which I can easily dispose of once I'm finished.

That's how easy it is once you've grown accustomed to working with Docker.

If you want to start learning now, you can view the Develop with Docker documentation which covers some basic information.

But to get further ahead, you have to play around with it to get the hang of it like I did.

My plans ahead

Smooth seas do not make skillful sailors - African Proverb

Even though Docker made it easy to build images and run containers, in no way did that make me a master.

I am still learning and dialing down my workflow.

To improve my skills, I plan to dive deeper when I start deploying to the cloud, working with a container orchestrator, and more.

Only then could I call myself an expert.

So far it's been a pleasing experience working with Docker and all their products.

I hope reading this convinces you to work with Docker if you have yet to do so.

I promise you'll gain so much from it.

Well, that's all I've got! Thank you for reading. As always, have a good one!

Registering for Apple and Google Developer Accounts

Billy Le — Tue, 23 Apr 2024 00:00:00 +0000

If you read my previous blog, I said I was going to form an LLC. I decided not to because I felt it was too early in my journey.

My goal right now is to build mobile apps. The problem is that I can't publish my projects.

So I signed up for Apple and Google Developer Accounts and wanted to share my research and experience.

Platform pros and cons

When it comes to comparing Apple and Android for development, I found these metrics important for me as a developer.

	Apple	Google
🪧 Developer Account Registration	$99 yearly	$25 one-time fee
📊 OS Market Share	27.58% (Q3 '23)	71.72% (Q3 '23)
📋 App Reviewal Process	~ 48 hours	~ 2 hours
💰 Revenue Share Model	70% to dev / 30% to platform	-
💻 Programming Language	Swift	Java, Kotlin
📱 Emulator Support	iOS devices, Andriod	Android

Apple costs a lot more than Google year-over-year and the strict review guidelines can slow iteration cycles but offer consumers higher-quality products.

For Google, you can iterate and validate ideas much more quickly.

You can also see that Apple owns less of the market share than Google but Apple generates more revenue because people are willing to pay more.

I didn't want to limit myself to one platform so I chose to target both platforms using Flutter as my tool of choice.

Registration Experience

On both platforms, the registration was pretty straightforward.

There are a few screens where they will ask you what kind of app you're building.

The following screenshots are redacted and incomplete but it should give you an idea of what the process would look like.

Apple Developer Program

To get started with the Apple Developer Program, you will start on their enrollment page.

Click "Enroll" and you'll be asked to sign in. After signing in, you'll see these next few pages.

I chose the Sole Proprietor account since I am not at the point where I need to form an LLC. This should be the last step but if not, you'll have to enter your payment details.

Google Play Console

The same goes for Google Play Console. Sign in and follow the flow.

Here are some screenshots from the Google Play Console's registration.

You would create a new Payment Profile if you never had one.

And lastly, you'll come to the Terms page. You can see all the steps on the left-hand side that you'll have to complete.

Approval process time

Google immediately activated my account. After activation, you still need to verify with them before you can publish any apps.

Google will ask you to verify by uploading a valid ID or using a physical Android device.

For Apple, I thought the approval would take longer. I've read that it may take up to 5 weeks for them to approve them but that wasn't the case for me.

It only took Apple one day to approve my account.

Wrap-Up

I know this post wasn't technical or anything but I hope it gives you an idea of what the registration process is for both platforms.

I'll be doing some mobile development in the coming weeks, so I hope I can share with you those experiences as well.

Thanks for reading and have a good one!

Diving Head First into the Startup Unknowns

Billy Le — Thu, 18 Apr 2024 00:00:00 +0000

After I'd been forced to quit my last employment, I've been idling by since I felt burnt out from that role.

I didn't have any drive to do anything for about a year but I have been keeping up-to-date on tech matters.

Watching the tech market plummet with massive layoffs and the rise of AI, I knew I had to do something or risk being left behind.

I started to pick up Golang as my backend language of choice for its simplicity and speed while also picking up PostgreSQL.

And then after a conversation with a friend, he recommended using Flutter for mobile development.

With this new stack, I rolled up my sleeves to work on some projects.

Project #1: Furfil

Furfil has been spinning in my mind for quite a while.

It's about creating a platform where pet services can meet customers. It's like Rover but will offer plenty of more services.

It will be released as a web and mobile app.

Project #2: Dotted

Dotted is a project that a friend and I are working on.

It's an AI mobile app that helps generate itineraries for traveling.

We're using Flutter to release on mobile, and potentially releasing a web app.

Learning how to launch startups

I listened to hours of podcasts about startups but I'm constantly thinking about how I'm supposed to launch my own.

The majority of the content I've been consuming is very broad and high-level. It doesn't necessarily cover the nitty-gritty details I need to take.

Like should I start an LLC first or use a sole proprietorship?

Should I use the beginning of a tax year to form the LLC?

Where should I set one up? Wyoming? Delaware? Do I need a lawyer from that state?

Should I have a holding company and hold ownership in another LLC for Dotted since that will be a partnership?

Can my partner qualify for working on Dotted since they're on an H1-B visa?

I have so many questions and they are coming in slowly. It's been paralyzing to take action because there is so much to do.

The struggles of app development

Development will be always slow on new languages and technologies being learned. As we push forward, there are always an area of unknowns and it takes time and research to figure out the best approach.

I get mentally exhausted from learning and hitting obstacles that I end up working on my website like this blog post as a way to reclaim my peace.

And every minute taken away from the projects means time to market is prolonged.

I'm thinking about starting Furfil from scratch using what I know to keep things simple and fast. But I know Furfil won't scale well with Node and MongoDB in the long run.

There's a tradeoff to everything.

Next course of action

Until I do something to push the needle forward, I will be in this constant state.

So I'm starting my new LLC next month. I have a domain ready and I'll announce it when it's finalized.

I have to learn by doing and learn by failing. If this is not the right decision, I'll learn to live with it and adapt accordingly.

That's how anyone can find success and every success story is different from one another.

It's time to write my own story.

Thanks for reading my rant. I hope you have a good one.

Keep Astro Content Collection Types in Sync on Git Commit

Billy Le — Wed, 17 Apr 2024 00:00:00 +0000

I'm not sure when but sometimes the type definitions in the .astro folder keep going out of sync once in a while. Instead of adding the schema definitions from my collections, it replaces them with the any type.

Here is a preview of the issue from my Git history:

This is an issue for me since I love working with Typescript and having that safety matters when I'm developing my site.

According to Astro's docs, it runs astro sync whenever you run astro dev or astro build so somehow during development, the types become any.

The fix

We're going to re-sync our types and make sure that we get the results we want by running the astro sync command again on a Git commit.

Add a script to your package.json called sync or whatever you like and give it the value astro sync.

{
  "scripts": {
    "sync": "astro sync"
  }
}

You'll need to have Husky installed in your project for this to work. It's relatively simple to set up and I talked about it here.

Inside your .husky/pre-commit file, add these lines anywhere in the file. I'm using pnpm. Remember to replace "pnpm" with your package manager CLI command to run scripts.

pnpm sync
git add .astro/types.d.ts

And that should do it! Whenever you make a new commit, the pre-commit will fire and it will sync your content collections' schemas perfectly.

Thanks for reading and have a good one! 😄

Fix Missing 404 Pages for Coolify Static Site Deployments

Billy Le — Mon, 15 Apr 2024 00:00:00 +0000

When I first started using Coolify, I came across a bug where my 404 page was not being served.

In development, it was all smooth sailing. But in production, going to a non-existent URL would always redirect back to the home page.

This was a bit frustrating since I didn't know where to start to begin debugging.

As of Coolify v4.0.0-beta.258, I suspect it was how Nixpacks did not correctly configure the server.

But luckily, I was able to come up with a solution and am here to share that with you if you're in this situation.

The solution

Instead of having Nixpacks magically take care of everything, we need to have two things to replace the build pipeline.

That is:

containerizing our site
creating a reverse proxy

The two technologies I chose are Docker and Nginx for this fix.

Install Docker Desktop

Download and install Docker Desktop, which will contain a graphical user interface for Docker. It comes with all the bells and whistles like the CLI, the background daemon, and Docker Compose.

Using Docker Init

To get started, you can use the command docker init which will run an interactive terminal where it can detect what you're using for your project.

This is what you'll see when the command is entered into the terminal:

Welcome to the Docker Init CLI!

This utility will walk you through creating the following files with sensible defaults for your project:
  - .dockerignore
  - Dockerfile
  - compose.yaml
  - README.Docker.md

Let's get started!

? What application platform does your project use? [Use arrows to move, type to filter]
> Node - (detected) suitable for a Node server application
  Go - suitable for a Go server application
  Python - suitable for a Python server application
  Rust - suitable for a Rust server application
  ASP.NET Core - suitable for an ASP.NET Core application
  PHP with Apache - suitable for a PHP web application
  Java - suitable for a Java application that uses Maven and packages as an uber jar
  Other - general purpose starting point for containerizing your application
  Don't see something you need? Let us know!
  Quit

Follow the prompts and it will generate a template for you.

Modifying the Dockerfile

If you look at the Dockerfile, it has some sensible stages like building the dependencies and building the app.

I'm removing most of the generated comments so it's easier to follow.

# syntax=docker/dockerfile:1

ARG NODE_VERSION=21.4.0
ARG PNPM_VERSION=8.12.0

FROM node:${NODE_VERSION}-alpine as base
WORKDIR /usr/src/app
RUN --mount=type=cache,target=/root/.npm \
    npm install -g pnpm@${PNPM_VERSION}

FROM base as build
COPY package.json pnpm-lock.yaml ./
RUN pnpm install --frozen-lockfile
COPY . .
RUN pnpm run build

FROM nginx:stable-alpine3.17 as final
COPY nginx.conf /etc/nginx/nginx.conf
COPY --from=build /usr/src/app/dist /usr/share/nginx/html
EXPOSE 4321

In the last step, I am pulling the latest Nginx image from DockerHub with the 'alpine' tag.

Then I'm copying over my nginx.conf file, which we'll create later, into the Nginx directory where it will be used as configuration.

Finally, from my build stage, I'm copying over my static files into the /usr/share/nginx/html directory.

Nginx will serve our static files from this default directory.

And finally exposing Port 4321, because that's what the local AstroJS development server is running on.

Create the nginx.conf file

At the root of your project directory, create a nginx.conf file.

The contents of this file will be something similar below for a static site.

worker_processes 1;

events {
  worker_connections 1024;
}

http {
  server {
    listen 4321;
    server_name _;

    root /usr/share/nginx/html;
    index index.html index.htm;
    include /etc/nginx/mime.types;

    gzip on;
    gzip_min_length 1000;
    gzip_proxied expired no-cache no-store private auth;
    gzip_types text/plain text/css application/json application/javascript application/x-javascript text/xml application/xml application/xml+rss text/javascript;

    error_page 404 /404.html;
    location = /404.html {
            root /usr/share/nginx/html;
            internal;
    }

    location / {
            try_files $uri $uri/index.html =404;
    }
  }
}

I won't explain all the details of the file but I want to note four parts.

Our listen 4321; matches what we exposed in the Dockerfile.

error_page 404 /404.html;

This line is going to serve my custom 404 page built by AstroJS.

location = /404.html {
          root /usr/share/nginx/html;
          internal;
}

The location of this 404 page is found in /usr/share/nginx/html

location / {
          try_files $uri $uri/index.html =404;
}

Finally, at the root path, we'll use a special $uri variable for a lookup for that specific URL that was entered. The try_files will continue to look for the file and if it's not found, we'll respond with a 404.

Testing locally with Docker

Everything is put in place, now it's time to test if this is going to work when we build an image with Docker.

Make sure that Docker Desktop is opened and in a terminal run the command:

docker build -t my-static-site .

Wait for the build to complete and if all goes well, you should see your built image with the tag name my-static-site in Docker Desktop.

Or if you're a terminal type of person, docker images -a

REPOSITORY TAG IMAGE ID CREATED SIZE
my-static-site latest fa5fdc1f7169 2 minutes ago 219MB
server latest 18ee5c19b642 14 hours ago 234MB

Now we're going to launch and start up a container by running the command:

docker run -p 4321:4321 my-static-site

The docker container should be running in your terminal now:

/docker-entrypoint.sh: /docker-entrypoint.d/ is not empty, will attempt to perform configuration
/docker-entrypoint.sh: Looking for shell scripts in /docker-entrypoint.d/
/docker-entrypoint.sh: Launching /docker-entrypoint.d/10-listen-on-ipv6-by-default.sh
10-listen-on-ipv6-by-default.sh: info: Getting the checksum of /etc/nginx/conf.d/default.conf
10-listen-on-ipv6-by-default.sh: info: Enabled listen on IPv6 in /etc/nginx/conf.d/default.conf
/docker-entrypoint.sh: Launching /docker-entrypoint.d/20-envsubst-on-templates.sh
/docker-entrypoint.sh: Launching /docker-entrypoint.d/30-tune-worker-processes.sh
/docker-entrypoint.sh: Configuration complete; ready for start up

In a browser window, go to localhost:4321 and you should see your website. If not, then your nginx might be misconfigured or you are missing something in the Dockerfile.

If your page loads, try going to a non-existent URL like localhost:4321/this-is-not-a-real-page and you should be greeted with your custom 404 page!

If it's a generic Nginx 404 page, you will have to fix that in your nginx.conf file.

Commit your files to Git and then push them to a remote repository like GitHub.

Deploying on Coolify

All we need to do now is deploy on Coolify.

I'm assuming you already have a project running on Coolify because you are here.

On the Configuration page, under "Build Pack", select "Dockerfile".

Then make sure the "Dockerfile Location" is set to /Dockerfile

Under the "Network" configuration, enter 4321 for "Ports Exposes" and click on "Save".

When you hit save, make sure to look at the Traefik configuration is also pointing to PORT 4321.

When that's done, click "Redeploy" and Coolify will start building from the Dockerfile we've created.

If it succeeds, you can go to your live site and start testing.

Conclusion

Hopefully, that fixes your issue! If all this is a little intimidating to you, don't worry, I've been there and you can reach out and get some help.

Now we know that all we need to do to fix the missing 404-page configuration is to write up our own Dockerfile and an Nginx config.

Well, that's all for now. Thanks for reading and have a good one!

Configure a Contact Form Email Server with Resend for Your Website

Billy Le — Sat, 13 Apr 2024 00:00:00 +0000

Sending an email from a contact form is a necessary task for any front-end developer. Results from a search engine provide a few solutions for implementing this feature.

They usually are:

Use a form provider where you send the data to their API and they will forward the email to your inbox
Use an email framework like Nodemailer
Create an SMTP Server to relay emails

The technical difficulty of implementing these features increases linearly.

But there is one other solution I found that is least talked about but it's quickly emerging and that is using Resend.

What is Resend?

Resend is a startup aimed at making sending emails easier for developers.

You can send transactional emails, start a marketing campaign, and create beautiful emails using React. And this all comes with a generous free tier.

You can also add your custom domain where the "from" field will be sent from your domain.

Resend Domain Config and API Key

Sign up for Resend and verify your email. There are two steps we're going to complete here. You can skip the Custom Domain instructions if that doesn't apply to you.

Add your Custom Domain

Once you're verified and logged into Resend, head over to the Domains page in the left panel. You should see a similar page to the one below.

I already have mine set up but click on "+ Add Domain" and you'll enter your Custom domain and a region.

After that, you need to go to your DNS provider and enter all the DNS records that Resend provides you on the following page. I have Cloudflare as my DNS provider.

There will be a button for you to verify your DNS records. My recommendation is to wait for an hour and then try to verify that your DNS records are correctly configured with your provider.

You should see all green "Verified" badges next to all the records you need to add.

Create a Resend API Key

Once that's done, head over to the API Keys page for Resend. Here I'm redacting my API Key for security purposes but I'll run you through setting up a new API Key with your custom domain.

Click on "+ Create API Key" and a dialog will pop up.

Enter a name for your API key.
Select "Sending Access" under Permission since we're only using this for sending emails.
In the Domain dropdown, select your verified custom domain.
Finish by clicking "Add"

And that's all! Now onto the coding part.

Setting up the Front-end

I'm using AstroJS and Tailwind for styling, but you can use vanilla or another framework if you like. Either works since we just need an HTML and some frontend JavaScript to make POST requests.

Create a simple Form element

You'll need a basic contact form markup:

<form class="contact-form flex flex-col space-y-4 max-w-md">
  <input
    type="text"
    name="name"
    class="h-10 px-3 rounded ring-2 ring-neutral-300"
    placeholder="Name"
    required
  />
  <input
    type="email"
    name="email"
    class="h-10 px-3 rounded ring-2 ring-neutral-300"
    placeholder="Email"
    required
  />
  <textarea
    name="message"
    class="px-3 py-2 rounded ring-2 ring-neutral-300"
    rows={5}
    placeholder="What would you like to say?"
    required></textarea>
  <div class="flex justify-end space-x-2">
    <button
      type="submit"
      class="px-3 py-1 rounded text-xl text-slate-50 bg-slate-900 dark:bg-slate-700 dark:ring-2 dark:ring-slate-50"
    >
      Submit
    </button>
  </div>
</form>

Basic Form Event Handler

In a script tag, we'll need to target the form and listen for events.

<script>
  const contactForm =
    contactsContainer.querySelector<HTMLFormElement>(".contact-form");

  if (contactForm) {
    contactForm.addEventListener("submit", async (e) => {
      e.preventDefault();

      const formEl = e.target as HTMLFormElement;
      const formData = new FormData(formEl);

      const requestBody = {
        name: formData.get("name"),
        email: formData.get("email"),
        message: formData.get("message"),
      };

      console.log(requestBody);
    });
  }
</script>

You might be using React or some other framework but the idea here is to prepare our front-end code to start sending requests.

Test form submission

This is all we're going to need for the time being. Fire up your frontend server then fill out your contact form and hit submit. You should see a log in the dev console with your input.

{
  "name": "billy",
  "email": "billy@example.com",
  "message": "hi from contact form"
}

Prepare the Back-end

I'm using Bun, which is a JavaScript run-time like Node. You should get very similar results if you're using Node and a web app framework like Express. If you need in that regard, feel free to reach out.

Create a `.env` file

Create a .env file. Use the template below since it is what I'm using these properties that will be used by our server.

You'll need to install the dot-env package if you're using Node. The link will show you how to set it up.

Be sure to enter your Resend API key here.

SERVER_PORT=3000
RESEND_API_KEY=<API Key from Resend>
EMAIL_TO=hi@billyle.dev
ALLOWED_ORIGIN=billyle.dev

Install the Resend package

We also need to install the resend package. We'll instantiate a new Resend object and pass in our API key which will allow us to send our emails.

This is what a basic setup would look like:

const resend = new Resend(Bun.env.RESEND_API_KEY);

const { error } = await resend.emails.send({
  from: `${name} <${Bun.env.EMAIL_TO}>`,
  to: [Bun.env.EMAIL_TO],
  subject: `New Message Received From ${name}`,
  react: EmailTemplate({ name, email, message }),
});

Creating our Bun server

We'll be creating our server next.

If you're unfamiliar with Bun, there is a web app framework called ElysiaJS which is similar to ExpressJS. It comes with some cool features like validation which I'm using below.

I've added some comments to explain a bit of what's going on.

import { Elysia, t } from "elysia";
import { cors } from "@elysiajs/cors";
import { Resend } from "resend";
import { EmailTemplate } from "./email-templates/message";
import winston, { format } from "winston";

const { errors, printf, combine, colorize, timestamp } = format;

// logger for server logs
export const logger = winston.createLogger({
  level: "info",
});

logger.add(
  new winston.transports.Console({
    format: combine(
      errors({ stack: true }),
      colorize({ all: true }),
      timestamp(),
      printf(
        ({ level, message, timestamp, stack }) =>
          `[${timestamp}]:${level}: ${message}${stack ? `\n\n${stack}` : ""}`,
      ),
    ),
  }),
);

const resend = new Resend(Bun.env.RESEND_API_KEY);
const serverPort = Bun.env.SERVER_PORT || 3000;

// creating Elysia instance
new Elysia()
  .use(
    cors({
      methods: ["POST"],
      origin: [
        Bun.env.NODE_ENV === "production"
          ? Bun.env.ALLOWED_ORIGIN
          : "localhost:4321",
      ],
    }),
  )
  .post(
    "/send-email",
    async (context) => {
      const { name, email, message } = context.body;

      try {
        // the part where we are sending emails
        const { error } = await resend.emails.send({
          from: `${name} <${Bun.env.EMAIL_TO}>`,
          to: [Bun.env.EMAIL_TO],
          subject: `New Message Received From ${name}`,
          react: EmailTemplate({ name, email, message }),
        });

        // error sending email, send back error status and message
        if (error) {
          return context.error((error as any).statusCode, error);
        }

        logger.info("New email received");
        return new Response(JSON.stringify({ message: "Success" }), {
          headers: {
            "content-type": "application/json",
          },
        });
      } catch (error) {
        // catch error and log it, respond to user
        if (error instanceof Error) {
          logger.error(error.message, error);
        }
        return context.error("Internal Server Error", error);
      }
    },
    {
      // body must be of three properties: name, email, and message
      // validation happens as a middleware
      body: t.Object({
        name: t.String({
          minLength: 3,
          error: "Name must be at least 3 characters",
        }),
        email: t.String({
          format: "email",
          error: "Invalid email format",
        }),
        message: t.String({
          minLength: 1,
          maxLength: 1024,
          error:
            "Message should be at least 10 characters and max of 1024 characters",
        }),
      }),
      // any errors that happens during validation will be logged
      error: ({ path, body, request: { method, headers }, error, code }) => {
        const errorMessage = `method=${method} path=${path} error=${
          error.message
        } body=${JSON.stringify(body)} userAgent=${headers.get("user-agent")}`;
        logger.error(errorMessage);
        return error;
      },
    },
  )
  // if any errors happen on the server itself, log the errors
  .onError(({ path, request: { method, headers }, error }) => {
    const errorMessage = `method=${method} path=${path} userAgent=${headers.get(
      "user-agent",
    )}`;
    logger.error(errorMessage, error);
    return error;
  })
  .listen(serverPort, () => {
    logger.info(`Server starting on PORT: ${serverPort}`);
  });

In a nutshell, we created a server that is listening on Port 3000.

Whenever a POST request is received to /send-email, our middleware will validate the incoming body.

If any validation errors occur, we log it on our server and also return it as a response object.

Now, if everything seems okay, we're going to attempt to send an email to Resend which in turn, will forward the email in our to: field.

Pretty simple right?

Front-end meets Back-end

Back on our front end, we're going to make a fetch request to our server listening on Port 3000. My AstroJS server is running on PORT 4321 so make sure you distinguish the two.

In the event listener on form submission, we'll update our code to use fetch() as a POST request to our email server.

Please not the comments in the following code.

<script>
  const contactForm =
    contactsContainer.querySelector<HTMLFormElement>(".contact-form");

  if (contactForm) {
    contactForm.addEventListener("submit", async (e) => {
      e.preventDefault();

      const formEl = e.target as HTMLFormElement;
      const formData = new FormData(formEl);

      const requestBody = {
        name: formData.get("name"),
        email: formData.get("email"),
        message: formData.get("message"),
      };

      try {
        const { message } = await fetch(
          import.meta.env.PROD
            ? "https://api.mycustomdomain.com/send-email" // host a production server with your custom domain
            : "http://localhost:3000/send-email",
          {
            method: "POST",
            body: JSON.stringify(requestBody),
            headers: {
              "Content-Type": "application/json",
            },
          },
        ).then((res) => res.json());

        // store input elements in a variable for later use
        const nameInput =
          formEl.querySelector<HTMLInputElement>('input[name="name"]');
        const emailInput = formEl.querySelector<HTMLInputElement>(
          'input[name="email"]',
        );
        const messageInput = formEl.querySelector<HTMLTextAreaElement>(
          'textarea[name="message"]',
        );

        // remove all error classes from the inputs
        nameInput?.classList?.remove("ring-red-500");
        emailInput?.classList?.remove("ring-red-500");
        messageInput?.classList?.remove("ring-red-500");

        // store adjacent siblings to see if they are error divs
        const errorName = nameInput?.nextElementSibling as HTMLDivElement;
        const errorEmail = emailInput?.nextElementSibling as HTMLDivElement;
        const messageError = messageInput?.nextElementSibling as HTMLDivElement;

        // each if statement checks the input adjacent sibling and removes them from the DOM
        // if they have the `data-error="true"` attribute
        if (errorName?.dataset?.["error"]) {
          errorName.remove();
        }
        if (errorEmail?.dataset?.["error"]) {
          errorEmail.remove();
        }
        if (messageError?.dataset?.["error"]) {
          messageError.remove();
        }

        // create the error div with the data-error="true" attribute
        function createErrorMessage(message: string) {
          const p = document.createElement("p");
          p.className = "text-sm text-red-400";
          p.dataset["error"] = "true";
          p.textContent = message;
          return p;
        }

        // insert the error divs after to the input element
        function insertErrorMessage(el: HTMLElement) {
          const error = el?.nextSibling as HTMLDivElement;
          if (!error?.dataset?.["error"]) {
            const div = createErrorMessage(message);
            el?.insertAdjacentElement("afterend", div);
          }
        }

        // create a toaster message upon success
        async function createSuccessToaster() {
          const div = document.createElement("div");
          const p = document.createElement("p");
          div.className =
            "fixed bottom-8 right-8 p-4 bg-slate-200 dark:bg-slate-700 shadoow-lg rounded-md opacity-0 transition-opacity duration-300 border-t-4 border-emerald-400 border-solid";
          p.className = "text-xl text-slate-800 dark:text-slate-100";
          p.textContent = "Your message has been sent!";
          div.appendChild(p);
          document.body.appendChild(div);

          // using sleep to animate the toaster
          await sleep(100);
          div.classList.remove("opacity-0");
          await sleep(3000);
          div.classList.add("opacity-0");
          await sleep(200);
          div.remove();
        }

        // message could be success or errors
        switch (message) {
          case "Success": {
            // reset the form on success and show a toaster
            formEl.reset();
            createSuccessToaster();
            break;
          }
          case "Name must be at least 3 characters": {
            if (nameInput) {
              insertErrorMessage(nameInput);
            }
            break;
          }
          case "Invalid email format": {
            if (emailInput) {
              insertErrorMessage(emailInput);
            }
            break;
          }
          case "Message should be at least 10 characters and max of 1024 characters": {
            if (messageInput) {
              insertErrorMessage(messageInput);
            }
            break;
          }
          default: {
            // if message is received, log it out in the dev console
            if (import.meta.env.DEV) {
              console.log("Unknown message: ", message);
            }
          }
        }
      } catch (err) {
        // if anything else happens during sending, log it out in the dev console
        if (import.meta.env.DEV) {
          console.log(err);
        }
      }
    });
  }
</script>

Alright, a lot going on here. Since I'm not using a front-end framework, I'm using vanilla JavaScript to manually manage the form state and show UI elements based on the server response.

And now if you try to submit a form, you should see it hitting your server and show up in the server logs.

Try submitting different values and see what kind of messages are generated.

Deploying your Email Server

Now it's time to deploy the email server.

First, you're going to need a server. You can purchase a Virtual Private Server (VPS) or go through a managed service like Digital Ocean Droplets or Heroku.

With the former services, it should be fairly easy since you'll connect your GitHub account, point the server to your GitHub repository, and let it build/run for you. There are plenty of tutorials on this topic which I will not cover here.

I have a Hetzner VPS with Coolify installed so I'll be using this configuration. If you're interested in this setup, please check out two of my other blog posts where I show you how to self-host with Coolify and add Github preview deployments to Coolify.

In the Coolify admin page, create a New Project as usual.

Then select the "Production" environment on the following page.

Adding a Resource

This next step will depend if you have Coolify integrated with GitHub or not. With a GitHub integration, Coolify can automatically deploy a new build whenever you make changes to your main branch.

If you don't have this configured yet, don't fret. You can just copy the GitHub URL to the email server repository but you have to manually redeploy anytime you make a change to see an effect.

Go ahead and add a new Resource and you will see this next page.

From there keep selecting the server you want to host it from, and then the destination.

Configuring the app settings

When you get to the Configuration page, you would want to choose the Nixpacks build pack. It will automatically detect your stack and deploy a container for you.

Before we deploy, we want to add environment variables.

Navigate to the environment variables page and enter the environment variables we used in the .env file.

There should be 4 variables to create:

SERVER_PORT: the PORT you want to use
RESEND_API_KEY: the key from Resend
EMAIL_TO: the email address where you will receive the messages
ALLOWED_ORIGIN: the domain that is only allowed to make requests

If you're running a server different from the front-end server, you'll need to use the ALLOWED_ORIGIN and enter your front-end domain value. This will help with CORS and allow your server to accept requests from your custom domain.

Then back on the main configuration page, we want to add a Start command to run after our build finishes.

Add NODE_ENV=production bun run start

Then in the Domain field, add a custom domain name. I have Coolify set up to use subdomains so here I'm using https://test-email.billyle.dev.

So my front-end application will now make POST requests to https://test-email.billyle.dev/send-email.

Click save and deploy your application.

If all is good, you should see a green status dot saying "Healthy".

Test the integration

Update your front-end code where you're making the POST request.

const { message } = await fetch(
  import.meta.env.PROD
    ? "https://test-email.billyle.dev/send-email" // change this part here
    : "http://localhost:3000/send-email",
  {
    method: "POST",
    body: JSON.stringify(requestBody),
    headers: {
      "Content-Type": "application/json",
    },
  },
).then((res) => res.json());

From the Contact Form, enter all the details and click Submit.

If it's successfully submitted, hopefully, you have a way of displaying to your users that it was successful. Here is my toast message that shows that.

From your Resend dashboard, you can all the emails that flowed through by checking the "Emails" page.

I can see the "Jane Doe" email I sent earlier which is a good thing.

And then in your inbox, you should see your test email as below.

Congratulations! It's all working! Now you can deploy your front-end and do the same testing to see if it works in production.

Conclusion

That was quite a long post but I hope it gave you some ideas on how you too could implement an email server using Resend and deploying it somewhere live.

The Resend documentation is well-written as they have nearly every language support. You can easily copy and paste the code and test it from there.

If you need help with any of this setup, please use my Contact Form!

There are some things I didn't include like fighting spam using honeypot techniques but that's above my current knowledge.

Well, until then, thank you for reading, and have a good one.

Highlight Table of Content Items Using Intersection Observer

Billy Le — Fri, 05 Apr 2024 00:00:00 +0000

Giving your readers a way to navigate through the Table of Contents (ToC) is a nice feature but I was still missing a critical detail that would make the experience much more pleasant.

The missing feature was a way to highlight or give some sort of visual indicator of which part of the ToC the reader was viewing.

I've adapted the work of Reza Zahedi as I did before in my other blog post so all credit goes to him.

You'll more or less likely find the same information in his blog and this post and I'm creating this post as an entry for my own record.

A bit about AstroJS remark support

AstroJS ships with remark, a markdown processor with many community-built plugins.

You can add things like linters, MDX support, or compile your markdown to PDFs. The list goes on and on.

I am going to use the remark-sectionize plugin. This plugin will parse through my markdowns and for every article heading greater than <h1>, it will wrap a surrounding <section> element.

To see what I mean, here is an example:

Before :

<article>
  <h1>My Article Title</h1>
  <h2 id="heading-1">This is the first heading</h2>
  <p>This paragraph is about whatever heading-1 is about.</p>
  <h2 id="heading-2">This is the second heading</h2>
  <p>This paragraph is about whatever heading-2 is about.</p>
</article>

After :

<article>
  <h1>My Article Title</h1>
  <section>
    <h2 id="heading-1">This is the first heading</h2>
    <p>This paragraph is about whatever heading-1 is about.</p>
  </section>
    <h2 id="heading-2">This is the second heading</h2>
    <p>This paragraph is about whatever heading-2 is about.</p>
  </section>
</article>

It seems simple enough, right?

Highlight Table of Contents

For now, I simply want to change the text color in the ToC whenever a reader is viewing that section.

To do so, I have to use the Intersection Observer API which will allow me to manipulate the DOM elements as they enter or leave the viewport.

Here are the steps I'll need to complete it:

Give my ToC a class name, .toc-links for selecting the DOM element.
Select all <section> elements within the <article> tag.
Create an Intersection Observer and write a callback function to process the event and data.
Inside the callback, find the heading element of that section, map it to the ToC, and toggle on/off the class active as they enter or leave.
Loop over the <section> tags from Step 1 and use the Intersection Observer we created to observe each section.

The Intersection Observer API

If you have never used or heard of Intersection Observer, it's a Web API that allows us to listen to events and trigger functions when an element is entering or leaving the viewport.

This is the perfect use case for using the Intersection Observer API because we want to manipulate DOM elements whenever the events fire.

We will create an Intersection Observer that will change the class name of the <a> tags inside our Table of Contents whenever we are viewing the corresponding section.

The implementation code

In my BlogLayout.astro file that is responsible for rendering the very HTML page you're reading, I'm going to write a <script> tag.

Here is the code:

<script>
  const articleSections = document.querySelectorAll<HTMLDivElement>("article section");

  const observer = new IntersectionObserver((entries) => {
    entries.map((entry) => {
      const heading =
        entry.target.querySelector<HTMLHeadingElement>("h2,h3,h4,h5");
      if (!heading) return;
      const id = heading.getAttribute("id");
      if (!id) return;
      const link = document.querySelector<HTMLAnchorElement>(
        `.toc-links a[href="#${id}"]`,
      );
      if (!link) return;

      const addRemove = entry.intersectionRatio > 0 ? "add" : "remove";
      link.classList[addRemove]("text-blue-500", "dark:text-blue-400");
    });
  });

  for (const section of articleSections) {
    observer.observe(section);
  }

  window.document.addEventListener("beforeunload", () => {
    observer.disconnect();
  });
</script>

Breaking the code down

const articleSections =
  document.querySelectorAll<HTMLDivElement>("article section");

I'm collecting all the article sections using the document.querySelectAll() function.

const observer = new IntersectionObserver((entries) => {});

I'm creating a new IntersectionObserver() that takes a callback function whenever it is fired.

The entries parameter is coming from the intersection event triggered and is an array of IntersectionObserverEntry.

entries.forEach((entry) => {});

Using the entries parameter from the callback, we loop over it in a .forEach().

From each entry, there is a target. That target is the HTML element that fired the event. In my case, it will be a <section> tag.

How does it know that it's a section element? Well, I'll explain later in the code.

const heading = entry.target.querySelector<HTMLHeadingElement>("h2,h3");
if (!heading) return;

To get the heading of the section, we use entry.target.querySelector<HTMLHeadingElement>("h2,h3") and store it in a variable called heading. There is a guard clause to return if nothing is found.

const id = heading.getAttribute("id");
if (!id) return;

Next, I find the id attribute by calling heading.getAttribute("id") and store that in another variable called id.

const link = document.querySelector<HTMLAnchorElement>(
  `.toc-links a[href="#${id}"]`,
);
if (!link) return;

Next up, find the associated <a> tag by using string interpolation and storing that into a link variable.

const addRemove = entry.intersectionRatio > 0 ? "add" : "remove";
link.classList[addRemove]("text-blue-500", "dark:text-blue-400");

Using the entry variable from before, we can detect when a section is entering or leaving by using the intersectionRatio. If the intersectionRatio is greater than 0, the element is entering, and when it's below 0, it is leaving.

The addRemove variable stores the key of the classList API so we can easily toggle on and off the class names.

If the section is being viewed, I changed the ToC item to a blue text and off when the section is no longer in view.

for (const section of articleSections) {
  observer.observe(section);
}

Now that the Intersection Observer is created with a callback function, we can observe elements in our DOM to invoke the callback as they enter or leave.

In this case, I loop over all the sections from my articleSections variable and observe them.

window.document.addEventListener("beforeunload", () => {
  observer.disconnect();
});

You may not need this but I added this part anyway. Before a user navigates away from the page, I want to disconnect the observer.

Summary

As you can probably see, the text turns blue when you go from one section to the other.

If there is a child section within a parent section, such as an h3 within an h2 section, it still keeps the parent heading highlighted.

This is great since most articles have a hierarchy.

Congratulations! You learned to add this simple feature in your blog or anywhere you need to highlight different parts of your site by using the Intersection Observer API.

You can do some more fancy stuff with the Intersection Observer like this Progress Navigation by Hakim El Hattab that I found via Kevin Drum.

If you end up implementing this, let me know! I would love to see your work.

Until next time, have a good one, and happy coding!

Use Husky and Node to Unstage Draft Blog Posts From Git

Billy Le — Thu, 21 Mar 2024 00:00:00 +0000

Astro allows us to only create static files during the build step for published work by filtering through the collection and filtering out draft posts. But it doesn't prevent Git from knowing the context of your collection.

So what ends up happening is you might check in your drafts in your Git history. For me, I didn't want my draft blog posts to be viewable until they were ready to be published.

I thought about adding my draft files into another folder and using gitignore, but it wasn't an elegant solution since I have to manually move files from the drafts folder and into the proper folder each time I want to publish a blog.

A solution I came up with was to use Husky to trigger pre-commit scripts and unstaged all my markdown drafts. I'll show you exactly how I did that below.

What is Husky?

If you don't know what Husky is, it's a program that will run during different life cycles of your Git workflow. This is particularly useful for doing a bunch of things before and after committing files in your Git history.

Usually, you will see the pre-commit hook often used for performing linting, prettifying, or running tests on your project.

List of Git Hooks Husky supports

Husky supports all client-side Git hooks. There are 13 of them in total.

applypatch-msg
commit-msg
post-applypatch
post-checkout
post-commit
post-merge
post-rewrite
pre-applypatch
pre-auto-gc
pre-commit
pre-push
pre-rebase
prepare-commit-msg

If you're interested in what Git hooks are, here is a list of all the different Git hooks.

Install Husky

To install Husky, you need to have Node installed since you will use npm.

I use pnpm, but you can use any package manager supported in the link above.

Run the command pnpm add husky -D. This will install Husky as a devDependency.

Then run pnpm exec husky init, so Husky can take care of the setup for you.

If you look in your project now, you should see a .husky folder. If you look inside, you will see a pre-commit file with the command pnpm test inside.

As a concept, if you tried to run git add . and git commit -m "my message" the pre-commit hook will trigger and run pnpm test. If your test happens to fail, then it won't commit anything and your Git history remains untouched otherwise you're golden.

Retrieving a list of your staged files

Now we need a way to list out all the files that are staged in Git. Luckily for us, we can do that with this command, git diff --name-status --staged.

This command grabs all staged files that were changed and returns the status mode and file names. This is how it would look in your terminal:

Press q to kill the process.

Preparing the Node script

Our next step requires us to write a Node script. Since my project is written in Typescript and I want to take advantage of the type system, so I am using ts-node to run the script.

However, if you're just using Node, then you can change the file extension to .js, and remove the types, and it should work the same.

Prerequisites

Install front-matter and ts-node packages
Ensure you have a Post schema type

We need a way to read from our front matter in our .md files. I found this package, front-matter, that easily allows us to get key-value pairs of our markdown.

The meat of the script

I created a file in my root directory called unstage-drafts.ts.

We'll need to change who can access the file with chmod, so in your terminal run the command chmod 777 unstage-drafts.ts to change the permissions.

Then inside the file, I wrote this script:

import fs from "node:fs/promises";
import childProcess from "node:child_process";
import util from "node:util";
import fm from "front-matter";
import type { Post } from "src/content/config.ts";

const execPromise = util.promisify(childProcess.exec);

let data = "";

process.stdin.on("readable", () => {
  let chunk;

  while (null !== (chunk = process.stdin.read())) {
    data += chunk;
  }
});

process.stdin.on("end", async () => {
  // process all markdown files and unstage any draft posts
  const stagedFiles: string[] = [];
  const markdownFiles: string[] = [];

  data
    .split("\n")
    .filter((x) => x)
    .forEach((line) => {
      if (line.endsWith(".md")) {
        if (!line.startsWith("D")) {
          const markdownFile = line.split("\t")[1] as string;
          markdownFiles.push(markdownFile);
        }
      } else {
        stagedFiles.push(line);
      }
    });

  let draftCount = 0;

  for (const file of markdownFiles) {
    const content = await fs
      .readFile(file, { encoding: "utf-8" })
      .then((f) => fm<Post>(f));

    if (content.attributes.draft) {
      draftCount++;
      await execPromise(`git reset ${file}`);
    }
  }

  if (draftCount === markdownFiles.length && !stagedFiles.length) {
    throw Error("only draft posts were staged.");
  }
});

Script breakdown

Let's do a quick break of what's going on.

The necessary imports of modules I'm using:

import fs from "node:fs/promises";
import childProcess from "node:child_process";
import util from "node:util";
import fm from "front-matter";
import type { Post } from "src/content/config.ts";

The command git diff --name-status --staged writes to out stdout, so we can read from it in Node by using process.stdin.

Here we're listening to the event "readable" which is a stream of bytes. Then each chunk is appended in our data variable.

let data = "";

process.stdin.on("readable", () => {
  let chunk;

  while (null !== (chunk = process.stdin.read())) {
    data += chunk;
  }
});

We're going to promisify() our childProcess.exec, so we can await it later.

const execPromise = util.promisify(childProcess.exec);

When our readable stream ends, we will listen to the event end and run an async callback function that uses the data variable to process all the staged files.

process.stdin.on("end", async () => {});

I have two variables - one that will keep track of non-.md files and another to store markdown files, respectfully called stagedFiles and markdownFiles.

I split the data by new lines and then filtered valid entries. Then for each item in the array, I test some conditions to check whether the file is .md or not.

If it is a markdown file, we want to check if it's not a D status. The "D" status here means that I've untracked the file that was previously tracked by Git and I don't want to unstage those changes.

If it is not "D" then we push it to the markdownFiles.

const stagedFiles: string[] = [];
const markdownFiles: string[] = [];

data
  .split("\n")
  .filter((x) => x)
  .forEach((line) => {
    if (line.endsWith(".md")) {
      if (!line.startsWith("D")) {
        const markdownFile = line.split("\t")[1] as string;
        markdownFiles.push(markdownFile);
      }
    } else {
      stagedFiles.push(line);
    }
  });

After we have a list of our staged markdown files, we're going to process each file in a for loop and read from the front matter. If the post is a draft, we update a counter and call await execPromise() to unstage it.

let draftCount = 0;

for (const file of markdownFiles) {
  const content = await fs
    .readFile(file, { encoding: "utf-8" })
    .then((f) => fm<Post>(f));

  if (content.attributes.draft) {
    draftCount++;
    await execPromise(`git reset ${file}`);
  }
}

This next condition is a guard to check if there are staged files to commit while also checking if all staged markdown files were drafts. If this ends up being true, it must mean we probably did a git commit on staged files that were only markdown drafts. I threw an error so that there isn't an empty commit history if this does happen.

if (draftCount === markdownFiles.length && !stagedFiles.length) {
  throw Error("only draft posts were staged.");
}

That's the entirety of the script. As you can see, you can do a lot more in this script if there are extra requirements.

Piping it all together

Back in our .husky/pre-commit file where we had a single line of pnpm test, we're going to replace that by combining both the git diff and the Node script by using the piping method.

Replace pnpm test with git diff --name-status --staged | node --import 'data:text/javascript,import { register } from "node:module"; import { pathToFileURL } from "node:url"; register("ts-node/esm", pathToFileURL("./"));' unstage-drafts.ts

The verboseness of the command above is important to Typescript and Node.

If you're not using Typescript, it will look a lot simpler:git diff --name-status --staged | node unstage-drafts.ts

Untracked files committed to history

There's one other important thing that I want to do -- removing my existing drafts in my Git history, so they are no longer available in my public repo.

To do that, run the command git rm --cached <path/to/file>.

I have one file, learning-golang-for-javascript-developers.md, that is a draft and is already in my Git history. I want to remove it so I run git rm --cached src/content/posts/learning-golang-for-javascript-developers.md.

Now the file is labeled as Untracked by Git.

Seeing the pre-commit hook in action

Time to put it to the test and make sure our drafts are no longer being committed. Running the commands in order to make sure I have everything staged correctly.

git add .
git rm --cached src/content/posts/learning-golang-for-javascript-developers.md
then followed by git status.

This is the output:

➜ billyle.dev git:(ft/husky-precommit) ✗ git status
On branch ft/husky-precommit
Changes to be committed:
  (use "git restore --staged <file>..." to unstage)
        modified: .astro/types.d.ts
        new file: .husky/pre-commit
        modified: package.json
        modified: pnpm-lock.yaml
        new file: public/images/blog/husky-node-unstage/husky-post-setup.png
        new file: public/images/blog/husky-node-unstage/list-staged-files.png
        new file: public/images/blog/husky-node-unstage/pre-commit-piping-script.png
        new file: public/images/blog/husky-node-unstage/untrack-files.png
        modified: src/content/config.ts
        deleted: src/content/posts/learning-golang-for-javascript-developers.md
        new file: src/content/posts/use-husky-and-node-to-unstage-draft-posts-from-git.md
        modified: src/layouts/BlogLayout.astro
        new file: unstage-drafts.ts

Untracked files:
  (use "git add <file>..." to include in what will be committed)
        src/content/posts/learning-golang-for-javascript-developers.md

Now I will make a git commit -m "remove existing drafts from git history and unstage drafts" and see that this blog post is removed from the staging area.

Checking git status shows me:

➜ billyle.dev git:(ft/husky-precommit) ✗ git status
On branch ft/husky-precommit
Untracked files:
  (use "git add <file>..." to include in what will be committed)
        src/content/posts/learning-golang-for-javascript-developers.md
        src/content/posts/use-husky-and-node-to-unstage-draft-posts-from-git.md

Awesome! It worked! I can freely work on all my draft blog posts without ever checking them into Git again.

The takeaway

So if you're like me and want some bit of automation in your creative process, you can use this solution. I'm pretty sure there are better ones out there but if you like this approach, feel free to take it and use it as your own.

In summary, we learned how to use Husky, piping the git diff --name-status --staged command output into Node, and letting our script unstaged draft blog posts.

I hope you learned something today and if not, that's alright! I'm glad you took the time to read it anyway.

Well, until next time, happy coding!

Creating Custom Table of Contents for Astro Content Collections

Billy Le — Wed, 13 Mar 2024 00:00:00 +0000

Having a Table of Contents (ToC) for your blog is nice because it allows users to see an overview of your content and provides a quick way to navigate between sections. To do this in Astro with the Content Collections API, there's a bit of legwork, but the results are satisfying. But first, let's talk about the issues I ran into.

The problem

I tried to do this with the plugin, 'remark-toc' , which is mentioned in the Astro documentation. What I didn't like about it is that if I wanted to include a ToC, I would have to manually add it to the top of all my .md files.

Another note is that wherever I included it in the markdown, the ToC sits statically and to style it, I would have to target the id and fight my existing blog layout.

This is not ideal for me. I had to figure out a better way to do this.

Retrieving all headers of a markdown

In the official documentation, there are two ways you can get all the headings of your blog posts. The two ways are when you're importing a .md into a .astro file or using the Astro.glob() function. Neither of those was valid in my case because I'm using the Content Collections API.

Buried in the documentation, I found that you can get the headings from a RenderedEntry if you're using the Content Collections API.

Inside of my /src/pages/posts/[...slug].astro where I am pre-rendering my blog posts using getStaticPaths(), I have a utility function that pulls all my published blog posts into a collection. From there, I extract the headings using a Promise.all().

---
import BlogLayout from "../../layouts/BlogLayout.astro";
import { allPosts } from "@utils/getCollection";
import type { GetStaticPaths } from "astro";

export const getStaticPaths = (async () => {
  const headings = await Promise.all(
    allPosts.map((entry) => entry.render().then((data) => data.headings)),
  );

  const posts = allPosts.map((entry, index) => {
    return {
      params: { slug: entry.slug },
      props: { entry, headings: headings[index] },
    };
  });

  return posts;
}) satisfies GetStaticPaths;

const { entry, headings } = Astro.props;
const { Content } = await entry.render();
---

<BlogLayout {...entry.data} {headings}>
  <Content />
</BlogLayout>

For reference, inside an Astro Collection, you have a list of Entries. These Entries have a render() method that compiles the .md file for rendering. It also returns a property called headings which I used here to collect all the headings in a given markdown.

Here is the shape of that:

// headings shape
const headings: {
  depth: number;
  text: string;
  slug: string;
}[];

With that, I returned it inside the props object which can be extracted from Astro.props.

Creating the heading hierarchy

I have all the headings passed down to my BlogLayout component, and now I can use it. The first thing I need to do is make sure that there is a hierarchy of headings so that the ToC properly indents the headings.

I tried doing this on my own with a recursive function but didn't have too much success. Luckily, I came across this blog by Reza Zahedi that showed me a good foundation to start with.

With the ~~stolen~~ copied code, I noticed that the nesting only allowed one list of subheadings. So if a heading has a depth of 2, and two headings succeeding that is of depth of 3 and 4 respectively, then it outputs something like this:

const nestedHeadings = [
  {
    depth: 2,
    text: "My Heading",
    slug: "my-heading",
    subheadings: [
      {
        depth: 3,
        text: "My Subheading 1",
        slug: "my-subheading-1",
      },
      {
        depth: 4,
        text: "My Subheading 2",
        slug: "my-subheading-2",
      },
    ],
  },
];

I was okay with this since I do not want the ToC to get carried away with indentations. I wanted to prevent from writing any headings greater than 3, so I added a guard to throw an error if I did include one by accident.

Inside my TOCHeading.astro component, I'm exporting an interface:

import type { MarkdownHeading } from "astro";
export interface HeadingHierarchy extends MarkdownHeading {
  subheadings: HeadingHierarchy[];
}

Inside my BlogLayout.astro component:

import type { HeadingHierarchy } from "@ui/components/TOCHeading.astro";
import type { MarkdownHeading } from "astro";

const { headings } = Astro.props;

function createHeadingHierarchy(headings: MarkdownHeading[]) {
  const topLevelHeadings: HeadingHierarchy[] = [];

  headings.forEach((heading) => {
    if (heading.depth > 3) {
      throw Error(
        `Depths greater than 3 not allowed:\n${JSON.stringify(heading, null, 2)}`,
      );
    }
    const h = {
      ...heading,
      subheadings: [],
    };

    if (h.depth === 2) {
      topLevelHeadings.push(h);
    } else {
      let parent = topLevelHeadings[topLevelHeadings.length - 1];
      if (parent) {
        parent.subheadings.push(h);
      }
    }
  });

  return topLevelHeadings;
}

const toc: HeadingHierarchy[] = createHeadingHierarchy(headings ?? []);
const hasToC = toc.length > 1;

I'm using a variable called hasToC since in some cases I have a short blog post with only one heading, and it doesn't make sense to show the ToC. I use this variable to conditionally render the ToC and the appropriate layout.

Rendering the ToC

Rendering is fairly straightforward in Astro. I have a TOCHeading.astro component that I found in the other blog post and made minor adjustments like giving it types and such.

If you're going to use a sticky ToC, be sure that the parent component has a position: relative and that there is no overflow property on it. If your parent is a flex or grid parent, you need to wrap your position: sticky ToC with a container so that it will properly work.

<section class={`${hasToC ? "max-w-7xl mx-auto lg:grid lg:grid-cols-4" : ""}`}>
  {hasToC && (
    <div class="relative mx-auto px-4 prose dark:prose-invert xl:pt-10 2xl:px-0">
      <nav class="xl:sticky xl:top-20">
        <h2 class="text-emerald-400">Table of Contents</h2>
        <ul>
          {toc.map((heading) => (
            <TOCHeading heading={heading} />
          ))}
        </ul>
      </nav>
    </div>
  )}

  <article
    class={`py-10 sm:py-20 px-4 mx-auto prose prose-h1:font-vidaloka dark:prose-invert
            prose-code:before:hidden prose-code:after:hidden
            sm:prose-lg lg:prose-xl
            ${hasToC ? "lg:col-span-3" : ""}
        `}
  >
    <h1>{title}</h1>
    <slot />
  </article>
</section>

The results

As you can see, my Table of Contents appears on the left-hand side. Now you can easily move between sections as you read!

For now, I'm only supporting the sticky ToC for desktops as I haven't found a good UI for tablets and mobile devices yet.

I guess all that's left to do is highlight the ToC heading that is currently being viewed, but I'll do that some other time.

I hope that was a bit helpful if you're trying to add a ToC for your Astro website if you're using the Content Collections API.

Well, thanks for reading and I hope you have a good one.

Enabling Developer Mode on iOS 17.3.1

Billy Le — Thu, 07 Mar 2024 00:00:00 +0000

I had trouble recently trying to find the "Developer Mode" settings on my iPhone. I tried viewing the "Privacy & Security" settings and scrolling down to the bottom only to find that it wasn't there.

Even the official documentation was not helpful and users around the internet repeated the same instructions.

It wasn't until I found an obscure comment that helped me unlock "Developer Mode". So now I'm going to share how I got "Developer Mode" to show.

How to enable "Developer Mode" for iPhone and Xcode

Download Xcode on your macOS device.
Connect your iPhone to your macOS device and make sure to trust your device on your iPhone.
And enter your passcode on your iPhone
Open Xcode and navigate to the settings "Product" > "Destination" > "Manage Run Destinations"
You should see your device now but there's a warning banner that "Developer Mode" is not enabled.
Head over to "Privacy & Security" in "Settings" on your iPhone and you should now see "Developer Mode".
Turn it on and it will ask you to "Restart" which is required.
Upon logging back into your iPhone, it will confirm you want to turn on "Developer Mode". Press "Turn On".
One last time you'll be asked to enter your passcode.
If you look at Xcode, you should see that your iPhone will try to pair. If not, you may need to wait or click on the warning banner.

That's it!

You now have "Developer Mode" set on your iPhone. Turn off "Developer Mode" by going back to your iPhone "Privacy & Security" settings if you no longer need it.

Good luck, happy coding and see you next time.

DEV Community: Billy Le

Common Errors for New Flutter Developers: Tips and Fixes

Installation problems and fixes

Clean and repair cache

Cocoapods errors

Cocoapods not installed error

Cocoapods base configuration

Target versions not supported

Launch the simulator from VS Code

Unable to boot the simulator

Springboard quit unexpectedly

Rename App ID / Bundle ID

Keeping this updated

Adding RSS Feed Content and Fixing Markdown Image Paths in Astro

The RSS content image issue

Cross-posting on dev.to

AstroJS image optimization

Building the RSS feed content

Add dependency node-html-parser

The image relative path fix

Check RSS output fix

Verifying fix on supported platforms

Conclusion and improvements

How Docker Breathes New Life into My Workflow

What is Docker 🐳?

How do I use Docker?

Docker Desktop - a must

Dockering through Docker CLI

My new version manager

Using Docker in Development

My plans ahead

Registering for Apple and Google Developer Accounts

Platform pros and cons

Registration Experience

Apple Developer Program

Google Play Console

Approval process time

Wrap-Up

Diving Head First into the Startup Unknowns

Project #1: Furfil

Project #2: Dotted

Learning how to launch startups

The struggles of app development

Next course of action

Keep Astro Content Collection Types in Sync on Git Commit

The fix

Fix Missing 404 Pages for Coolify Static Site Deployments

The solution

Install Docker Desktop

Using Docker Init

Modifying the Dockerfile

Create the nginx.conf file

Testing locally with Docker

Deploying on Coolify

Conclusion

Configure a Contact Form Email Server with Resend for Your Website

What is Resend?

Resend Domain Config and API Key

Add your Custom Domain

Create a Resend API Key

Setting up the Front-end

Create a simple Form element

Basic Form Event Handler

Test form submission

Prepare the Back-end

Create a .env file

Install the Resend package

Creating our Bun server

Front-end meets Back-end

Deploying your Email Server

Adding a Resource

Configuring the app settings

Test the integration

Conclusion

Highlight Table of Content Items Using Intersection Observer

A bit about AstroJS remark support

Highlight Table of Contents

The Intersection Observer API

The implementation code

Breaking the code down

Create a `.env` file