DEV Community: logarithmicspirals

How I Set Up Tailscale for Secure Tunneling and Accessing Private LLMs

logarithmicspirals — Sat, 07 Mar 2026 23:33:45 +0000

The Setup: SCaLE 23x and a Happy Coincidence

For the past few years, I've owned a Synology NAS. However, I have not really utilized its full potential. Over the last couple months, I've started diving deeper into its capabilities and potential use cases beyond storage.

So far, my primary use of the NAS has been to store pictures, videos, file backups, and host some small Docker containers. For example, I've been hosting a Heimdall instance to provide me with a customizable dashboard. A couple months ago, I decided to install a Pi-hole container for network wide adblocking. Setting up Pi-hole was a catalyst that drove me to dive deeper into what the NAS is capable of.

After installing Pi-hole, I also set up HomeAssistant as a VM. After doing this, I felt very comfortable setting up and configuring both VMs and containers for myself.

Fast forward to this week. I've planned on attending SCaLE 23x, and thought I would experiment with setting up a personal VPN to my home network. My primary motivation was to have a secure tunnel while using the public wifi. After a little exploration, I found out I had the following options:

Set up Wireguard as a Docker container.
- This required more manual configuration than I was willing to invest.
Set up Synology's VPN Server app with OpenVPN.
- This felt heavier than what I needed.
Use Synology's Tailscale app.
- Immediately intriguing with its promises of simplicity.

Initially, I was hesitant to try Tailscale because it required setting up an account. However, as I read more about it, and learned it was built on top of Wireguard, I decided to give it a try.

Turns out, Tailscale was really easy to set up and provides everything I needed. Conveniently, there was even a sponsored workshop on Tailscale, which I was able to attend, that covered how to connect Tailscale to AWS EC2 instances. Seeing how flexible the tailnet model was gave me the idea to use it for accessing Ollama on my home PC.

Now let's dive in to how I set everything up.

Prerequisites and Architecture Overview

Here are the prerequisites you'll need if you want to follow along:

Synology NAS with DSM 7+. I have a DS220+ with 6GB of aftermarket RAM.
Home PC with a GPU.
Tailscale account.
Laptop.

And here's a broad outline of the tailnet topology:

Setting Up Tailscale

First, you have to set up the NAS. In broad strokes, that involves these steps:

Installing the Tailscale app in DSM.
Creating a Tailscale account.
Linking the NAS to the account via the app.
Modifying the NAS to act as an exit node (via SSH terminal commands).

I won't go into detail on this, though. For more detailed instructions, see Access Synology NAS from anywhere.

Second, you need to install Tailscale on the PC and the laptop. For specific downloads, visit the Tailscale Downloads page.

Once the PC has been set up with Tailscale, make note of the tailnet IP address for it. It'll look something like 100.x.x.x.

Setting Up Ollama on the PC

First, download Ollama to the PC. For Windows, you can download Ollama at the official download page.

