Raymond Camden

Generating PDF Invoices from Word Templates with officeParser

2026-10-27T18:00:00+00:00

Last week I shared a demo ("Generating PDFs from Word Templates with officeParser") that made use of the awesome officeParser open source library. That demo was a simple "customer report" web app that took custom data and a Word template. Once the form was submitted, the library converted tokens in the Word template to real data and output a PDF. I decided to build another demo using the library, this time on the server with a simple Node.js script.

As I mentioned previously, this new feature mimics Adobe's Document Generation API. At the time I wrote my blog post, the library just supported simple transformations. So given `` in your Word template, if you passed a name value of 'Ray', you would see that in the resulting PDF.

Now the library's been updated to support:

Conditional logic
Looping
Formatting of values

Basically, and no shade to Adobe (not that I think they care), this open source library replicates the most of the same functionality, on your server, for free.

Given these new features, I thought a simple "data invoicing system" would be a good demo. The idea being:

You have data for invoices, usually in a database, but for me, just a JSON file.
You have a Word template for the invoice.
A script combines this together and spits out PDFs.

The first thing I built was the Word template. I used one of the built-in Word templates and modified it a bit. The screenshot below is from Word's online viewer which frankly looks pretty jank. In my desktop Word it looked a lot better:

In this template you can see the simple tokens but also an example of looping in the table using for line in lineItems. Also note the formatting on the dollar amounts. I could have found a way to get conditionals in, but figured this was interesting enough.

My raw data is just JSON. Here's part of the file:

{
  "invoices": [
    {
      "invoiceNumber": 100,
      "name": "Ada Lovelace",
      "email": "ada@example.com",
      "lineItems": [
        {
          "description": "Consulting",
          "quantity": 3,
          "unitCost": 150
        },
        {
          "description": "Travel expenses",
          "quantity": 1,
          "unitCost": 48.75
        }
      ]
    },
    {
      "invoiceNumber": 101,
      "name": "Grace Hopper",
      "email": "grace@example.com",
      "lineItems": [
        {
          "description": "Database review",
          "quantity": 2,
          "unitCost": 225
        }
      ]
    },
    {
      "invoiceNumber": 102,
      "name": "Katherine Johnson",
      "email": "katherine@example.com",
      "lineItems": [
        {
          "description": "Orbital trajectory analysis",
          "quantity": 2,
          "unitCost": 310
        },
        {
          "description": "Technical review",
          "quantity": 3,
          "unitCost": 85.5
        },
        {
          "description": "Project meeting",
          "quantity": 1,
          "unitCost": 120
        }
      ]
    },
    {
      "invoiceNumber": 103,
      "name": "Alan Turing",
      "email": "alan@example.com",
      "lineItems": [
        {
          "description": "Systems consulting",
          "quantity": 4,
          "unitCost": 175
        },
        {
          "description": "Prototype review",
          "quantity": 2,
          "unitCost": 240
        },
        {
          "description": "Documentation",
          "quantity": 6,
          "unitCost": 42.5
        },
        {
          "description": "Materials",
          "quantity": 1,
          "unitCost": 63.25
        }
      ]
    }
  ]
}

And finally, here's the script that does the processing:

const { readFile, mkdir, writeFile } = require('node:fs/promises')
const path = require('node:path')
const { OfficeConverter, OfficeTemplate } = require('officeparser')

function isRecord(value) {
  return value !== null && typeof value === 'object' && !Array.isArray(value)
}

function requireText(value, label) {
  if (typeof value !== 'string' || value.trim() === '') {
    throw new Error(`${label} must be a non-empty string.`)
  }

  return value.trim()
}

function toCents(value, label) {
  if (typeof value !== 'number' || !Number.isFinite(value) || value < 0) {
    throw new Error(`${label} must be a non-negative number.`)
  }

  const cents = Math.round((value + Number.EPSILON) * 100)
  if (!Number.isSafeInteger(cents)) {
    throw new Error(`${label} is too large to represent as currency.`)
  }

  return cents
}

function buildInvoiceData(json, issuedOn = new Date()) {
  if (!isRecord(json) || !Array.isArray(json.invoices) || json.invoices.length === 0) {
    throw new Error('The JSON file must contain a non-empty "invoices" array.')
  }

  const invoiceDate = [
    issuedOn.getFullYear(),
    String(issuedOn.getMonth() + 1).padStart(2, '0'),
    String(issuedOn.getDate()).padStart(2, '0'),
  ].join('-')

  return json.invoices.map((invoice, invoiceIndex) => {
    const invoiceLabel = `Invoice ${invoiceIndex + 1}`
    if (!isRecord(invoice)) {
      throw new Error(`${invoiceLabel} must be an object.`)
    }

    if (!Number.isSafeInteger(invoice.invoiceNumber) || invoice.invoiceNumber <= 0) {
      throw new Error(`${invoiceLabel} invoiceNumber must be a positive whole number.`)
    }

    const recipientName = requireText(invoice.name, `${invoiceLabel} name`)
    const recipientEmail = requireText(invoice.email, `${invoiceLabel} email`)
    if (!/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(recipientEmail)) {
      throw new Error(`${invoiceLabel} email must be a valid email address.`)
    }
    if (!Array.isArray(invoice.lineItems) || invoice.lineItems.length === 0) {
      throw new Error(`${invoiceLabel} must contain at least one line item.`)
    }

    let subtotalCents = 0
    const lineItems = invoice.lineItems.map((item, itemIndex) => {
      const itemLabel = `${invoiceLabel} line item ${itemIndex + 1}`
      if (!isRecord(item)) {
        throw new Error(`${itemLabel} must be an object.`)
      }

      const description = requireText(item.description, `${itemLabel} description`)
      if (!Number.isSafeInteger(item.quantity) || item.quantity <= 0) {
        throw new Error(`${itemLabel} quantity must be a positive whole number.`)
      }

      const unitCostCents = toCents(item.unitCost, `${itemLabel} unitCost`)
      const lineTotalCents = unitCostCents * item.quantity
      if (!Number.isSafeInteger(lineTotalCents) || !Number.isSafeInteger(subtotalCents + lineTotalCents)) {
        throw new Error(`${itemLabel} total is too large to represent as currency.`)
      }
      subtotalCents += lineTotalCents

      return {
        description,
        quantity: item.quantity,
        unitCost: unitCostCents / 100,
        total: lineTotalCents / 100,
        lineTotal: lineTotalCents / 100,
      }
    })

    const invoiceNumber = String(invoice.invoiceNumber)
    const salesTaxCents = Math.round(subtotalCents / 20)
    const totalCents = subtotalCents + salesTaxCents
    if (!Number.isSafeInteger(totalCents)) {
      throw new Error(`${invoiceLabel} total due is too large to represent as currency.`)
    }

    return {
      invoiceNumber,
      invoiceDate,
      recipientName,
      recipientEmail,
      lineItems,
      subtotal: subtotalCents / 100,
      salesTax: salesTaxCents / 100,
      total: totalCents / 100,
    }
  })
}

