DEV Community: Krzysztof "Chris" Radomski

Developing Payload CMS plugins

Krzysztof "Chris" Radomski — Wed, 01 Jul 2026 22:19:35 +0000

A practical guide to building, testing, and shipping Payload 3.x plugins from a real visual editor plugin.

Payload plugins look simple at first: take a config in, return a config out. That model is a gift. It means a plugin can add fields, endpoints, admin components, hooks, collections, and editor behavior from a small touch point.

The tricky part is not the plugin function itself. The tricky part is everything around it: local development, import maps, package exports, testing, HMR, and the difference between source code and the code your users install.

This article is based on lessons from building payload-visual-editor, a Payload plugin experiment for visual editing inside live previews. The repo follows the official Payload plugin template, but the most useful lessons came from the rough edges.

Start with the plugin shape

Payload plugins are config transformers. The common shape is a curried function: plugin options first, incoming Payload config second.

import type { Config, Plugin } from 'payload'

export const myPlugin =
  (pluginOptions: MyPluginConfig): Plugin =>
  (incomingConfig: Config): Config => {
    const config: Config = {
      ...incomingConfig,
      collections: [...(incomingConfig.collections || [])],
      endpoints: [...(incomingConfig.endpoints || [])],
    }

    // Extend collections, fields, endpoints, hooks, or admin config.

    if (pluginOptions.disabled) {
      return config
    }

    return config
  }

The important habit is to preserve what the app already has. Spread existing arrays. Keep existing hooks. Call an existing onInit before adding your own initialization. Treat the user app as the owner of the config.

That sounds obvious, but it is where many plugin bugs begin. A plugin should compose with the host app. It should not quietly replace parts of it.

Keep source, dev, and published output separate

In this repo, the plugin lives in three worlds.