Next, open a Powershell terminal and run the following command (replace 100.x.x.x with the PC's tailnet IP address):

setx OLLAMA_HOST 100.x.x.x

This sets the variable permanently for future sessions but won't affect the currently running Ollama process, so restart Ollama. One way to do this is kill the app via Task Manager, and then reopen it. With the environment variable set, Ollama will now accept incoming requests from tailnet.

On the laptop, you can verify everything is working with the following command:

curl http://100.x.x.x:11434/api/tags

You should receive some JSON indicating the request was successful. For example, {"models":[]} will be returned if you have no models downloaded yet.

Accessing Ollama Remotely Over the Tailnet

A good way to access the models on the PC from the laptop is via Open WebUI. For instructions on how to set it up, you can follow the official quickstart guide. Open WebUI allows you to access the models via a chat interface, and configure custom model providers.

Follow the instructions to set up Open WebUI on the laptop. After setting everything up, it should be available on http://localhost:3000. For me, I run it as a Docker container via Podman.

To set up the PC as a model provider, go to Settings > Admin Settings > Connections.

Scroll down to the Ollama section, and click the + button. Enter http://100.x.x.x:11434 as the base URL, then click save.

Now, you can proceed to install models. Click on the "Manage" button (looks like a download icon). Enter in the model name, click the "Pull" button (looks like a download icon).

If everything has been set up correctly, you can open a new chat and select the model from the dropdown list.

What You Get Out of This

With everything set up, there are two distinct but complementary benefits from this tailnet system.

The first is a secure tunnel for general internet traffic. When you're on an untrusted network — like conference WiFi — routing your traffic through the NAS exit node means your ISP at home handles your connection rather than whatever's running on the local network. It's a lightweight alternative to a commercial VPN, and one you fully control.

The second is access to private LLMs running on your own hardware. Unlike cloud-hosted models, nothing you send to Ollama leaves your home network. Your prompts, your data, and your model weights stay on your PC. For anyone doing work they'd rather not pipe through OpenAI or Anthropic, this is a meaningful distinction — and once it's set up, the experience through Open WebUI is smooth enough that you won't miss the convenience of hosted models.

Enhancing Markdown Image Handling in Astro

logarithmicspirals — Mon, 01 Dec 2025 06:23:09 +0000

Introduction

After writing new content, committing the markdown, and pushing to GitHub, my Astro build pipeline runs.

Since my site is built with Astro, I have a custom integration I've written which runs at the end of the build process and cross-posts the markdown content of my articles to DEV and Hashnode.

This workflow works, but the biggest friction point is images — specifically, how Astro handles them inside Markdown.

Why I Needed Better Markdown Image Handling

Since I am cross-posting the raw markdown to other platforms, the markdown content includes image URLs relative to my project file system. When building the site, Astro automatically converts these relative URLs to canonical URLs with the site domain as the base.

Here's an example of what these image URLs in the markdown look like:

![Some cool image](./image.png)

However, these relative URLs don't work outside of the build context. This is what my publishing workflow looked like before automation:

Write new content.
Commit and push to GitHub.
Wait for the build to complete.
Go to DEV and Hashnode.
Edit the drafts to replace the relative image URLs with the live URLs from my site.
Publish the drafts.

Unfortunately, this process is repetitive, time-consuming, and error-prone. Naturally, I've been wanting to fully automate this process to remove the draft creation and editing. My goal is to be able to immediately create a draft, and have it be published without my intervention. I also want updates in my repo to automatically sync to other platforms without breaking images.

To achieve these things, I needed to create stable image URLs which can replace the relative URLs in the raw markdown before it gets cross-posted.

The Issue With Astro’s Default Behavior

Astro converts Markdown images into optimized formats (like WebP) and places them in dist/, but it does not copy the original files.

Additionally, Astro adds hashes to the file names which are unstable. One of the issues I encountered in the past is the hashes can change between Astro versions and builds. Unfortunately, this means image links on other sites can become broken over time.

Here’s how a typical file gets transformed during build:

./image.png → dist/_astro/image.2db932.webp → https://logarithmicspirals.com/_astro/image.2db932.webp

When I would export the markdown to other sites, I would have to manually modify all the images to use the built image files.

My Solution to the Problem

To solve this problem, I came up with the following solution:

Expose the markdown in a way which can be accessed within the integration.
Read the markdown file and extract the image URLs.
Convert the filesystem-relative image URLs to absolute filesystem URLs.
Hash the image based on content.
Copy the image file to dist/canonical-images/${name}.${hash}${extension}.
Rewrite the URL in the markdown.
Cross-post the modified markdown to other sites.

Modifying My Custom Integration

One of the first things I had to do was create a service class for modifying strings containing markdown content. Here's what my service class looks like:

class RemarkRemapImages {
  // Private instance variables

  constructor(
    private readonly logger: AstroIntegrationLogger,
    private readonly dir: URL, // The build output directory.
    siteUrl: string,
  ) {
    // Assign the instance variables.
  }

  async remapImages(markdown: string, filePath: string): Promise<string> {
    // Given markdown content and its path on the disk,
    // convert the relative URLs to absolute URLs.
  }
}

Since this class is intended to be managed by the cross-post integration, I'm passing the integration logger provided by the Astro framework to the constructor.

I’m keeping the implementation details out of this post to stay focused on the higher-level architecture. The real implementation handles AST traversal, hashing, file copying, and URL rewriting. The goal is simply to show how the integration manages Markdown processing through a dedicated service class.

In my codebase, I am also passing this into the DEV and Hashnode client classes I have created. Here's an example showing the DEV client:

// The DevClient class is for non-integration and
// non-authenticated use cases.
class DevIntegrationClient extends DevClient {
  constructor(
    private readonly apiKey: string,
    private readonly remarkRemapImages: RemarkRemapImages,
    private readonly logger: AstroIntegrationLogger,
  ) {
    super();
  }

  async createDevDrafts(devDrafts: DevDraft[]) {
    // ...
    for (let i = 0; i < devDrafts.length; i++) {
      // ...
      const resultStatus = await this.createDraft(devDraft);
      // ...
    }
    // ...
  }

  async createDraft(devDraft: DevDraft) {
    try {
      const response = await fetch(`https://dev.to/api/articles`, {
        // Headers, etc
        body: JSON.stringify({
          article: {
            // ...
            body_markdown: await this.remarkRemapImages.remapImages(
              devDraft.body_markdown,
              devDraft.filePath,
            ),
            // ...
          }
        }),
      });
      // ... Returns response.status
    } catch (e) {
      this.logger.error(JSON.stringify(e));
    }

    return undefined;
  }
}

Lastly, these classes are wired together via the custom integration:

const crossPost = (siteUrl: string): AstroIntegration => {
  let routes: IntegrationResolvedRoute[];

  return {
    name: "cross-post",
    hooks: {
      "astro:routes:resolved": (params) => {
        routes = params.routes;
      },
      "astro:build:done": async ({ assets, logger, dir }) => {
        const remarkRemapImages = new RemarkRemapImages(logger, dir, siteUrl);

        // ... Get the DEV cross-post JSON.

        if (devJson) {
          // ...
          const token = process.env.DEV_API_KEY;

          if (token) {
            // A factory function constructs the service object.
            const devIntegrationClient = createDevIntegrationClient(
              token,
              remarkRemapImages,
              logger,
            );
            await devIntegrationClient.createDevDrafts(data);
          } else {
            // ...
          }

          // ...
        } else {
          // ...
        }
      }
    }
  };
}

The Outcome

By generating stable, content-based URLs for every Markdown image, each file now has a permanent location that won’t change across builds or Astro versions. This ensures that cross-posted Markdown renders correctly on platforms like DEV and Hashnode without breaking image links. Because the URLs no longer depend on Astro’s internal asset pipeline or its hashed filenames, updates to posts can be published confidently and consistently across platforms.

Conclusion

By generating stable, content-based URLs for every Markdown image, I finally removed the most fragile part of my cross-posting pipeline. Now I can publish and update posts across platforms without worrying about broken links or manually fixing image paths.

This improvement is a key step toward fully automating my publishing workflow. In a future post in this series, I’ll cover how I handle syncing updates and keeping external platforms consistent with my Astro content.

From Prototype to Production: How Promptfoo and Vitest Made podcast-it Reliable

logarithmicspirals — Sat, 13 Sep 2025 21:56:43 +0000

Introduction

In my previous article, From Idea to Audio: Building the podcast-it Cloudflare Worker, I detailed how I had created a simple Cloudflare Worker which could create podcast scripts and audio from a source blog post.

While I was not sure if I would continue working on the project, I made some breakthroughs in my understanding of how to build a serverless app powered by an LLM. One of the key pieces I was missing was LLM evaluations (evals). With evals, I was able to massively improve my development speed and feel much more confident in the progress of the project. Being confident in the quality of the podcasts gave me the energy I needed to keep going with the project.

Why LLM Evals Matter

When you’re building traditional software, testing usually means making sure your code behaves correctly: does this function return the right value, does this API respond in time, does this component render as expected? But with generative AI apps, there’s a new dimension — the quality of the model’s output itself. Even if your API endpoints all work perfectly, the app can still “fail” if the generated script sounds robotic, skips key information, or produces inconsistent episode structures.

That’s where LLM evals come in. Instead of only testing the code around the model, evals test the behavior of the model inside your app. They let you measure whether the text produced is useful, accurate, and consistent across many runs — which is critical if you want to move from a fun prototype to something people can actually trust.

One way I brought the power of evals into this project is through promptfoo. With promptfoo, I was able to quickly get started creating eval tests in my TypeScript environment. A test might check, for example:

Does every generated script include an introduction and conclusion?
Does the host’s name appear in the dialogue?
Is the transcript free of obvious hallucinations (like citing a source that isn’t in the blog post)?

To get started with promptfoo, I installed it like so:

npm install --save-dev promptfoo

After setting up and configuring promptfoo, I was able to create a script called "evals" in my package.json and run it as follows:

npm run evals

The evals script looks like this:

npm run export-schemas && npx dotenvx run -f .dev.vars -- sh -c 'cd evals && PROMPTFOO_DISABLE_TELEMETRY=1 promptfoo eval'

Here's what it does:

A custom script is used to convert TypeScript types from my source code into JSON schema files within the evals/ directory.
The dotenvx package is used to read the environment variables of .dev.vars into memory so that promptfoo has access to them. Promptfoo expects a .env file, but the Worker expects a .dev.vars file locally. This step bridges that gap.
The script switches to the evals/ directory and then runs promptfoo using the config file in that directory.

Currently, I have evals which confirm the following:

The expected hosts are used, and no other hallucinated participants are present.
The show title is mentioned in the script.
The correct JSON schema is used.
LLM graders are giving passing scores to the scripts.
The content of the script is relevant to the post.
The script passes OpenAI's moderation criteria.

The Role of Integration Tests in Gen AI Apps

While the LLM evals tell me if the content is good, integration tests tell me if the system is behaving correctly. Most of the issues I ran into weren’t “the model produced a weird sentence.” They were the boring but important things: a request that didn’t persist correctly, an episode that never left processing, or an endpoint that returned the wrong status code.

To catch these, I wrote integration tests with Vitest. Instead of just mocking everything, the tests spin up a temporary database and exercise the actual REST endpoints. That means I can simulate creating an episode, check that it moves through the lifecycle, and verify that the audio and metadata end up where they belong.

To install Vitest in my project, I ran the following command:

npm install --save-dev vitest

Since I was working with the Cloudflare Workers framework, I was able to configure my tests to have a temporary D1 database and R2 bucket. The same migration scripts used to run the app are applied before the tests are run. For context, Cloudflare Workers have a feature where developers can version their database changes using migration scripts. Having the test database configuration match the real database configuration is very easy with this feature. Here's what my vitest.config.ts file looks like:

import path from "node:path";
import {
    defineWorkersProject,
    readD1Migrations,
} from "@cloudflare/vitest-pool-workers/config";

export default defineWorkersProject(async () => {
    const migrationsPath = path.join(__dirname, "migrations");
    const migrations = await readD1Migrations(migrationsPath);

    return {
        test: {
            setupFiles: ["./tests/apply-migrations.ts"],
            poolOptions: {
                workers: {
                    miniflare: {
                        compatibilityDate: "2025-08-03",
                        d1Databases: { DB: ":memory:" },
                        d1Persist: false,
                        bindings: { TEST_MIGRATIONS: migrations },
                        r2Buckets: ["podcasts"]
                    },
                },
            },
        },
    };
});

With these integration tests, I am able to confirm things like:

Episode creation and deletion work as expected.
The right status code is returned when a request to make the same episode twice is made.
Audio files are uploaded to the right location.

Integration tests are also useful for making sure changes made to the codebase don't break anything. As such, I also added Husky to the project so that I could run the tests every time I tried to push code from my laptop to GitHub.

My Husky script, .husky/pre-push, is pretty simple:

#!/bin/sh

npm run prepush

The actual meat of this prepush hook is the "prepush" script in package.json which looks like npm run typecheck && npm test && npm run evals. In English, this script does the following:

Runs type checks on the project to look for developer errors.
Runs all available tests with Vitest.
Runs the evals script to confirm the models still behave as expected.

Iterating Faster with Promptfoo + Vitest

The biggest unlock came when I started running evals and integration tests together in my development loop. Promptfoo gave me immediate feedback on content quality — whether scripts still had an intro and conclusion, whether the host’s name appeared consistently, and whether hallucinations crept in. At the same time, Vitest confirmed that the APIs, database migrations, and storage flows all worked as expected.

That combination gave me confidence to move faster. I could tweak prompts, refactor code, or adjust infrastructure without constantly worrying about breaking something. If an eval failed, I knew it was a content issue. If a test failed, I knew it was a system issue. Together, they formed a feedback loop that made iteration smoother, reduced surprises, and made shipping updates feel much less risky.

Lessons Learned

Schemas eliminate drift. Converting TypeScript types to JSON schemas kept evals aligned with the source code and cut down on manual setup.
Evals catch subtle regressions. Automated checks surfaced issues—like the host’s name quietly disappearing—that slipped past manual review.
Tests and evals reinforce each other. Tests safeguard the system (routes, state, storage) while evals safeguard the output (tone, structure, relevance). Together, they build confidence.

What’s Next

Here's what is coming up for podcast-it:

Integration into my blog. I will be generating podcast episodes for all my existing blog posts.
Enriching scripts with relevant content from the web.
Adding script editing through a micro frontend.
Investigating model fine tuning to see if longer scripts can be generated without losing quality.

Conclusion

Moving podcast-it from “it works” to “it’s reliable” wasn’t about shipping new features—it was about building confidence. Promptfoo gave me a way to measure output quality, integration tests kept the system stable, and unit tests still catch the small stuff early. Together, they create a safety net that makes iterating on a generative AI app sustainable. If you’re building with LLMs, set up that loop early—you’ll avoid a lot of pain later.

From Idea to Audio: Building the Podcast-It Cloudflare Worker

logarithmicspirals — Sat, 16 Aug 2025 23:57:43 +0000

Introduction

Not so long ago, I had the idea to turn blog posts into podcast episodes. My first few attempts at this resulted in a manual workflow where the final results would be uploaded to YouTube. The flow was as follows:

Copy the link to the article from the browser.
Paste the link into NotebookLM.
Wait for the audio to be generated.
See if it was good. Otherwise, tweak the settings and repeat step 3.
Once the audio was good, download it to my laptop.
Next, use Headliner to create a video from the audio and upload it to YouTube.

Needless to say, there was a lot of waiting involved in this process. After doing this a couple times, I thought it would be interesting to try and automate it in some way.

In this post, I’ll walk through building podcast-it — a Cloudflare Worker that can take a blog post and return a playable audio file — and share the early decisions, setup, and challenges along the way.

Choosing the Tech Stack

The main limitation was obvious right away: NotebookLM doesn’t have an API, so there was no way to automate against it. That meant I’d have to recreate the key functionality myself — from generating the narration script to producing the audio.

Since my site already runs on Cloudflare, using Cloudflare Workers felt like a natural fit:

They run close to users, so responses are quick.
The free tier is generous enough for small projects.
I could experiment with Workers beyond static site hosting.

For the audio generation, I chose OpenAI for both text generation and text-to-speech synthesis. For storage, Cloudflare’s R2 handles the audio files, and D1 stores episode metadata.

Because the Worker would eventually need to integrate with my blog, I built it as a REST API from the start — making it easy to call from my site or any other client.

Here’s the high-level goal I started with:

Project Setup

Getting started with Workers was pretty simple. I started by reading up on their documentation, and then creating a copy of the backend API template using Hono + Chanfana + D1 + Vitest template. This template was useful because it provides an OpenAPI page, which is something I'm already familiar with and find quite useful for building REST APIs.

For reference, here's the command I used:

npm create cloudflare@latest -- --template=cloudflare/templates/chanfana-openapi-template

Additionally, I had to install the OpenAI SDK:

npm install openai

With everything installed, I had to update the configurations in the wrangler.jsonc file. Specifically, I needed to add bindings for R2 and D1:

"r2_buckets": [
  {
    "bucket_name": "podcasts",
    "binding": "podcasts"
  }
],
"d1_databases": [
  {
    "binding": "DB",
    "database_name": "podcasts",
    "database_id": "da7da40e-c9ac-4115-8773-1dcdeb8f4635",
    "migrations_dir": "migrations"
  }
],

For this project, I also decided to remove the start command from the package.json, and just keep the npm run dev command. I also modified the dev command to use a new migrate command to make sure the database would be updated:

"migrate": "wrangler d1 migrations apply podcasts --local",
"dev": "npm run migrate && wrangler dev",

The migrate command applies the database scripts from the migrations/ directory. The directory holds SQL scripts which can be used to version how the database is built. See the D1 Migrations docs for more information. I was not using this approach when I first started the project, but I found it to be quite useful to have a way to build the database in the same way across environments.

Additionally, I had to make a tests/ directory since none existed when I first downloaded the template.

Once everything was set up, I would use the npm run dev to run the app and access the OpenAPI page at http://localhost:8787/.

Core Functionality: Text to Speech

For this project, I went with OpenAI for both script writing and audio synthesizing. Rather than reading raw blog text directly, I generate a narration script first and then convert it to audio. This makes the result sound more natural.

At a high-level, these are the components involved in creating the podcast episode:

Asynchronous Episode Creation

One key realization was that the episode creation endpoint needed to be asynchronous. Audio generation and storage can take several seconds, and blocking the request until everything finishes would create a poor experience. Instead, when the Worker receives a POST /api/episodes request, it immediately returns a response with a slug while the Worker continues processing in the background.

A companion endpoint, GET /api/episodes/:slug, returns the current status of that episode (e.g., pending, complete) along with metadata once the audio is complete.

Here's what the episode creation looks like:

curl -X POST http://localhost:8787/api/episodes \
  -H "Content-Type: application/json" \
  -d '{
    "slug": "making-a-podcast-app",
    "content": "Today I will be talking about how I made a podcast generation app. First, lets talk about...",
    "hosts": [
      {
        "name": "string",
        "voice": "alloy"
      }
    ]
  }'

The response body just repeats back the details of the created episode and is returned with a 202 status code:

{
  "success": true,
  "episode": {
    "slug": "making-a-podcast-app",
    "content": "Today I will be talking about how I made a podcast generation app. First, lets talk about...",
    "hosts": [
      {
        "name": "string",
        "voice": "alloy"
      }
    ],
    "status": "pending"
  }
}

The 202 status code signals that the request was accepted but processing is not yet complete.

Internal Flow

The steps inside the Worker look like this:

Receive a blog post as raw text.
Use OpenAI to generate a narration script.
Send that script to OpenAI’s text-to-speech API.
Store the resulting audio in R2.
Save metadata (status, timestamps, transcript) in D1.
Update the episode’s status in D1 so the retrieval endpoint reflects the latest state.

Episode Retrieval

Now, to retrieve the episode using GET /api/episodes/:slug, the request looks like this:

curl -X GET http://localhost:8787/api/episodes/making-a-podcast-app

When you retrieve an episode, the response reflects its current state. At first, it may look like this:

{
  "success": true,
  "episode": {
    "slug": "making-a-podcast-app",
    "audioFile": null,
    "status": "pending",
    "transcript": null
  }
}

Once processing finishes, it looks like this:

{
  "success": true,
  "episode": {
    "slug": "making-a-podcast-app",
    "audioFile": "making-a-podcast-app.wav",
    "status": "complete",
    "transcript": "{\"dialogue\":[{\"hostName\":\"string\",\"dialogue\":\"Hi everyone, today I’m diving into the process of building a podcast generation app.\"},..."
  }
}

In both cases, the response code is a 200.

Once the status is complete and the audioFile field is populated, the audio endpoint can be used to retrieve the actual audio:

curl -X 'GET' \
  'http://localhost:8787/api/audio/making-a-podcast-app.wav' \
  -H 'accept: audio/mpeg'

Storing and Serving Episodes