function makeFilename(invoice) {
  const customerSlug = invoice.recipientName
    .normalize('NFKD')
    .replace(/[\u0300-\u036f]/g, '')
    .replace(/[^a-z0-9]+/gi, '-')
    .replace(/^-|-$/g, '')
    .toLowerCase() || 'customer'

  return `${invoice.invoiceNumber.toLowerCase()}-${customerSlug}.pdf`
}

async function generateInvoices(inputPath, outputPath, templatePath) {
  const input = JSON.parse(await readFile(inputPath, 'utf8'))
  const invoices = buildInvoiceData(input)
  const template = await readFile(templatePath)

  await mkdir(outputPath, { recursive: true })

  const renderedDocuments = await OfficeTemplate.render(template, {
    data: invoices,
    onMissing: 'error',
  })
  if (!Array.isArray(renderedDocuments) || renderedDocuments.length !== invoices.length) {
    throw new Error('officeparser did not return one rendered document per invoice.')
  }

  for (const [index, invoice] of invoices.entries()) {
    const renderedDocx = renderedDocuments[index]
    if (!(renderedDocx instanceof Uint8Array)) {
      throw new Error(`officeparser did not return a rendered document for ${invoice.invoiceNumber}.`)
    }

    const { value: pdfBytes } = await OfficeConverter.convert(renderedDocx, 'pdf', {
      generatorConfig: {
        pdfConfig: { engine: 'native' },
      },
    })

    if (!(pdfBytes instanceof Uint8Array)) {
      throw new Error(`officeparser did not return PDF data for ${invoice.invoiceNumber}.`)
    }

    const outputFile = path.join(outputPath, makeFilename(invoice))
    await writeFile(outputFile, pdfBytes)
    console.log(`Created ${outputFile}`)
  }
}

async function main(args) {
  if (args[0] === '--help' || args[0] === '-h') {
    console.log('Usage: node script.js [invoices.json] [output-directory]')
    return
  }
  if (args.length > 2) {
    throw new Error('Usage: node script.js [invoices.json] [output-directory]')
  }

  const inputPath = args[0]
    ? path.resolve(args[0])
    : path.join(__dirname, 'invoices.json')
  const outputPath = args[1]
    ? path.resolve(args[1])
    : path.join(__dirname, 'output')
  const templatePath = path.join(__dirname, 'invoiceTemplate.docx')

  await generateInvoices(inputPath, outputPath, templatePath)
}

if (require.main === module) {
  main(process.argv.slice(2)).catch((error) => {
    console.error('Invoice generation failed:', error)
    process.exitCode = 1
  })
}

module.exports = { buildInvoiceData, generateInvoices, makeFilename }

It can be run at the CLI and takes arguments for where the data is and where to write it out - along with basic defaults for each. buildInvoiceData does the job of mapping the 'raw' data to what I need for the operation. This is something I did with Adobe's APIs as well. Rarely was the source data in a shape that mapped directly to the Word template, so a bit of shaping handles that transformation.

The officeParser library part is here:

const renderedDocuments = await OfficeTemplate.render(template, {
	data: invoices,
	onMissing: 'error',
})

That second arg is interesting. If the Word template references a value you don't pass, you can have the library simply ignore it, or throw an error. I like throwing an error as it makes it obvious when you've screwed something up.

After the conversion is done, the bits are all saved out to PDFs using the invoice number and name of the person getting the invoice.

There's a bit more to the script above, but the gist is - read the data, shape it, pass it along with the template, save the result.

Here's an example of how one looks:

Pretty cool, right? I mean, we all agree, PDFs are REALLY COOL! Anyway, you can grab all the bits, along with the Word template and sample output here: https://github.com/cfjedimaster/webdemos/tree/master/officeparser/invoice

Building the Unicorn-themed app of my dreams with TinyJS

2026-10-23T18:00:00+00:00

Everyone likes to talk about light versus dark theme while no one is addressing the real need for our users - a proper unicorn theme. I mean, take a look at this beauty:

This is Uninote, a desktop note taking application that - well - takes notes. You create notebooks, write notes, and that's it. No AI features. Nothing complex, just a note taking app. I've had a love/hate relationship with these apps for years. I was a huge Evernote fan until it went to poo. I currently use OneNote and... it's ok but I wish it was better. And yes, before folks chime in with suggestions, I'm aware I've got choices, but I "share" note access with my wife so one of the caveats is that I need an app she's comfortable with and I can deal with as well.

That being said - TinyJS is a cool as hell platform to build desktop apps and I thought I'd try building a basic note application with it. You can peruse all the code you want, and if you clone the repo and use the CLI, run a build yourself (I don't have any plans to release a "real" app - maybe) if you want to see it in action. Most of it is "just" HTML, CSS, and JavaScript, so let me share some of the more interesting tidbits.

Design

Before getting into the code, let me talk about the design. I began in Claude and used this prompt:

im building a simple desktop app with TinyJS that is a note taking application, 
like Evernote and OneNote. the app will be called Uninote, and is unicorn 
themed. functionality is pretty simple - you have notebooks that have a name, 
you can add, edit, and remove notebooks. notebooks have notes with a title, 
last edited value, and just a block of text (no support for binary data). it 
should support light/dark mode

can you give me 3 mocks for this - images only if you can, no HTML. as i said, 
its unicorn themed so it should slick, but cute

Let me just say - I greatly appreciate AI tools that can deal with my typos. Claude did a pretty good job with the three mocks it created, but the design you see above was a clear favorite for me. While I love the light version, the dark version is pretty great as well:

This blew away most of my daily Claude usage however, so I took it to Copilot in Visual Studio Code to convert the mock to HTML. I forgot to tell it to ignore the desktop UI (ie OSX app frame stuff) so I had to ask it to do that as a followup, but it worked well.

This was done in a new app scaffolded by the TinyJS CLI. As I mentioned in my first post, you can scaffold an app with Alpine and TypeScript, and Copilot had no issues going from mock to layout with that setup. From there, I basically "rolled back" the mock data into Alpine directives. So for example, my mock had a list of notebooks that I was able to convert to a proper list in Alpine based on data.

Code

