feat: implement blog RSS feed handler and update routing

brookslybrand · brookslybrand · commit 904c269de6b6 · 2026-02-12T11:49:51.000-06:00
- Add blog RSS feed handler in server/routes/blog-rss.ts
- Wire /blog/rss.xml endpoint in server.ts for production
- Remove old blog RSS route from React Router in app/routes.ts
- Add Vitest tests for blog RSS handler and E2E tests for the RSS endpoint
- Update README to reflect new routing behavior and migration status
diff --git a/app/remix/README.md b/app/remix/README.md
@@ -7,6 +7,7 @@ Both systems run side-by-side in the same server during migration.
 ## Purpose
 
 This document is the migration playbook for:
+
 - route wiring conventions in `server.ts`
 - implementation constraints in `app/remix/`
 - guardrails that keep production stable while migration is in progress
@@ -31,37 +32,47 @@ Current `app/remix/` contents:
 app/remix/
 |- document.tsx
 |- tsconfig.json
+|- blog-rss.test.ts
 |- test-route.tsx
 |- test-route.test.ts
 `- README.md
 ```
 
 Current server wiring behavior:
+
 - `/healthcheck` is handled directly in `server.ts` (stable operational endpoint)
+- `/blog/rss.xml` is handled directly in `server.ts` with a production-safe Remix handler
 - `/remix-test` is wired only in development as a Remix smoke test page
 - all remaining routes are handled by React Router via the catch-all
 
 ## Production constraints
 
 - Dynamic `.tsx` route imports are currently considered development-only.
 - Production use of dynamic Remix route modules depends on the precompile/asset strategy (still in progress).
-- Keep `/healthcheck` on a stable server handler until that strategy is finalized.
+- For production migrations today, prefer stable handlers that can be imported directly by `server.ts` (no Vite-only transforms like `import.meta.glob`).
+- Keep `/healthcheck` on a stable server handler until the dynamic asset strategy is finalized.
 
 ## Dual-route strategy
 
 When a user-facing route is migrated to Remix, keep the equivalent React Router route in `app/routes.ts` until linking pages are also migrated.
 
 Why this is required:
+
 - React Router intercepts client-side `<Link>` navigation.
 - If a route is missing from the React Router manifest, client navigation can resolve through catch-all and produce incorrect behavior.
 
 Expected behavior during migration:
+
 - direct URL access: fetch-router can serve Remix route
 - client-side navigation from React Router pages: React Router serves its route module
 - links from Remix pages using plain `<a>`: full reload, then fetch-router serves Remix route
 
 Remove route entries from `app/routes.ts` only after inbound linking surfaces are migrated.
 
+Exception:
+
+- Non-navigated resource endpoints (for example RSS/robots/sitemap-style URLs) can be removed from `app/routes.ts` once they are mapped explicitly in `server.ts` for production.
+
 ## Conventions
 
 ### JSX pragma (required)