Episodes are stored across two layers. The audio files themselves are placed in R2 object storage, which provides cheap, scalable storage and allows the Worker to serve audio directly without worrying about persistence. Each audio file is stored using the episode slug as the key, so for example making-a-podcast-app.wav maps directly to /api/episodes/making-a-podcast-app. The metadata for each episode — including slug, transcript, timestamps, and current status (pending or complete) — lives in D1, making it easy for the retrieval endpoint to respond with structured JSON without embedding the actual audio.

When a client requests an audio file through GET /api/audio/:filename, the Worker streams the file directly from R2 back to the client. D1 is only ever queried for metadata, and R2 is only ever queried for raw binary audio. This separation of responsibilities turned out to be crucial. Without it, I would have had to encode audio as base64 in JSON responses, which would be slow and bloated. By splitting storage in this way, the Worker can serve fast metadata lookups while still delivering large audio files efficiently.

Here’s an example of downloading the audio file with curl:

curl -X GET http://localhost:8787/api/audio/making-a-podcast-app.wav \
  -H 'accept: audio/mpeg' --output making-a-podcast-app.wav

Testing the Worker

The integration tests exercise the real endpoints with OpenAI mocked. A few things they verify:

A non-existent route returns 404 with the plain text body "404 Not Found".
GET /api/episodes:
- Returns 200 with an empty list when the table is cleared.
- After inserting one row directly into D1, returns 200 with a single episode whose slug, status, audioFile, and transcript match the row.
POST /api/episodes (episode creation):
- Mocks openai.responses.parse to return a minimal dialogue and openai.audio.speech.create to return a 64-byte audio buffer.
- Returns 202 on creation.
- A subsequent GET /api/episodes/:slug returns 200 with status: "complete" and audioFile: "<slug>.wav".
- GET /api/audio/<audioFile> returns 200 with binary audio; the byte length matches the mocked buffer and the first few bytes are identical.
Duplicate creation is rejected:
- A second POST /api/episodes with the same slug returns 409 with the body "Conflict: episode already exists".

The tests reset state where needed (e.g., deleting from Episodes before list assertions) and focus on observable behavior: correct status codes, payload fields, and that audio retrieval returns real bytes. There’s also a TODO to add an "error" status path in the database for failure cases.

Unfortunately, I did encounter some difficulties when trying to use Vitest with the Workers framework. Specifically, I was unable to create a __mocks__ directory, and I also found Vitest's watch mode does not work with D1.

For the __mocks__ workaround, my test file has the following mock created at the top:

vi.mock("openai", () => {
  class OpenAI {
    constructor(_: any) { }
    get responses() {
      return { parse: responsesParse };
    }
    get audio() {
      return { speech: { create: audioCreate } };
    }
  }
  return { default: OpenAI };
});

As far as watch mode goes, there isn't a workaround for me at the moment. I suppose I could try to create a mock D1 instance, but that would require more time than I want to invest in it. For those interested in these particular problems, I found the following issues had been reported on GitHub:

Vitest watch mode and D1: https://github.com/cloudflare/workers-sdk/issues/9913.
Vitest __mocks__ not working: https://github.com/cloudflare/workers-sdk/issues/7679.

Conclusion

Building podcast-it gave me a chance to explore Cloudflare Workers beyond static hosting and really stress-test R2 + D1 together. The biggest takeaway was how much simpler the architecture became once I split audio storage and metadata storage — trying to jam everything into one place would have been painful.

The project is still rough around the edges, but it’s already useful for quickly turning writing into audio. In a follow-up, I’ll show how to wire podcast-it directly into my site’s publishing workflow.

If you’d like to dig into the code or try it yourself, the repo is open source: github.com/h93xV2/podcast-it. Feedback, bug reports, and ideas are very welcome.

Cache OpenAI Embeddings with SQLite for Low-Cost Astro Builds

logarithmicspirals — Thu, 05 Jun 2025 02:04:01 +0000

Introduction

Over the last few posts, I have been writing about how I implemented a "Similar Posts" component on my blog. In the first post, I presented an approach for recommending posts to users based on semantic similarity. In the second, most recent post, the concept was refined to include a filter to reduce the possibility of bad recommendations. In this third post, I will be looking at the feature from a developer perspective.

While working on the previous posts, I was using Astro's dev mode quite a bit. With Astro, one can run the command npm run dev to host the site locally in dev mode. When edits are made to files, the build automatically refreshes. I noticed the time needed to refresh was much slower than before the embedding code was added. Upon closer inspection, I realized the creation of the embeddings was quite slow and would happen each time the site refreshed.

The Cost of Re-Embedding — and Why SQLite Wins

Each time Astro rebuilt the site, it was calling the OpenAI API to re-embed all the posts — even though the post content hadn’t changed. That’s both inefficient and costly. When an API call is made, the build is slowed down by network latency and computation times. With a cache, I can save the results of previous requests.

To avoid repeated calls and improve performance, I evaluated a few caching strategies. When compared to some of the other available options, SQLite presents itself as a very appealing solution. The options I looked at were as follows:

A SQLite database.
Cloudflare KV or D1.
Astro DB.
JSON file.

While my first instinct was to reach for just plain SQLite, I gave some thought towards Cloudflare services or the Astro DB service. Something which immediately ruled out the Cloudflare services was the fact my site is completely, statically generated. To use KV or D1, I would need to create and manage an API key.

With Astro DB, my thinking was that I am basically just using SQLite. Astro DB uses libSQL under the hood, and libSQL is a fork of SQLite. I found a Reddit thread about libSQL which made me think very carefully about using the service. One of the commenters mentioned the Redis debacle, and I realized for this project it would be better to stick to plain SQLite.

Lastly, the JSON idea came from OpenAI embeddings cookbook. The cookbook is written in Python and uses a pkl file for caching. An equivalent for my Astro project would be a JSON file. However, I still decided to go with the SQLite approach since it would be more scalable over time. For example, I could switch to a different programming language or move my database to the cloud via Astro DB or Turso.

Implementing the Cache in Your Astro Build

The caching mechanism will work as follows:

Given a slug and body for a post, hash the post body. This ensures we can detect when post content has changed, even if the slug stays the same.
Check if a record exists for the slug in the database.
If a record does not exist, compute the embedding. Save the embedding and hash to the database. Return the embedding.
If a record does exist and the hashes do not match, recompute the embedding. Save the new embedding and hash to the database. Return the embedding.
If a record does exist and the hashes match, return the embedding from the database.

Implemented in code, this is what the embedding with caching function looks like:

// src/utils/openai.ts

const currentFilePath = fileURLToPath(import.meta.url);
const currentDir = dirname(currentFilePath);
const astroDir = resolve(currentDir, '../..', '.astro');
const dbPath = join(astroDir, 'embeddings.db');

if (!existsSync(astroDir)) {
  mkdirSync(astroDir);
}

const db = new Database(dbPath);
db.exec(`
  CREATE TABLE IF NOT EXISTS embeddings (
    post_id TEXT PRIMARY KEY,
    post_hash TEXT,
    embedding TEXT
  );
`); // Define the table for caching the embeddings.

type EmbeddingsRow = {
  post_id: string;
  post_hash: string;
  embedding: string;
};

const getPostEmbedding = async (apiKey: string, post: PostContent): Promise<Embedding> => {
  const {slug, content} = post;
  const hash = createHash('sha256'); // Step 1
  hash.update(content);

  const hashedContent = hash.digest('hex');
  const row = db.prepare('SELECT * FROM embeddings WHERE post_id = ?').get(slug) as EmbeddingsRow;

  if (!row) { // Step 2/3. Embedding is not cached, so we generate one and save it.
    const vector = await getEmbedding(apiKey, content);
    const insert = db.prepare('INSERT INTO embeddings (post_id, post_hash, embedding) VALUES (?, ?, ?)');
    insert.run(slug, hashedContent, JSON.stringify(vector));

    return {
      slug,
      vector
    };
  } else if (row.post_hash !== hashedContent) { // Step 4. Post was updated, so we regenerate and save a new embedding.
    const vector = await getEmbedding(apiKey, content);
    const update = db.prepare('UPDATE embeddings SET post_hash = ?, embedding = ? WHERE post_id = ?');
    update.run(hashedContent, JSON.stringify(vector), slug);

    return {
      slug,
      vector
    };
  }

  return {
    slug,
    vector: JSON.parse(row.embedding), // Step 5. Return the embedding from the cache.
  };
};

// Helper method for common OpenAI requests.
const getEmbedding = async (apiKey: string, content: string): Promise<number[]> => {
  const openai = getClient(apiKey);
  const response = await openai.embeddings.create({
    model: "text-embedding-3-small",
    input: content
  });
  const vector = response.data[0].embedding;

  return vector;
};

Choosing the .astro Directory for the Cache

You might be wondering why the SQLite file is stored inside the .astro directory. This choice is intentional:

Astro already uses this folder for build artifacts, so it’s not committed to version control.
It’s automatically ignored in most setups (.gitignore, .prettierignore, etc.).
Cloudflare Pages caches .astro/ between builds for up to seven days, which means the cache can persist across deploys without needing any additional configuration.

This setup keeps things tidy, avoids polluting the project root, and gives you build-time performance benefits for free if you’re deploying to Cloudflare. Caching could come in handy for situations where a lot of changes are being deployed within the seven day window.

Real-World Impact: Performance, Cost, and Stability

The best way to show how caching improves performance is with some data. To illustrate how caching helps, I ran three build scenarios for my Astro site:

No caching.
Caching enabled, but cache has not been created.
Caching enabled, and cache exists.

For the first two scenarios, the commands were as follows:

rm -r .astro
time npm run build

For the third scenario, I did not want to delete the .astro directory because that's where the SQLite DB file lives. So for the third scenario, I just ran:

time npm run build

Each scenario was run five times. The total run time was saved for each run. I then computed the average of those times so that each scenario could be compared quantitatively. Here are the results:

Scenario	Average Real Time (s)	Min (s)	Max (s)
Without caching	16.9342	15.593	19.563
With caching, no cache	18.2872	16.403	21.159
With caching, cache hit	6.2574	6.011	6.575

As expected, the fastest build time is when the cache exists. A whole ten seconds is saved in comparison to the no-cache approach. Interestingly, the slowest time is when caching is enabled but no cache exists yet. This is probably because the inserts add a little extra time as compared to the no-caching approach.

Beyond just the numbers, this approach brought noticeable improvements in my development workflow:

Speed: Local builds are significantly faster with cached embeddings. Once the cache is warm, I can refresh the site in under 7 seconds.
Savings: Each API call to OpenAI costs time and money. By caching embeddings, I eliminate redundant requests and reduce usage-based costs over time.
Stability: With everything stored locally, builds are more deterministic and can even run offline. That’s a big deal when working in CI environments or disconnected dev setups. Future improvements could even involve using local LLMs to further decouple from the web.

Caching doesn’t just improve numbers — it improves confidence in your toolchain.

Conclusion

Caching embeddings turned out to be one of those rare changes that improved everything at once — speed, cost, and reliability. By introducing a simple SQLite-based layer, I eliminated redundant API calls, dramatically reduced build times, and made local development feel snappy again.

It’s easy to reach for the cloud or a more complex tool, but sometimes the best solution is the simplest one. SQLite offered just the right balance of power and portability for my static Astro setup — and it’s flexible enough to evolve with the project.

If you’re building AI-powered features into your site, especially in a static or semi-static environment, don’t wait to add caching. You’ll save time, money, and frustration — and your build process will thank you.

Refining “Similar Posts” for Relevance and Simplicity

logarithmicspirals — Sat, 31 May 2025 20:54:58 +0000

Introduction

In a previous post, I described how I created a "Similar Posts" component for my blog. Originally, that was going to be a one-shot post. After deploying the new feature, I noticed that some of the recommended posts were irrelevant.

Why the Old Approach Fell Short

Shortly after publishing my last post, I was surfing the web and came across something I had not considered while implementing my "Similar Posts" feature. For example, when I was looking at my previous article AMD RX 6700 XT Overclocking: Unlocking Max Performance I noticed the following posts were displayed as similar:

While the first post seemed reasonable, I thought the other two seemed unrelated. This observation sent me on a search to determine if there was something I was missing. While asking ChatGPT, it suggested I should try to set a threshold score. However, ChatGPT's suggestion did not include a way to calculate the score empirically. So I did some Google searches.