So most of this is vanilla Alpine type stuff, where the interesting bit comes in is the persistence, which uses SQLite. SQLite access is provided in the "backend" code. You begin with one import:

import { Database } from 'tjs:sqlite';

And then handle your database initialization. For me it looks like so:

let db = null;

export const api = {
  initDB: async () => {
    db.exec(`
CREATE TABLE IF NOT EXISTS notebooks (
  id INTEGER PRIMARY KEY AUTOINCREMENT,
  name TEXT NOT NULL
);      
     `);

    db.exec(`
CREATE TABLE IF NOT EXISTS notes (
  id INTEGER PRIMARY KEY AUTOINCREMENT,
  title TEXT NOT NULL,
  content TEXT NOT NULL,
  notebook_id INTEGER NOT NULL,
  created DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
  updated DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
  FOREIGN KEY (notebook_id) REFERENCES notebooks(id) ON DELETE CASCADE
);      
     `);
    db.exec('PRAGMA foreign_keys = ON');

    return true;
  },
  // more stuff
}

My database is two simple tables - one for notebooks and one for notes. TinyJS takes any method defined in the api export and lets you call it from the client. So in my Alpine startup I've got:

async init() {
    await tiny.api.call('initDB')
    // more stuff
}

The rest of the 'CRUD' (Creating, Reading, Updating, Deleting), are just more DB calls. On the front end, I gather the data, pass it to the backend via tiny.api.call, and write the SQL back there.

So for example, to just get a list of notebooks:

// in the front end
this.notebooks = await tiny.api.call('getNotebooks')

And:

getNotebooks: async () => {
if (!db) throw new Error('Database not initialized. Call initDB first.');
return db.prepare(`
    SELECT notebooks.id, notebooks.name, COUNT(notes.id) AS noteCount
    FROM notebooks LEFT JOIN notes ON notes.notebook_id = notebooks.id
    GROUP BY notebooks.id ORDER BY notebooks.id
`).all();
},

That's basically it. Let me share two more little TinyJS bits. To copy to the clipboard, I did not use the usual web platform way, but rather:

await tiny.clipboard.write({ text: `${note.title}\n\n${note.content}` })

I'm not sure what that offers in contrast to the Clipboard API and will find some time to figure that out.

The second is a small thing, but super useful. Your TinyJS app has a 'controller' JSON file that lets you set a heck of a lot of properties. One of those is the window size:

"size": "960x640",

But out of the box, you can set a default size and have the app automatically remember the window size and position:

"size": "960x640",
"rememberWindows": true,

I was convinced I was going to need a "listen for window resize and persist" type logic but nope - one line in JSON. Perfect.

Photo by Annie Spratt on Unsplash

Adding a PDF Display to Eleventy

2026-10-21T18:00:00+00:00

This will be a short one. I've talked about embedding PDFs on web pages for probably close to ten years now. Blame Adobe. Blame me being a nerd and finding this stuff interesting. Blame whoever. While I've blogged about the topic, I've also actually done that on my site here, in a variety of different ways.

A while back I realized I wasn't being consistent with how I did... "stuff" here, like call outs, Youtube links, etc. I started a guide doc so I'd have a quick way to remember what I did last time, and be more consistent.

One item on there I had left as "figure it out later" was proper PDF embedding. This week I finally nailed that down. EmbedPDF is a library I've mentioned here before so I leaned on it, and went with an incredibly simple snippet:

<div id="pdf-dis" style="width: 100%; height: 400px; margin-bottom: 30px"></div>
 
<script type="module">
import EmbedPDF, { ZoomMode } from 'https://cdn.jsdelivr.net/npm/@embedpdf/snippet@2/dist/embedpdf.js';
 
EmbedPDF.init({
	type: 'container',
	target: document.getElementById('pdf-dis'),
	src: 'https:// ....',
	theme: { preference: 'system' },
	disabledCategories: ['annotation'],
	zoom: {
		defaultZoomLevel: ZoomMode.FitWidth
	}
});
</script>

This does a few things that make sense on my blog, and may not for you. I use the ZoomMode feature to make the PDF document automatically be as wide as the container. Honestly, I don't know why this isn't the default, but given that PDFs can specify their own default view, the library may just usually let it decide. The rest of the code is pretty much vanilla from the docs.

So that's the snippet. To make it a shortcode in Eleventy, I added this to my page which defines all the shortcodes for my blog:

const embedPDF = (id, url, height="500px") => {
  return `
<div id="${id}" style="width: 100%; height: ${height}; margin-bottom: 30px"></div>
 
<script type="module">
import EmbedPDF, { ZoomMode } from 'https://cdn.jsdelivr.net/npm/@embedpdf/snippet@2/dist/embedpdf.js';
 
EmbedPDF.init({
	type: 'container',
	target: document.getElementById('${id}'),
	src: '${url}',
	theme: { preference: 'system' },
	disabledCategories: ['annotation'],
	zoom: {
		defaultZoomLevel: ZoomMode.FitWidth
	}
});
</script>
  `;
};

This gets loaded by my Eleventy config script and inside a post, I can:

{% embedPDF "pdf-viewer-1", "https://static.raymondcamden.com/assets/document.pdf" %}

Which gives you:

I found this useful, and I hope you do too.

Links For You (10/19/26)

2026-10-19T18:00:00+00:00

Wowza - I'm like nearly a month late on this. This is where I'd try to come up with a good excuse, but I think if I just randomly point around at things and said... "life" most of you would completely understand where I'm coming from. It's been a difficult few months for myself, and for nearly every person I know. This week I'm going to try focus on the positive and the things that make me smile, and I hope all my lovely readers can do the same!

Make Music, Not War

First up is the appropriately named Hyperblam, a music making tool that lets you use a declarative language to create sick beats as the kids say. What does that look like? Here's one example:

<!-- bus! (master signal chain) -->
<chain-blam id="bus">
<gain-blam id="bits" gain="0.25" bypass>
    <lfo-blam type="square" beats="0.001" prop="gain" gain="0.25">
    <blam-blam from="#kick" prop="beats" value="0.001~0.003" chance="0.3"></blam-blam>
    </lfo-blam>
</gain-blam>
<phaser-blam id="swoosh" center="6000" depth="4000" q="0.5" bypass></phaser-blam>
<analyser-blam id="analyser" smoothing="0.6"></analyser-blam>
</chain-blam>

And you can play the song this is a part of here:

See the Pen HYPERBLAM (HELLO HYPERBLAM) by Heydon (@heydon) on CodePen.

This UI library will make you jelly...

Jelly as in jealous - and again - that's what the kids say, right? Jelly UI is a UI web component library for "jelly" type interfaces. Think fat, but soft, bright colors and such. I love web components for libraries like this, and this one is on my list to try soon in a demo.

