Forem: gyani

I shipped 19 SEO essays in 12 days from a single Next.js page file

gyani — Sat, 16 May 2026 07:22:48 +0000

I have been quietly running an experiment for the last twelve days. I wanted to know how minimal the publishing pipeline for a real SEO essay corpus can be if I gave up every CMS, every markdown loader, and every static-site generator that pretended to be lightweight but turned out to require its own ecosystem.

The answer ended up being one Next.js page file, one slug allowlist, one sitemap function, and a postscript script that probes the live URL after deploy. Nineteen essays are live as I write this, all ranked individually in sitemap.xml, all internally linked, all with stable URLs and zero rebuild surprises. The whole pipeline is small enough that a human in a hurry can read it in five minutes.

This post is the file. Not a tutorial about the file. The actual structure.

The shape

The route lives at apps/web/app/essays/[slug]/page.tsx. Everything an essay needs is in two arrays in that file plus one small allowlist file next to it.

// apps/web/app/essays/[slug]/page.tsx

import { notFound } from 'next/navigation';
import { ESSAY_SLUGS } from '@/lib/essay-slugs';

export const dynamic = 'force-static';
export const dynamicParams = false;

type Essay = {
  slug: (typeof ESSAY_SLUGS)[number];
  title: string;
  publishedAt: string;
  body: string;
};

const ESSAYS: Essay[] = [
  {
    slug: 'why-matching-layer-is-physically-blind',
    title: 'Why the matching layer is physically blind, on purpose',
    publishedAt: '2026-05-08',
    body: `
      ... essay prose here, plain markdown-ish strings ...
    `,
  },
  // ... 18 more
];

export function generateStaticParams() {
  return ESSAY_SLUGS.map((slug) => ({ slug }));
}

export default function EssayPage({ params }: { params: { slug: string } }) {
  const essay = ESSAYS.find((e) => e.slug === params.slug);
  if (!essay) notFound();
  return <Article essay={essay} />;
}

ESSAY_SLUGS is a const tuple in its own file so the type system catches typos at compile time. Slugs in the renderer that are not in the allowlist will not type-check; slugs in the allowlist with no renderer entry will hit notFound() and return a real 404.

// apps/web/lib/essay-slugs.ts
export const ESSAY_SLUGS = [
  'why-matching-layer-is-physically-blind',
  'letters-mode-is-mercy',
  'why-dating-apps-feel-exhausting',
  // ... 16 more
] as const;

That is the single source of truth for the corpus. Sitemap reads it. Index page reads it. Renderer reads it. Three callers, one list. When a new essay ships, one line in this file and one entry in the renderer is the whole diff.

Sitemap, index, internal linking

Because ESSAY_SLUGS is a typed tuple, the sitemap generator is six lines.

// apps/web/app/sitemap.ts
import type { MetadataRoute } from 'next';
import { ESSAY_SLUGS } from '@/lib/essay-slugs';

export default function sitemap(): MetadataRoute.Sitemap {
  return ESSAY_SLUGS.map((slug) => ({
    url: `https://byvibration.com/essays/${slug}`,
    lastModified: new Date(),
  }));
}

The /essays index page does the same lookup and renders a card per essay, ordered by publishedAt descending. Adding a new essay automatically promotes it to the top of the index and into the sitemap on the next deploy. There is nothing else to remember.

Internal linking is a function call inside the prose. Each essay body has a small Related block at the bottom that pulls related slugs by cluster tag (introvert cluster, friendship cluster, etc.). The cluster mapping is another tiny const next to the slug list. Total moving parts so far: three files.

The "is it actually live" probe

Vercel deploys are usually fast, but there is one failure mode that bit me hard. A page can return HTTP 200 while serving the home shell when something upstream of the renderer crashes silently. The status code lies.

To catch this, the post-deploy probe asserts three things: the page returns 200, the rendered <title> contains a stem of the slug, and the slug is present in the live sitemap.xml. If any of those fail, the deploy is treated as not-live, even on 200.

# superbot/util/essay_liveness.py
def is_live(slug: str) -> bool:
    page = httpx.get(f"https://byvibration.com/essays/{slug}", timeout=10)
    if page.status_code != 200:
        return False
    title = re.search(r"<title>([^<]+)</title>", page.text)
    if not title or not any(
        stem in title.group(1).lower() for stem in slug.split("-") if len(stem) > 3
    ):
        return False
    sitemap = httpx.get("https://byvibration.com/sitemap.xml", timeout=10).text
    return f"/essays/{slug}" in sitemap

This is the single most-useful seven-minute piece of code in the pipeline. It caught a soft-404 for me on essay number five before I noticed the slug was being silently rewritten by middleware. The fix took ten minutes; without the probe it would have taken a week of confusion about why search was not seeing the page.

What I did not build

A markdown loader. A frontmatter parser. An MDX pipeline. A CMS adapter. A headless preview environment. A content directory. A draft state machine. A separate build pipeline for content vs. application code.

Every one of those was suggested by some part of my brain along the way. None of them earned their place. The reason is honest: the corpus is small, the cost of typing prose inline is trivial, and the type checker is the only quality gate that actually catches the bugs that ship in production. The simplest model that works is the model.

The day I have one hundred essays I will probably move to a markdown directory. Until then, the file fits on one screen of any normal editor, the array is sorted by date, and I can grep my own corpus instantly.

