Raymond Camden

A Simple Weather App in TypeScript

2026-09-26T18:00:00+00:00

Happy Sunday, my fellow nerds. If you've been keeping up with my posts (all 4 of you - thank you!) then you know I've been experimenting with TypeScript (and Vite) recently. This past week I decided to try building a real "app", and of course by app I mean something incredibly small, but a bit "real world"-ish to kind of get a feel for what the development process felt like.

I decided on a fairly simple weather application. The application would prompt you for a location. That location gets geocoded to longitude and latitude values. With those values, I'd grab a simple weather forecast. After you add one, you can add another, and delete as well. Finally, all the values are stored in local storage so that on reload you get the same values loaded immediately.

If you actually want to see this - you can head over to https://weather-app-ts-vite-alpine.netlify.app/. The complete source may be found here: https://github.com/cfjedimaster/typescript-stuff/tree/main/weather-demo. Now let me dig into what I discovered while building it.

The One Thing

Let me start off with what I think is the biggest thing that clicked with me. While building out the various parts and using (at least some) of the TypeScript features, I immediately ran into probably the biggest win - immediate feedback in my editor when I had screwed things up. And yea, I know that's something TypeScript provided since day one, but it's also a bit different to kind of see it in action while building the app. Especially since I had two or three times when I had to refactor how I was doing things. Having the types in place (specifically for my remote API calls) helped keep things in order across the different moving parts.

I also found myself being forced to think more about how those parts interacted. So for example, a wrapper to my geocoding service - I instinctively knew what I had wanted - but having it spelled out in code actually made me see possible issues - modify my approach - and so forth - all earlier than I would have in my usual development process.

Again - this wasn't necessarily a surprise to me. This all fell in line with what I knew about TypeScript and what I had expected. But never having built an app from scratch with TypeScript before it still felt pretty cool to actually see all this play out.

The Architecture

It feels a bit silly to talk about the architecture of such a small little app, but this is how I built out the parts.

Once again, I used Vite.
On top of that, I used Alpine.js. In case you missed it, my last blog post discussed how to do this.
The main page handles displaying the 'weather cards' along with a simple form to add new locations.
When a location is entered, I use the excellent Geocodio API to translate it into longitude and latitude.
With that information, I use the Pirate Weather API to get the forecast.

The UI

As mentioned above, this was a Vite and Alpine app, but I also decided to try adding a UI library in as well. I picked Web Awesome primarily for the Card element. I've used this library in the past (when it was called Shoelace) and I really like it, especially as it uses web components. They also make it easy to only import what you need.

In my main.ts, this came down to:

import '@awesome.me/webawesome/dist/styles/webawesome.css';
import '@awesome.me/webawesome/dist/components/card/card.js';
import '@awesome.me/webawesome/dist/components/input/input.js';
import '@awesome.me/webawesome/dist/components/button/button.js';

With this in place, it was a simple matter to use the components. As an example:

<div class="wa-flank:end wa-gap-xs">
<wa-input placeholder="New Location (America, Canada, Mexico, UK only)" x-model="newLocation"></wa-input>
<wa-button variant="brand" @click="addLocation(newLocation)">Add</wa-button>
</div>

Make note of the classes on the div tag there. That comes from Web Awesome's various utility classes and this was a place where I leaned on my AI tool to help.

Here's the entirety of the main HTML page which shows you both Web Awesome in play as well as my Alpine directives:

<!doctype html>
<html lang="en" class="wa-dark">
  <head>
    <meta charset="UTF-8" />
    <link rel="icon" type="image/svg+xml" href="/favicon.svg" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>Weather Demo</title>
  </head>
  <body>
    <div x-data="app" class="container wa-stack">

      <header>
        <h1>Weather Demo</h1>
      </header>

      <template x-if="locations.length === 0"> 
        <p>No locations added yet. Add a location to get started.</p>
      </template>
      <div class="wa-grid wa-gap-1" style="--min-column-size: 30ch;">
      <template x-for="(location,index) in locations" :key="location.name">
        <wa-card class="card-basic" >
          <h3 slot="header" x-text="location.name"></h3>
          <wa-button appearance="plain" @click="removeLocation(index)" slot="header-actions">
            <wa-icon name="trash" variant="solid" label="Delete"></wa-icon>
          </wa-button>
          <template x-if="location.weather">
            <p x-html="`Temperature: ${location.weather.temperature}°F<br/>Condition: ${location.weather.summary}<br>Low: ${location.weather.low}°F<br/>High: ${location.weather.high}°F`"></p>
          </template>
          <template x-if="!location.weather">
            <p>Loading weather data...</p>
          </template>
        </wa-card>
      </template>
        </div>

      <div class="wa-flank:end wa-gap-xs">
      <wa-input placeholder="New Location (America, Canada, Mexico, UK only)" x-model="newLocation"></wa-input>
      <wa-button variant="brand" @click="addLocation(newLocation)">Add</wa-button>
      </div>

    </div>
    <script type="module" src="/src/main.ts"></script>
  </body>
</html>

The Three "Services"

I'm using "services" in quotes there as it feels a bit overly dramatic to name it as such, but I broke out three parts into their own files - one for geocoding, one for the weather, and one for storage. Let's start with storage first.

This file wraps the calls to LocalStorage and in theory - I could easily switch out to IndexedDB in the future - but I'd have to mark the functions async of course:

import type { SavedLocation } from './types';

// This is where it's stored in localStorage. 
const KEY = 'weather-locations';

// Type guard: checks at runtime that an unknown value really is a SavedLocation.
// localStorage can contain anything (old versions of your app, manual edits),
// so we validate instead of trusting it.
// Ray, in case you forget, the value is means that if the function returns true, 
// it's ok for TS to consider the value as of type SavedLocation
function isSavedLocation(value: unknown): value is SavedLocation {
  if (typeof value !== 'object' || value === null) return false;
  const v = value as Record<string, unknown>;
  return (
    typeof v.name === 'string' &&
    typeof v.longitude === 'number' &&
    typeof v.latitude === 'number'
  );
}