@@ -102,9 +113,7 @@ import { Document } from "../document";
 
 export default async function handler() {
   const html = await renderToString(
-    <Document title="Page Title">
-      {/* page content */}
-    </Document>,
+    <Document title="Page Title">{/* page content */}</Document>,
   );
 
   return new Response("<!DOCTYPE html>" + html, {
@@ -132,13 +141,26 @@ Current preferred pattern in this repo:
 
 1. Define route map(s) with `route(...)` from `remix/fetch-router/routes`
 2. Register handlers with `router.map(routeMap, controller)`
-3. For development-only smoke routes, register only when Vite dev server is present
-4. Keep React Router entries in `app/routes.ts` for user-facing routes during dual-stack period
-5. Add a colocated Vitest test where possible
+3. Put production-ready Remix routes in the always-on route map (outside the Vite-only block)
+4. Reserve `if (viteDevServer)` route maps for smoke tests and dynamic dev-only module imports
+5. Keep React Router entries in `app/routes.ts` for user-facing routes during dual-stack period
+6. Add a colocated Vitest test where possible
+
+Production-safe handler placement:
+
+- If a handler needs Node-only APIs (for example filesystem access), implement it in `server/routes/` and call it from `server.ts`.
+- Do not duplicate these handlers in `app/remix/`; keep a single source of truth in `server/routes/`.
+
+Handler loading pattern (important):
+
+- In development, map Node-backed route handlers through `loadRemixModule(...)` so handler edits reload without restarting the dev server.
+- In production, map those same handlers with static imports from `server/routes/*` for boot-time validation and predictable runtime behavior.
+- Avoid dynamic `import()` on production request paths unless there is a specific need and monitoring/error handling is in place.
 
 ### HTML attributes
 
 `remix/component` uses HTML attributes, not React camelCase:
+
 - `class` not `className`
 - `innerHTML` not `dangerouslySetInnerHTML`
 - `fill-rule` not `fillRule`
@@ -167,16 +189,19 @@ Before opening a PR that changes `app/remix/` or fetch-router mappings:
 - Do not import modules that pull in `react-router` types
 - Keep `/healthcheck` on stable server path unless migration strategy explicitly changes
 - Keep user-facing route entries in `app/routes.ts` until dual-route migration is complete
+- For production migrations, prefer handlers that can run from `server.ts` without Vite-only transforms
 - Add or update tests for new route handlers and server route wiring
 
 ## Migration status (living section)
 
 In progress:
+
 - `app/remix/` scaffolding (`document.tsx`, isolated tsconfig, smoke-test route)
 - server route map wiring pattern using fetch-router `route(...)`
+- production Remix handler for `/blog/rss.xml` wired in `server.ts`
 
 Not yet fully migrated:
-- user-facing Remix route modules wired in production
+
 - client asset/precompile strategy for production Remix route imports
 - blog pages (`/blog`, `/blog/:slug`)
 - OG image generation (`/img/:slug`)
diff --git a/app/routes.ts b/app/routes.ts
@@ -9,7 +9,6 @@ export default [
     route("newsletter", "routes/marketing/newsletter.tsx"),
     route("blog", "routes/marketing/blog-index.tsx"),
     route("blog/:slug", "routes/marketing/blog-post.tsx"),
-    route("blog/rss.xml", "routes/resources/blog-rss.tsx"),
   ]),
 
   route("jam", "routes/jam/pages/layout.tsx", [
diff --git a/app/routes/resources/blog-rss.tsx b/app/routes/resources/blog-rss.tsx
diff --git a/e2e/blog-rss.spec.ts b/e2e/blog-rss.spec.ts
@@ -0,0 +1,15 @@
+import { test, expect } from "@playwright/test";
+
+test.describe("Blog RSS endpoint", () => {
+  test("returns XML with expected feed metadata", async ({ request }) => {
+    const response = await request.get("/blog/rss.xml");
+
+    expect(response.ok()).toBe(true);
+    expect(response.headers()["content-type"]).toContain("application/xml");
+
+    const xml = await response.text();
+    expect(xml).toContain("<rss");
+    expect(xml).toContain("<title>Remix Blog</title>");
+    expect(xml).toContain("<link>https://remix.run/blog</link>");
+  });
+});
diff --git a/server.ts b/server.ts
@@ -10,6 +10,7 @@ import { route } from "remix/fetch-router/routes";
 import { compression } from "remix/compression-middleware";
 import { staticFiles } from "remix/static-middleware";
 import { rateLimit, filteredLogger } from "./server/middleware.ts";
+import blogRssHandler from "./server/routes/blog-rss.ts";
 import sourceMapSupport from "source-map-support";
 
 sourceMapSupport.install();
@@ -78,6 +79,7 @@ const router = createRouter({
 // ---------------------------------------------------------------------------
 const remixRoutes = route({
   healthcheck: "/healthcheck",
+  blogRss: "/blog/rss.xml",
 });
 
 async function loadRemixModule(path: string) {
@@ -90,17 +92,24 @@ async function loadRemixModule(path: string) {
 
 // Keep healthcheck on a stable path during migration so deploy checks never
 // depend on the in-progress Remix route asset strategy.
-router.map(remixRoutes, {
-  healthcheck() {
-    return new Response("OK", {
-      headers: {
-        "Cache-Control": "no-store",
-        "Content-Type": "text/plain; charset=utf-8",
-      },
-    });
-  },
+router.map(remixRoutes.healthcheck, () => {
+  return new Response("OK", {
+    headers: {
+      "Cache-Control": "no-store",
+      "Content-Type": "text/plain; charset=utf-8",
+    },
+  });
 });
 
+if (viteDevServer) {
+  router.map(remixRoutes.blogRss, async () => {
+    const mod = await loadRemixModule("./server/routes/blog-rss.ts");
+    return mod.default();
+  });
+} else {
+  router.map(remixRoutes.blogRss, blogRssHandler);
+}
+
 if (viteDevServer) {
   const devRemixRoutes = route({
     remixTest: "/remix-test",
diff --git a/server/routes/blog-rss.test.ts b/server/routes/blog-rss.test.ts
@@ -0,0 +1,29 @@
+import { describe, it, expect } from "vitest";
+import { CACHE_CONTROL } from "../../app/lib/cache-control";
+import { buildBlogRssResponse } from "./blog-rss";
+
+describe("blog RSS route handler", () => {
+  it("returns an RSS XML response with cache headers", async () => {
+    const response = buildBlogRssResponse([
+      {
+        slug: "hello-world",
+        title: "Hello World",
+        summary: "A first post",
+        date: new Date("2025-01-01T00:00:00.000Z"),
+      },
+    ]);
+
+    expect(response).toBeInstanceOf(Response);
+    expect(response.status).toBe(200);
+    expect(response.headers.get("Content-Type")).toBe("application/xml");
+    expect(response.headers.get("Cache-Control")).toBe(CACHE_CONTROL.DEFAULT);
+
+    const xml = await response.text();
+    expect(xml).toContain("<rss");
+    expect(xml).toContain("<title>Remix Blog</title>");
+    expect(xml).toContain(
+      "<description>Thoughts about building excellent user experiences with Remix.</description>",
+    );
+    expect(xml).toContain("<link>https://remix.run/blog/hello-world</link>");
+  });
+});
diff --git a/server/routes/blog-rss.ts b/server/routes/blog-rss.ts
@@ -0,0 +1,96 @@
+import { readdir, readFile } from "node:fs/promises";
+import { Feed } from "feed";
+import parseFrontMatter from "front-matter";
+import { CACHE_CONTROL } from "../../app/lib/cache-control.ts";
+
+interface BlogRssFrontmatter {
+  title?: string;
+  summary?: string;
+  date?: string | Date;
+  draft?: boolean;
+}
+
+export interface BlogRssPost {
+  slug: string;
+  title: string;
+  summary: string;
+  date: Date;
+}
+
+const POSTS_DIRECTORY = new URL("../../data/posts/", import.meta.url);
+
+export async function getBlogRssPosts(): Promise<BlogRssPost[]> {
+  const entries = await readdir(POSTS_DIRECTORY, { withFileTypes: true });
+  const posts: BlogRssPost[] = [];
+
+  for (const entry of entries) {
+    if (!entry.isFile() || !entry.name.endsWith(".md")) {
+      continue;
+    }
+
+    const fileUrl = new URL(entry.name, POSTS_DIRECTORY);
+    const source = await readFile(fileUrl, "utf8");
+    const { attributes } = parseFrontMatter<BlogRssFrontmatter>(source);
+
+    if (attributes.draft || !attributes.title || !attributes.summary) {
+      continue;
+    }
+
+    const parsedDate =
+      attributes.date instanceof Date
+        ? attributes.date
+        : new Date(String(attributes.date ?? ""));
+
+    if (Number.isNaN(parsedDate.getTime())) {
+      continue;
+    }
+
+    posts.push({
+      slug: entry.name.replace(/\.md$/, ""),
+      title: attributes.title,
+      summary: attributes.summary,
+      date: parsedDate,
+    });
+  }
+
+  return posts.sort((a, b) => b.date.getTime() - a.date.getTime());
+}
+
+export function buildBlogRssResponse(posts: BlogRssPost[]) {
+  const blogUrl = "https://remix.run/blog";
+
+  const feed = new Feed({
+    id: blogUrl,
+    title: "Remix Blog",
+    description:
+      "Thoughts about building excellent user experiences with Remix.",
+    link: blogUrl,
+    language: "en",
+    updated: posts.length > 0 ? posts[0].date : new Date(),
+    generator: "https://github.com/jpmonette/feed",
+    copyright: "© Shopify, Inc.",
+  });
+
+  for (const post of posts) {
+    const postLink = `${blogUrl}/${post.slug}`;
+    feed.addItem({
+      id: postLink,
+      title: post.title,
+      link: postLink,
+      date: post.date,
+      description: post.summary,
+    });
+  }
+
+  return new Response(feed.rss2(), {
+    headers: {
+      "Content-Type": "application/xml",
+      "Cache-Control": CACHE_CONTROL.DEFAULT,
+    },
+  });
+}
+
+export default async function blogRssHandler() {
+  const posts = await getBlogRssPosts();
+  return buildBlogRssResponse(posts);
+}
