DEV Community

Cover image for Turning My Astro Similar Posts Feature into an Open Source Integration
logarithmicspirals
logarithmicspirals

Posted on Originally published at logarithmicspirals.com

Turning My Astro Similar Posts Feature into an Open Source Integration

For a while, the code behind my blog's Similar Posts component lived inside my site. It started as a way to recommend related articles, then grew to include a relevance threshold and a SQLite cache. Those earlier posts documented how I built it:

After using that implementation on my own site, I wanted to make the same capability easier to add to another Astro project. That meant turning site-specific utilities into an integration that other sites could configure and call.

One thing which helped me decide to do this was feedback on Bluesky:

Screenshot of feedback on Bluesky

Also, I have been open-sourcing other parts of my site's source code, and this seemed like a useful next project. Hopefully, others can find it useful for quickly adding similar post recommendations to their Astro sites.

From a Site Feature to an Astro Integration

The first version of Similar Posts was deliberately small. I sent each article's text to OpenAI's embedding API, compared the resulting vectors with cosine similarity, and displayed the closest matches. When some recommendations looked wrong, I added a threshold and a way to inspect pairwise scores. Then, to avoid paying to embed unchanged articles on every build, I cached each vector in SQLite under Astro's .astro directory.

That sequence worked for one site, but it left several decisions embedded in my site's files: which collection to read, which model to call, where the cache lived, how to handle a missing API key, and what to do when the provider was unavailable. Moving the feature into an Astro integration gave those choices a reusable configuration surface and let the integration handle the build-time work.

The result is astro-content-vectors, an integration for ranking Astro content entries by embedding similarity. It targets static builds: the vectors are generated while Astro builds the site, and the recommendations can be rendered into the resulting pages without a runtime vector service. The current package requires Astro 7 or later and Node.js 20 or later for its build process.

Comparing to Other Similar Projects

This package is one of several ways to add embedding-based recommendations to an Astro site. The projects below solve a similar reader-facing problem, but they make different choices about where vectors live, how they are generated, and how recommendations get attached to content.

Here are the main differences I found when I compared their documented approaches:

::csv{src="./project-comparison.csv"}

The overlap is the goal—semantic recommendations for Astro content—not an identical architecture. For a small static site, an in-process ranking pass and local SQLite cache may be enough. If you want locally executed Transformers.js models, compare Astro Related Content; if you already operate Qdrant and want recommendations integrated into a loader, compare Astro Recommend Article. The best fit depends on where you want embedding generation and vector storage to run.

Choosing a Provider for Each Environment

I wanted local development to work with a model running in LM Studio and production builds to use OpenAI. The integration uses the OpenAI SDK for the embeddings request; LM Studio works because its local server exposes an OpenAI-compatible API.

Here's the shape of the configuration I use on this site:

import { defineConfig } from "astro/config";
import astroContentVectors from "astro-content-vectors";

export default defineConfig({
  integrations: [
    astroContentVectors({
      collections: ["blog"],
      provider: {
        type: "openai",
        model: "text-embedding-3-small",
      },
      environments: {
        development: {
          provider: {
            type: "lmstudio",
            baseUrl: "http://127.0.0.1:1234/v1",
            model: "text-embedding-nomic-embed-text-v1.5",
          },
        },
      },
      fallback: {
        baseUrl: "http://127.0.0.1:1234/v1",
        model: "text-embedding-nomic-embed-text-v1.5",
      },
      threshold: 0.65,
      limit: 3,
    }),
  ],
});
Enter fullscreen mode Exit fullscreen mode

There is one default provider and optional environment overrides. Astro's development and production modes choose the matching configuration by default, and a project can provide its own environment key when it needs a different naming scheme.

When OpenAI is selected, the integration reads OPENAI_API_KEY from the build environment automatically. If the key is missing or the OpenAI request cannot connect, it tries the configured LM Studio fallback. If that also fails, it logs a warning and returns no recommendations by default, so an unavailable embedding service does not break a static build. Projects that want provider failures to stop the build can set failOnError: true.

One practical detail I had to keep in mind is that OpenAI-compatible APIs do not guarantee identical model limits. During local testing, LM Studio warned that an input of 5,198 tokens exceeded the loaded model's 2,048-token context and was truncated. The request format was compatible, but the model's context window still affected the embedding. For long entries, the local model needs a context window large enough for the text being sent.

Reusing the SQLite Cache Code

The cache was part of the original implementation I had already written about, and I wanted that work to carry forward into the package. I used my existing code as the source for the integration's SQLite cache: the embeddings table kept the same post_id, post_hash, and embedding columns, and the cache still hashes source text to decide whether to reuse or refresh a vector.

I did not paste the original function in verbatim. I separated the database operations from the embedding provider and the content-ranking runtime so the integration could support different providers. The package cache also includes the provider and model in its cache key. That way, a vector made by one model is not mistaken for a vector made by another. Requests can be batched as well, rather than making one API call for every entry.

The cache still lives in .astro by default, so it stays with Astro's build artifacts. SQLite remains the default, and the current integration can instead use Cloudflare D1 as a remote cache when builds need a shared cache backend. That option uses Cloudflare's API during the build, so it requires account and database IDs plus an API token with D1 edit access. D1 stores and retrieves the embeddings; similarity ranking still happens in memory during the build. Cache entries are keyed by collection, entry ID, provider, and model, and are refreshed when source text changes.

The integration also handles long entries by splitting Markdown at paragraph and heading boundaries before embedding. It combines chunk vectors using a token-weighted average; chunkTokens and alwaysChunk let a project adjust that behavior. This matters because an OpenAI-compatible API does not make every model's context window the same. The package can also write pairwise similarity scores into .astro/content-vector-similarities/ when outputSimilarityScores is enabled. I used that output on this site to keep tuning the threshold based on actual scores instead of guessing.

Making the Package Usable and Testable

The public API has two parts: add the integration in astro.config, then call getRelatedContent from an Astro component or page. The helper returns IDs and similarity scores in descending order, leaving the site free to decide how to render the matches.

---
import { getRelatedContent } from "astro-content-vectors/astro";

const recommendations = await getRelatedContent("blog", Astro.props.post.id);
---
Enter fullscreen mode Exit fullscreen mode

I also wanted confidence that it worked as an installed Astro package, not just as source imported inside its own repository. The project has unit tests for the cache and ranking behavior, integration tests for provider configuration, and an install test that packs the package, installs it into an Astro fixture, and runs a static build against a mock embeddings server.

That end-to-end check exercises the path a user takes: install the package, add it to Astro's config, call the helper, and build the site. It caught issues that unit tests alone would not cover, such as whether the package exports resolve correctly after compilation.

Conclusion

This integration grew directly out of the work in the previous posts. The cosine similarity logic, the threshold investigation, and the SQLite caching idea all started as parts of one site feature. Packaging them as an integration gave me a way to reuse that work across Astro projects while keeping the implementation's history visible.

If you'd like to try it, see astro-content-vectors on npm or browse the source on GitHub. Start with the installation and configuration guide, then tune the provider, threshold, and result limit for your own content.

Top comments (0)