Unfortunately, most of the discussions on the first page of Google did not mention how to calculate a threshold. There was one GitHub repository which mentioned using K-means clustering, and there were some discussions on various forums like the OpenAI Developer Community. From reviewing these resources, I came to the conclusion there is no one-size-fits-all approach to determining a cutoff point.

Goals for the Similar Post Component

The component should do the following:

Select only the most relevant posts to be displayed.
Help users find content in a way which is not provided by other components on the page.
Display nothing if no relevant posts can be found.

While I knocked around different ideas like calculating tag overlap or series alignment, the simplest approach seemed to be adding the cosine similarity threshold as a cutoff. To figure out what the threshold was, I needed to first gather some data and do some calculations.

Gathering the Data

To guide my decision-making, I created a new API endpoint to collect and analyze post similarity scores. An API endpoint would allow me to quickly display the results of important calculations like mean, median, and percentiles. The endpoint I created was src/pages/api/post-similarity.json.ts and it contains the following code:

// src/pages/api/post-similarity.json.ts

import { POST_EMBEDDINGS } from "@content/tags-and-posts";
import { getPairWiseSimilarityScores } from "@utils/related-posts";

export async function GET() {
  const similarities = getPairWiseSimilarityScores(POST_EMBEDDINGS);
  const sortedSimilarities = [...similarities].sort((a, b) => a - b);

  // Do the math.
  const min = Math.min(...similarities);
  const max = Math.max(...similarities);
  const mean = similarities.reduce((a, b) => a + b, 0) / similarities.length;
  const half = Math.floor(similarities.length / 2);
  const median = sortedSimilarities.length % 2
    ? sortedSimilarities[half]
    : (sortedSimilarities[half - 1] + sortedSimilarities[half]) / 2
  const p90 = sortedSimilarities[Math.floor(similarities.length * 0.9)];
  const p75 = sortedSimilarities[Math.floor(similarities.length * 0.75)];

  // Return the results as JSON.
  return new Response(
    JSON.stringify({
      min,
      max,
      mean,
      median,
      p75, // 75th percentile
      p90, // 90th percentile
      numberOfScores: similarities.length, // For sanity check.
      similarities
    })
  );
}

For clarification, the method getPairWiseSimilarityScores is new and was added to the src/utils/related-posts.ts file. The function computes cosine similarity for all pairs of posts on the site. The function does not compare posts to themselves. Here's the code for the function:

// src/utils/related-posts.ts

const getPairWiseSimilarityScores = (embeddings: Embedding[]) => {
  const pairs: number[] = [];

  for (let i = 0; i < embeddings.length; i++) {
    // Start inner loop at i + 1 to not compute similarity between a post and itself.
    for (let j = i + 1; j < embeddings.length; j++) {
      const sim = getCosineSimilarity(embeddings[i].vector, embeddings[j].vector);
      pairs.push(sim);
    }
  }

  return pairs;
};

With the array of scores, I was able to see a clear picture of the kinds of posts I have been writing. Here's what I saw in the JSON returned from the endpoint:

Calculation Type	Result
Min	0.08
Max	1
Mean	0.49
Median	0.58
p75	0.66
p90	0.72
Number of Scores	496

For the sanity check "Number of Scores", this was just to confirm I calculated the correct number of pair-wise cosine similarity scores. The expected value was (n x (n - 1)) / 2 where n is the number of posts. With 32 posts, we have (32 x 31) / 2 which is 496.

Upon initial review of these results, I first tried to set the threshold at 0.72 so only the most relevant posts would be displayed. However, when I went through all the articles I noticed a lot only had one or two posts showing up as similar. This didn't seem quite right to me. Knowing that there was a wide dispersal of scores from 0.08 to 1, I decided to try and visualize the data.

To better understand the spread of scores, I exported the similarities array from the API’s JSON response into Google Sheets and created a histogram:

To me, it looks like a bimodal distribution. Usually, when a bimodal distribution is observed it indicates there are two populations being measured. From this, we can ascertain the data has a dense cluster of topic similarity around 0.65, since that is the value in the middle of the upper mode. Interestingly, this is pretty close to the 75th percentile. The lower mode maybe indicates a cluster of loosely related topics. We can also see the 90th percentile value of 0.72 only allows a very small number of posts to pass the cutoff.

How the Component Works Now

Selecting only posts with a cosine similarity at or above 0.65 should allow for the most number of posts with a high level of semantic similarity to be displayed. With that in mind, I had to modify the code used for gathering related posts.

The main change is now the "Similar Components" section could have less than three articles listed, or not appear at all, because of the threshold filtering. Previously, all posts had more than three similar articles. With this new approach, articles may not have any other post pass the threshold.

With the threshold hard-coded into the file containing the post collecting function, this is what src/utils/related-posts.ts was updated to:

// src/utils/related-posts.ts 

const COSINE_THRESHOLD = 0.65; // The hard-coded threshold cosine similarity score.

const getSlugToMostRelatedPostsMap = (embeddings: Embedding[]) => {
  const slugToMostRelatedPosts: Map<string, ScoredPost[]> = new Map();

  for (const a of embeddings) {
    const sims: ScoredPost[] = embeddings
      .filter(b => b.slug !== a.slug)
      .map(b => ({
        slug: b.slug,
        score: getCosineSimilarity(a.vector, b.vector),
      }))
      .filter((c) => COSINE_THRESHOLD <= c.score) // New step to only allow posts at or over the threshold.
      .sort((a, b) => b.score - a.score)
      .slice(0, 3);

    slugToMostRelatedPosts.set(a.slug, sims);
  }
  return slugToMostRelatedPosts;
};

Conveniently, the way I developed my "Similar Posts" component prevents it from being displayed when no similar posts are found. See my last article for the full code, but pay attention to this part:

---
// src/components/blog/SimilarPosts.astro
// ...
---
{
  posts.length > 0 && (
    <!-- HTML for the component here -->
  )
}

The posts.length > 0 is a logical gate to prevent the component from appearing. With an empty list, no HTML is rendered.

Future Considerations

The data provided by the embeddings opens up interesting avenues of exploration. For example, it could be paired with search performance data from Google Search Console to help me determine which posts can be archived. A post without any search clicks or embedding connections could be a target for archiving. On the flip side, a post with lots of embedding connections and good search results might indicate an opportunity for content growth.

This makes me want to prioritize two things from a site owner perspective:

Replace image slugs with full image URLs in markdown before cross-posting.
Automatically update posts on other platforms.

If I want to auto update posts on DEV and Hashnode, I need to first solve the image URL problem for the markdown bodies.

Conclusion

Refining this feature reminded me that building with AI isn’t just about plugging in smart tools—it’s about constantly validating whether the results actually make sense. What looks good on paper (or in code) doesn’t always translate to a meaningful experience for readers. By stepping back, analyzing the data, and adjusting a single threshold, I was able to make my “Similar Posts” component both smarter and simpler.

As with any machine learning-driven feature, relevance isn’t automatic—it’s earned through iteration.

Add 🤖 AI‑Powered Similar Posts 🔍 to Your Astro Blog — Here’s How

logarithmicspirals — Sun, 25 May 2025 02:27:41 +0000

Introduction

Since last year, I have wanted to find more ways to integrate AI into my blog. So far, I’ve used AI to help write posts, research posts, cross-post, and generate hero images. Of those, cross-posting is the only process that runs fully autonomously. To enrich the site experience and require less manual input from me, I came up with the idea of using embeddings to find similar posts for each article.

One idea I had was to use embeddings for creating a "Similar Posts" component. The idea was inspired by Hashnode's "More Articles" component displayed at the bottom of posts.

The Hashnode component is interesting, but it seems to only display the three most recent articles. While taking some visual inspiration from it, my "Similar Posts" component instead uses text embeddings and cosine similarity calculations to select the three articles to display.

Understanding the AI Approach

First, let's clarify something. What is an embedding? For those who are unaware, OpenAI defines an embedding as follows:

An embedding is a vector (list) of floating point numbers. The distance between two vectors measures their relatedness. Small distances suggest high relatedness and large distances suggest low relatedness.

With respect to my "Similar Posts" feature, I will be converting each post to a vector. Then I will compare each vector to all the others by calculating their distances to each other.

In other words, the technique will be:

Calculate embeddings for all articles by passing each article’s text to an embedding model.
Compare the embedding for the given article with the embeddings of all other articles using cosine similarity.
Select the articles corresponding to the top three embeddings with the closest cosine similarity.

To help visualize this, I have created the following diagram:

In summary, the embedding model can be thought of as a function. The model takes text as an input, and returns an array of numbers which represent a vector within the space of the model. To mirror this functional thinking, I defined the following types to represent my blog posts as inputs and outputs:

// The PostContent will be our input.
type PostContent = {
  slug: string;
  content: string;
};

// The Embedding will be our output.
type Embedding = {
  slug: string;
  vector: number[];
};

For the embedding model, I decided to use OpenAI's embeddings API with the text-embedding-3-small model. To make things clearer, here's a diagram representing how posts will be converted to embeddings:

Now let's move on to how I actually implemented this in code.

Generating Similar Post Data

After defining the two types above, I added them to my src/utils/openai.ts file. Then I defined a new function getPostEmbedding:

// src/utils/openai.ts

type PostContent = {
  slug: string;
  content: string;
};

type Embedding = {
  slug: string;
  vector: number[];
};

const getPostEmbedding = async (apiKey: string, post: PostContent): Promise<Embedding> => {
  const openai = getClient(apiKey);
  const response = await openai.embeddings.create({
    model: "text-embedding-3-small",
    input: post.content
  });

  return {
    slug: post.slug,
    vector: response.data[0].embedding,
  };
};

The getPostEmbedding function is pretty simple. It just takes the text of the post, sends it to OpenAI's API, and then returns the resulting embedding. Next, I needed to pass each post to the embedding function. With my site, I have one file which loads all the posts in to memory called src/data/tags-and-posts.ts. Here's what I did:

// src/data/tags-and-posts.ts

const embeddings: Embedding[] = [];

for (let i = 0; i < posts.length; i ++) {
  const post = posts[i];

  // Other computations are done here, like tag grouping.

  const embedding = await getPostEmbedding(import.meta.env.OPENAI_API_KEY || '', {
    slug: post.id,
    content: post.body || '' // NOTE: We're using post.body which is the raw markdown of the blog post
  });

  embeddings.push(embedding);
};

Next, I had to perform the cosine similarity calculations. To handle this, I created a new file src/utils/related-posts.ts and added the following code:

// src/utils/related-posts.ts

const getCosineSimilarity = (vectorA: number[], vectorB: number[]) => {
  // See https://stackoverflow.com/a/64816824 for dot product calculation explained.
  const dot = vectorA.reduce((sum, val, i) => sum + (val * vectorB[i]), 0);
  const magnitudeA = Math.sqrt(vectorA.reduce((sum, val) => sum + (val * val), 0));
  const magnitudeB = Math.sqrt(vectorB.reduce((sum, val) => sum + (val * val), 0));
  return dot / (magnitudeA * magnitudeB);
};

// A new type used for comparing posts to each other.
type ScoredPost = {
  slug: string;
  score: number;
};

const getSlugToMostRelatedPostsMap = (embeddings: Embedding[]) => {
  const slugToMostRelatedPosts: Map<string, ScoredPost[]> = new Map();

  for (const a of embeddings) {
    const sims: ScoredPost[] = embeddings
      .filter(b => b.slug !== a.slug)
      .map(b => ({
        slug: b.slug,
        score: getCosineSimilarity(a.vector, b.vector), // This is where the cosine similarity calculation comes in.
      }))
      .sort((a, b) => b.score - a.score)
      .slice(0, 3);

    slugToMostRelatedPosts.set(a.slug, sims);
  }

  return slugToMostRelatedPosts;
};

The function getSlugToMostRelatedPostsMap returns a map of slugs (represented as strings) to the most related posts. This map can be used to then retrieve the most relevant Post objects for a given post. Going back to tags-and-posts.ts, here's how I integrated the new function:

// src/utils/tags-and-posts.ts