I copied a few samples from their docs and threw it in a CodePen:

See the Pen Jelly UI by Raymond Camden (@cfjedimaster) on CodePen.

Your new RSS Feed Reader

Last but definitely not least is an incredible new product from my buddy Robert - Feedhouse is an RSS reader, but with so many features it goes far beyond just RSS parsing. It has great social aspects (you can mark up and comment on items in your feed, you can share collections of feeds), it supports sites without RSS feeds, it lets you sign up for newsletters with a custom address and automatically parse the items into your feed, and so much more. If you want to learn more about how it's built, Robert wrote up a great post on it: Everything Feedhouse Does, From the Boring Parts Up.

Just For Fun

My readers know I'm a huge fan of covers and imagine my surprise when I discovered this one by School of Seven Bells... enjoy!

Generating PDFs from Word Templates with officeParser

2026-10-17T18:00:00+00:00

I've been singing the praises of the officeParser library for a while. It's an open source JavaScript library that can parse, extract, and convert between PDFs and Office documents, as well as OpenOffice, ePub and more. My demos have all focused on client-side examples but obviously the library would work great in a server side workflow as well. I haven't worked at Adobe for years now, but I still get strangely excited working with documents. I'll just add that to the long list of reasons I'm a big nerd.

A few weeks ago, I reached out to Harsh Ankur about an idea inspired by Adobe's Document Generation API. This was probably my favorite API in their suite of PDF services. You take a Word document, put in tokens, and call the API with your data. The API would swap out the tokens with real data and give you a PDF in return. (Or Word again if you wanted that.) I suggested this to Harsh and then - voila - he added it!

At this time, the token system is simply a replacement system. You add My name is in your Word document, and if you pass { "name":"Juniper Montage"} via the library's APIs you'll get My name is Juniper Montage on the way out.

This new support is a core API, OfficeTemplate, and supports both replacing values from a regular JavaScript object or returning an array of results from a JavaScript array of objects. (Which, by the way, is something I was trying to get Adobe to add to their APIs. One of their competitors, DocuGenerate, has had this for a while.)

Here's how simple it is to use. First, create and save a Word document. Formatting doesn't matter - make it as pretty or simple as you would like. Here's an example with a few tokens:

Imagine this is stored as customerReport.docx. To turn this into a PDF, you would first import the relevant libraries (in the sample below I'm using an npm installed version, not CDN):

import { OfficeConverter, OfficeTemplate } from 'officeparser/browser-native-pdf'

Then - grab the Word document as binary data:

const response = await fetch('/assets/customerReport.docx')
const template = new Uint8Array(await response.arrayBuffer())

Get some sample data:

const data = {
  customerName: 'Northwind & Co',
  date: '2026-10-16',
  productsTotal: 7,
  reportYear: 2026,
  profit: 2500,
  losses: 125,
  recommendation: 'Continue growing. Duh',
  reporter: 'Juniper Montage',
}

Next, use the library to convert the template:

const docx = await OfficeTemplate.render(template, { data })

Finally, turn the rendered document into a PDF. The result's value is the PDF's binary data:

const { value: pdfBytes } = await OfficeConverter.convert(docx, 'pdf', {
  generatorConfig: { pdfConfig: { engine: 'native' } },
})

At this point you can do whatever, like open it in a new tab:

const pdf = new Blob([pdfBytes], { type: 'application/pdf' })
window.open(URL.createObjectURL(pdf), '_blank')

As a note, this requires an additional package, only in the browser, pdf-lib.

A Real Demo

To show this in action, I built a simple demo that lets you fill in a form, and get the result as a PDF.

This form is tied to a bit of JavaScript that grabs the values, makes use of Intl to format dates, numbers, and currencies, and then uses officeParser to create a dynamic PDF from your values. Here's an example:

Try this yourself here: https://cfjedimaster.github.io/webdemos/officeparser/wordtemplate/dist/index.html

You can find the complete source for this here: https://github.com/cfjedimaster/webdemos/tree/master/officeparser/wordtemplate

As I mentioned above, currently the token system is relatively simple, but I've been talking with Harsh about some improvements that I bet will land pretty soon. Let me know what you think!

Adding Google Auth to TinyJS

2026-10-12T18:00:00+00:00

A few days ago I posted about my experience playing around with TinyJS. This is a very light "web to desktop app" platform for - well - building desktop apps. Its simplicity and similarity to PhoneGap (at least for the desktop) has got me interested in seeing what I can build with the project. One of my ideas would be improved with a login system so I naturally looked into adding a "Login with Google" feature. While this was mostly straightforward, I ran into some oddities and figured I'd share it here.

I went into this exploration with a basic idea of how I'd approach it:

Create an app in the Google Cloud console to represent my app, getting the client id and secret.
Generate a link using the standard OAuth flow
For my redirect URL, use a custom URI scheme (like mycustomapp://) so that on redirect from Google, it would open the app automatically
The response would include the code I'd exchange for an access token (and refresh token), at which point I could get the user's profile and have their name and email address. I'm only thinking of that as my mental model for this little POC is just login, not using other Google services.

Right away I hit a couple of snags.

Google's OAuth flow specifically blocks the use of a custom URI scheme. Instead, you need to hit a locally running web server which would handle getting and verifying the code. I've actually seen this before, you end up with a new tab in your browser that says you can close the tab, but I had never implemented it before.
The next bit isn't a snag per se, but in my research, I found that in most places, your desktop app can include just the client id, but for Google, you must include the secret as well. Obviously that makes me nervous as heck, but again, this is apparently a well known thing for desktop apps that authenticate with Google. While I don't feel 100% certain about this, I asked multiple agents, Googled, and so forth, and they all seemed to be in agreement. Absolutely correct me in a comment below if I'm wrong.

Alright, so with all of that in mind - I want to once again thank the author of the program for pointing me to the platter demo which implements the local web server mentioned above. I was able to point my coding agent to that when working through the demo.

I have not put my code into a GitHub repo, but will include everything below. As this was just a POC I didn't feel like it was necessary, but if you want a zip, just ask. Nicely. Or not. I'll still send it.

The Code

Ok, let me start with the simplest part, the HTML. I'm not using Alpine for this, or any real CSS. It's just this:

<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8">
<title>__NAME__</title>
<link rel="stylesheet" href="style.css">
</head>
<body>

<main>
  <h1>Google sign-in Test</h1>
  <a id="login-link" href="#">Login with Google</a>
  <section id="profile" aria-live="polite" hidden>
    <h2>Signed in</h2>
    <p><strong>Name:</strong> <span id="profile-name"></span></p>
    <p><strong>Email:</strong> <span id="profile-email"></span></p>
  </section>
  <p id="login-error" role="alert" hidden></p>
</main>

<script src="app.js"></script>
</body>
</html>

I've got a login link (blank, that gets filled in later), a section that's displayed when you are logged in, and a block for errors. The login link should be hidden as well (I'll explain why later), but again I was trying to keep this simple.

Now let's look at the JavaScript, and this is a bit of a mess. With a proper framework like Alpine it would be better organized, but it gets the job done.

const CLIENT_ID = "safe but why not be sure";

const REDIRECT_URI = "http://127.0.0.1:8765/callback";
const TOKENS_KEY = "google-oauth-tokens";

async function makeLoginUrl() {
  const b64url = (buf) =>
    btoa(String.fromCharCode(...new Uint8Array(buf)))
      .replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");

  const verifier = b64url(crypto.getRandomValues(new Uint8Array(32)));
  const challenge = b64url(
    await crypto.subtle.digest("SHA-256", new TextEncoder().encode(verifier))
  );
  const state = b64url(crypto.getRandomValues(new Uint8Array(16)));

  // keep these for the token exchange step
  sessionStorage.setItem("pkce_verifier", verifier);
  sessionStorage.setItem("oauth_state", state);

  const params = new URLSearchParams({
    client_id: CLIENT_ID,
    redirect_uri: REDIRECT_URI,
    response_type: "code",
    scope: "openid email profile",
    access_type: "offline",
    prompt: "consent",
    code_challenge: challenge,
    code_challenge_method: "S256",
    state,
  });

  return `https://accounts.google.com/o/oauth2/v2/auth?${params}`;
}

document.addEventListener("DOMContentLoaded", async () => {
  const loginLink = document.querySelector("#login-link");

  try {
    const savedTokens = await tiny.app.secrets.get(TOKENS_KEY);
    if (savedTokens) {
      try {
        const session = await tiny.api.call("restoreSession", {
          tokens: JSON.parse(savedTokens),
          clientId: CLIENT_ID,
        });
        await tiny.app.secrets.set(TOKENS_KEY, JSON.stringify(session.tokens));
        showProfile(session.profile);
        return;
      } catch {
        await tiny.app.secrets.delete(TOKENS_KEY);
      }
    }
    await prepareLogin(loginLink);
  } catch (error) {
    showError(`Google sign-in failed: ${error.message}`);
  }
});

async function prepareLogin(loginLink) {
  const url = await makeLoginUrl();
  const state = sessionStorage.getItem("oauth_state");
  const codeVerifier = sessionStorage.getItem("pkce_verifier");
  loginLink.href = url;
  loginLink.target = "_blank";
  loginLink.rel = "noopener";

  loginLink.onclick = async () => {
    try {
      const session = await tiny.api.call("waitForCode", {
        port: 8765,
        state,
        codeVerifier,
        clientId: CLIENT_ID,
      });
      await tiny.app.secrets.set(TOKENS_KEY, JSON.stringify(session.tokens));
      showProfile(session.profile);
    } catch (error) {
      showError(`Google sign-in failed: ${error.message}`);
      await prepareLogin(loginLink);
    }
  };
}

function showProfile(profile) {
  document.querySelector("#profile-name").textContent = profile.name || "Not provided";
  document.querySelector("#profile-email").textContent = profile.email || "Not provided";
  document.querySelector("#profile").hidden = false;
  document.querySelector("#login-link").hidden = true;
  document.querySelector("#login-error").hidden = true;
}

function showError(message) {
  const errorOutput = document.querySelector("#login-error");
  errorOutput.textContent = message;
  errorOutput.hidden = false;
}

I start off with a utility function to generate my login link. Note that redirect URI - it's going to be hosted by my app via the backend script and makes an assumption on a port that's free. A better version would try a set of ports to see which can be used.

In my DOMContentLoaded block I've got multiple things going on.

First off - I look at a secure storage system for an existing access token. This is documented in the secrets and auth section of TinyJS's docs. If the values exist, a call to the backend is made to try to verify the values and treat the user as already logged in.

If this fails, or the values weren't there, we:

Get the login URL and update the DOM
Tell the backend to fire up the HTTP server
And then wait for a success.

The final two functions just display the profile or an error. Now let's look at the backend:

// Yes, I said it was safe, still, why share it here?
const GOOGLE_CLIENT_SECRET = "my secret brings the boys to the yard";

async function exchangeCodeForToken({ code, codeVerifier, clientId, port }) {
  const response = await fetch("https://oauth2.googleapis.com/token", {
    method: "POST",
    headers: {
      "content-type": "application/x-www-form-urlencoded",
    },
    body: new URLSearchParams({
      code,
      client_id: clientId,
      client_secret: GOOGLE_CLIENT_SECRET,
      redirect_uri: `http://127.0.0.1:${port}/callback`,
      grant_type: "authorization_code",
      code_verifier: codeVerifier,
    }),
  });
  const tokens = await response.json();
  if (!response.ok || tokens.error) {
    throw new Error(tokens.error_description || tokens.error || `Token request failed (${response.status}).`);
  }
  return tokens;
}

async function refreshAccessToken(refreshToken, clientId) {
  const response = await fetch("https://oauth2.googleapis.com/token", {
    method: "POST",
    headers: {
      "content-type": "application/x-www-form-urlencoded",
    },
    body: new URLSearchParams({
      client_id: clientId,
      client_secret: GOOGLE_CLIENT_SECRET,
      refresh_token: refreshToken,
      grant_type: "refresh_token",
    }),
  });
  const tokens = await response.json();
  if (!response.ok || tokens.error) {
    throw new Error(tokens.error_description || tokens.error || `Token refresh failed (${response.status}).`);
  }
  return tokens;
}

function expiresAt(tokens) {
  const expiresIn = Number(tokens.expires_in);
  if (!tokens.access_token || !Number.isFinite(expiresIn) || expiresIn <= 0) {
    throw new Error("Google returned an invalid access token response.");
  }
  return Date.now() + expiresIn * 1000;
}

async function getUserProfile(accessToken) {
  const response = await fetch("https://openidconnect.googleapis.com/v1/userinfo", {
    headers: {
      authorization: `Bearer ${accessToken}`,
    },
  });
  const profile = await response.json();
  if (!response.ok) {
    throw new Error(profile.error_description || profile.error || `Profile request failed (${response.status}).`);
  }
  return {
    name: profile.name || "",
    email: profile.email || "",
  };
}

async function restoreSession(tokens, clientId) {
  if (!tokens?.access_token || !tokens?.refresh_token || !tokens?.expires_at) {
    throw new Error("Saved sign-in is incomplete.");
  }

  let refreshedTokens = {};
  if (tokens.expires_at <= Date.now() + 60000) {
    refreshedTokens = await refreshAccessToken(tokens.refresh_token, clientId);
  }

  const updatedTokens = {
    access_token: refreshedTokens.access_token || tokens.access_token,
    refresh_token: refreshedTokens.refresh_token || tokens.refresh_token,
    expires_at: refreshedTokens.access_token
      ? expiresAt(refreshedTokens)
      : tokens.expires_at,
  };
  const profile = await getUserProfile(updatedTokens.access_token);
  return { profile, tokens: updatedTokens };
}

async function waitForCode(port, expectedState, codeVerifier, clientId) {
  return new Promise((resolve, reject) => {
    let server;
    let timer;
    let settled = false;
    let processing = false;

    const stopServer = () => {
      if (timer) clearTimeout(timer);
      if (!server) return;
      const activeServer = server;
      server = null;
      try {
        activeServer.close();
      } catch (error) {
        console.error("Failed to close OAuth callback server:", error);
      }
    };

    const finish = (error, code, closeImmediately = false) => {
      if (settled) return;
      settled = true;
      if (timer) clearTimeout(timer);
      if (closeImmediately) stopServer();
      else setTimeout(stopServer, 1000);
      if (error) reject(error);
      else resolve(code);
    };

    const escapeHtml = (value) => String(value)
      .replace(/&/g, "&amp;")
      .replace(/</g, "&lt;")
      .replace(/>/g, "&gt;")
      .replace(/"/g, "&quot;")
      .replace(/'/g, "&#39;");
    const htmlResponse = (message, status = 200) => new Response(
      `<html><body><h3>${escapeHtml(message)}</h3></body></html>`,
      {
        status,
        headers: {
          "content-type": "text/html; charset=utf-8",
          "content-security-policy": "default-src 'none'; style-src 'unsafe-inline'",
        },
      }
    );

    server = tjs.serve({
      port,
      fetch: async (request) => {
        let url;
        try {
          url = new URL(request.url);
        } catch {
          return htmlResponse("Invalid callback request.", 400);
        }

        if (url.pathname !== "/callback") return htmlResponse("Not found.", 404);
        if (settled) return htmlResponse("This login request has already been processed.", 410);
        if (processing) return htmlResponse("This login request is being processed.", 409);
        if (url.searchParams.get("state") !== expectedState) {
          return htmlResponse("State mismatch. Return to the app and try again.", 400);
        }

        const oauthError = url.searchParams.get("error");
        if (oauthError) {
          finish(new Error(oauthError));
          return htmlResponse("Login failed: " + oauthError);
        }

        const code = url.searchParams.get("code");
        if (!code) {
          finish(new Error("OAuth callback did not include an authorization code."));
          return htmlResponse("Login failed: authorization code was missing.", 400);
        }

        processing = true;
        try {
          const tokens = await exchangeCodeForToken({
            code,
            codeVerifier,
            clientId,
            port,
          });
          const profile = await getUserProfile(tokens.access_token);
          finish(null, {
            profile,
            tokens: {
              access_token: tokens.access_token,
              refresh_token: tokens.refresh_token,
              expires_at: expiresAt(tokens),
            },
          });
          return htmlResponse("Login complete. You can close this tab.");
        } catch (error) {
          finish(error);
          return htmlResponse("Token exchange failed: " + error.message, 502);
        }
      },
    });

    timer = setTimeout(() => {
      finish(new Error("Timed out waiting for the OAuth callback."), null, true);
    }, 120000);
  });
}

export const api = {
  restoreSession: ({ tokens, clientId }) => {
    if (!clientId) throw new Error("Google client ID is required.");
    return restoreSession(tokens, clientId);
  },
  waitForCode: ({ port, state, codeVerifier, clientId }) => {
    if (!codeVerifier || !clientId) {
      throw new Error("OAuth code verifier and client ID are required.");
    }
    return waitForCode(port, state, codeVerifier, clientId);
  },
};

This one's a bit of a beast, but some are fairly standard. Both exchangeCodeForToken and refreshAccessToken are standard OAuth stuff. Ditto for getUserProfile. The important bit is waitForCode. This is where the small web server is kicked off that attempts to handle the redirect back from Google. I said up front I used AI to build most of this and I have to be honest, I'm glad I did as this part would have taken me quite some time.

All in all - it works great. The only real issue is a nit-picky one - when the app loads you see the login link for a second before the stored auth is verified. A bit of UX magic there would handle that.

There's an important part left out of this that I'll need to tackle next - which is how I would take the verified identity here and pass it to a remote service in a secure way such that the remote service can also verify it ("Yes, this was Raymond Camden") before performing an action.

Tiny Apps with TinyJS

2026-10-08T18:00:00+00:00

About a year ago, I was still running my live stream (Code Break) and my final three streams all covered one topic - building desktop applications with non-native code. I covered Tauri (HTML on the front, Rust on the back) and Flet (all Python). Recently I came across another option, tinyjs.

TinyJS (technically the name is "tinyjs" but I can't make myself use the lowercase in my writing like that ;) is a lot like PhoneGap/Apache Cordova. Your application is the system web view shipped along with the ability to make system calls via a bridge to txiki.js. This bridge gives you full access to the file system and more, like any other native app.

Unlike PhoneGap, this is just for desktop apps, which is fine, but I think the biggest selling point is the size of the bundled app - typically around 6 megs. That's tiny versus something like Electron.

It's got hooks into everything a desktop app could need, like native dialogs and OS menus and such. It can write securely to the OS's credential store, use SQLite, and even handle application updating.

I've just begun playing with it recently and I've got a few ideas for apps I want to build, but I thought I'd share a quick demo. This one's a bit ugly, and to be clear, that's on me. As it's a web view, you've got full control over how the end result looks. I was just going for something quick and dirty in my test.

First Steps

After doing a quick install, you can scaffold at the command line with:

tinyjs new appname

By default this scaffolds out a vanilla application (no React default, woot!) with a few files and folders - the important ones (at least initially while testing and learning) are:

frontend - the UI/UX layer (HTML, CSS, JS)
main.js - a "backend" file that lets you build services you expose to your front end code. This is where you do "system" stuff your frontend JavaScript can't do.

As an example, your backend code could use this:

export const api: Record<string, TinyApiHandler> = {
  hello: async ({ name }: { name: string }) => 'hi ' + name + ' — from the backend',
};

Which would then be available in the frontend as await tiny.api.call('hello', {...}).

Running the app is done via tinyjs dev which will load the app and enable HMR. In my testing, reloading was incredibly quick, but I didn't build anything large (yet).

Working with Alpine

The CLI has got a number of different scaffolds you can use, including Alpine. (And I should say - huge thanks to tarwin, the creator - who answered a lot of my questions via email and added stuff I asked for left and right!) I scaffolded one like that and one thing I'll note - the scaffold for different frameworks will differ a bit from the simple app you get by default. Each project has a tinyjs.json file which has metadata for the project, including where your backend file is and how the frontend works.

For my simple test, I wanted to check a few things. First, is CORS still enforced when using fetch? The short answer is yes, it is. The longer answer is that doesn't matter as you can use tiny.fetch instead. I thought it would be fun then to build a simple "RSS to HTML" application where I could enter an RSS feed and render the items.

I copied the browser distributable for the rss-parser project and simply included it in my HTML via a script tag. Here's the entirety of that file:

<!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>RSS Parser</title>
  </head>
  <body>
    <section id="center" x-data="hello">
      <h1>RSS Parser</h1>
      <input x-model="url" placeholder="RSS feed URL" /> <button @click="parse">Parse</button>
      <template x-if="items.length > 0">
        <div>
        <h2>Items</h2>
        <ul>
          <template x-for="item in items" :key="item.link">
            <li>
              <a :href="item.link" target="_blank" x-text="item.title"></a>
            </li>
          </template>
        </ul>
        </div>
      </template>
    </section>
    <script src="/src/rss-parser.min.js"></script>
    <script type="module" src="/src/main.ts"></script>
  </body>
</html>

That's all regular Alpine.js stuff, nothing fancy there. Now for the JavaScript:

import './style.css';
import 'simpledotcss/simple.min.css';

import Alpine from 'alpinejs';

Alpine.data('hello', () => ({
  name: 'world',
  url: 'https://www.raymondcamden.com/feed.xml',
  items: [],
  async init() {
  },
  async parse() {
    const parser = new RSSParser();
    let req = await tiny.fetch(this.url);
    let res = await req.text();
    let feed = await parser.parseString(res);
    this.items = feed.items;
  },
  async ask() {
    // Every function in the backend's api object is callable from the page.
    this.reply = await tiny.api.call('hello', { name: this.name })
  },
}))

Alpine.start()

A few things to note here - I've got some junk in the file still, like the ask function which was a leftover from the scaffold. The important bit is the parse function. The RSSParser object has the ability to parse a URL, but it uses fetch and is blocked by CORS. So instead I get the XML via tiny.fetch and pass it to parseString. And that's literally it. Here's a screenshot of the application running:

More Info

The docs obviously are a great place to start, and if you're curious about more of how it actually works, there's a good explanation of that as well.

My next demo is going to be testing an OAuth login flow with the application. The project supports registering custom URL schemes which is typically how that's handled so it should be possible, but I want to test it out myself of course. :)

Photo by Lukas Blazek on Unsplash

Adding My Latest CodePens to My Blog

2026-10-06T18:00:00+00:00

I've been a fan of CodePen for many, many years, and it's one of the few services I spend money on to help support. A few months back, they released an entirely new version that dramatically improved the service (CodePen 2.0) and it just made me more happy I was a supporter. Just a few days ago they announced more changes including a full API. I thought it would be fun to add a display of my recent pens. Yes, I thought that would be fun, because that's the kind of nerd I am.

Adding Dynamic Content to a SSG

It has been a very long time since I blogged about anything related to static site generators. There's no particular reason for that, but I figure this is a good time to bring up the topic again, specifically about how static sites can include dynamic content. There's two main paths to this.

The first is getting content at build time. For Eleventy, this is done with data files that are executed at build time and can return ad hoc data for use in your templates. As an example of that, the list of books I'm reading on my Now page are gathered via a GraphQL query:

const HARDCOVER_BOOKS = process.env.HARDCOVER_BOOKS;

export default async function() {

    if(process.env.SKIP_REMOTE_DATA) return [];
    if(!HARDCOVER_BOOKS) return [];
    let req;

    let body = `
    {
    user_books(
        where: {user_id: {_eq: 65213}, status_id: {_eq: 2}}
    ) {
        book {
            title
            image {
                url
            }
            contributions {
                author {
                    name
                }
            }
        }
    }
    }
    `.trim();

    try {
        req = await fetch('https://api.hardcover.app/v1/graphql', {
            method:'POST', 
            headers: {
                'authorization':HARDCOVER_BOOKS,
                'Content-Type':'application/json'
            },
            body:JSON.stringify({query:body})
        });
    } catch (e) {
        console.log('Hardcover API error', e);
        return [];
    }

    let data = (await req.json()).data.user_books.map(ob => ob.book);
    /* normalize authors */
    data = data.map(b => {
    b.authors = b.contributions.reduce((list,c) => {
        if(c.author) list.push(c.author.name);
        return list;
        },[]);
        return b;
    });

    return data;

};

The list of books returned there can then be rendered in my page template:

<div class="films">
{% for book in hardcover_books  %}
  <div class="film">
  {% if book.image != null %}
  <img src="https://res.cloudinary.com/raymondcamden/image/fetch/c_fit,w_216/{{book.image.url}}" alt="Cover of {{ book.title }}">
  {% else  %}
  <img src="https://res.cloudinary.com/raymondcamden/image/fetch/c_fit,w_216/https://static.raymondcamden.com/images/no_cover_available.jpg" alt="No Cover Available">
  {% endif %}
  "{{ book.title  }}" by {{ book.authors | join: ', ' }}
  </div>
{% endfor %}
</div>

As you can tell by the class names, I use the same logic for the films I've watched. In both cases, the data doesn't change terribly often so I'm ok with it being a bit out of date. I also publish something to the blog every week so it's never too far behind.

That's option 1. Option 2 is to use JavaScript and an API. That ensures the content is always 100% up to date but it has other trade offs. Some APIs don't have CORS support and APIs requiring keys that can't be in client-side code. In that case, I simply use a serverless function which Netlify makes pretty simple.

Getting my Pens

Ok, so given that I've decided to fetch my CodePens via JavaScript on the front-end via a serverless function, I first created a key in CodePen's settings, added to my Netlify configuration, and then wrote a quick and dirty function:

import { Context } from '@netlify/functions'

export default async (request: Request, context: Context) => {
  try {

    const CP_KEY = process.env.CODEPEN_KEY;

    const req = await fetch('https://api.codepen.io/v2/pens?sort=updated&direction=desc&access=Public&template=false&per_page=10', {
      method: 'GET',
      headers: {
        'Authorization': `Bearer ${CP_KEY}`,
        'Content-Type': 'application/json'
      }});
    
    let data = await req.json();

    // now lets do some mapping 
    data = data.map((pen: any) => {
      return {
        title: pen.title,
        url: pen.urls.editor,
        created_at: pen.created_at,
        updated_at: pen.updated_at,
        screenshot: pen.screenshot_urls.small
      }
    });

    return new Response(JSON.stringify(data), {
      headers: {
        'Content-Type': 'application/json'
      }
    })
  } catch (error) {
    return new Response(error.toString(), {
      status: 500,
    })
  }
}

I'm filtering by public pens and pens that aren't templates, sorted by last updated, and capping the list to 10. Then I map the data to a much smaller set of information as I only need part of what's returned in my front end.

Then all I needed to do was add it to my stuff page:

let $pens = document.querySelector('#pens');

let pens = await fetch('/.netlify/functions/get-codepens').then(r => r.json());

pens.forEach(p => {
	let pen = document.createElement('a');
	pen.className = 'penBox';
	pen.href = p.url;
	pen.target = '_blank';
	pen.rel = 'noopener noreferrer';

	let screenshot = document.createElement('img');
	screenshot.src = p.screenshot;
	screenshot.alt = '';
	screenshot.loading = 'lazy';

	let title = document.createElement('h3');
	title.textContent = p.title;

	pen.append(screenshot, title);
	$pens.append(pen);
});

Sweet. Of course, I think I'm the only person who visits either my stuff or now pages, but they make me happy!

A Not-So-Simple RSS App in TypeScript

2026-10-02T18:00:00+00:00

Ok, I lie, this demo is also pretty simple, but I wanted to break the pattern of the last few posts and at least pretend this example is a bit more complex. As I try to find excuses to write more TypeScript, I thought a great example of that would be a simple RSS aggregator. You hit the site, tell it the feeds you care about, and it renders a date sorted list of entries.

Because RSS typically can't be parsed in client-side JavaScript (don't know why? ask me below!) so I'd have to make use of a serverless function to proxy the calls (and at the same time, handle turning the XML into JSON).

Now, to be fair, I had built nearly the same thing back in February: Building an RSS Aggregator with Astro . This let me crib a bit of the work already done.

For this one, my stack was:

Vite for the build process
Alpine on the front end
TypeScript, as much as possible
Hosting on Netlify to make the serverless function easier to do
WebAwesome, which I've used in the previous ones, for the UI

You can test this yourself here: https://ts-rss-vite.netlify.app/. The full source is here: https://github.com/cfjedimaster/typescript-stuff/tree/main/rss-reader-1.

I figure yall have seen a few of these posts already, so let me focus on sharing the interesting stuff.

Run TypeScript Checking

I mentioned in my last post that when Vite would reload, it wasn't running the TypeScript checker. It only did this when a build was run. Enabling this checking while in dev mode took two steps.

First, simply add "strict": true, to tsconfig.json. Funny enough, in years past I can remember removing this when I was trying to get something working in a TypeScript app and I was too lazy to learn or figure it out.

Second, I had to add vite-plugin-checker to the app and modify vite.config.ts.

import { defineConfig } from 'vite';
import checker from 'vite-plugin-checker';

export default defineConfig({
  plugins: [checker({ typescript: true })],
});

This file doesn't exist by default so it was a net new file for the app. As soon as I did that, if I screwed something up on purpose (ahem, I only make mistakes on purpose), I saw errors in my terminal when Vite was running.

The Serverless Function

For the backend, I used the ntl CLI (this is Netlify's CLI tool) to scaffold a function, which helpfully includes a TypeScript option. For the most part, the code here is a simpler version of what I had done for the Astro site, specifically I didn't bother with BLOB caching. Anyway, here's that function:

import Parser from 'rss-parser';
import type { Context } from '@netlify/functions';

type FeedItem = {
  title: string;
  link: string;
  pubDate: string;
  content: string;
  feedTitle: string;
};

export default async (request: Request, context: Context) => {
  if (request.method !== 'POST') {
    return new Response('Method not allowed', {
      status: 405,
      headers: { Allow: 'POST' },
    })
  }

  try {
    const body: unknown = await request.json()
    const parser = new Parser();

    if (
      typeof body !== 'object' ||
      body === null ||
      !('feeds' in body) ||
      !Array.isArray(body.feeds)
    ) {
      return new Response('Request body must include a feeds array', {
        status: 400,
      })
    }
    console.log('Parsing feeds:', body.feeds);

    let reqs: Promise<any>[] = [];
    let items: FeedItem[] = [];

    for(const feed of body.feeds) {
      reqs.push(parser.parseURL(feed.url));
    }

    const results = await Promise.allSettled(reqs);
    for (const result of results) {
        if (result.status === 'fulfilled') {
            const feed = result.value;
            console.log(`Fetched feed: ${feed.title} with ${feed.items.length} items.`);
            let newItems:any[] = [];
            feed.items.forEach(item => {
                /*
                will use content as a grab all for different fields
                for example, netlify had summary, not content
                */
                let content = item.contentSnippet || item.summary || item.content || '';
                newItems.push({
                    title: item.title,
                    link: item.link,
                    content: content,
                    pubDate: item.pubDate,
                    feedTitle: feed.title
                });
            });

            items.push(...newItems);

        } else {
            console.error('Error fetching/parsing feed:', result.reason);
        }
    }

    // now sort items by pubDate descending
    items.sort((a, b) => new Date(b.pubDate) - new Date(a.pubDate));

    return new Response(JSON.stringify(items), {
        status: 200,
        headers: {
        "Content-Type": "application/json",
        },
    });

  } catch(e) {
    console.log(e);
    return new Response('Request body must be valid JSON', {
      status: 400,
    })
  }
}

This is all pretty simple but I liked having the ability to create a custom type for my results.

I did run into an error after I created the function - and it's one I've seen twice now. Something in what the Netlify CLI does breaks some dependencies and my app fails to run at all. I passed the error to Claude and what it said was:

The most likely cause is that adding the Netlify function pulled in an older 
typescript that's now being resolved instead of your project's version. This 
usually happens when a netlify/functions package has its own package.json, 
or when netlify-cli or the functions bundler is running an older tsc from a 
different node_modules.

Its suggested fix, npm i -D typescript@latest, was enough to correct it. I definitely won't forget this when it happens again.

What's Next?

This has been so fun, at least for me. I've got my next two ideas ready! (Well, in my head at least. ;)

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