1. showcasing my skills for potential employers
2. Sharing my music with my friends
3. starting a blog about nothing in particular

The first two of this list were checked off by whipping up a quick portfolio site with a nifty frontend wrapper to display my listening history from last.fm. I used tanstack start to do this as I fear the triangle man at nextjs and it is always a great opportunity to try a new technology to learn when doing a low risk project.

All three of these goals are small enough tasks which many people before me have taken on.

So what went wrong with the blog?

Defining the problem

When taking on this personal task I didn't handle it as if I were at work. Consulting stakeholders, data analysis to define what actually needs to be tackled to generate an adequate solution.

Where I ended up

Being driven by wanting to use the hottest technology options led me the poorest solution. I created a postgres database with neon and stored my images in vercel blob, created a markdown text editor that I had to login to use on my site with github SSO.

Lets circle back to the problem. I want the ability to create blog posts. Fullstop I didn't need a shitty editor I whipped up that crashed from many various combinations of special characters.

Now I can just commit .md files to my repo and use any other better text editor in existence. Problem solved.

No regrets I still had fun exploring whats out there and even this is still overkill, I really don't need react with all the SSR components going on, but this is the life I live.

Lighthouse

Lighthouse is an auditing tool maintained by Google that has the capabilities to assess a site's performance, accessibility, best practices and Seo. Google's PageSpeed Insights uses lighthouse under the hood to perform analysis on pages if you are familiar with that.

What Vercel already gives you

Vercel has Speed insights which is easy to set up but is only limited to showing you how the user is performing when actively used. There seems to be a promoted integration with Vercel DebugBear that can serve the same purpose. However on the day I did this, their docs were down so I did not proceed.

Goals

• Lighthouse can be run locally for quick development (this can also be integrated with Chrome)
• Tests are run on all branches pushed to Github
• Production deploys are also subjected to testing

Setting up Lighthouse

Prerequisites

• Code is hosted on Github
• Project is deployed to Vercel
• Basic Github actions knowledge

Installation and configuration

In your project run with your dedicated package manager

pnpm add -D @lhci/cli  

Create a lighthouserc.cjs file in the root of your directory here we will need to consider that this will be getting read locally and from Github actions.

const fs = require('fs')

const isProduction =
  process.env.BASE_URL && process.env.BASE_URL.includes('jeremyharland.com')

const paths = ['/', '/pick', '/your', '/urls', '/here']
const urls = paths.map(
  (path) => `${process.env.BASE_URL || 'http://localhost:3000'}${path}`,
)

module.exports = {
  ci: {
    collect: {
      url: urls,
      numberOfRuns: isProduction ? 3 : 1,
      settings: {
        preset: 'desktop',
        throttlingMethod: 'simulate',
        mobile: false,
        width: 1350,
        height: 940,
        deviceScaleFactor: 1,
        chromeFlags: '--headless --no-sandbox',
        blockedUrlPatterns: [
          '*google-analytics*',
          '*googletagmanager*',
          '*hotjar*',
          '*segment*',
          '*sentry*',
        ],
      },
    },
    upload: {
      target: 'temporary-public-storage',
    },
  },
}

Build your project and serve it locally, performance scores will be poor if you run the dev server instead of the built preview

pnpm build && pnpm preview

then on another console run the tests

pnpm dlx @lhci/cli autorun 

Once these have finished open the report and you should hopefully see something like this.

Github Integration

Workflow YAML file

create a lighthouse.yml in .github/workflows/ with the following content.

name: Lighthouse CI

on:
  deployment_status:

jobs:
  lighthouse:
    if: github.event.deployment_status.state == 'success'
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Install pnpm
        uses: pnpm/action-setup@v4
        with:
          version: 9.15.4
      - uses: actions/setup-node@v4
        with:
          node-version: '24'
          cache: pnpm

      - name: Set base URL
        id: url
        run: |
          if [ "${{ github.event.deployment.environment }}" = "Production" ]; then
            echo "value=https://yourdomain.com" >> $GITHUB_OUTPUT
          else
            echo "value=${{ github.event.deployment_status.target_url }}" >> $GITHUB_OUTPUT
          fi

      - name: Run Lighthouse CI
        run: pnpm dlx @lhci/cli autorun
        env:
          BASE_URL: ${{ steps.url.outputs.value }}
          LHCI_GITHUB_APP_TOKEN: ${{ secrets.LHCI_GITHUB_APP_TOKEN }}

Lighthouse Github App

Although not required, this makes your pr's look a bit nicer and creates a small summary of your actions run. Configure lighthouse ci for your Github project.

Add LHCI_GITHUB_APP_TOKEN as a secret for your actions.

Vercel Protection rules

If you had jumped the gun and pushed this all to Github you will have noticed that your preview runs would have failed due to lighthouse not being able to access your page.

In your Vercel project deployment protection settings create a bypass secret that we will add as headers to our lighthouse config.

Add this to your github action secrets as VERCEL_AUTOMATION_BYPASS_SECRET and pass this into the autorun action in lighthouse.yml. Finally in the Lighthouse config file add this to the settings section.

extraHeaders: {
          'x-vercel-protection-bypass':
            process.env.VERCEL_AUTOMATION_BYPASS_SECRET || '',
        },

Now lighthouse will be able to successfully access preview branches and pushing to your repo should look like this now.

Assertions