// ... At this point, we’ve created an array of embeddings.

const slugToRelatedPosts: Map<string, ScoredPost[]> = getSlugToMostRelatedPostsMap(embeddings);

const getRelatedPostsFromSlug = (slug: string) => {
  const similarScoredPosts = new Set(slugToRelatedPosts.get(slug)?.map(scoredPost => scoredPost.slug) || []);
  const related: Post[] = [];

  for (const post of posts) {
    if (similarScoredPosts.has(post.id)) {
      related.push(post);
    }
  }

  return related;
};

The getRelatedPostsFromSlug function can now retrieve the most similar posts for a given slug (aka id property). With all the necessary calculations and functions ready, we can display the results on the site.

Displaying Related Posts in Astro

To display related posts, I first created a new Astro component file called src/components/blog/SimilarPosts.astro:

---
import { getRelatedPostsFromSlug, type Post } from '@content/tags-and-posts';
import HeroImage from './HeroImage.astro';

interface Props {
  post: Post;
}

const { post } = Astro.props;

const posts: Post[] = getRelatedPostsFromSlug(post.id);
---

{posts.length > 0 && (
  <section class="section">
    <h2 class="title is-4 has-text-centered">Similar Posts</h2>
    <div class="columns is-multiline">
      {posts.map((similarPost, index) => {
        const heroImage = similarPost.data.heroImage;

        return (
          <div class="column is-one-third">
            <div class="card h-100">
              <div class="card-image">
                <HeroImage
                  image={heroImage}
                  alt={similarPost.data.heroImageAlt}
                  loading="lazy"
                  isThumbnail={true}
                />
              </div>
              <div class="card-content">
                <h3 class="title is-5 mb-2">
                  <a class="title-link" href={`/blog/${similarPost.id}/`}>
                    {similarPost.data.title}
                  </a>
                </h3>
                <p class="is-size-6">{similarPost.data.description}</p>
              </div>
            </div>
          </div>
        );
      })}
    </div>
  </section>
)}

The actual UI of this is similar to the Hashnode one since I'm displaying three posts in a row with the image at the top of the card. However, mine does not display the author since all the posts on the site are written by me.

Finally, I added the new component to the bottom of my blog posts. The component was added to the file src/pages/blog/[id].astro which is the file used to generate the page for each post. I won't show the whole file because it's too large, but here's what the code looks like:

---
// ...

export async function getStaticPaths() {
  return POSTS.map((post: Post) => ({
    params: { id: post.id },
    props: { post },
  }));
}

const { post } = Astro.props;

// ...
---

<!-- ... -->

<SimilarPosts post={post} />

Lastly, here's a screenshot of what the new component looks like in the browser:

Conclusion

This “Similar Posts” feature is a small but meaningful upgrade that improves content discovery without sacrificing the simplicity of a static site. By precomputing embeddings and using cosine similarity, I was able to generate AI-powered recommendations that are fast, relevant, and completely server-free. It’s a great example of how practical AI tooling can enhance the developer experience — even in static site projects.

📂 Implementing Series Support in Astro 🛠️

logarithmicspirals — Sat, 08 Mar 2025 05:28:50 +0000

Introduction

In my previous post on adding series support to my blog, I discussed the motivation behind this feature—how grouping related posts into a cohesive narrative enhances content organization, improves discoverability, and fosters deeper engagement. By implementing series support, I aimed to bridge content silos, making it easier for readers to follow along while also leveraging cross-platform compatibility with DEV and Hashnode.

Now that the why is clear, it’s time to explore the how. This post is a deep dive into the technical implementation of series support in my Astro-powered blog. I’ll walk through the data modeling process, UI updates, and platform integration strategies that allow me to seamlessly structure and display series-based content—both on my site and across external platforms.

By the end of this post, you’ll see how I built a flexible, scalable series system that enhances my blogging workflow while maintaining compatibility with DEV and Hashnode’s different approaches to series. Let’s get started! 🚀

Designing a Series Data Model

The first step toward adding series support to my blog was defining how a series should be structured. To enhance my own understanding, I looked to DEV and Hashnode for inspiration. Both platforms support the creation of series for posts, but they approach the concept in dramatically different ways.

First, let's look at DEV since creating a series through the Forem API is relatively simple compared to Hashnode. To understand the DEV approach, we can look at the Forem API v1 docs for publishing an article. The key thing to notice is the series field can be either a string or null. In other words, all one needs to do is pass a string value for the series when creating a draft or publishing an article. Pretty simple!

Now, let's turn our attention to Hashnode. Hashnode has a more complex approach to series creation than DEV. In contrast to DEV, Hashnode requires three additional fields for each series: slug, cover image, and description. The slug is an identifier used to create a page for the series. A series page on Hashnode displays the cover image, description, and posts in the series.

In short, DEV allows series creation by simply passing a string, while Hashnode requires additional metadata like a slug, cover image, and description. Here’s a direct comparison:

Feature	Hashnode	DEV
Slug	Yes	No
Name	Yes	Yes
Cover image	Yes	No
Description	Yes	No

Since I want to support cross-posting to both platforms, I have to support all of the Hashnode features. In terms of data, I must support the slug, name, cover image, and description. However, I do not necessarily need to have my page structure and UI mimic that of Hashnode.

Adding Series to the Content Layer

First, I had to define the structure of a series in the content layer. Here's what I came up with:

const series = defineCollection({
  schema: ({ image }) => z.object({
    name: z.string(),
    description: z.string(),
    coverImage: image(),
    coverImageAlt: z.string()
  }),
  loader: glob({ pattern: "**/*.json", base: "./src/data/series" }),
});

I have added an additional field coverImageAlt which represents the alt text for the cover image. In Astro v5, the slug is automatically generated from the file name using the content loader API. However, the slug in this case is represented as the ID for the collection entry. I chose JSON files for series data because they provide a structured, easily queryable format that integrates well with Astro’s content collections. Each series will be defined through a JSON file in the src/data/series folder. So a series file src/data/series/my-new-series.json will have a slug/ID of my-new-series.

Here's how my approach compares to DEV and Hashnode:

Feature	Hashnode	DEV	Logarithmic Spirals
Slug	Yes	No	Yes
Name	Yes	Yes	Yes
Cover image	Yes	No	Yes
Description	Yes	No	Yes
Cover image alt	No	No	Yes

To connect this to my posts, I had to add a field for a series reference to the post schema definition:

const BasePostSchema = z.object({
  title: z.string().min(1),
  description: z.string().min(1),
  pubDate: z.coerce.date(),
  updatedDate: z.coerce.date().optional(),
  heroImageAlt: z.string(),
  tags: z.array(reference('tags')).min(1).max(5),
  series: z.optional(reference('series'))
});

This BasePostSchema is extended to create different post collections. For example, I have a collection defined for all my posts saved as markdown files and a collection for my posts imported from DEV. Here's what the markdown post collection looks like:

const PostSchema = ({ image }) => BasePostSchema.extend({
  heroImage: image(),
  publish: z.boolean()
});

const blog = defineCollection({
  loader: glob({ pattern: '**/*.{md,mdx}', base: "./src/data/blog" }),
  schema: PostSchema
});

To start, I will only create series from markdown posts. However, I will eventually work on pulling series from DEV and Hashnode into their own content collections.

Creating New Pages

Once I had figured out what the series structure looked like, I decided to add new pages so visitors would be able to navigate easily through them. The inspiration for this approach came from Hashnode's series implementation. The reason they require more data is because they use the data to generate pages. Looking at their approach, I realized I needed the following:

A page to show all the series on my site.
A page for each series showing the cover image, title, description, and associated articles.

These pages provide a structured way for visitors to browse and follow series content:

/blog/series/ for the page showing all the series.
/blog/series/{id}/ for the individual series pages.

Here's what the new "Series" page looks like:

And here's what an individual series page looks like:

Updating the UI

With series pages in place, the next step was ensuring smooth navigation. I made several UI updates to help visitors find and explore series content effortlessly. Here's what the new navbar looks like:

Previously, my navbar had separate links for ‘Blog’ and ‘Tags’. Now, I’ve consolidated them under a single ‘Blog’ dropdown, making room for a dedicated ‘Series’ link. This keeps the navigation clean while ensuring series content is easy to access.

Additionally, I also took cues from DEV and Hashnode to add some kind of navigation element indicating an article is part of a series. By having a link to the series associated with each article, it should be easier for visitors to find the other articles in a series. Here's an example:

In the above screenshot, we can see an open book icon with a link. The link says "Building a Better Blog with Series Support". The link directs users to the series which the article is a part of.

Platform Integration

For a while, I have been cross-posting to DEV via RSS. When new posts get published to my RSS feed, DEV can automatically import them to create drafts. However, I want to have more control over how the publishing is done. Moving to use the Forem API V1 gives me that control.

DEV

Building on the work I did to implement Hashnode cross-posting, I have added some new code to handle DEV cross-posts via the Forem API V1. To start, I had to create a new endpoint to give me JSON for DEV. The endpoint is /api/posts-for-dev.json:

// src/pages/api/posts-for-dev.json.ts

import { POSTS } from "@content/tags-and-posts";
import type { DevDraft } from "@utils/devto";
import { getCollection, type CollectionEntry } from "astro:content";

export async function GET() {
  const series = await getCollection('series');
  const postData: DevDraft[] = POSTS
    .filter(post => post.collection === 'blog')
    .map((post: CollectionEntry<'blog'>) => {
      if (!post.body) {
        throw new Error(`Post with ID ${post.id} has no body`);
      }

      const seriesId = post.data.series?.id;
      const seriesName = seriesId ? series.find(s => s.id === seriesId)?.data.name : undefined;

      return {
        title: post.data.title,
        body_markdown: post.body,
        series: seriesName,
        main_image: post.data.heroImage,
        description: post.data.description,
        id: post.id,
        tags: post.data.tags.map(tag => tag.id.replace("-","")) // Note the string replacement
      };
    });

  return new Response(JSON.stringify(postData));
}

Something I want to call out in the above code is the string replacement tag.id.replace("-",""). The "-" character needs to be removed from tags because DEV only supports alphanumeric characters in their tags. I was getting the following error when trying to create a draft:

Reason for failure: {"error":"Tag \"content-strategy\" contains non-alphanumeric or prohibited unicode characters and Tag \"technical-writing\" contains non-alphanumeric or prohibited unicode characters","status":422}

Unfortunately, the DEV API was not helpful in resolving this error. In fact, the API documentation is incorrect. It states the tags field is type string. However, it's actually a string array. So ["webdev","api"] is valid, but "webdev,api" is invalid.

Anyway, moving on. The generated JSON is then read from the file system. Requests are made to the Forem API using the parsed data:

// src/integrations/cross-post.ts

const devJson = getJsonFromApiEndpoint(assets, '/api/posts-for-dev.json', routes, logger);

if (devJson) {
  const { fileContent, filePath } = devJson;
  const data: DevDraft[] = JSON.parse(fileContent);
  const token = process.env.DEV_API_KEY;

  if (token) {
    await createDevDrafts(token, data, logger);
  } else {
    logger.error('No DEV API key configured');
  }

  fs.rmSync(filePath);

  apiDirectory = path.dirname(filePath);
} else {
  logger.error('Could not retrieve JSON for DEV cross-posts');
}

The important part of the above snippet is the call to the createDevDrafts function. The definition for this function is as follows:

// src/utils/devto.ts