export function getLocations(): SavedLocation[] {
  const locations = localStorage.getItem(KEY);
  if(!locations) return [];

  const parsed = JSON.parse(locations);
  return Array.isArray(parsed) ? parsed.filter(isSavedLocation) : [];
}

export function addLocation(location: SavedLocation): void {
  const locations = getLocations();
  locations.push(location);
  localStorage.setItem(KEY, JSON.stringify(locations));
}

export function removeLocation(index: number): void {
  const locations = getLocations();
  locations.splice(index, 1);
  localStorage.setItem(KEY, JSON.stringify(locations));
}

The first thing you see on top is importing a type that defines what a 'stored location' is in terms of my application. From that file, here is the definition:

export type SavedLocation = {
  name: string;
  longitude: number;
  latitude: number, 
  weather?: WeatherData;
};

This should mostly make sense - the name comes from the user, the longitude and latitude from the geocoding service.

The weather part actually comes after the app loads in the existing values from local storage and hits the weather API. There's a part of me that looks at that and thinks maybe I should have a type for the "stored" value and one for the "live" value. I also think I could possibly cache the weather so that on reload it's quicker, but weather data is the kind of thing that gets stale pretty quickly.

Here's that file:

import type { WeatherData } from './types';

const KEY = import.meta.env.VITE_PIRATE_KEY as string;

export async function getWeather(lat: number, lng: number): Promise<WeatherData> {
    const req = await fetch(`https://api.pirateweather.net/forecast/${KEY}/${lat},${lng}?units=us&exclude=minutely,hourly,alerts,flags`);
    const res = await req.json();

    return {
        summary: res.currently.summary,
        temperature: res.currently.temperature,
        low: res.daily.data[0].temperatureLow,
        high: res.daily.data[0].temperatureHigh
    };

}

And here's the type:

export type WeatherData = {
  summary: string;
  temperature: number;
  low: number;
  high: number;
}

Finally, here's the geocoding wrapper:

import type { GeoCodedLocation } from './types';

// Only the fields we use from Geocodio's "simple" format
type GeocodioSimpleResponse = {
  lat?: number;
  lng?: number;
};

const KEY = import.meta.env.VITE_GEOCODIO_KEY as string;

export async function geoCode(location: string): Promise<GeoCodedLocation> {
    const req = await fetch(`https://api.geocod.io/v1.7/geocode?q=${encodeURIComponent(location)}&format=simple&api_key=${KEY}`);
    const res = (await req.json()) as GeocodioSimpleResponse;

    if(!res || !res.lat || !res.lng) {
        throw new Error('No results');
    }

    return { lat: res.lat, lng: res.lng };
}

You'll notice I do the HTTP call slightly different here. I've got an inline type here that defines what is being used from Geocodio. I'll be honest and say I want to think about these two approaches and figure out when I should use each. I mean, when you look at GeoCodedLocation:

export type GeoCodedLocation = {
  lat: number;
  lng: number;
};

I honestly don't get the point of the inline type as well. I was having AI help me a bit, so it's on me to nail down if this makes sense in the context of the file. I'll be returning to that soon.

The Core App

Now let's put it together with my core file - which is mainly Alpine.js specific:

import Alpine from 'alpinejs';

import '@awesome.me/webawesome/dist/styles/webawesome.css';
import '@awesome.me/webawesome/dist/components/card/card.js';
import '@awesome.me/webawesome/dist/components/input/input.js';
import '@awesome.me/webawesome/dist/components/button/button.js';
import './style.css';

import type { SavedLocation } from './types';
import { getLocations, addLocation, removeLocation } from './storage';
import { getWeather } from './weather';
import { geoCode } from './geocode';

Alpine.data('app', () => ({
  locations: [] as SavedLocation[],
  newLocation: '',
  init() {
    this.locations = getLocations();
    if(this.locations.length > 0) {
      this.hydrateWeather();
    }
  },
  async addLocation(location: string) {
    if(!location) return;
    const geo = await geoCode(location);
    const newLoc: SavedLocation = { name: location, longitude: geo.lng, latitude: geo.lat };
    this.locations.push(newLoc);
    // just noticed my method is addLocation as is the imported one. works but - eww. 
    addLocation(newLoc);
    this.newLocation = '';
    // in theory it is wasteful to hydrate ALL of them, but it's a super quick call
    this.hydrateWeather();
  }, 
  removeLocation(index: number) {
    this.locations.splice(index, 1);
    // same issue with naming - advice?
    removeLocation(index);
  },
  async hydrateWeather() {
    for(const loc of this.locations) {
      const weather = await getWeather(loc.latitude, loc.longitude);
      loc.weather = weather;
    }
  }
}));

Alpine.start();

If you actually took the time to read all that, you can see I wrote a few questions to myself. By accident, I ended up having Alpine methods with the same name as methods in my services, and that really bugs me... but it also works... so... yeah. It's kinda clear that this.something is Alpine and something is being imported in, but I still don't care for that. How would you rename things? (And I'd assume the rename would be on the Alpine side.)

I also notice a few lines where I didn't define my type. A quick search shows that by adding strict:true to my tsconfig.json would fix that. I know in the past I've seen that in projects and it's annoyed the heck out of me, so I get why Vite's scaffold doesn't include it, but for my next project, I'm going to turn that on so I can be a bit more precise in my learning with TypeScript.

Your Turn!

Ok, I know blogging is dead (again) and no humans read these posts again, but if you are reading this, and know TypeScript well, I'd love any and all feedback! Give me a comment below and help me keep learning this.

Photo by Patrick Fore on Unsplash

A Simple Alpine.js Template with Vite and TypeScript

2026-09-22T18:00:00+00:00

This will be a quick one - but as I think more about TypeScript and how I'd like to learn (and play, and build silly demos), I naturally thought it may make sense to look at how I'd use Alpine.js with that stack. Alpine's been my go to library for web apps that reach the level of complexity where I'd like some help with DOM manipulation and such. I don't always use it, because (imho) the default stack should be as vanilla as possible (obviously I'm going a bit off ranch with these explorations into TypeScript and Vite) but Alpine is lightweight and simple and just a great little library in general. What follows isn't necessarily a "template" as it's got a bit of template code with it, but I thought it would be helpful to share. As always, let me know what you think!