What this looks like in practice

The cadence has been roughly one essay every fifteen hours, written in plain prose, ported into the array, slug added to the allowlist, pushed. Vercel deploys. The probe runs. The sitemap updates. Google indexes it within forty-eight hours. The internal links to the rest of the corpus stay correct because they are computed, not hand-maintained.

The unit of friction per new essay is "write the essay." Everything downstream of that is one diff against one file.

If you have an essay practice and you are intimidated by the pipeline question, this is a version of "just ship it" that has an answer. One file. One allowlist. One probe. Nineteen essays in twelve days from that pattern, with the type checker as your friend.

I would skip every CMS until you actually need one.

I work on Byvibration, where the corpus this file feeds lives. The essays index is at byvibration.com/essays.

A dating algorithm that physically cannot read photos (and why I wrote it that way)

gyani — Sat, 16 May 2026 00:44:18 +0000

A dating algorithm that physically cannot read photos (and why I wrote it that way)

gyani — Fri, 15 May 2026 15:13:14 +0000

I have been writing a connection app for a year. Last week I open-sourced the matching engine, and the only design choice I want to walk through is the one that took the longest to talk myself into: the matcher does not have access to photos. Not "it ignores them." Not "it deprioritizes them." It cannot see them. The TypeScript build fails if you try.

If you only want the punchline, here it is.

// soulmate-core/src/rank.ts
export function rank(viewer: Profile, candidate: Profile): number;

type Profile = {
  prompts: PromptAnswers;       // five short text answers
  voice: VoiceTranscript;       // ~30 sec, kept as text
  intent: Intent;               // friendship | relationship | community
  meta: ProfileMeta;            // age band, city, language, etc.
};
// no photo field. anywhere on this type.

The image bytes live in a different table, behind a different read path, behind a mutualVibe boolean. The function above has no reference to that table and no way to obtain one through normal app wiring. The constraint is enforced by the compiler.

The repo is at github.com/donnowyu/soulmate-core if you want to read along.

Why type-level, not flag-level

The natural shape of this is a feature flag. if (allow_photo_in_ranking) { ... }. Several products built on this shape. I think it is the wrong shape. Three reasons.

Flags get flipped by people who weren't in the room when the principle was set. A future engineer, looking at the engagement dashboard on a tired evening, will propose a "secondary signal" A/B test. They will be right that the metric will move. They will be wrong that what is being measured is what we said we cared about. A flag does not survive that conversation. A type signature does.
The constraint should live in the artifact, not the documentation. A README that says "do not use photos in ranking" is a memo. A type that has no photo field is a build error. Banks do not enforce referential integrity with memos.
It is honest in a way I can verify in public. The repo is open. You can look at the entry-point type and convince yourself in 60 seconds. You do not have to take my word for anything.

The cost of doing it this way

I will not pretend this was free.

The most expensive part was the data model. I had to design the schema so that the photo entity has its own service, its own access control, its own read path. The image upload pipeline never returns to the matching service. The "show me a face" step is a separate request, gated server-side on the existence of a mutualVibe row keyed by both user IDs. That is not a refactor you do in an afternoon.

The second cost was deciding what Profile should contain so that ranking still works. I tried a lot of things. The current shape (five prompts plus a transcribed voice clip plus intent metadata) is the smallest set I found that produces matches I can defend on inspection. Most of a year was spent reducing it to that.

The third cost is a soft one. There is a class of user who, on the existing apps, sorts mostly by face. They will look at this product and bounce. That is fine. They were not the users I was trying to find.

The trick of the embedding

The text answers and the voice transcript get concatenated into a single document per user. That document is embedded into a 1536-dim vector. Ranking is cosine similarity over those vectors, with two soft rerankers (ideology distance, shared-passion overlap) breaking ties.

This is not exotic. The trick is not in the math. The trick is in the input. By construction, the model has never seen a pixel. By construction, the model has no learned latent dimension that correlates with attractiveness, because nothing in the training distribution ever encoded one. The rerank loop is small enough to read.

// rerank pseudocode
const baseline = cosine(viewerEmb, candidateEmb);
const ideologyPenalty = distance(viewer.ideology, candidate.ideology);
const passionBoost   = jaccard(viewer.passions, candidate.passions);
return baseline - 0.15 * ideologyPenalty + 0.10 * passionBoost;

You can argue with the coefficients. I have. The coefficients are not the point of the post.

Why I am writing this on Dev.to

Because the type-system argument is the part of the project that is interesting to people who write code for a living, and because most of the press around "no photo dating apps" handles the question at the marketing layer, where it is much less interesting. The interesting question is whether the constraint is structural, and structural constraints are something a dev audience can read in source. I wanted that audience to be able to verify the claim without me in the room.

If you want the long-form essay version of this argument, it is on the product site at byvibration.com/essays/why-matching-layer-is-physically-blind. If you want the code, the repo link is at the top. If you want to push back on any of the choices, the comments are open and I will be in them.

I work on byvibration. The matching engine is open source. I am writing about it here because I think the type-signature framing is a transferable idea: constraints you want to honor across a long time should be expressed in the artifact, not the team's memory.---
title: A dating algorithm that physically cannot read photos (and why I wrote it that way)
published: false
canonical_url: https://byvibration.com/essays/why-matching-layer-is-physically-blind

tags: typescript, webdev, discuss, architecture