const createDevDrafts = async (apiKey: string, devDrafts: DevDraft[], logger: AstroIntegrationLogger) => {
  const allUsedCanonicalUrls = new Set((await getAllArticles(apiKey))
    .map((article: { canonical_url: string }) => article.canonical_url));

  let draftsCreated = 0;

  for (let i = 0; i < devDrafts.length; i ++) {
    const devDraft = devDrafts[i];
    const canonicalUrlForDraft = `${SITE}/blog/${devDraft.id}`;
    const oldUrl = `${SITE}/${devDraft.id}`;

    if (!(
        allUsedCanonicalUrls.has(canonicalUrlForDraft)
          || allUsedCanonicalUrls.has(canonicalUrlForDraft + "/")
          || allUsedCanonicalUrls.has(oldUrl)
          || allUsedCanonicalUrls.has(oldUrl + "/")
      )) {
      const resultStatus = await createDraft(apiKey, devDraft, logger);

      if (resultStatus === 201) {
        draftsCreated += 1;
        allUsedCanonicalUrls.add(canonicalUrlForDraft);
        logger.info(`Draft created on DEV with slug ${devDraft.id}`);
      } else if (resultStatus) {
        const statusMeaning = ERROR_STATUS_CODE_TO_MEANING.get(resultStatus);
        logger.error(`Upload to DEV failed for slug ${devDraft.id} with reason ${statusMeaning}`);
      } else {
        logger.error(`No status code received from DEV for slug ${devDraft.id}`);
      }
    } else {
      logger.info(`Post exists on DEV with slug ${devDraft.id}`);
    }
  }

  logger.info(`DEV drafts created = ${draftsCreated}`);
};

The important part to take note of is the if-condition which checks whether or not the current canonical URL has been used. This check prevents multiple copies of a draft from being created. The canonical URLs are created by first getting a list of
all the articles from my account:

// src/utils/devto.ts

const getAllArticles = async (apiKey: string) => {
  return await (await fetch(`https://dev.to/api/articles/me/all`, {
    'headers': {
      'api-key': apiKey
    }
  })).json();
};

When an article's canonical URL has not been used, we create the draft through the Forem API by setting the published field to false:

// src/utils/devto.ts

const createDraft = async (apiKey: string, devDraft: DevDraft, logger: AstroIntegrationLogger) => {
  try {
    const response = await fetch(`https://dev.to/api/articles`, {
      method: 'POST',
      headers: {
        'api-key': apiKey,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        article: {
          title: devDraft.title,
          body_markdown: devDraft.body_markdown,
          published: false, // Creates a draft.
          series: devDraft.series,
          main_image: devDraft.main_image,
          canonical_url: `${SITE}/blog/${devDraft.id}/`,
          description: devDraft.description,
          tags: devDraft.description
        }
      })
    });
    const status = response.status;

    if (status !== 201) {
      logger.error(`Reason for failure: ${JSON.stringify(await response.json())}`)
    }

    return status;
  } catch (e) {
    logger.error(JSON.stringify(e));
  }

  return undefined;
};

Hashnode

For Hashnode, I did not have to do as much work since I already had built out an integration. I simply had to update the existing code to include the creation of a series if one did not already exist:

// src/utils/hashnode.ts

// This is inside the createDraft function:

if (post.series) {
  const result: SeriesResult = await grapQLClient.request(getSeriesBySlugQuery, { slug: post.series.slug });
  const seriesId = result.me.publications.edges[0].node.series?.id;

  if (seriesId) { // A series exists.
    draftVariables.input['seriesId'] = seriesId
  } else {
    logger.info('No series exists with name ' + post.series.name);

    const newSeriesInput: CreateSeriesInput = {
      name: post.series.name,
      slug: post.series.slug,
      descriptionMarkdown: post.series.description,
      coverImage: SITE + post.series.coverImage,
      publicationId: publicationId
    };
    const newSeriesResult: CreateSeriesResult = await grapQLClient.request(createSeriesMutation,
      { input: newSeriesInput }); // We make a new series because one does not exist yet.

    draftVariables.input['seriesId'] = newSeriesResult.createSeries.series.id;
  }
}

Conceptually, this differs from DEV. With DEV, we simply pass the series name, whereas with Hashnode, we must first create a series object. Once we have a series object, we link an article to the series by passing the series ID when creating the article draft. To get the existing series, I first use this query:

query GetSeriesBySlug($slug: String!) {
  me {
    publications(first: 1) {
      edges {
        node {
          series(slug: $slug) {
            id
          }
        }
      }
    }
  }
}

If a series already exists for the slug I'm using, I will use the corresponding ID when creating the draft. However, if a series does not exist then I create one with the following mutation:

mutation CreateSeries($input: CreateSeriesInput!) {
  createSeries(input: $input) {
    series {
      id
    }
  }
}

The input for this mutation is defined as follows:

type CreateSeriesInput = {
  name: string;
  slug: string;
  descriptionMarkdown: string;
  coverImage: string;
  publicationId: string;
};

Conclusion

Building series support in my Astro-powered blog was more than just a technical exercise—it was a step toward better content organization, improved discoverability, and seamless cross-platform integration. By structuring series data effectively, I’ve created a system that:

✅ Groups related posts under a cohesive series for easier navigation.
✅ Enhances content discoverability through dedicated series pages.
✅ Improves the reading experience with clear visual indicators and structured UI updates.
✅ Supports cross-posting to DEV and Hashnode, ensuring consistency across platforms.

This implementation lays the groundwork for even more advanced features, such as automated series synchronization across platforms, intelligent content recommendations, and scheduled series publishing. As I continue refining this system, I plan to explore automating updates via APIs, making it even easier to manage series content across multiple platforms.

If you’re working on a similar challenge or have insights into structuring blog series, I’d love to hear your thoughts! How do you organize related content on your blog? Let’s collaborate and build better blogging experiences together. 🚀

Adding Series Support to My Blog: The Why and How 🤔🔍

logarithmicspirals — Thu, 06 Mar 2025 01:57:39 +0000

Introduction

While looking for ways to improve my blog, I noticed Hashnode and DEV both support series creation. For those unaware, a blog series is a collection of posts with a single narrative thread. After observing this concept being shared across these two platforms, I had an epiphany about what I needed to do with my own blog. I decided I would implement my own version of a blog series feature ☝️🤓💡.

The Series Lightbulb Moment

One thing that played a part in coming up with this idea was the writing process for my previous post My 2025 Roadmap: Balancing Growth, Creativity, and Impact.

In that post, I mentioned my desire to complete Hashnode's Serial Blogger challenge. When thinking about how I could complete that challenge, I realized Hashnode and DEV both support series creation. While their implementations differ, the feature allows related content to be grouped together.

Naturally, I saw a connection between these things. By building out series support for my own blog, I could group together all the posts related to completing the challenge while also leveraging the series feature on other platforms. Furthermore, creating my own series implementation would provide content to write about and prepare me for the Serial Blogger challenge.

Current Content Structure

My current content structure is built around a stream of posts. Some posts refer back to other posts for small, tangential reasons. However, there is no mechanism for connecting posts together under a single narrative. While this has worked so far, I have been planning some new content which would benefit greatly from being organized under a series.

While I do not have the benefit of creating series right now, I am able to add tags to my posts. For anyone interested, I wrote about adding support for tags (back when I was running my site with Gatsby) in an article titled Updating Blog Tags: Simple Metadata Enhancements. Tags are useful for grouping related content together, and when I cross-post my content I'm able to leverage the same tags on other platforms. However, tagged posts may not be directly related to each other. In contrast, a series is a group of posts all directly related to each other.

Series Vision

By organizing content under different series, my hope is to make different articles more easily discovered. Additionally, I hope it will encourage visitors to return over time as new articles in the series are published. One technique I have considered trying in this area is creating a post schedule. If I can build up a backlog of articles, I can publish them on a regular basis. From what I understand, frequent content updates are one of the best ways to
attract attention and improve appearance in search results.

Furthermore, a series system presents an opportunity for moving towards intelligent content suggestion. For example, if a user is reading an article which is part of a series, I can display a recommendation for them to read the next article in a series. Once I have a simple component like that in place, I could modify it to recommend users to similar articles based on content. The recommendations could be generated automatically rather than me having to structure the articles into groups via tags or series.

Beyond My Blog

Extending series support beyond my site unlocks a more connected content ecosystem. Readers who follow my posts on DEV or Hashnode will experience the same logical content flow, regardless of the platform they choose. This consistency can foster stronger engagement and loyalty. Specifically, DEV and Hashnode both support series creation via their APIs. By creating a tighter integration with other platforms, my goal is to give my audience a seamless experience no matter how, and where, they choose to engage.

Leveraging the APIs from DEV and Hashnode, I plan to automate series creation and synchronization across platforms. For instance, when a new post is added to a series on my blog, it could automatically update the corresponding series on these external platforms. This automation not only saves time but also ensures consistency across my content ecosystem.

I’m just getting started with this cross-platform series integration. In upcoming posts, I’ll document my approach to automating this process and share any lessons learned along the way. If you’ve tackled a similar challenge or have insights on cross-platform content strategies, I’d love to hear from you!

Conclusion

Adding series support to my blog is more than just a technical upgrade—it’s a strategic move toward better content organization, discoverability, and engagement. By grouping related posts into cohesive series, I aim to create a more intuitive reading experience for visitors while laying the groundwork for advanced features like intelligent content recommendations. Additionally, this functionality will make it easier to maintain consistency across platforms like DEV
and Hashnode.

Looking ahead, I’m excited to experiment with scheduled series posts, test out content suggestions, and track how these changes impact reader engagement. If you’ve implemented a similar feature on your blog or have ideas for enhancing content organization, I’d love to hear your thoughts! Let’s learn and grow together as we build better blogging experiences. 💡✨

My 2025 Roadmap: Balancing Growth, Creativity, and Impact

logarithmicspirals — Sat, 18 Jan 2025 22:36:14 +0000

This is a submission for the 2025 New Year Writing challenge: Compiling 2025.

My Roadmap for 2025

When I initially started writing this, everything was "business as usual." Coming off the heels of the holiday season, I was filled with optimism for 2025. However, as I started writing this roadmap, a terrible saga began to unfold. Multiple wildfires started up around me in the mountains surrounding Los Angeles. The devastation has extended to multiple communities and shaken the lives of millions of people.

While my challenges have been small in comparison, I was forced to confront a difficult question after receiving a false evacuation alert: what would I leave behind?

The wildfires around Los Angeles were a humbling experience, prompting deep reflection about what truly matters: loved ones, meaningful work, and health. With this renewed clarity, I’m approaching 2025 with a strategic focus on growth that aligns with my values and technical ambitions.

Personal Goals

First, I want to outline my personal goals. To me, these are important because without them I would allow myself to be consumed by my career or hobbies. Having things to look forward to outside of work gives me external motivation to complete things and do things well. Without external motivations, one can easily lose site of why they are working and run the risk of burnout.

As such, my personal goals for this year are:

Make quality time for loved ones 🏠.
Get plenty of sleep, exercise, and good nutrition 🥕.
Take a much needed roadtrip vacation 🚗.
Publish some music I have been working on since last year 🎶.

The roadtrip and music goals are the ones I am most looking forward too. The roadtrip is exciting because it can help achieve the first two goals. On the other hand, releasing my songs is exciting because it is a form of self-expression free from the constraints of engineering and career growth 😄. Exercising creative muscles is so important because without them life becomes dull and robotic.

Skills to Develop

Coming up with a list of skills is a little tricky since I already have developed quite a few useful ones in my career. Having moved to a more advanced role, I need to look for resources which help push me towards more high-value and difficult skill sets.

Having done some research, I want to focus on the following:

Distributed system design.
NoSQL and search databases.
Event-driven architectures.

These skills—distributed system design, NoSQL and search databases, and event-driven architectures—align with the growing demands of scalable, real-time, AI-driven systems. These areas are not entirely new to me, so I will be deepening my knowledge of them rather than exploring them for the first time. My personal website will serve as a proving ground to apply and deepen these competencies. For example, I have been wanting to build a "related articles" component which would recommend new articles for readers based on embeddings of other posts.

By mastering distributed systems, I aim to increase my ability to deliver high-impact solutions that align with business goals. Through NoSQL and search databases, I hope to broaden my knowledge of solutions to big-picture problems.

Another way I would like to build these skills is through this Data Engineering specialization by DeepLearning.AI . The key parts of the specialization I am most interested in are courses 2 and 3, where the focus is on pipeline building and data storage. Having completed some courses and specializations from them in the past, I have found there content to be as informative as it is practical.

Side Projects to Pursue

There are multiple side projects I want to tackle this year:

Build a SaaS idea I formulated at the end of last year.
Complete the Hashnode Serial Blogger challenge.
Continue to expand the reach of my personal website.