Step One - the Scaffold

In my first post a few days ago, I mentioned that the Vite scaffold support lets you create a vanilla application with TypeScript. I used that for my code and removed as much of the demo code as I could. I do wish Vite's template was a bit more minimal.

Step Two - Adding Alpine

Usually I make use of the Alpine CDN in my demos, for this one, I instead installed it as a dependency. I also installed the Alpine types dependency. Here's my package.json:

{
  "name": "alpine-test-1",
  "private": true,
  "version": "0.0.0",
  "type": "module",
  "scripts": {
    "dev": "vite",
    "build": "tsc && vite build",
    "preview": "vite preview"
  },
  "devDependencies": {
    "@types/alpinejs": "^3.13.11",
    "typescript": "~6.0.2",
    "vite": "^8.3.0"
  },
  "dependencies": {
    "alpinejs": "^3.17.4"
  }
}

Step Three - the HTML

Ok, so this part is really simple. Alpine "ties" to your DOM usually via an x-data attribute. That means this is the bare minimum:

<div x-data="app">
</div>

But of course you'll have more Alpine directives and more HTML. Also, "app" is not required, but is the name I pretty much use all the time. For my template/demo, I output a couple of variables and included a few click directives just to test stuff out. Oh, I also added Simple.css to just to make it look prettier. That's absolutely not necessary. The Vite demo actually imports CSS in their main TypeScript file (you can see that on Stackblitz here) and I'm not sure how I feel about that. I know it minimizes the code, but it feels really weird to me. Anyway, here's my HTML:

<!doctype html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <link rel="icon" type="image/svg+xml" href="/favicon.svg" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <link rel="stylesheet" href="https://cdn.simplecss.org/simple.min.css">
    <title>alpine-test-1</title>
  </head>
  <body>
    <div x-data="app">
      <p>
      <span x-text="message"></span>
      </p>
      <p>
      <button @click="meow()">Meow (default)</button>
      <button @click="meow('Purr...')">Meow (custom)</button>
      </p>
      <ul>
        <template x-for="(cat, index) in cats" :key="index">
          <li x-text="cat.name"></li>
        </template>
      </ul>
    </div>
    <script type="module" src="/src/main.ts"></script>
  </body>
</html>

Step Four - Enter the TypeScript

Ok, for the final bit - my TypeScript code:

import Alpine from 'alpinejs';

type Cat = {
  name: string;
  breed: string;
  gender: 'male' | 'female';
};

Alpine.data('app', () => ({
  message:'Hello from Alpine!',
  cats: [] as Cat[],
  init() {
    this.cats.push({ name: 'Whiskers', breed: 'Siamese', gender: 'male' });
    this.cats.push({ name: 'Fluffy', breed: 'Persian', gender: 'female' });
  },
  meow(message:string = 'Meow!') {
    alert(message);
  }
}));

Alpine.start();

Let me point out the important bits. Unlike my usual Alpine demos, I import Alpine here from the local install. I also need to fire Alpine.start() manually. But outside of that, it's pretty vanilla Alpine - define the app and include relevant variables and methods, which in this case is pretty small.

Now obviously I'm trying to learn TypeScript as well, but I kept it pretty short here. I've defined a type for Cat and when I worked with the data, my editor (Visual Studio Code) provided support as I'd expect - it knew the right parts of a cat and correctly flagged an error if I tried to include something that wasn't defined in the type.

As a reminder, this is all done in the editor - it wouldn't be a "real" error in production - but the idea here - and the benefit of TypeScript - is that I'd (hopefully!) catch it much earlier.

Outside of that, you can also see where I define cats as an array of Cat and specify that the message argument to meow is string.

Again - this is pretty minimal TypeScript usage, but I dig it, and I can really see how in some of my larger Alpine demos in the past, the additional safety/checking/etc would have been real helpful I think.

There Is No Step Five

If you want the code to try it yourself, you can copy it from here: https://github.com/cfjedimaster/typescript-stuff/tree/main/alpine-test-1. I know this was pretty short, but I'd still love any feedback or advice, so hit up the comments below!

Links For You (9/20/26)

2026-09-20T18:00:00+00:00

Happy "Football is Back" season to those of you who celebrate. I'm currently watching my Saints take on the Ravens (who are also a favorite of mine) and hoping for our first win. The last few weeks have been incredibly busy (I feel like I always say that, sorry) with a trip for work that then morphed into a short vacation with my wife and I which included my first Blizzcon (which is freaking cool as hell) and our first visit to Disneyland. (We've been to Disney World a few times.) I think we both agreed that Disney World is cooler, but the crowds and - most importantly - the weather - was much better in California.

RSS Lookup

First up for the links today is RSS Lookup, a simple web site that lets you paste in a URL and see if it has a RSS feed. Not every site does a good job of letting you know about their RSS options so this can make it easier. Most likely I think the bookmarklet will be more useful to folks.

If your curious, here's the meta tag used to signify a site's feed:

<link rel="alternate" type="application/rss+xml" 
title="Your Site Title - RSS Feed" href="https://example.com" />

Interfaces, a collection by Ron Domingue

Ron is someone I've known for a while, a local down here in Louisiana, who has done some incredibly stunning visual works. His Interfaces is a collection of various UI interfaces for different types of data. I'd be hard pressed to pick a favorite, but Landfall is a stunning visualization of hurricane tracks and their landfall.

Remember Imagemaps?

Imagemaps are one of those old web techs that used to be everywhere, and then disappeared. In case you don't remember, the idea was that one image on a web page, when clicked, could have multiple different destinations based on where you clicked. Typically this was defined in HTML with coordinates mapping to URLs. But you could also handle the location on the server side as well. In that form, the coordinates are included in the URL and your server side tech has to handle figuring out what goes where.

This post, "Today I Rescued 7,234 Old GIFs", by Dan Q explores how he attempted (and succeeded) in scraping a bunch of Gif icons for an old directory.