Now you can add some assertions to your lighthouse config. The main thing to note here is that your SEO assertions will need to be off for previews as these pages are not indexed.

assert: {
      assertions: {
        // SEO specifics — skip on preview, these will always fail
        'meta-description': isProduction ? ['warn', { minScore: 1 }] : 'off',
        'robots-txt': isProduction ? ['warn', { minScore: 1 }] : 'off',
        canonical: isProduction ? ['warn', { minScore: 1 }] : 'off',
      }
}

Tips & Future iterations

For my project I created a script that pulls all my urls from sitemap.xml and writes them to a text file. This is executed within the lighthouse workflow. Currently these only test for one type of screen view so there is room to extend that.

Tanstack Start Docs

The Tanstack Start documentation are great and comes with an SEO guide that outlines how to create sitemaps.xml and robots.txt files statically and dynamically. I had no need to create a dynamic robots.txt for this site and opted to just use Tanstack's built-in sitemap generator. Reading the guide on the the dynamic robots.txt would have shown exactly what to do for the rss.xml file. The docs also recommend reading the Tanstack Router as they are coupled by design.

Generating a dynamic rss.xml file

Perquisites

This guide assumes you have a way to return all your posts/content and your tanstack start site is not statically deployed.

Server Route

Create a server route with the file src/routes/rss[.]xml.ts, this was not abundantly clear to me but is outlined in the File Name Conventions apart of the router documentation. Download the rss npm package with

pnpm install rss

or with whatever package manager you are using.

Then after configuring your posts you should end up with a file looking like

import { env } from '@/env'
import { createFileRoute } from '@tanstack/react-router'
import { allPosts } from 'content-collections'
import RSS from 'rss'

export const Route = createFileRoute('/rss.xml')({
  server: {
    handlers: {
      GET: async () => {
        const siteUrl = env.PUBLIC_BASE_URL

        const feed = new RSS({
          title: '<Your Title Here>',
          description:
            '<Your description Here>',
          feed_url: `${siteUrl}/rss.xml`,
          site_url: siteUrl,
          language: 'en',
          pubDate: new Date(),
          copyright: `All rights unreserved ${new Date().getFullYear()}`,
        })

        allPosts.map((post) => {
          feed.item({
            title: post.title,
            description: post.description,
            author: post.authors.join(', '),
            url: `${siteUrl}/blog/${post.slug}`,
            date: post.published,
            custom_elements: [
              { 'content:encoded': { _cdata: post.rendered.markup } },
            ],            
            enclosure: post.headerImage
              ? {
                  url: post.headerImage,
                  type: 'image/jpeg',
                }
              : undefined,
          })
        })
        return new Response(feed.xml({ indent: true }), {
          status: 200,
          headers: {
            'Content-Type': 'text/xml',
          },
        })
      },
    },
  },
})

Configuration

• In your headers you can control how long your want to cache this for or not at all
• There is more rss options you can configure or less! I like to add the image if it is present as most modern readers will render this in there ui.

What is RSC

RSC is the React feature that allows the server to do the rendering for the client, leading to less JS that the client has to download.
I won't debate on whether or not people require it, this site does not but I like to use this as a place to try new things.

TanStack vs Next.js

The team at TanStack have driven a client-first framework with the ability to opt into RSC where you see fit. Conversely, Next.js is RSC-first and then components are marked as use client when they are meant to be rendered on the client. This, by design, leads people to offload extra compute onto their server, which conveniently is likely to be Vercel.

At work I am dealing with a semi-large Next.js project with all the bells and whistles, and I come across this pattern that people seem to fall into:

Fetching data on the server then rendering some view component ✅

async function FaqPage() {
  let data: FaqContent;
  try {
    data = await getFaqContent();
  } catch (e) {
    redirect('/error');
  }

  return <FaqPage data={data} />;
}

export default FaqPage;

So far so good! Then diving into the actual Faq page, I will often see the opening line:

'use client'

Hindering all the setup involved with the power of RSC, likely because there is a button somewhere on that page. The nature of the framework being server-first strips the significance of RSC, as it is not a conscious thought that devs make when building.

Whereas on the TanStack side, I had a go converting the bulk of my pages here into server components, as most of my pages have no client interaction whatsoever, so it makes sense.

Here is my blog page using RSC now

const getBlogPageContent = createServerFn().handler(async () => {
  const Renderable = await renderServerComponent(<Blog />)
  return { Renderable }
})

export const Route = createFileRoute('/_layout/blog/')({
  loader: async () => {
    const { Renderable } = await getBlogPageContent()
    return { BlogPageContent: Renderable }
  },
  component: BlogPage,
})

function BlogPage() {
  const { BlogPageContent } = Route.useLoaderData()
  return <>{BlogPageContent}</>
}

Everything still reads like it did before, but it just feels more deliberate that I am loading things on the server for a purpose, and it is not just magic happening under the framework's hood. I am yet to do a more complex page that requires both client and server components, which will be a fairer test - but for now I'll just stick to drinking the TanStack Kool-Aid!

I set out to do this initially as a means of improving my general writing skills. I am rarely writing nowadays and did a degree that also didn't demand writing!

Also have been wanting to hone in on my skills of using markdown, I want to enjoy notion but I despise having to do a "/" to initiate anything.

ps this editor is so scat I cannot do a less then sign without the whole thing crashing.