If I could complete any one of these I would be happy, but the top one on my last is the realization of a SaaS idea I came up with at the end of last year. Unfortunately, I can not share many details since the project is still in its early stages. However, I will say the next steps are:

Finish doing market research on the idea.
Create a simple prototype for testing.

The SaaS idea, like my website, provides an opportunity to develop the skills I listed in the previous section. For my project, I will have the opportunity to exercise system design, database development, and AI/ML skills. Additionally, I have the added bonus of being my own customer since the SaaS app is something I will be integrating with my website.

Lastly, expanding the reach of my website is something I want to keep working on. So far, I have been able to syndicate my blog posts across DEV, Hashnode, and BlueSky. I want to further expand this reach by cross-posting to Mastodon and maybe even LinkedIn. Another area I want move into is cross-posting images from my photo gallery over to BlueSky.

With these goals and projects, I’m excited to make 2025 a year of growth, creativity, and impact.

✍️ Cross-Posting Astro Blog Posts to BlueSky Using GPT-4 🧠

logarithmicspirals — Fri, 03 Jan 2025 12:00:00 +0000

The Problem

As I've added content to my website, I've started posting links to various social media platforms. In the past, I experimented with Mastodon, but didn't find it to be very useful. I've moved over to BlueSky recently and have started making posts about my new content there. However, I find the process of creating posts to be repetitive and somewhat tiring.

My solution to this is to expand on my previous efforts ofauto-publishing to Hashnode with a custom Astro integration, and add functionality to create posts on BlueSky. To save time writing the posts, I will have an LLM generate the text of the post for me using the content of the blog post as a starting point. For the model, I'll be using OpenAI's GPT-4o.

Once I've updated my integration, this is how my website will share content with other sites (I've colored the BlueSky connection green to indicate it's new):

A New Cross-Posting Algorithm

Since I previously had figured out how to cross-post to Hashnode with a custom Astro integration, I figured it would make a good starting point for this new work.

For this specific use-case, this is what the sequence of steps will look like for making the post on BlueSky:

The astro:build:done arrow is the hook from the Astro framework which the integration waits for before running.

AOnce the update is complete, the integration will perform the following steps:

Perform the existing Hashnode cross-post steps.
Load the JSON data from a new API endpoint for BlueSky.
Get the most recent posts from BlueSky.
Check if the most recent blog post is newer than the latest BlueSky post.
If the most recent blog post is newer, use GPT-4o to write a BlueSky post.
Post the AI-generated content to BlueSky.
Clean up any remaining API files from the dist folder.

Building on the Custom Integration

Following the pattern I developed for Hashnode, I created a new API endpoint called src/pages/api/post-for-bluesky.json.ts:

// Imports here ...

export async function GET() {
  const posts: PostForBlueSky[] = POSTS.map(post => {
    const body = post.collection === 'blog' ? post.body : post.data.body;
    const id = post.id;
    const heroImageSrc = post.data.heroImage.src;

    if (!body) throw new Error(`Body missing for post with ID ${id}`);

    if (!heroImageSrc) throw new Error(`Hero image missing for post with ID ${id}`);

    return {
      body,
      slug: post.id,
      pubDate: post.data.pubDate.toISOString(), // BlueSky has its post createdAt values represented by ISO datetime strings.
      title: post.data.title,
      description: post.data.description,
      thumbSrc: heroImageSrc
    };
  });

  return new Response(
    JSON.stringify(posts[0])
  );
}

However, in contrast to the Hashnode endpoint, this endpoint does NOT return a list of all my posts. Rather, it returns only the most recent post.

After that, I updated my integration to grab the JSON data from the file system, convert it to an object, and then use that to create the BlueSky post:

// src/integrations/cross-post.ts

// ... Existing code here.
// ... The following TS code is inside of the astro:build:done hook and occurs after the Hashnode code.

const blueSkyJson = getJsonFromApiEndpoint(assets, '/api/post-for-bluesky.json', routes, logger);

if (!blueSkyJson) {
  logger.error('Could not retrieve JSON for BlueSky cross-posts');
  return;
}

const { fileContent, filePath } = blueSkyJson;
const password = process.env.BLUESKY_PASSWORD || "";
const username = process.env.BLUESKY_USERNAME || "";
const openAiApiKey = process.env.OPENAI_API_KEY || "";

if (!(password && username && openAiApiKey)) {
  logger.error('Missing API keys for BlueSky cross-post');
  return;
}