Not gonna lie - kinda miss the old web. :)

Just For Fun

Ok, usually I share cool music videos here, but today I want to share something different. My father-in-law shared this short with us and while it's marked as comedy, it's a pretty deep 30-ish minute short staring Jane Kaczmarek. It's definitely worth your time!

It's only a decade late, I'll learn TypeScript!

2026-09-18T18:00:00+00:00

I've been a bit worried lately. Of course, my friends will tell you that's my norm. But more specifically, I've been worried about my coding skills. As I use AI to generate more and more code, and it does that job well, I kinda miss actually writing code. I've also had a bit of writer's block in terms of topics to cover, and especially in the area of the web platform. A few days ago it occurred to me - I've never really dug into TypeScript. Sure, I've used it, many times, in the fourteen or so years it's been out, but many times I kinda guess at what I'm doing and it was never my default for projects. Partly that's due to my philosophy of avoiding a build step in my projects and just KISS in general.

But as I said - the inspiration hit me this past week and I thought I'd do some digging. Here's a few initial thoughts and experiments. Oh, and I still used AI a bit and I'll explain exactly how in the post below.

TypeScript via Vite

Working with TypeScript can be as simple as npm i -g typescript and then tsc somefile.ts. I decided to use Vite instead as it's focused on web projects and most of my development involves web projects. I assume most of my readers know of Vite, but if you somehow have managed to avoid hearing about it or using it yet, it is a lightning quick build tool for web projects. By "lightning quick" I mean that I still remember the first time I used it thinking it had failed to actually do anything - that's how quick it works.

I also appreciated the fact that Vite's CLI supports a vanilla-ts scaffold that is really lightweight. On the other hand, I'm not necessarily a fan of what it actually shows as it feels a bit like bad practice, specifically an index file with just one div:

<!doctype html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <link rel="icon" type="image/svg+xml" href="/favicon.svg" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>Vite + TS</title>
  </head>
  <body>
    <div id="app"></div>
    <script type="module" src="/src/main.ts"></script>
  </body>
</html>

And then injects a bunch of HTML in main.ts:

import './style.css'
import heroImg from './assets/hero.png'
import typescriptLogo from './assets/typescript.svg'
import viteLogo from './assets/vite.svg'
import { setupCounter } from './counter.ts'

document.querySelector<HTMLDivElement>('#app')!.innerHTML = `
<section id="center">
  <div class="hero">
    <img src="${heroImg}" class="base" width="170" height="179">
    <img src="${typescriptLogo}" class="framework" alt="TypeScript logo"/>
    <img src="${viteLogo}" class="vite" alt="Vite logo" />
  </div>
  <div>
    <h1>Get started</h1>
    <p>Edit <code>src/main.ts</code> and save to test <code>HMR</code></p>
  </div>
  <button id="counter" type="button" class="counter"></button>
</section>

<div class="ticks"></div>

<section id="next-steps">
  <div id="docs">
    <svg class="icon" role="presentation" aria-hidden="true"><use href="/icons.svg#documentation-icon"></use></svg>
    <h2>Documentation</h2>
    <p>Your questions, answered</p>
    <ul>
      <li>
        <a href="https://vite.dev/" target="_blank">
          <img class="logo" src="${viteLogo}" alt="" />
          Explore Vite
        </a>
      </li>
      <li>
        <a href="https://www.typescriptlang.org" target="_blank">
          <img class="button-icon" src="${typescriptLogo}" alt="">
          Learn more
        </a>
      </li>
    </ul>
  </div>
  <div id="social">
    <svg class="icon" role="presentation" aria-hidden="true"><use href="/icons.svg#social-icon"></use></svg>
    <h2>Connect with us</h2>
    <p>Join the Vite community</p>
    <ul>
      <li><a href="https://github.com/vitejs/vite" target="_blank"><svg class="button-icon" role="presentation" aria-hidden="true"><use href="/icons.svg#github-icon"></use></svg>GitHub</a></li>
      <li><a href="https://chat.vite.dev/" target="_blank"><svg class="button-icon" role="presentation" aria-hidden="true"><use href="/icons.svg#discord-icon"></use></svg>Discord</a></li>
      <li><a href="https://x.com/vite_js" target="_blank"><svg class="button-icon" role="presentation" aria-hidden="true"><use href="/icons.svg#x-icon"></use></svg>X.com</a></li>
      <li><a href="https://bsky.app/profile/vite.dev" target="_blank"><svg class="button-icon" role="presentation" aria-hidden="true"><use href="/icons.svg#bluesky-icon"></use></svg>Bluesky</a></li>
    </ul>
  </div>
</section>

<div class="ticks"></div>
<section id="spacer"></section>
`

setupCounter(document.querySelector<HTMLButtonElement>('#counter')!)

I'm probably being real nit picky here, but having 99% of the HTML for something in JavaScript versus HTML that gets enhanced feels off to me. But again - I'm being picky, and the actual code spit out is pretty minimal. (I could go on for ages about what's "appropriate" for scaffolded projects and such. Give me a soap box and I'll tell you more.)

So yeah, that's how I started. I pretty much nuked most of the code in main.ts and simplified even more.

I mentioned earlier I still used a bit of AI in my exploration, and one example was to help clarify things a bit. For example, my very high level basic understanding of TypeScript basically came down to type annotations like so:

let name:string = "Ray";

This line in the sample code confused me:

document.querySelector<HTMLDivElement>('#app')!.innerHTML = `

So I simply asked Claude to explain it:

The <HTMLDivElement> (generic type argument)

By default, querySelector returns Element | null. Element is a very generic type — 
TypeScript doesn't know whether it's a div, an input, an SVG circle, etc. That 
matters because different elements have different properties: Element doesn't 
have .value, for example, but HTMLInputElement does.

Writing querySelector<HTMLDivElement>('#app') tells TypeScript: "trust me, the 
thing this selector finds is a div." So the return type becomes 
HTMLDivElement | null instead of Element | null, and you get proper autocomplete 
and type checking for div-specific properties.

Like the !, this is a compile-time-only assertion — TypeScript doesn't verify 
it. If #app were actually a <span>, the code would still compile and run; you'd 
just have a lying type.

Fun fact: in this particular line the generic is technically unnecessary, since 
.innerHTML exists on Element anyway. It's there mostly out of habit/convention 
(this looks like the Vite starter template). It becomes genuinely useful when 
you need element-specific properties like .value, .src, or .checked.

Cool. And this is something I've really liked about AI in the past. I feel like my question, a particular syntax being used, wouldn't Google well and AI tools do a better job of getting to the right answer.

At this point, I felt ready to write something.

Actually, let's not build for the web...

So when I figured out a good simple thing to build, I realized I didn't actually need a web UI for it, at least not initially, so I did a quick pivot and looked up info on vitest, a "Vite-native" testing framework. I actually don't have a huge amount of experience with unit tests as so much of my work is educational, demo based, and such, that tests aren't really required. That being said, I've written them, I'm familiar with Jest (which vitest is compatible with), so it seemed like an easy win.

I did a quick npm i -D vitest and added this to my package.json scripts block: "test": "vitest"

This let me run npm run test in my terminal and get immediate feedback on what I was writing.

Roll the dice...

About five years ago, I thought it would be fun, and surely pretty simple, to build an RPG in Vue.js (here's the first entry: "Testing Vue.js Application Files That Aren't Components". I never finished that project, but I don't care - it was fun to work on.

As part of that project, I built a simple "dice" utility that supported typical D&D dice rolls of the form: xDy. This translates to roll a Y-sided dice X times. It can get fancy too, so 2d6+2 means roll a six sided die two times and then add two tp the final result. (You could imagine a scenario where a player is attempting to do something they are talented at, so the +2 represents a bonus to their chance to do the thing.)

The code for that looked like so:

export const dice = {

	roll(style) {
		let bonus=0, total=0;
		if(style.indexOf('+') > -1) {
			[style, bonus] = style.split('+');
		} 
		
		let [rolls, sided] = style.split('d');
		
		//console.log(rolls, sided);
		for(let i=0;i<rolls;i++) {
			total += getRandomIntInclusive(1, sided);
		}
		total += parseInt(bonus);
		return total;
	}
}

function getRandomIntInclusive(min, max) {
  min = Math.ceil(min);
  max = Math.floor(max);
  return Math.floor(Math.random() * (max - min + 1)) + min; //The maximum is inclusive and the minimum is inclusive 
}

I thought a good first test would be to attempt to rewrite this in a TypeScript file. I actually broke it out into two files, one for the roll action and a 'util' one for the random number selection.

I'll share the utility function first as it was the simplest change:

export function getRandomInt(min: number, max: number): number {
  min = Math.ceil(min)
  max = Math.floor(max)
  return Math.floor(Math.random() * (max - min + 1)) + min
}

This was really simple - just adding types to my arguments and result. I also removed inclusive from the name as I never see myself needing a non-inclusive random number selection.

The test for this was pretty simple too:

import { describe, it, expect } from 'vitest'
import { getRandomInt } from './utils'

describe('getRandomInt', () => {
  it('returns a number between min and max', () => {
    const min = 1;
    const max = 2;
    const randomInt = getRandomInt(min, max);
    expect(randomInt).toBeGreaterThanOrEqual(min);
    expect(randomInt).toBeLessThanOrEqual(max);
  })

  it('returns an integer', () => {
    const randomInt = getRandomInt(1, 10);
    expect(Number.isInteger(randomInt)).toBe(true);
  })
});

I discovered after writing this that you can actually screw with Math.random() which is cool af as the kids say, so I may return to this. But now let's turn to the dice stuff which got REALLY complicated, but in a fun way.

My first version went a bit like this:

import { getRandomInt } from './utils.ts';

export const dice = {

	/*
	xdy

	x rolls of a y sided dice

	xdy+n
	xdy

	x rolls of a y side dice + n
	*/
	roll(styleInput: string): number {
		let bonus:number=0, total:number=0;
        let bonusStr:string='';
        let style = '';

        if(styleInput.indexOf('+') > -1) {
			[style, bonusStr] = styleInput.split('+');
			bonus = Number(bonusStr);
		} else style = styleInput;
		
		const [rollsStr, sidedStr] = style.split('d');
		const rolls = Number(rollsStr);
		const sided = Number(sidedStr);

		//console.log(rolls, sided);
		for(let i=0;i<rolls;i++) {
			total += getRandomInt(1, sided);
		}

		total += Number(bonus);
		return total;
	}
}

And you'll notice it's a bit longer than the original version, and I don't mean more characters, I expected that, but some things took me a bit by surprise. Take this (original) line:

let [rolls, sided] = style.split('d');

My original code just coerced rolls into a number, which is bad, but I tried this and it didn't work:

let [rolls:number, sided: number] = style.split('d');

Which is obvious - the result of the string split function is strings. What didn't occur to me at the time was to chain to map:

let [rolls, sided] = s.split('d').map(Number);

Live and learn, right? I built some basic tests for that and was curious what else I could do. I turned to my AI agent (Claude in this case) and just asked what other 'dice format' options were available, and was pleasantly surprised to discover quite a few. In particular I thought these made sense:

Keep highest, lowest, using KH or KL. So for example, 3D6KH1 means roll a six sided die three times, keep the highest one.
Given a dice string input, what's the lowest value, and what's the highest value?

At this point, I decided to let AI help me write a bit of the code and handle updating the library to be a bit more flexible. The final result supports all of the above:

import { getRandomInt } from './utils.ts';

const VALID_ROLL_REGEX =
    /^(\d*)d(\d+)(?:(kh|kl|dh|dl)(\d+))?([+-]\d+)?$/i;

function validRoll(style: string): boolean {
    return VALID_ROLL_REGEX.test(style);
}

function parseRoll(styleInput: string) {
    if (!validRoll(styleInput)) {
        throw new Error(`Invalid dice roll style: ${styleInput}`);
    }

    const match = styleInput.match(VALID_ROLL_REGEX)!;

    return {
        rolls: match[1] ? Number(match[1]) : 1,
        sided: Number(match[2]),
        keepMode: match[3]?.toLowerCase(),
        keepCount: match[4] ? Number(match[4]) : 0,
        bonus: match[5] ? Number(match[5]) : 0,
    };
}

function applyKeepDrop(
    dice: number[],
    keepMode: string | undefined,
    keepCount: number,
): number[] {
    if (!keepMode || keepCount === 0) {
        return dice;
    }

    dice.sort((a, b) => a - b);

    switch (keepMode) {
        case 'kh':
            return dice.slice(-keepCount);
        case 'kl':
            return dice.slice(0, keepCount);
        case 'dh':
            return dice.slice(0, -keepCount);
        case 'dl':
            return dice.slice(keepCount);
        default:
            return dice;
    }
}

export function roll(styleInput: string): number {
    const { rolls, sided, keepMode, keepCount, bonus } =
        parseRoll(styleInput);

    const dice: number[] = [];

    for (let i = 0; i < rolls; i++) {
        dice.push(getRandomInt(1, sided));
    }

    const total = applyKeepDrop(dice, keepMode, keepCount)
        .reduce((sum, die) => sum + die, 0);

    return total + bonus;
}

export function rollWithAdvantage(styleInput: string): number {
    return Math.max(roll(styleInput), roll(styleInput));
}

export function rollWithDisadvantage(styleInput: string): number {
    return Math.min(roll(styleInput), roll(styleInput));
}

export function minRoll(styleInput: string): number {
    const { rolls, keepMode, keepCount, bonus } = parseRoll(styleInput);
    const dice = Array(rolls).fill(1);

    return applyKeepDrop(dice, keepMode, keepCount)
        .reduce((sum, die) => sum + die, 0) + bonus;
}

export function maxRoll(styleInput: string): number {
    const { rolls, sided, keepMode, keepCount, bonus } =
        parseRoll(styleInput);
    const dice = Array(rolls).fill(sided);

    return applyKeepDrop(dice, keepMode, keepCount)
        .reduce((sum, die) => sum + die, 0) + bonus;
}

I won't share the entire test file (don't worry, I'll link to the repo in a bit), but as I mentioned above, you can actually "hack" random and that's really freaking sweet. For example, here is a test for rolls where you drop the lowest value:

it('handles drop lowest', () => {
    const spy = vi.spyOn(Math, 'random')
        .mockReturnValueOnce(0.1)  // first roll → low
        .mockReturnValueOnce(0.9);  // second roll → high

    const result = roll('2d6dl1');
    expect(result).toBe(6);

    spy.mockRestore();
});

Looking at it just now I see the second mock isn't needed - I'll fix that (eventually, honest) - but you get the idea.

The bits, and nothing but the bits...

So this isn't a "real" project, but I loved getting my feet wet in TypeScript and - tbh - just writing some darn code. The repo is here: https://github.com/cfjedimaster/typescript-stuff/tree/main/vite-one

I've already got an idea for a next project, one that will actually have a web presence, so I'll share that when I get the time.

And this is where you come in. I'd be willing to bet 99% of you are writing TypeScript daily and have plenty of comments - so let me know. Just be gentle. Please.

Building a Document Q&A System with On-Device AI

2026-09-06T18:00:00+00:00

Every now and then I build a demo for a presentation and think to myself - this deserves its own blog post. I then promptly forget to actually do that. Even better, I completely forget to even show the demo in the presentation. A few weeks ago I made my first presentation at RenderATL and gave my talk on Chrome's on-device AI technology. I've been blogging about this particular set of APIs for a few years now and I've given talks on it at numerous conferences. While these APIs are still evolving, many of them (and the ones I'm using today in particular) are now fully GA for Chrome. For this demo, I put together a few things I've done before into one cohesive tool - a completely client-side application that lets you pick a file, get a summary, and then chat with it.

The Stack

The demo is built from a few different things:

First, I'm making use of the incredibly excellent officeParser library by Harsh Ankur. This library can take any Office document, or PDF, or ODT, or CSV, and so on, and creates a parsed version you can do nearly anything with. For me, the most important feature is the ability to convert the file into Markdown which can then be used with AI.
Next, it makes use of Chrome's Summarizer API which - you guessed it - provides summaries of textual input.
Finally, it makes use of Chrome's Prompt API to let you ask questions about the input.

The web app itself is a simple Vite app using vanilla JavaScript. I used my AI agent to set up the application and create the design and there was quite a bit of back and forth to get things locked down, but the end result is pretty cool I think.

The App

Ok, I'm obviously going to link to it, and the source, too, but I thought I'd share a few screenshots for people who may be on Safari, or maybe reading this on iOS where Chrome is locked down to the Safari engine.

On opening the app, you get a three panel UI. The left side is for selecting and previewing the document. The upper right is for the summary. The rest of the right column is for Q and A:

I selected my resume and after a few seconds, I get a summary. Now - I should clarify - the reason it works fast for me is that Chrome has already downloaded the roughly 4 gig model. That's absolutely not insignificant. But it's also a model shared by the browser for any web site making use of these APIs so it's not something a user has to download again and again.

Here's the summary that was displayed:

This is nearly perfect. For some reason it thinks I worked at Microsoft and as far as I know I only mention Microsoft once in the resume and it's in regard to work done at Webflow.

But that brings up a great first use of the Q and A - I specifically asked if Ray worked at Microsoft and I got the proper response:

"The provided document does not mention Ray Camden working at Microsoft."

I asked a followup question about PHP and I liked the response:

Honestly that's a pretty deep answer and kind of impressive I think.

Anyway, if you like this, and are using an up to date Chrome (on desktop or Android), you can check it out here: https://document-question-answer.netlify.app/. You can peruse the source up here: https://github.com/cfjedimaster/doc_qa

My Family Allowance - a Simple Allowance Tracking Site

2026-09-02T18:00:00+00:00

As you can probably tell, I've been on a bit of a builder kick the last few weeks. Today's "release" (it's been live for a few days already) is a tool to help fix a manual process we had in our family - tracking allowance for the kids.

Previously we made use of a Google Sheet. Each kid had a column. When a kid would ask for something, we'd look to see when we last added allowance, multiply the number of weeks by their rate, add it, and then add another row to reduce by the amount they were spending. A simple formula on the right hand side would give a running total so they could see what their current balance was.

I decided to take this manual process and turn it into a proper application.

Using Cursor, I created an application with the following features:

The parent signs up with their Google account.
They then have a simple admin to add, edit, and delete kids while setting their weekly allowance.
The parent can then add or remove funds when necessary.
Every Sunday, automatically, allowance is paid.
They are given a unique URL for their family and can set a basic password. A great idea for this would be the same password used for wifi in the house.
The "family" URL lets kids see their totals, and even click in to see a transaction history if they want to remember what they spent money on.

The stack is Astro, hosted on Netlify, with their Netlify DB as the storage system.

That's it! You can check it out here: https://www.myallowance.family/. If you want to check out the source, you can check out the repo: https://github.com/cfjedimaster/myfamilyallowance

Photo by Igal Ness on Unsplash

Weather Nerd? Check out My OSX Radar Widget

2026-09-01T18:00:00+00:00

I know I'm not alone in being a bit of a weather nerd. Along with four or five weather apps on my phone, I've got two physical devices in my office that show the weather and a weather widget on my Mac that shows the day's forecast. That's not enough. What I really wanted was a radar widget as well, so I built one:

Ok, to be fair, I used Cursor to build it - but it really scratched an itch I've had for a while to constantly have one more thing to distract me.

If you want a copy of this yourself (or want to make it better!), I've set up a GitHub repo here: https://github.com/cfjedimaster/precipradar. I've got both the source as well as a build for easy installation.

Note that as with my LEGO screensaver, you'll need to run a CLI command to authorize the app, but that's a onetime operation. Enjoy!

Like LEGO? Got a Mac? Get My Screensaver

2026-08-26T18:00:00+00:00

Good morning my fabulous readers. This will be a quick post as I just wanted to share something cool I built with Cursor over the past couple of days - a LEGO screensaver. I'm a huge fan of "show me something random from something I like" and have built multiple bots in that vein. I recently discovered Rebrickable's LEGO datasets which contains a CSV file of LEGO sets. The data looks like so:

set_num,name,year,theme_id,num_parts,img_url
0003977811-1,Ninjago: Book of Adventures,2022,761,1,https://cdn.rebrickable.com/media/sets/0003977811-1.jpg
001-1,Gears,1965,756,43,https://cdn.rebrickable.com/media/sets/001-1.jpg
0011-2,Town Mini-Figures,1979,67,12,https://cdn.rebrickable.com/media/sets/0011-2.jpg
0011-3,Castle 2 for 1 Bonus Offer,1987,199,0,https://cdn.rebrickable.com/media/sets/0011-3.jpg
0012-1,Space Mini-Figures,1979,143,12,https://cdn.rebrickable.com/media/sets/0012-1.jpg
0013-1,Space Mini-Figures,1979,143,12,https://cdn.rebrickable.com/media/sets/0013-1.jpg

I thought it would be cool to select a random set, show the year, name, number of pieces, and render the image as well. I gave this CSV to Cursor and started iterating on building a simple OSX screensaver. I had it filter out sets where the number of pieces was greater than or equal to 50 (typically "swag", non-buildable items) or with names that also appeared to be non-buildable things.

After that, I just let Cursor handle creating the project. I know nothing about OSX development, thankfully Cursor does. The only real issue I ran into was OSX aggressively caching the screensaver data which made updates a bit difficult. I think we (and by that I mean mostly Cursor, and some me) figured that out eventually.

Here's an example of how it looks:

Alright, so before I link you to the GitHub repo, a quick warning. I'm not paying Apple for a developer's license which means if you get the build, you'll need to run a one-time command in your terminal to whitelist the app.

Ok, with that out of the way, head over to the repo and check it out: https://github.com/cfjedimaster/lego-screensaver

Links For You (8/23/26)

2026-08-23T18:00:00+00:00

Greetings, programs. Once again, I'm a bit behind on these posts, but I just got back from two weeks of travel and I'm so happy to be home for a while. My last trip was pretty stressful. On the way out, our plane blew a tire (or tires) which required an emergency landing in Dallas (which is where we were scheduled to stop anyway). Everything ended up fine, but as I said, stressful. Then coming home we were minutes from our destination when the pilot had to turn around due to storms. You can actually see exactly where in the route where they said NOPE:

For this, and other reasons, I'm damn happy I've got a therapy session tomorrow. So, let's get to the links.

And the winner for best project name goes to...

I've only given this a cursory glance, but the name itself was enough to make me giggle: The Mullet Stack. The Mullet Stack describes itself as "JavaScript in the front, Python in the back", and describes the combination of a backend built with FastAPI and Pydantic and a front end using React and TypeScript. Now, I'm no React fan, and when I was playing with Python web frameworks last year (this year? time is weird) I didn't get around to checking out FastAPI, but this guide does a great job of walking you through the process of setting up both ends and wiring things together nicely.

Change to Clipboard Reading in JavaScript

If you've ever done anything with JavaScript and the clipboard, the Chrome team has made a change to the API in order to improve performance. "Selective format read: A better default for the Async Clipboard API" discusses how, at least previously, reading from the clipboard could be a bit of a performance hit as the browser would read in all representations of data in the clipboard (along with sanitization) even though your code (typically) only used one format. (As an FYI, when you copy something to the clipboard, it can be represented in multiple different formats.) Their article describes how data is now lazy loaded and - well that's mainly it. This change has also been implemented in Safari and Firefox has indicated they may adopt this as well.

You may also be interested in my post about this here: Handling Paste Events in JavaScript

A New Option for Generating RSS

I've spent a heck of a lot of time writing code to both generate and parse RSS. One thing you'll notice if you look for libraries like this is that - typically - they're pretty old. To be fair, RSS is a spec and hasn't changed in a while. (A quick Google check seems to confirm the last change was 2009.) The feed JavaScript/Typescript library is an example of this, with portions over 8 years old, but it very recently was updated and if you find yourself needing to generate RSS, I'd probably start here.

Just For Fun

Last time I shared a good cheesy 80s video so why not follow it up with even more cheese? This is from a movie I plan on sharing with my kids real soon now...

Using the Cursor SDK to Build a Project Documenter

2026-08-22T18:00:00+00:00

I've shared a few posts recently talking about how I'm using Cursor to learn and employ agentic development. Primarily that work has all been done via our Agent view, but this is just one of the surfaces you can use with the platform. I had a chance recently to try out the SDK and I thought I'd share a little demo I built with it.

First - some explanation would be helpful. You can use Cursor with the desktop application, on the web, via CLI, on iOS, even via API. But the SDK lets you use the platform from your code. There's an SDK for TypeScript, Python, and a bridge that embeds a TypeScript server and lets you use any language. Honestly I've never seen that before in a platform and it's pretty freaking cool. (And... just to remind folks, I do work at Cursor so I'm biased, but that's absolutely an honest opinion.)

With the SDK, you can do all the things you can usually do with the platform - run prompts in different modes - swap models at will, including the auto router which makes it easier, even kick off agents that run in the cloud. Definitely check the docs for a full detailed list of what you can do, but it's basically the platform itself - in your code.

I built a quick demo with the TypeScript SDK, but then switched over to Python as I felt it a bit easier for me to use. The quickstart shows how easy it is:

import os

from cursor_sdk import Agent, LocalAgentOptions

with Agent.create(
    model="composer-2.5",
    api_key="crsr_key",
    local=LocalAgentOptions(cwd=os.getcwd()),
) as agent:
    print(agent.send("Summarize what this repository does").text())

This returns the final result of the prompt, but you also have the ability to get everything that was generated, so for example, the detailed list of tool calls and such. You can also decide between streaming or just waiting and getting the final result.

All of this just works - which is what you want in a SDK - and the quick start example is one of my favorite things to do with Cursor - basically "what the heck is this repo/set of code doing" - and I thought it would be cool to turn this into a CLI tool.

To be clear, normally I'd use the Cursor Agent window, open the repo or folder, and use Ask mode to describe the project. But if I'm not planning to work with the code later and just want a good explanation, a CLI tool could be useful for this purpose instead.

Of course, the easiest way to build this is to use Cursor itself. I set up a new folder and started a new plan:

/plan create a Python CLI that makes use of the Cursor SDK. The CLI is a 
tool that will scan a code base and generated a detailed report of the 
application/code base of the folder being scanned. What it does, what 
technologies it use, what frameworks are in place, and so forth.

The CLI should support a help command. 
The CLI will scan the current directory by default, but supports an 
argument to specify a path.
The CLI will output Markdown, but an argument allows for a PDF file output.
Require a filename to store the result.

This created the following plan:

By the way, the Architecture was a pretty Mermaid chart that's not rendering on my blog:

The end result - in terminal I can create a report in either Markdown or PDF. I'll share a link to the entire thing below, but let's take a look at the Python file responsible for analyzing the codebase via the Cursor SDK:

"""Run a local Cursor agent to produce a codebase Markdown report."""

from __future__ import annotations

import os
import sys
from pathlib import Path

from cursor_sdk import Agent, AgentOptions, CursorAgentError, LocalAgentOptions

PROMPT = """\
Explore this codebase thoroughly (manifests, configs, source layout, docs) and \
produce a detailed report about the application.

Cover at least:
- Overview / purpose of the project
- Primary languages and runtimes
- Frameworks and major libraries
- Architecture and top-level structure
- Entry points and how to run, build, and test (if discoverable)
- Notable tooling (CI, linters, package managers, etc.)
- Anything else material about how the app works

Rules:
- Do not modify, create, or delete any files.
- Return ONLY Markdown for the report (headings, lists, short code snippets as needed).
- Do not wrap the entire reply in a single fenced code block.
"""


class ScanError(Exception):
    """CLI-facing scan failure with an exit code."""

    def __init__(self, message: str, exit_code: int) -> None:
        super().__init__(message)
        self.exit_code = exit_code


def _require_api_key() -> str:
    api_key = os.environ.get("CURSOR_API_KEY", "").strip()
    if not api_key:
        raise ScanError(
            "CURSOR_API_KEY is not set. Export it before running codebase-report.",
            exit_code=1,
        )
    return api_key


def _extract_markdown(result: object) -> str:
    text = getattr(result, "result", None)
    if isinstance(text, str) and text.strip():
        return text
    raise ScanError("Agent finished but returned no report text.", exit_code=2)


def scan_codebase(scan_path: Path) -> str:
    """Analyze *scan_path* with a local Cursor agent and return Markdown."""
    api_key = _require_api_key()
    cwd = str(scan_path.resolve())

    print(f"Scanning {cwd} with Cursor agent…", file=sys.stderr)

    try:
        result = Agent.prompt(
            PROMPT,
            AgentOptions(
                api_key=api_key,
                model="composer-2.5",
                local=LocalAgentOptions(cwd=cwd),
            ),
        )
    except CursorAgentError as err:
        retryable = getattr(err, "is_retryable", False)
        raise ScanError(
            f"startup failed: {err.message} (retryable={retryable})",
            exit_code=1,
        ) from err

    status = getattr(result, "status", None)
    if status == "error":
        run_id = getattr(result, "id", "unknown")
        raise ScanError(f"run failed: {run_id}", exit_code=2)

    return _extract_markdown(result)

This is pretty robust and the prompt it uses is really well written. (Ok, as a reminder folks, don't forget prompt writing is still important and you can cheat at that by asking your AI agent to improve your prompt before you actually run it.)

I did a quick run of this on my blog and got the following:

This is a rather simple example, but being able to use the Cursor platform in code like this could be really freaking powerful I think. If you've done something like this, I'd love to hear more, share a comment below. You can check out the full code here: https://github.com/cfjedimaster/cursor_python_sdk_cli_demo