Forem: William March

What breaks when you ship Next.js on Cloudflare Workers

William March — Sat, 16 May 2026 19:20:09 +0000

I've been building Finterm, a financial terminal
that runs entirely in a browser tab, on Cloudflare
Workers via @opennextjs/cloudflare. The promise
is the obvious one — global edge runtime,
near-zero cold starts, pay-per-request pricing.
The catch is that Workers don't run Node.js. Every
package in your dependency tree has to work in
the Workers runtime, and a surprising number of
common ones don't.

This is a rough log of what I had to rip out and
what I replaced it with, plus a couple of patterns
that turned out to be necessary on Workers but
irrelevant on Node.

## bcrypt → Argon2id via @noble/hashes

bcryptjs reaches for crypto.randomBytes and a
few other Node primitives that aren't polyfilled
in Workers. Argon2id is the modern alternative
anyway, and @noble/hashes exposes a pure-JS
implementation that runs anywhere and lines up
with current OWASP guidance. The migration was a
one-line change in the password hasher plus a
re-hash on next login.

## cheerio / jsdom / parse5 → htmlparser2

For the news reader I needed to extract article
bodies from arbitrary HTML. cheerio pulls in
parse5, which doesn't run on Workers, and
jsdom is even further away from compatibility.
htmlparser2 is SAX-style streaming and pure JS,
so it runs anywhere — but you have to walk the
events yourself rather than querying a tree. Worth
it for the runtime portability.

## The Yahoo Finance crumb handshake

Not a Workers issue specifically, but I hit it
harder because of Workers. Yahoo's quoteSummary,
options, and profile endpoints require a session
cookie and a crumb token bound to that session.
The dance: first you GET https://fc.yahoo.com/,
which returns 404 with Set-Cookie for A1 and A3;
then you GET /v1/test/getcrumb with those
cookies, which returns the crumb as plain text;
then every gated request needs that cookie plus
&crumb=... appended to the URL.

  const seed = await fetch('https://fc.yahoo.com/',
  { headers: BROWSERY });
  const cookie = seed.headers.getSetCookie()
    .map(c => c.split(';')[0])
    .filter(c => c.startsWith('A1=') ||
  c.startsWith('A3=') || c.startsWith('A1S='))
    .join('; ');
  const crumbRes = await fetch('https://query1.finan
  ce.yahoo.com/v1/test/getcrumb', {
    headers: { ...BROWSERY, Cookie: cookie },
  });
  const crumb = (await crumbRes.text()).trim();

A few gotchas. The getcrumb endpoint returns
text/plain, not JSON, so you can't send an
Accept: application/json header — it'll 406. The
User-Agent has to look browsery; a plain
curl/8.x or your fetch library's default gets
rate-limited fast. The cookie and crumb stay valid
for roughly thirty minutes, after which you
re-handshake. I cache the pair per-isolate and
refresh on the first 401.

## Single outbound gateway

Workers isolates are short-lived but they do
persist module state across requests on a single
isolate, which makes the obvious caching patterns
work better than on a per-request serverless
model.

Every upstream HTTP call in the app goes through
one route — /api/data/[...path]. The route looks
up the endpoint by path, runs the provider
function, attaches Cache-Control: s-maxage=N, stale-while-revalidate=86400, and lets the
Cloudflare edge cache do the heavy lifting. A
four-tier per-IP rate limiter only fires on cache
misses, so a popular ticker can be served to
thousands of users without ever hitting Yahoo or
SEC again that minute.

This pattern also gave me a single chokepoint for
an SSRF guard, so user-supplied paths can't reach
back into Cloudflare's metadata service or some
internal hostname.

## Pop-outs that share React state

Off the Workers topic but a fun one. Each window
in the dashboard has a popout button. It calls
window.open('/popout.html'), then React-renders
the same component switch into the popout's
document. The popout writes back to the parent's
workspace state through a callback, so edits
round-trip in real time.

Two non-obvious things had to change in the
window-body components. Any addEventListener or
matchMedia has to be bound to the popout's own
window (I expose this through a
useOwnerWindow(ref) hook). And any
document.createElement for an offscreen canvas
has to go through
someExistingNode.ownerDocument.createElement so
the node belongs to the popout's DOM rather than
the parent's.

## Result

Finterm is live at
finterm.xyz — open it, type
a ticker, and a chart, SEC fundamentals, options
chain with Greeks, and analyst estimates open as
draggable windows. Everything described above runs
in Cloudflare's edge: no Node server, no cold
starts to speak of.

Happy to go deeper on any of the above if there's
interest.

Drop-in AI Chat for Any Website — No Framework Required

William March — Thu, 16 Apr 2026 11:53:11 +0000

I was building a website builder platform and needed an AI assistant that could talk to users, call backend functions, and drop into any page without coupling to a framework. Everything I found was tied to React or required a backend SDK. So I built my own.

What it does

aichats renders a floating chat button on your page. Click it, chat opens. The LLM handles conversation and when it needs to do something — search products, create a ticket, query a database — it calls your tools automatically.

The full tool-calling loop runs without manual orchestration. You define tools, the LLM decides when to call them, the plugin executes them, feeds results back, and the LLM responds.