const agent = await getAgent(username, password);
const latestPost: PostForBlueSky = JSON.parse(fileContent);
const heroImgSrc = fileURLToPath(new URL(latestPost.thumbSrc.replace(/^\//, ''), dir));

logger.info(`Astro dir is ${dir}`);
logger.info(`Thumb src is ${latestPost.thumbSrc}`);
logger.info(`Hero image is ${heroImgSrc}`);

const isPublished = await makeBlueSkyPost(username, agent, latestPost, openAiApiKey, heroImgSrc);

if (isPublished) {
  logger.info(`Post with slug ${latestPost.slug} posted to BlueSky`)
} else {
  logger.info(`No post made to BlueSky`);
}

fs.rmSync(filePath);

if (!apiDirectory) {
  apiDirectory = path.dirname(filePath);
}

if (apiDirectory) {
  fs.rmSync(apiDirectory, { recursive: true });
}

// ...

Astute observers may notice the BlueSky integration isn’t exactly like the previous Hashnode code. That's because of a few things:

I upgraded to Astro v5, so there are some differences in the integrations API.
I created this helper function getJsonFromApiEndpoint.
New environment variables OPENAI_API_KEY, BLUESKY_USERNAME, and BLUESKY_PASSWORD.

For security, these environment variables are stored in a .env file, excluded from version control using .gitignore. When running in production, the environment variables are stored in an encrypted form with Cloudflare as part of the build configuration.

The getJsonFromApiEndpoint does what the name implies; it gets the JSON string from the API file. However, one additional clarification I will make is the PostForBlueSky type looks like this:

// Exported from src/utils/bluesky/index.ts

type PostForBlueSky = {
  body: string;
  slug: string;
  pubDate: string;
  title: string;
  description: string;
  thumbSrc: string;
};

It will become clearer in the next section why this is the shape I chose for the JSON.

Adding BlueSky Support

BlueSky has good documentation about how to create a post in this article titledCreating a post. Essentially, there are three steps:

Create an agent.
Login.
Create the post.

However, when I tried to follow it I got a little confused about what the right way to go about implementing rich text with an external site embed. Fortunately, I was able to find this helpful post titledUsing the BlueSky API by Raymond Camden. Raymond gave a clear example of how to include both rich text and an embed in the same post.

One key detail: the login rate limit is lower than for other operations. While testing, I accidentally exceeded the rate limit and had to wait 24 hours for it to reset.

Anyway, building off of Raymond and BlueSky's articles, this is the code I came up with:

// src/utils/bluesky/index.ts
// ... Imports and type definitions here.

const makeBlueSkyPost = async (
  username: string, agent: AtpAgent, latestPost: PostForBlueSky, openaiApiKey: string, heroImageSrc: string
) => {
  const response = await agent.getAuthorFeed({
    actor: username
  });
  const feed = response.data.feed;
  const postUris = feed.map(item => item.post.uri);

  let posts: PostThread[] = [];

  for (let i = 0; i < postUris.length; i++) {
    const postThreadResponse = await agent.getPostThread({ uri: postUris[i], depth: 0 });
    const postThread = postThreadResponse.data.thread.post as PostThread;

    posts.push(postThread);
  }

  posts.sort((a, b) => {
    const dateA = (new Date(a.record.createdAt)).valueOf();
    const dateB = (new Date(b.record.createdAt)).valueOf();
    return dateB - dateA;
  });

  const canLatestPostBePublished = new Date(latestPost.pubDate) > (new Date(posts[0].record.createdAt));

  if (canLatestPostBePublished) {
    const postUrl = SITE + "/blog/" + latestPost.slug + "/";
    const text = await generateBlueSkyPostTextFromArticle(openaiApiKey, latestPost.body, postUrl);

    if (text) {
      const rt = new RichText({ text });

      await rt.detectFacets(agent);

      const file = fs.readFileSync(heroImageSrc);
      const imageFileType = await fileTypeFromBuffer(image); // Comes from the file-type package.
      const { data } = await agent.uploadBlob(image, { encoding: imageFileType?.mime } );

      await agent.post({
        $type: 'app.bsky.feed.post',
        text: rt.text,
        facets: rt.facets,
        createdAt: new Date().toISOString(),
        embed: {
          $type: 'app.bsky.embed.external',
          external: {
            uri: postUrl,
            title: latestPost.title,
            description: latestPost.description,
            thumb: data.blob
          }
        },
      });
    } else {
      throw new Error("Could not generate text for BlueSky post");
    }
  }

  return canLatestPostBePublished;
};

// ... Exports here.

The most useful thing I found in Raymond's post was the correct way to make the uploadBlob call. Passing the image with the encoding argument is very simple and straightforward 🔥.

Generating Posts with GPT-4

The code for getting a response from OpenAI is pretty simple. OpenAI has a nice TypeScript SDK which makes making the requests fairly straightforward. The main reason I picked it is because of my familiarity with their API and SDK. Here's what the code looks like:

// src/utils/openai.ts

import OpenAI from 'openai';

const getClient = (apiKey: string) => {
  return new OpenAI({
    apiKey
  });
};

const generateBlueSkyPostTextFromArticle = async (apiKey: string, postContent: string, url: string) => {
  const client = getClient(apiKey);
  const chatCompletion = await client.chat.completions.create({
    messages: [
      {
        role: 'developer',
        content: `
          You are an expert social media manager. Your task is to write a short, high-engagement BlueSky post in first-person based on the provided blog content. 
          Here are the requirements:
          1. The post must be a single sentence that teases the blog content.
          2. The link to the full article is: ${url}.
          3. Include that link (and any hashtags, if desired) at the end of the same sentence.
          4. Limit the entire post to a maximum of 300 characters.
          5. Do not clip words or sentences; it should read naturally as one complete sentence.
          6. Write in the first-person perspective.
        `
      },
      {
        role: 'user',
        content: postContent
      }
    ],
    model: 'gpt-4o'
  });

  return chatCompletion.choices[0].message.content;
};

export {
  generateBlueSkyPostTextFromArticle
}

Testing Approach

As far as testing goes, I went with a somewhat lazy approach. Since my BlueSky account is still growing, I felt comfortable testing posts directly. The approach allowed me to finish the integration quicker, but also had the downside of creating new posts with broken links on my account. Thankfully, BlueSky allows users to delete posts.

If I had an account with many followers, I would probably have opted for a test account where I could make mistakes without the fear of losing followers. Additionally, I also decided to not write any unit tests. So far, I've treated unit tests as technical debt for my website and have ticket in my backlog for writing some.

In summary, my testing flow was just:

Check the API endpoint with npm run dev.
Create a post with npm run build.

Results and Reflections

If I've done everything correctly, this article should be the first one cross-posted to BlueSky 😃.

The integration process went smoother than expected, thanks to BlueSky’s API and Raymond Camden’s example. Reusing my existing Hashnode integration sped things up, and GPT-4o handled generating concise, engaging post text with ease.

What Worked Well:

BlueSky’s API – Simple and well-documented.
Astro Integration Reuse – Saved significant development time.
GPT-4o Output – The AI-generated posts felt natural and effective.

Challenges:

Testing – Without a test BlueSky account, I had to post live, resulting in some trial-and-error cleanup.
Rate Limits – Managing rate limits required careful handling to avoid duplicate posts.

Despite the minor bumps, automating this process was worth it. Posting is now one less thing I have to think about.

Creating a Custom Astro Integration: Auto-Publishing to Hashnode

logarithmicspirals — Fri, 29 Nov 2024 00:00:00 +0000

Introduction

Cross-posting blog content across multiple platforms can be a powerful way to expand your reach and engage with different audiences. However, manually syncing posts to each platform can be time-consuming and prone to inconsistencies. To solve this, I created a custom integration for Astro—a modern static site generator—to automatically sync my blog posts to Hashnode via its GraphQL API.

This integration allows me to maintain full control over formatting, save valuable time, and seamlessly extend the visibility of my content. In this post, I’ll share the challenges I encountered, the solutions I implemented, and the step-by-step process of creating this integration. Whether you’re looking to automate your own cross-posting workflow or curious about building custom Astro integrations, this guide has something for you.

Why I Created This Integration

Logarithmic Spirals embodies recursive spirals. From its inception, I have developed it under the meta concept of building a blog about building a blog. As I add features, I create content. As I create content, I create features. However, at a certain point the concept needs to spiral outward beyond the confines of the Logarithmic Spirals domain. DEV has provided a good starting point for this, but I've been wanting to expand beyond it for some time.

Hashnode was my next goal, but I was stymied by difficulties in getting my existing content to automatically sync with it. My first attempt was with RSS since that's what I use for DEV. However, Hashnode and DEV proved to be too different in their support of RSS imports. Subsequently, I put Hashnode to the side.

Reasons for me wanting to explore an integration:

Future potential to post to other platforms.
Tighter control over formatting and presentation on other platforms.
Potential to use the DEV API.

What kicked off another look into this for me was my previous work on figuring out how to syncDEV posts with my Astro site. Once I realized I could pull in posts from external sources, the path forward on posting to other platforms became clearer. This set the stage for developing an efficient, automated way to cross-post to Hashnode while keeping my workflow lean and cost-effective.

Finding the Right Solution

One big issue I found right off the bat with integrations is integrations don't have access to import.meta.envvariables. My first attempt at writing a Hashnode script relied on other, existing scripts which in turn relied on environment variables being available from the Astro runtime. If I were to continue down that path, I would've needed to rewrite multiple files to support execution from outside the Astro runtime.

After assessing the problem, I came up with the following solutions:

Have a static endpoint which produces JSON for all the posts. Create an integration which runs on build completion. Read the JSON from the endpoint and then post to the necessary location. Delete the JSON file when finished.
Create a component which only runs once per build and only runs during production builds.
Modify the content collection script to post the drafts to Hashnode when running in production.
Write some kind of app (like a cronjob) which could poll an endpoint on the site for new content.

Right off the bat, I want to avoid writing any additional code which runs outside of the static site generation flow. I have been committed to keeping this site's costs at, or extremely close to, zero. Running additional apps or serverless functions would prevent me from achieving this goal.

Of these options, choice one seemed the best because the drafts would only be created when the build is successful. I didn't want to be creating drafts during unsuccessful builds or during local development because that would make maintenance of the drafts on Hashnode more difficult. Additionally, a better solution to start with would make it easier to skip the draft step in the future.

Cross-Post Algorithm

Outline

Restructure content data to the shape needed by the integration.
Expose the data as JSON via a static endpoint src/pages/api/posts-for-hashnode.json.ts.
Consume the JSON via integration API in the astro:build:done step.
Convert the JSON to the shape recognized by the integration.
Iterate over each post and check if a slug already exists for a draft or post on the target Hashnode publication.
If the slug does not exist, create a new draft via Hashnode's API. Otherwise, move to the next post.

Here's a visualization of this algorithm as a flow chart:

The Code

First, I have the code for the static endpoint. Here's how I pass the content data to the integration::

// src/pages/api/posts-for-hashnode.json.ts
import { POSTS } from "@content/tags-and-posts"; // This is an array of post data.
import type { HashnodePost } from "@utils/hashnode";

export async function GET() {
  const postData: HashnodePost[] = POSTS
    .filter(post => post.collection !== 'dev-to') // Going to work on DEV posts in the future.
    .map(post => {
      return {
        title: post.data.title,
        subtitle: post.data.description,
        contentMarkdown: post.body,
        publishedAt: post.data.pubDate.toISOString(),
        slug: post.slug,
        tags: post.data.tags.map(tag => {
          return {
            name: tag,
            slug: tag
          };
        }),
        coverImageUrl: post.data.heroImage.src
      };
    });

  return new Response(
    JSON.stringify(postData)
  );
}

The API code is relatively simple. I just take the existing post data saved in the POSTS variable, filter out any DEV posts, and then reshape the data to fit the HashnodePost shape. The data is then converted to a JSON string for later consumption by the integration.

The integration code is in a file called src/integrations/cross-post.ts and looks like this:

import { createHashnodeDrafts, type HashnodePost } from "../utils/hashnode";
import type { AstroIntegration, RouteData } from "astro";
import fs from 'fs';
import 'dotenv/config';

const hashnodePublicationHost = "logarithmicspirals.hashnode.dev";

const crossPost: AstroIntegration = {
  name: 'cross-post',
  hooks: {
    'astro:build:done': async ({ routes, logger }) => {
      let postJsonRoute: RouteData | undefined = undefined;

      for (const route of routes) {
        if (route.pathname === '/api/posts-for-hashnode.json') {
          postJsonRoute = route;
          break;
        }
      }

      if (postJsonRoute && postJsonRoute.distURL) {
        const filePath = postJsonRoute.distURL.pathname;
        const fileContent = fs.readFileSync(filePath, 'utf8');
        const data: HashnodePost[] = JSON.parse(fileContent);
        const token = process.env.HASHNODE_TOKEN;

        if (token) {
          await createHashnodeDrafts({
            hashNodeToken: token,
            publicationHost: hashnodePublicationHost,
            posts: data
          }, logger);
        } else {
          logger.error('No hashnode token configured');
        }

        fs.rmSync(filePath.replace('/posts-for-hashnode.json', ''), { recursive: true });
      }
    }
  }
};

export default crossPost;

The integration runs when the build completes. I loop over the routes and look for the built version of the API endpoint. Once I find it, I read the generated JSON. After checking for the existence of the Hashnode access token, I proceed to create the drafts. Lastly, I remove the JSON file from the build output.

Finally, I have the code which creates the drafts through the Hashnode API (note I've commented out some things which I will fill in later):

import { gql, GraphQLClient } from "graphql-request"
import { SITE } from "../consts";
import type { AstroIntegrationLogger } from "astro";

const HASHNODE_URL = 'https://gql.hashnode.com';

// GraphQL queries/mutations here.

// Type definitions here.

const createHashnodeDrafts = async (args: DraftCreationArguments, logger: AstroIntegrationLogger) => {
  const grapQLClient = new GraphQLClient(HASHNODE_URL, {
    headers: {
      authorization: args.hashNodeToken
    }
  });

  let draftsCreated = 0;

  for (let i = 0; i < args.posts.length; i++) {
    const post = args.posts[i];
    const slug = post.slug;
    const postWithSlug: ExistingPostResult = await grapQLClient.request(getPostBySlug,
      { publicationHost: args.publicationHost, slug });
    const draftSlugs = postWithSlug.publication.drafts.edges.map(edge => edge.node.slug);

    if (!(postWithSlug.publication.post || draftSlugs.includes(slug))) {
      logger.info(`No post exists on Hashnode with slug ${slug}`);

      const created = await createDraft(grapQLClient, postWithSlug.publication.id, post, logger);

      if (created) {
        draftsCreated += 1;
      }
    } else {
      logger.info(`Post or draft exists on Hashnode with slug ${slug}`);
    }
  }

  logger.info(`Hashnode drafts created = ${draftsCreated}`);
};

const createDraft = async (
  grapQLClient: GraphQLClient, publicationId: string, post: HashnodePost, logger: AstroIntegrationLogger
) => {
  const draftVariables = {
    input: {
      title: post.title,
      subtitle: post.subtitle,
      contentMarkdown: post.contentMarkdown,
      publishedAt: post.publishedAt,
      slug: post.slug,
      tags: post.tags,
      settings: {
        enableTableOfContent: true,
        activateNewsletter: true
      },
      originalArticleURL: SITE + '/blog/' + post.slug + '/',
      publicationId: publicationId,
      disableComments: false,
      coverImageOptions: {
        coverImageURL: SITE + post.coverImageUrl
      }
    }
  };

  try {
    await grapQLClient.request(createDraftMutation, draftVariables);

    return true;
  } catch (err) {
    logger.error(JSON.stringify(err.response.errors));
  }

  return false;
};

export {
  createHashnodeDrafts
}

In broad strokes, the createHashnodeDrafts function:

Creates a GraphQL client.
Loops over the posts and checks if a Hashnode post or draft already exists with the post's slug.
If a no such slug is taken, the post is reshaped and used to create the final draft slug.

Here's what the removed query, mutation, and types look like:

const getPostBySlug = gql`
  query GetPostBySlug($publicationHost: String!, $slug: String!) {
    publication(host: $publicationHost) {
      id
      post(slug: $slug) {
        id
      }
      drafts (first: 50) {
        edges {
          node {
            slug
          }
        }
      }
    }
  }
`;

const createDraftMutation = gql`
  mutation CreateDraft($input: CreateDraftInput!) {
    createDraft(input: $input) {
      draft {
        id
        canonicalUrl
      }
    }
  }
`;

type ExistingPostResult = {
  publication: {
    id: string;
    post: {
      id: string;
    };
    drafts: {
      edges: Array<{
        node: {
          slug: string;
        };
      }>;
    };
  }
}

export type HashnodeTag = {
  name: string;
  slug: string;
};

export type HashnodePost = {
  title: string;
  subtitle: string;
  contentMarkdown: string;
  publishedAt: string;
  slug: string;
  tags: HashnodeTag[];
  coverImageUrl: string;
};

type DraftCreationArguments = {
  hashNodeToken: string;
  publicationHost: string;
  posts: HashnodePost[];
}

A keen observer will note there's a drawback to the getPostBySlug query. There's a max limit of 50 slugs which can be returned. From my research, it seems like there isn't a way to look up a draft by slug via the GraphQL API. This is unfortunate, and makes things a little trickier. While this isn't an issue for me now, it could be if I ever end up with more than 50 drafts.

Drawbacks to the Solution

As previously mentioned, one drawback of this approach is in how Hashnode's API is designed. If I wanted to scale this up in the future, I would have to figure out a way to quickly check if a slug is already taken. My intuition tells me a database might be needed for that. Some other drawbacks are:

There's no way to look up drafts by slug on Hashnode. Need to be mindful not to make too many or I might end up with duplicate drafts.
JSON from the endpoint has to match the shape understood by the integration. This is a tight coupling.
Creating an endpoint just to later delete it feels hacky.

Benefits of the Solution

On the other hand, there are significant benefits to this custom integration:

Streamlines cross-posting to Hashnode, eliminating manual uploads.
Keeps hosting and operations costs at zero.
Built with future integrations and enhancements in mind.

The biggest benefit is that I can push the original markdown to Hashnode. In the past, the RSS imports would always have weird formatting issues and would require a lot of manual editing. The only manual editing I have to do now is adjust the image links because of how I store image files relative to the markdown. Furthermore, these benefits better position me for some future updates.

Follow-up Enhancements

Building off of this new feature, I want to make the following enhancements to my site:

Move DEV cross-posting away from RSS.
Create an integration for automatic BlueSky posts.
Research cross-posting on daily.dev and Hackernoon.
Dial in the cross-post algorithm to allow direct publishing without initial draft creation.

Generally speaking, these enhancements will help me continue to expand the reach of Logarithmic Spirals.

Conclusion

Building a custom Astro integration to cross-post blog content to Hashnode has been a rewarding project. It not only simplifies my workflow but also ensures my content reaches a wider audience with minimal manual effort. By leveraging Astro’s build hooks and Hashnode’s GraphQL API, I’ve created a solution that’s efficient, scalable, and tailored to my needs.

While there are still areas for improvement—such as refining the draft handling process and exploring direct publishing options—this integration is a strong foundation for future enhancements. As I continue to expand its capabilities, I plan to explore integrations with other platforms like BlueSky, Hackernoon, and daily.dev.

If you’ve been looking for ways to automate your content distribution or are interested in creating your own Astro integrations, I hope this post has provided some valuable insights. I’d love to hear your thoughts—what challenges have you faced in automating your workflow, and what platforms would you like to see integrated next? Let’s keep the conversation going!