payload-plugin-visual-editor/
|-- src/ # Plugin source
|-- dev/ # Full Payload + Next.js app for development
`-- dist/ # Compiled package output

Each world has a different job. src/ is the code you write. dev/ is a real Payload app that consumes the plugin while you build it. dist/ is the package your users install.

That separation keeps the feedback loop fast without lying about what you are shipping. During normal development, the dev app points at src/. Before publishing, the build proves that dist/ contains the files consumers will import.

Avoid a self-link dependency

One tempting local setup is to make the dev app install the plugin through a self-reference like link:.. It works locally, but it makes the package model muddy.

The cleaner approach is to let the dev app resolve the package name to source files. In the example repo, that takes three small pieces.

First, dev/tsconfig.json maps the package name and public subpaths to files under src/. Second, dev/next.config.mjs maps the same package subpaths at runtime for Next.js. Third, dev/payload.config.ts imports the plugin entry directly, because Payload’s CLI runs under Node and does not know about Next.js aliases.

import { payloadVisualEditor } from '../src/index.js'

export default buildConfig({
  plugins: [payloadVisualEditor({ collections: { posts: true } })],
})

This gives you a fast local loop. You can edit TypeScript in src/, refresh the dev app, and avoid rebuilding the package after every change. Use pnpm build when you want to validate the published artifact.

Be explicit about public entry points

A Payload plugin usually has more than one kind of code. The plugin function is server-safe config code. Admin UI components may be client components. Some admin components can be React Server Components.

Those should not all be exported through one door. The package in this repo exposes separate entry points.

{
  "exports": {
    ".": "./dist/index.js",
    "./client": "./dist/exports/client.js",
    "./rsc": "./dist/exports/rsc.js"
  }
}

The main export is for the plugin function and shared types. The /client export is for components and hooks with 'use client'. The /rsc export is for server components used in admin slots that support them.

This makes your package easier to reason about. It also helps consumers avoid accidentally pulling client-only code into server config.

Admin components are resolved by path string

Payload admin components are not usually direct imports in your config. They are identified by component paths that Payload resolves while building the admin panel. The Payload custom components docs cover the model in detail.

In a plugin, the path often points to your package name and a named export.

collection.admin.components.edit.beforeDocumentControls = [
  ...(collection.admin.components.edit.beforeDocumentControls || []),
  'payload-plugin-visual-editor/client#VisualEditorAdmin',
]

That string has to line up with your package exports.

// src/exports/client.ts
export { VisualEditorAdmin } from '../admin/VisualEditorAdmin.js'

If the string says payload-plugin-visual-editor/client#VisualEditorAdmin, then your dev aliases must also understand payload-plugin-visual-editor/client. The generated import map must understand it too. That is why import maps deserve their own workflow.

pnpm generate:types
pnpm generate:importmap

Regenerate the import map whenever you add, rename, remove, or move admin components. If an admin component stops rendering after a rename, suspect the import map first.

Configure Next.js for the dev app, not for the published package

The dev app in this repo uses @payloadcms/next/withPayload with a normal Next.js config. Because the dev app aliases the package name to src/, Next.js compiles those files as local source.

That means the dev app does not need transpilePackages for this plugin during local development. Consumers install the built package from dist/. For them, transpilePackages should be unnecessary unless you see a real parse error in a downstream Next.js app.

That distinction matters. Do not ask every consumer to carry workaround config just because your development setup needed aliases.

Cache in-memory MongoDB across HMR

The most surprising bug in this setup came from the database. For local development and tests, the repo can run with mongodb-memory-server instead of a persistent DATABASE_URL.

That is convenient, but there is a trap when Payload runs inside next dev. Next.js Hot Module Replacement can re-evaluate payload.config.ts. Turbopack can also reset module caches.

If the config creates a fresh in-memory MongoDB instance on every load, each HMR cycle gets a new empty database. Seeded content disappears. The frontend may show stale or empty state.

The fix is to cache the memory server URI on globalThis for the life of the Node process.

const globalStore = globalThis as unknown as {
  _mongoMemoryDBUri?: string
}

if (!globalStore._mongoMemoryDBUri) {
  const memoryDB = await MongoMemoryReplSet.create({
    replSet: { count: 3, dbName: 'payloadmemory' },
  })

  globalStore._mongoMemoryDBUri = `${memoryDB.getUri()}&retryWrites=true`
}

process.env.DATABASE_URL = globalStore._mongoMemoryDBUri

Use MongoMemoryReplSet, not a standalone memory server, when testing transactional behavior. MongoDB transactions require a replica set. Use a real DATABASE_URL in dev/.env when you want data to survive full process restarts.

Test at the right layer

Good plugin tests are layered. Use Vitest unit tests for pure logic in src/. Those tests should be fast and free of Payload bootstrapping when possible.

Use integration tests when you need a real Payload instance. That includes endpoints, schema transformations, hooks, and Local API behavior.

beforeAll(async () => {
  payload = await getPayload({ config })
})

afterAll(async () => {
  await payload.db.destroy()
})

Always tear down the database in afterAll. That is especially important with in-memory MongoDB and parallel test workers.

Use Playwright for behavior that depends on real browser APIs. Selection, contenteditable, live preview iframes, drag-and-drop, and focus handling are all browser problems. Do not pretend they are unit-test problems.

For this plugin, E2E tests run serially because the dev app shares an in-memory database. That tradeoff is worth it. It avoids races while testing the behavior users actually touch.

The live preview lesson

The most interesting part of this plugin is not the package setup. It is the live preview editing model.

Visual editing means touching real DOM inside a preview while Payload is also pushing document updates. That creates a sharp edge. If the user is typing inside a contenteditable region and the preview re-renders, React can wipe the DOM node.

When that happens, the cursor jumps, selection disappears, and uncommitted text can be lost. The fix is to pause preview updates while edit mode is active. Queue the latest incoming preview data, then flush it when edit mode ends.

const pendingRef = useRef<DevPost | null>(null)
const editingRef = useRef(isVisualEditing)

editingRef.current = isVisualEditing

subscribe({
  callback: (data) => {
    if (editingRef.current) {
      pendingRef.current = data
      return
    }

    setPost(data)
  },
})

useEffect(() => {
  if (!isVisualEditing && pendingRef.current) {
    setPost(pendingRef.current)
    pendingRef.current = null
  }
}, [isVisualEditing])

That pattern belongs in plugin documentation. The plugin can provide tools and conventions, but the consumer preview page still controls how live data enters React state.

Prefer field-scoped editable regions

There is another DOM lesson hiding in visual editing. Not every editable boundary feels natural.

Wrapping individual words in spans breaks native text selection. Making the entire page editable lets users delete boundaries between fields. The better compromise is to mark field-level regions.

Each editable region maps to one Payload field path. Inside that region, the browser can handle selection naturally. Outside it, the document structure remains protected.

For rich text, choose the largest valid wrapping block. Early versions matched the smallest leaf node, so each paragraph became its own editable island. That made drag selection across paragraphs awkward. It also made Cmd+A feel wrong.

Choosing the largest valid field wrapper made the rich text field behave like one editing surface. That kind of detail is easy to miss in an API design. It is painfully obvious when you test in a real browser.

Build before you publish

The publishing flow should prove that the package works as a package.

pnpm clean
pnpm build
pnpm test
pnpm check

The build should emit declarations and compiled JavaScript into dist/. The package should publish dist/, not src/ or the dev app.

Check peerDependencies before publishing. Payload belongs in peerDependencies, because the host app owns its Payload version. Your dev app can keep @payloadcms/ui, database adapters, Next.js, and test tooling in devDependencies.

Before opening a PR, I like to check this list.

pnpm build succeeds.
dist/ contains the files from the package exports map.
Types are regenerated when schema changes.
The import map is regenerated when admin components change.
Unit, integration, and E2E tests pass.
Typecheck and lint pass.
The README explains install, config, exports, and any required consumer setup.
Breaking changes are called out.
The Payload peer dependency range is intentional.

Closing thought

Payload plugins are pleasant because the core abstraction is small. Most real-world complexity comes from making that small abstraction behave well inside a full app, a dev server, a package manager, and a browser.

The best plugin setup keeps those boundaries visible. Source code is not the package. The dev app is not the consumer app. Admin component paths are not regular imports. Live preview state is not normal page state.

Once those boundaries are clear, the work gets much calmer. You can focus on the plugin behavior instead of wrestling the toolchain.

Locking down a public write endpoint on Cloudflare

Krzysztof "Chris" Radomski — Mon, 11 May 2026 21:21:25 +0000

Online scoreboard — locking down a public api endpoint.

Math4Kids is a small timed math quiz I built for fun and learning. And because this is the second time I’ve built a small game hosted on Cloudflare, I’m writing down how I handled the sensitive parts, as much for my own reference as anyone else’s..

Once you put such a public write endpoint on the internet, a few questions show up. Who can post a score? How do you stop bots from flooding the board? How honest should you be about what you can actually guarantee?

The text is divided into 3 main parts: what is implemented, what is skipped, and what I accepted.

What I was worried about

Bots spamming fake scores. Someone breaking the API with a weird payload. Leaking something embarrassing in an error message. Secret keys ending up in the client bundle. Even if this is just a playground, common sense still applies, and the lesson learned here will compound into better instincts for future projects.

What I wasn’t worried about: cryptographically proving a human sat down and played the game. Anything running in the browser can be faked. I know this. I accepted it.

The stack

Next.js (edge runtime) deployed to Cloudflare Pages via [@cloudflare/next-on-pages](http://twitter.com/cloudflare/next-on-pages). Scores live in Cloudflare D1. There’s an in-memory fallback when no D1 binding is present, so plain next dev still works.

All the security logic sits in two route handlers: GET/POST /api/scores and POST /api/session.

Layer 1: Route handler hygiene

The boring stuff first.

SQL is parameterized via prepare().bind(), so usernames never get concatenated into a query string. Request bodies over 8 KB get rejected with HTTP 413 before JSON.parse ever sees them. Usernames are 1–32 chars with no ASCII control characters. Scores must be finite integers in [0, 500], a fast human probably can’t score more in a 60-second round.

Three per-IP rate limiters run in isolate memory: 120 req/min on GET /api/scores, 15 on POST /api/scores, 30 on POST /api/session. The client always gets a generic 500 on errors; real details stay in logs.

CORS is an exact-origin allowlist (ALLOWED_ORIGINS is a comma-separated env var). First-party requests, where the Origin matches the handler’s own URL, are always allowed (fixes e.g. preview branches).

Every response sets Cache-Control: no-store and CDN-Cache-Control: no-store. Without those, Cloudflare will happily cache the empty-leaderboard response on first request and you’ll spend an hour wondering why scores aren’t showing up. If you forget these, there is always manual cache busting to the rescue.

Reads are public. Writes are where the rules live.

Layer 2: Turnstile

I’m using the invisible widget. The site key goes in NEXT_PUBLIC_TURNSTILE_SITE_KEY (Next.js public env, fine to expose), the secret goes into Pages secrets via wrangler secret put. Server-side verification uses CF-Connecting-IP as remoteip, falling back to X-Forwarded-For.

The interesting bit is what gets checked beyond the basic success flag. The handler also asserts that data.action === “score_submit”, which rejects any token minted by a widget that doesn’t carry that action (including widgets running on other sites). It checks data.hostname against the configured ALLOWED_ORIGINS hostnames too (not in local dev).

The widget uses execution: “execute” and action: “score_submit”, which means it doesn’t run on render. The client triggers it once, shortly after mount, to proactively mint a session JWT so the first score submit is instant. Low friction for real users, real friction for unattended scripts.

It does not prove a human played the game. It just makes “run a curl loop” stop being viable.

Layer 3: Session JWTs so Turnstile isn’t per-request

Verifying a Turnstile token on every score post would be slow and irritating. So there’s a short-lived HS256 session JWT, minted in the route handler with the Web Crypto API. No library required for a payload this small.

The flow:

POST /api/session validates a Turnstile token (when TURNSTILE_SECRET_KEY is set) and returns { sessionToken }. If SESSION_SIGNING_SECRET isn’t configured, the endpoint returns 404 and is effectively disabled.

POST /api/scores accepts a valid session JWT in place of a Turnstile token. With both secrets configured, the JWT is tried first; a fresh Turnstile token is accepted as fallback in case the session-mint request fails.

The client caches the token in a React ref. Not localStorage, because I don’t want it surviving a reload. It refreshes 45 seconds before exp and retries once on a 401.

Payload looks like { v: 1, typ: “math4_score_sess”, jti, iat, exp }, signed HS256 with SESSION_SIGNING_SECRET. Default TTL is 300 seconds, configurable via SESSION_TTL_SEC and clamped to 120–900. The jti is a random UUID, but it isn’t tracked server-side, so a token is reusable for its full TTL window. More on that in the gaps section.

Layer 4: The client-side submission gate

The SubmitScoreScreen component checks scores.length < 10 || score > scores[9]?.score before showing the name input. If your run wouldn’t crack the top 10, you see a “you didn’t make it” screen instead of a form.

This isn’t security. It’s protection against accidents. Someone with devtools open for five minutes can bypass it, and that’s fine. The point is to keep the experience clean for honest players, who are the overwhelming majority of anyone who’ll ever touch this thing.

Secret hygiene

Three categories, three handling rules:

NEXT_PUBLIC_TURNSTILE_SITE_KEY lives in wrangler.toml [vars]. It’s public by design; committing it is correct.

TURNSTILE_SECRET_KEY and SESSION_SIGNING_SECRET go through wrangler secret put in production, .dev.vars for wrangler pages dev, or .env.local for plain next dev.

There’s an .env.example documenting which is which and how to mint the signing secret (openssl rand -base64 48 does it).

The line between wrangler.toml [vars] (committed config, public) and wrangler secret (encrypted, never in git) is the thing to get right. Everything else is detail.

What I accepted

A few honest gaps:

Scores can be faked. There’s no server-side simulation of the game. The leaderboard reflects what clients report, not what they played.

Session tokens are reusable within their TTL. The jti is minted but not tracked, so a single valid token can submit several scores until it expires (5 minutes by default). For a hobby game that’s fine. For anything with stakes you’d want a server-side store.

Per-isolate rate limits aren’t global. Workers run in multiple isolates across edge nodes, so a distributed flood will get past the limiter. If you need genuinely global rate limiting, that’s Durable Objects or Cloudflare’s rate limiting product, not a Map in isolate memory.

Client-side controls are client-side controls. The submission gate is honest UX, not a barrier.

The read API is public and is staying that way. Someone scraping the top 10 isn’t a problem I plan to solve.

What I’d add if the stakes went up

A server-side jti blocklist would close the reusable-token gap. Use a KV namespace with a TTL matching SESSION_TTL_SEC. POST /api/session writes the ID; POST /api/scores rejects any jti already in the store. One score per session token. KV’s eventual consistency is good enough for this; the occasional duplicate inside a narrow race window doesn’t matter for a leaderboard.

A Durable Object rate limiter would replace the per-isolate Maps. Single object keyed on IP, single atomic counter, genuinely global. Worth the complexity if distributed abuse becomes a real pattern.

A signed score payload would close the obvious cheating vector partway. At the end of a game, the server issues a short-lived token that commits to { score, timestamp }. The client sends that on submit; the server verifies it’s the same token it issued. This doesn’t stop someone who reverse-engineers the game flow, but it does stop arbitrary number injection without a prior server round-trip.

An admin panel would be handy: even an admin-only delete endpoint, something as simple as DELETE /api/scores/:id behind a bearer token, removes the need to open a D1 console to clean up.

Structured logging into Cloudflare Logpush, or a tail worker dumping into R2, gives you something to actually query when the board starts looking weird. A burst of submissions from one IP, all just above the #10 threshold, is exactly the kind of pattern you want to be able to see.

TL;DR

Parameterize your SQL. Cap your payloads. Validate your inputs. Bind Turnstile tokens to the action and hostname you expect. Keep secrets out of the bundle. Be honest about what you can guarantee.

It’s a toy, so I didn’t overbuild it.. I also didn’t leave the door open.

If you find something broken in my deployment, please reach out privately.

I Built a Free, No-Account Drawing App. Here’s the Tech Stack.

Krzysztof "Chris" Radomski — Tue, 09 Sep 2025 14:46:04 +0000

I’ve launched a free web app for instant visual communication: draw.paperplane.builders.

It solves a simple problem: sharing a sketch shouldn’t require an account or saving files. My solution is to store the entire vector drawing directly in the URL. You draw, copy the link, and share. That’s it. It’s a free tool, and there is no need to use an account to share drawings because they are stored in the URL.

Here is the tech stack that made it possible to build this so quickly.

Built with Next.js and TypeScript

The application’s foundation is built on # Nextjs and # TypeScript. This stack was chosen to ensure a robust, scalable, and maintainable codebase. Next.js provided the familiar and easy to use framework, while TypeScript added the type-safety needed to manage complexity — providing strong contracts between various moving parts of this app.

A Final Touch with Rough.js

For the visual style, I used # Roughjs. It’s a interesting JavaScript library that gives the drawings a sketchy, hand-drawn feel. This ensured a unique visual identity — paper like — without the need to build some hacky solution, or even worse, a complex rendering engine from scratch by myself :)

Instant Deployment with Cloudflare

Deployment was handled by # Cloudflare. Pushing the code live on a global network took minutes, not hours, and for a project this size, it’s completely free. No server overhead, just a few minutes spend on tools and dns configs. More decision making than actual work.

Ethical Analytics with Self-Hosted Umami

To understand usage patterns without compromising user privacy, I used a self-hosted instance of # Umami. It’s a lightweight, open-source analytics tool that provides the insights I need while respecting my users.

The Result

The result is a tool that is fast, private, and completely free to use. It’s built on the idea that anyone can build anything, you only need some time and Javascript.

As for the business model, enough to say I give it 2 out of 3. It’s cheap, and it’s free.

Try it for yourself and share a sketch with https://draw.paperplane.builders

How I Used GitHub Actions to Never Miss a Steam Deck Restock

Krzysztof "Chris" Radomski — Mon, 05 May 2025 20:38:51 +0000

The frustration is universal. You’ve got your heart set on that impossible-to-find item — maybe it’s a high-end graphics card, those limited-edition sneakers, or in my case, a Steam Deck OLED. The traditional approach to nabbing one is soul-crushing: obsessively refreshing pages, setting calendar reminders, and inevitably experiencing that gut-wrenching feeling when you realize you forgot to check on the exact day it came back in stock.

While hunting for a refurbished Steam Deck OLED, I remembered stumbling across a post about someone who automated bike promotion alerts using Puppeteer. Lightbulb moment! If they could automate their hunt, why couldn’t I? But the question remained — where should I run this solution? Buy a VPS? There had to be a more elegant (khem, cheap!) approach.

Enter GitHub Actions: The Free Automation Tool You’re Probably Overlooking

Most web scraping solutions force you into one of two unpleasant corners: pay for a service or manage your own server. But there’s a surprisingly powerful alternative hidden in plain sight — GitHub Actions! It’s completely free (with a generous 2000 minutes per month per user), requires zero server maintenance, and already has email notifications baked right in.

TL;DR — Here and below is the complete code that can transform your shopping slash scrapping frustrations:

on:
  push:
  workflow_dispatch:
  schedule:
    - cron: '*/60 * * * *'

jobs:
  scheduled:
    runs-on: ubuntu-latest
    steps:
    - name: Check out this repo
      uses: actions/checkout@v4

    - name: Set up Node.js
      uses: actions/setup-node@v3
      with:
        node-version: '16'

    - name: Install Puppeteer
      run: npm install puppeteer

    - name: Create Node.js script for Puppeteer
      run: |-
        cat << 'EOF' > fetchPage.js
        const fs = require("fs");
        const puppeteer = require("puppeteer");

        (async () => {
          try {
            const browser = await puppeteer.launch({
              args: ["--no-sandbox", "--disable-setuid-sandbox"],
            });
            const page = await browser.newPage();
            await page.goto(
              "https://store.steampowered.com/sale/steamdeckrefurbished/",
              { waitUntil: "networkidle0" }
            );

            await page.focus("div.CartBtn");
            const btns = await page.$$("div.CartBtn");

            let result = [];
            for (let t of btns) {
              result.push(
                await t.evaluate(
                  (x) =>
                    x.parentElement.parentElement.parentElement.parentElement
                      .textContent
                )
              );
            }

            const isOled512gbAvailable = result.some(
              (x) => x.includes("Steam Deck 512 GB OLED") && x.includes("Add to cart")
            );

            console.log({ result });

            if (isOled512gbAvailable) {
              console.log("Oled in stock!");
              const timestamp = new Date().toISOString();
              fs.appendFileSync(
                "in_stock.txt",
                `OLED 512GB in stock at ${timestamp}\n`
              );
            } else {
              console.log("No oled in stock.");
            }

            await browser.close();
          } catch (error) {
            const timestamp = new Date().toISOString();
            fs.appendFileSync(
              "error.txt",
              `Error at: ${timestamp} - ${error.message}\n`
            );
            console.error(error);
          }
        })();

        EOF

    - name: Run Puppeteer script
      run: node fetchPage.js

    - name: Commit and push changes
      run: |-
        git config user.name "Automated"
        git config user.email "actions@users.noreply.github.com"
        git add in_stock.txt error.txt || true

        if git diff --cached --quiet; then
          echo "No changes in in_stock.txt or error.txt. Exiting."
          exit 0
        fi

        git commit -m "Automated update at $(date +"%Y/%m/%d %H:%M")"
        git push

Don’t let the code intimidate you! It might look complex at first glance, but it’s actually quite straightforward when broken down. Let’s dissect it piece by piece:

Automation Triggers

on:
  push:
  workflow_dispatch:
  schedule:
    - cron: '*/60 * * * *'

This section defines when our script springs into action:

On every push to the repository (useful for testing)
When manually triggered (for on-demand checks)
Most importantly, on a schedule! The cron expression */60 * * * * tells it to run every 60 minutes like clockwork

This scheduled automation is the heartbeat of our solution — it ensures our digital scout is consistently checking for stock without your manual intervention. You could adjust the frequency, but remember that each check consumes some of your GitHub Actions minutes.

Environment Setup

jobs:
  scheduled:
    runs-on: ubuntu-latest
    steps:
    - name: Check out this repo
      uses: actions/checkout@v4
    - name: Set up Node.js
      uses: actions/setup-node@v3
      with:
        node-version: '16'
    - name: Install Puppeteer
      run: npm install puppeteer

This section might seem like boring setup code, but it’s where the foundation gets laid. We’re using the latest Ubuntu agent, checking out our repository, installing Node, and — critically — installing Puppeteer the headless browser that will do our actual browsing and checking.

Scraping Script

const fs = require("fs");
const puppeteer = require("puppeteer");

(async () => {
  try {
    const browser = await puppeteer.launch({
      args: ["--no-sandbox", "--disable-setuid-sandbox"],
    });
    const page = await browser.newPage();
    await page.goto(
      "https://store.steampowered.com/sale/steamdeckrefurbished/",
      { waitUntil: "networkidle0" }
    );
    await page.focus("div.CartBtn");
    const btns = await page.$$("div.CartBtn");
    let result = [];
    for (let t of btns) {
      result.push(
        await t.evaluate(
          (x) =>
            x.parentElement.parentElement.parentElement.parentElement
              .textContent
        )
      );
    }
    const isOled512gbAvailable = result.some(
      (x) => x.includes("Steam Deck 512 GB OLED") && x.includes("Add to cart")
    );
    console.log({ result });
    if (isOled512gbAvailable) {
      console.log("Oled in stock!");
      const timestamp = new Date().toISOString();
      fs.appendFileSync(
        "in_stock.txt",
        `OLED 512GB in stock at ${timestamp}\n`
      );
    } else {
      console.log("No oled in stock.");
    }
    await browser.close();
  } catch (error) {
    const timestamp = new Date().toISOString();
    fs.appendFileSync(
      "error.txt",
      `Error at: ${timestamp} - ${error.message}\n`
    );
    console.error(error);
  }
})();

This is where the real magic happens! Let’s break down what this digital detective is doing:

Browser Setup : We launch a specialized headless browser (no visual interface needed) with specific arguments required for GitHub’s environment.
Site Navigation : Our script visits the Steam Deck refurbished page and patiently waits for everything to load.
Element Detection : It identifies all cart buttons on the page.
Content Extraction : For each button, it cleverly navigates up the HTML family tree to grab the full product description. (Yes, this is a bit of a hack — in a more robust solution, we might use more targeted selectors.)
Availability Analysis : The script then scans through all results, checking for both “Steam Deck 512 GB OLED” and “Add to cart” text appearing together.
Alert Logging : If the coveted item is in stock, it records the exciting news with a timestamp in in_stock.txt.
Error Handling : If anything goes wrong, it documents the issue in error.txt for troubleshooting.

Running the Script and Recording Results

- name: Run Puppeteer script
  run: node fetchPage.js
- name: Commit and push changes
  run: |-
    git config user.name "Automated"
    git config user.email "actions@users.noreply.github.com"
    git add in_stock.txt error.txt || true

    if git diff --cached --quiet; then
      echo "No changes in in_stock.txt or error.txt. Exiting."
      exit 0
    fi

    git commit -m "Automated update at $(date +"%Y/%m/%d %H:%M")"
    git push

These final steps execute our carefully crafted plan:

Run our Node.js script
Set up Git with an automated user identity
Stage any changes to our tracking files
Check if there were actually any changes (if not, exit quietly)
Commit with a detailed timestamp and push the changes

Here’s the brilliant part: If our script detects the Steam Deck in stock, it modifies in_stock.txt, triggering a commit. GitHub then sends you a notification about this commit—essentially alerting you that your coveted item is available! No custom notification system needed; we're cleverly repurposing GitHub's built-in features.

Why This Approach Shines

This solution offers several compelling advantages:

Zero Infrastructure Costs : No servers to maintain or cloud resources to pay for.
Built-in Notification System : GitHub’s commit notifications act as your personal alert system.
Complete History : Every check is documented in your repository history — perfect for tracking patterns.
Easy Debugging : The error.txt file helps troubleshoot any issues, or you can run the script locally.
Infinitely Customizable : You can easily adapt this framework to monitor virtually any website.

Ethical Considerations Before You Deploy

Before implementing this solution, a few important points to consider:

Respect Rate Limits : Be courteous to the website’s resources. Checking every few minutes might be too aggressive and could potentially get your IP flagged.
Check Terms of Service : Some websites explicitly prohibit scraping in their ToS. Always verify before deploying.
Personal Use Only : This solution is designed for personal use, not for enabling scalping or mass reselling.

The Ironic Plot Twist

Did this ingenious solution help me snag my Steam Deck OLED? Not exactly. The only time the console became available was in the middle of the night, and I only saw the notification the next morning — too late!

However, this project wasn’t a total loss. I adapted this script for a completely different purpose: monitoring a Next.js website hosted with a provider notorious for unannounced outages. When the website goes down, the script commits an update to the error.log file on the release branch, triggering a page rebuild and restart. Problem solved!

The Developer’s Satisfaction

There’s something uniquely satisfying about using your programming skills to solve real-world problems. So many of our technical abilities seem confined to our professional work, rarely crossing over to enhance our personal lives. This project was a refreshing reminder that our coding skills can actually make everyday frustrations a little more manageable.

Have you leveraged GitHub Actions or other developer tools to solve real-world problems outside of work? I’d love to hear about your creative solutions in the comments!