npm install aichats

Quick start — script tag

Drop this on any HTML page:

<script src="https://unpkg.com/aichats/dist/ai-chat-plugin.js"></script>
<script>
  AIChatPlugin.create({
    apiKey: "sk-...",
    provider: "openai",
    systemPrompt: "You help customers find products.",
    tools: [
      {
        type: "function",
        function: {
          name: "search_products",
          description: "Search the product catalog",
          parameters: {
            type: "object",
            properties: { query: { type: "string" } },
            required: ["query"],
          },
        },
      },
    ],
    actionEndpoint: "/api/chat",
  });
</script>

ES Module

import { create } from "aichats";

create({
  provider: "anthropic",
  apiKey: "sk-ant-...",
  model: "claude-sonnet-4-6",
  systemPrompt: "You are a helpful assistant.",
  tools: TOOLS,
  actionEndpoint: "/api/chat",
});

Next.js

"use client";
import { useEffect } from "react";

export default function Chat() {
  useEffect(() => {
    import("aichats").then((mod) => {
      mod.create({
        provider: "openai",
        apiKey: process.env.NEXT_PUBLIC_AI_KEY!,
        tools: TOOLS,
        actionEndpoint: "/api/chat",
      });
    });
  }, []);
  return null;
}

Tool calling — the interesting part

Define tools with the OpenAI function-calling schema. The plugin handles the loop:

User sends message
LLM responds with text, tool calls, or both
Plugin executes each tool call against your endpoint
Results fed back to the LLM
Repeat until the LLM responds with just text

Your server receives:

{ "action": "search_products", "args": { "query": "shoes" } }

And responds:

{ "result": "[{\"name\": \"Running Shoes\", \"price\": 89.99}]" }

The LLM reads the result and summarises it for the user.

Or handle tools client-side — no server needed:

create({
  onAction: async (name, args) => {
    if (name === "get_cart") return JSON.stringify(cartStore.getItems());
    return "Unknown action";
  },
});

Server route examples

Next.js App Router:

// app/api/chat/route.ts
import { NextResponse } from "next/server";

export async function POST(request: Request) {
  const { action, args } = await request.json();

  switch (action) {
    case "search_products": {
      const products = await db.product.findMany({
        where: { name: { contains: String(args.query) } },
        take: 10,
      });
      return NextResponse.json({ result: JSON.stringify(products) });
    }
    default:
      return NextResponse.json({ result: `Unknown: ${action}` });
  }
}

Express:

app.post("/api/chat", async (req, res) => {
  const { action, args } = req.body;

  switch (action) {
    case "search_products": {
      const { rows } = await pool.query(
        "SELECT * FROM products WHERE name ILIKE $1 LIMIT 10",
        [`%${args.query}%`]
      );
      return res.json({ result: JSON.stringify(rows) });
    }
    default:
      return res.json({ result: `Unknown: ${action}` });
  }
});

FastAPI:

@app.post("/api/chat")
async def chat(body: ChatAction):
    if body.action == "search_products":
        rows = await pool.fetch(
            "SELECT * FROM products WHERE name ILIKE $1 LIMIT 10",
            f"%{body.args['query']}%"
        )
        return {"result": json.dumps([dict(r) for r in rows])}
    return {"result": f"Unknown: {body.action}"}

Theming

All CSS custom properties. Override on your page — no build step:

/* Dark theme */
:root {
  --acp-primary: #6366f1;
  --acp-bg: #0f172a;
  --acp-text: #e2e8f0;
  --acp-border: #334155;
}

/* Size */
:root {
  --acp-width: 480px;
  --acp-height: 700px;
}

/* Brand colours */
:root {
  --acp-primary: #16a34a;
  --acp-blue: #16a34a;
  --acp-blue-light: #f0fdf4;
}

Mobile responsive — goes fullscreen under 480px automatically.

Under the hood

Zero dependencies — just HTML, CSS, JS
~30KB minified
Multi-provider: OpenAI, Anthropic, LM Studio, Ollama (any OpenAI-compatible API)
Expand/collapse panel with keyboard support
Proxy support for CORS (local models on different ports)
Max iteration cap to prevent runaway tool loops
Runtime API: setTools(), setSystemPrompt(), send(), clear(), destroy()
TypeScript types included

All config options

Option	Type	Default	Description
`provider`	`"openai" \	"anthropic" \	"lmstudio"`
`apiKey`	`string`	required	API key (stays client-side)
`model`	`string`	provider default	Model override
`baseUrl`	`string`	provider default	Base URL override
`proxyUrl`	`string`	—	Route all LLM requests through a proxy
`systemPrompt`	`string`	—	System prompt
`tools`	`ToolDef[]`	`[]`	Tools the LLM can call
`actionEndpoint`	`string`	—	Server URL for tool execution
`onAction`	`(name, args) => Promise<string>`	—	Client-side tool handler
`maxIterations`	`number`	`8`	Max tool round-trips per message
`title`	`string`	`"AI Chat"`	Header title
`position`	`"bottom-right" \	"bottom-left"`	`"bottom-right"`