DEV Community: Jay @ Designly

Open Knowledge Format vs RAG: Why Your Agent Should Read a Wiki

Jay @ Designly — Sun, 23 Aug 2026 02:47:11 +0000

Most agent stacks reach for a vector database the moment the model needs a fact it was not trained on. That instinct is reasonable when the answer is buried in years of tickets and leftover wiki pages. It is a strange instinct when the answer is a definition your team already agreed on, wrote down, and still argues about in Slack whenever someone "improves" it.

Take weekly active users. Someone asks the agent how you compute it. You already know the answer lives in a metric doc that points at the orders table and a freshness playbook for the days the warehouse is late. The agent does not know that. If you have wired it the usual way, it never gets a chance to. The docs go into a chunker, the chunker cuts the WAU paragraph away from the schema it depends on, and at query time a retriever returns a few fragments that look related. The model infers the join. Sometimes it gets the join right. Sometimes it counts sign-ins because an onboarding page used the words "active user." You cannot tell, from the fluent paragraph it returns, whether the model reasoned badly or the retriever handed it the wrong slice.

That is retrieval-augmented generation doing the job it was built for, which is search. You have a haystack. You do not know which document matters. You embed the pile, rank by similarity, and let the model stitch something together. The trouble starts when you use that same machinery to store a fact you can already name. Splitting a known definition into chunks and hoping the right slice comes back is wasted work, and it throws away the links between the metric, the table, and the playbook.

In April 2026, Andrej Karpathy wrote down a different pattern. Instead of rediscovering the same facts from raw documents on every question, you keep a wiki the model can read and maintain. When a new source arrives, the model does not just index it. It files the useful parts into pages that already exist, updates the cross-references, and notes where the new material contradicts the old. The knowledge compiles once and stays current. Google Cloud picked that pattern up on 12 June 2026, when Sam McVeety and Amir Hormati published the Open Knowledge Format. OKF is the shared contract for the wiki. It is a format. You do not install it, and you do not need a vector product to use it.

What the folder actually is

An OKF bundle is a directory of markdown files. Each file is one concept, and a concept can be a table, a metric, an API, a policy, or a runbook. The path is the identity. metrics/weekly_active_users.md is both the filename on disk and the address other files use when they point at it.

Every concept file starts with YAML frontmatter. The v0.2 spec requires one field, type. Title, description, tags, and a resource URI are recommended. Everything else is optional, including whatever extra keys your team wants to hang on the document. Concepts link to each other with ordinary markdown links, so the folder is a graph sitting on top of the directory tree. Two reserved names handle navigation. index.md lists a directory so an agent can skim one level without loading the whole bundle into context. log.md is the changelog. You can ship the directory as a git repo, a tarball, or a folder on disk. If you can cat a file, you can read OKF.

Google Cloud’s Knowledge Catalog, the catalog that used to be called Dataplex, can ingest a bundle and serve it to agents. That is one consumer among many. The format does not care whether the reader is Knowledge Catalog, Obsidian, GitHub, MkDocs, or a file-read tool in an agent loop.

A morning question and four files

Suppose you sell a product and someone asks the agent how you compute weekly active users. The bundle that answers that question can be this small.

sales/
  index.md
  tables/orders.md
  metrics/weekly_active_users.md
  playbooks/orders_freshness.md

index.md is the map. The spec keeps frontmatter off index files, except an optional version key at the bundle root.

# Sales

* [Orders](tables/orders.md) - One row per completed customer order.
* [Weekly active users](metrics/weekly_active_users.md) - Unique customers with a delivered order in the last 7 days.
* [Orders freshness](playbooks/orders_freshness.md) - What to do when `orders` lags the SLA.

The metric file states the fact and points at the table it depends on.

---
type: Metric
title: "Weekly active users"
description: "Unique customers with a delivered order in the last 7 days."
tags: [sales, activation]
verified:
  - { by: human:finance@acme, at: 2026-07-01T09:00:00Z }
stale_after: 2026-12-31T00:00:00Z
---

# Definition

A weekly active user is a distinct `customer_id` on [orders](/tables/orders.md) with `order_status = 'delivered'` and `order_ts` in the last 7 days.

# Notes

Do not count accounts that only signed in. Activity here means a completed order. If `orders` is late, stop and follow the [freshness playbook](/playbooks/orders_freshness.md).

The table file holds the grain and the join. The playbook holds the triage steps. None of that is buried in a long Confluence page.

The agent reads index.md, opens the metric, follows the link to orders, and only opens the playbook if freshness is in doubt. Path resolution is the traversal. There is no embed step and no ranking step, because the relationships are already written down as links. A foreign key, a metric’s source table, and the runbook that uses both are sitting in the files. Vector retrieval would have flattened those same relationships into disconnected text and asked the model to guess the structure it should have been handed.

Now run the same morning the RAG way. You dump the warehouse docs, the finance policy, and last year's incident notes into a vector store. The splitter cuts the WAU paragraph away from the orders schema and cuts the "delivered only" rule away from the notes sitting two headings down. The retriever returns fragments. The model writes a confident paragraph. If the paragraph is wrong, you have two suspects, the reasoner and the retriever, and no clean way to tell them apart. A direct file read leaves one.

The same files work for people. You can cat them, preview them on GitHub, open them in Obsidian, and run git blame on the day someone changed "active" to mean "signed in." There is no SDK between you and the fact. A stale WAU definition becomes a pull request instead of a silent re-index. Rollback is git revert. Review is the same habit you already have for code.

Cost follows that shape. For a small set of facts the agent reads on almost every task, you skip embeddings, a vector database, and a reranker, and you pay file-read tokens for the concept it actually opens. index.md is how you keep that bill from turning into "load the whole wiki." If you pour thousands of concept files into context you will rebuild the haystack on purpose. The curated core has to stay small, or you have invented a second search problem and called it a knowledge base.

When agents write the wiki

v0.1 was the folder and the links. v0.2, published 24 July 2026, is the part that treats the folder as a knowledge base that machines will keep writing. A page a person wrote comes with an implicit guarantee. You can walk down the hall. Ten thousand concepts minted overnight do not give you that, so the spec puts the trust questions in frontmatter, where a consumer can read them without spending tokens on the body.

The new fields are optional, and their absence means something. An unverified concept is distinguishable from a verified one. sources records what a concept was built from. generated records who wrote the current text and when. verified is a separate list of confirmations, human or machine, and from that list a consumer derives a trust tier of unverified, machine-confirmed, or human-reviewed. status moves a concept through draft, stable, and deprecated. stale_after is an absolute date, so staleness is a comparison you can run in code.

OKF records those signals. It does not compute a credibility score, because a score is subjective, does not travel between consumers, and goes stale the moment you write it down. Whoever reads the bundle decides what the signals are worth.

The other addition is Attested Computation, and it exists for a nastier moment than "where did this sentence come from." An agent reports a dollar figure. Did it produce that number the way finance said it must, or did it invent its own SQL? An attested computation is its own concept. It carries the sanctioned query or API call, the parameters the agent may fill, an executor, and a deterministic attester with no language model in it. The agent supplies values. It does not edit the computation. The executor returns a receipt, and the attester checks that the thing that ran matches the thing on disk. A swapped table name fails the check. That is a different job from retrieving a similar query out of a vector index.

Bare RAG can bolt some of this on as chunk metadata. Every team invents its own schema, and the next consumer has to learn it. OKF writes the fields once so any reader interprets them the same way.

The haystack is still a haystack

OKF does not replace retrieval. Google did not claim that, and the spec is explicit about the jobs it refuses. It does not prescribe storage, serving, or a query engine. It does not swallow OpenAPI or your warehouse catalog. It points at those things.

Use RAG when the corpus is large and you cannot predict which document matters. Support tickets, Slack threads, years of Confluence, and stray PDFs belong in retrieval because you cannot curate what you cannot name, and you should not try to hand-shape a pile that changes faster than you can read it. The hard problem just moves. RAG’s hard problem is retrieval quality. A knowledge base’s hard problem is staleness. If nothing rewrites the file when the warehouse or the finance policy changes, OKF becomes a confident wrong answer. Pick the approach whose hard problem you can actually solve.

Two questions help. Do you already know when this fact changes? Is a wrong answer expensive? If both are yes, curate it. If either is no, retrieve it. Most production agents need both. Named, high-stakes facts go to the bundle. "It's in there somewhere" goes to the vector store. You can even index the bundle, because one-concept markdown makes cleaner chunks than raw source dumps, but the source of truth for weekly active users is still the markdown file, not the index.

The failure mode on the OKF side is over-curation. If you pour everything into the bundle and call it a platform, you get a second unmaintained wiki. A fact earns a concept file when the agent reads it on nearly every task and a wrong answer causes real damage. Everything else stays in retrieval.

Start with the files you already have

You do not need Google Cloud to try this. Put one concept in each file, give it a type, a title, and a one-line description, and link the files the way a human would click through them. Keep the bundle in git. If your docs already live as versioned markdown with stable paths, you are most of the way there. If the same fact lives on three pages with no links between them, no producer can turn that mess into a clean bundle. Fix the docs first.

The spec is short. The repo ships sample bundles for GA4 e-commerce, Stack Overflow, Bitcoin public data, and a fictional retailer named acme_retail, plus a static HTML visualizer that turns any bundle into a graph in one file. Recheck the spec before you treat those names as frozen. The older copy under knowledge-catalog/okf is a snapshot. Build against the current repo.

If you can name the fact, write it down and let the agent read the file. Stop asking a retriever to rediscover it.

Thank You!

Thank you for taking the time to read my article and I hope you found it useful (or at the very least, mildly entertaining). For more great information about web dev, systems administration and cloud computing, please read the Designly Blog. Also, please leave your comments! I love to hear thoughts from my readers.

If you want to support me, please follow me on Spotify or SoundCloud!

Please also feel free to check out my Portfolio Site

Looking for a web developer? I'm available for hire! To inquire, please fill out a contact form.

This story was originally published at blog.designly.biz on August 22, 2026.

How DeepSeek Harness Saves Tokens by Not Editing History

Jay @ Designly — Tue, 18 Aug 2026 01:01:12 +0000

An agent is not a chat with a good memory. It is a loop that resends the entire transcript on every step.

The model does one thing. Text in, text out. When the call ends, it remembers nothing. Step 40 is not "continue from last time." Step 40 is step 1 plus 39 more chapters, shipped again. System prompt, tool schemas, every message, every tool result, the whole pile.

That is why a long coding session can feel cheap on the way out and surprisingly expensive on the way in. Output is the new work. Input is mostly you, re-reading yourself.

Providers will skip re-reading the front of that transcript. The trick is called prefix caching. It has one condition, and the condition is a little bit rude. The bytes at the front of this request must be word-for-word identical to last time.

Picture the model reading your conversation the way a person reads a book, page one forward, because what page 400 means depends on everything before it. There is no skipping to the good part. The order is the meaning. If the first 200 pages match, the provider restores a bookmark and starts there. Change one character on page 3 and every page after it means something slightly different. The bookmark is toast. The book gets read again, and you pay full price for the reread.

DeepSeek Harness is built around that condition. Once something has been sent to the model, it does not go back and change it. A wrong file path stays in the log. You append a line that says, yup, that path was wrong.

That sounds like bookkeeping. It is how you stop paying to re-read your own diary.

Two columns on one price list

DeepSeek publishes both rates, which is unusual and honestly pretty useful. These are V4-Pro numbers as of 17 August 2026, per million input tokens.

	Off-peak	Peak
Cache hit	$0.022	$0.044
Cache miss	$0.66	$1.32

That is 30×. Same model. Same text. Neighboring columns of one table. Peak hours (01:00–04:00 and 06:00–10:00 UTC) do not shrink the gap. They just make a busted prefix more expensive.

The harness shipped as an MIT developer preview on 13 August. Peak billing landed three days later. That is not a contradiction. A wrapper that keeps the prefix still is how the dearer miss column stays survivable.

The architecture does not send fewer tokens. An agent still resends the whole history every step. What it decides is which column those tokens land in.

A 100-step bill

This is a simplified model, not a benchmark. Recheck the pricing page before you budget from it.

Assume a 100-step coding session on V4-Pro, off-peak.

10,000-token header that never needs to change (system prompt + tool schemas)
2,000 new tokens per step (assistant + tool results)
input at step k = 10_000 + 2_000 × (k − 1)

Step 1 sends 10k tokens. Step 100 sends 208k. Over the whole run the provider sees about 10.9 million input tokens. That number does not move. The architecture only moves which rate you pay.

If history stays still, append-only, each byte is a miss once and a hit forever after.

	Tokens	Off-peak
Cache miss (new bytes only)	208,000	$0.14
Cache hit (replayed prefix)	10,692,000	$0.24
Input total	10.9M processed	~$0.37

Almost 98% of the input is billed at the hit rate. That is the fun part.

If history gets rewritten, or the prefix never matches, those same 10.9M tokens are all misses. About $7.19.

About 19× for the same work. The model did not get smarter. The wrapper just stopped editing page 3.

One edit is enough to feel it. By step 80 the prompt is ~168k tokens. A static step is roughly $0.005 (166k hit + 2k miss). Rewrite a tool result sitting in the middle of that prompt and the bookmark dies. That one step costs about $0.11, at the expensive end of the session. Keep trimming, refreshing, and summarizing in place, and you never get a stable prefix again. You are now the person who keeps moving the bookmark and wondering why the library is so slow.

Output is a different line on the bill (V4-Pro $1.98 / $3.96 per million, off-peak / peak). Static history does not touch it. Long agent runs are still input-dominated, because history is resent every step. The MIT license is not free inference. The local web UI is not a local model. The harness is what keeps you in the cheap column of a bill you still pay.

The sensible choices point the wrong way

Most harnesses cannot keep the bookmark, because agents edit history constantly.

a summary replaces old turns when the context fills
bulky tool output gets trimmed in place to make room
a file is re-read and the fresh copy is swapped over the stale one

Every one of those is a reasonable thing to do. Every one reaches backward into the transcript. Every one throws the bookmark away at the moment the conversation is longest and re-reading it costs the most. Helpful, tidy, and accidentally expensive.

The real design question for a harness is not which tools to offer or how to word the prompt. Can you run a 200-step session without ever going back and editing what you already sent?

If the answer is "we summarize when it gets long," you have already answered no.

They made rewriting unexpressible

DeepSeek's 5 July 2026 reconstructable requests design note is delightfully blunt about the shape. A session is not a list of messages. It is an append-only log of typed events. A user message is an event. An assistant reply is an event. A tool result is an event. The log only grows at one end. No sneaking back to page 3 with a red pen.

The message history handed to the model is not stored. It is derived on every step by folding a pure function over the events. There is no message array to reach into, because there is no message array. You cannot edit what does not exist.

The principle fits on one line. Model-visible means durably referenced.

If something can reach the model, it must be reconstructable from the log (plus the immutable objects the log points at, plus a pinned code version). Byte for byte. Not equivalently. Identically.

Cache stability is corollary number one, not the headline. They did not set out to build a cache optimizer. They built a log you cannot edit and a projection that is a pure function of it. Prefix stability falls out the other side. In their words, stability is emergent, not managed.

When something has to change, you append. Trim a bulky tool result and that trim is itself a new log event, carrying the shorter value under the same call id. The correction goes on the end. The history in front of it is untouched.

They close the door in code, not in prose. Derived messages are deep-frozen. If a plugin reaches through a projection to mutate history, it does not corrupt the log. It throws. A request the log does not explain cannot be constructed by accident, not by the loop and not by a listener a third party plugs in later.

They even rejected the obvious safety net: compare consecutive requests and warn on divergence. A warning arrives after the bad request has shipped. A rule you can only check by reading the code decays the first week somebody is in a hurry. We have all been that somebody.

So they wrote a module whose job is to disbelieve the agent loop. On every request it builds a fresh session, replays the log from the beginning, derives the messages again, and compares that answer against what the loop is about to send, so the live cache cannot vouch for itself. On top of that, a paid test against the real API fails unless the second request in a conversation reports cache-read tokens.

The bill is the assertion. If the cheap column does not light up, the design is lying.

Compaction is where append-only gets hard

Sooner or later the conversation grows past what the model can hold. The harness has to summarize the old part so the work can continue. That means a second call to the model. This is the case that should break an append-only design, if anything does.

The obvious summarizer puts a fresh system prompt at the front ("you are a summarizer") plus the conversation to condense. That is reasonable, and close to the most expensive move available. The system prompt sits at token one, which is exactly where the cache starts keying. One differing first token invalidates the entire prefix. The summarizing call shares nothing with the warm request that just tripped the limit. You pay full miss price for the whole history twice, at the longest moment. Congratulations, you summarized your way into a bigger bill.

The fix reads like nothing and turns out to be the whole idea. Leave the cached prefix alone. Replay the previous request word for word, same system prompt, same tool definitions, same history, then hang the summarizer instruction off the end. The call is a strict extension of what the provider already cached. The bookmark survives. The provider reads a new instruction and nothing else. The summary lands in the log as a new event. The conversation continues on a prefix that was never disturbed.

They go further than "send the model what it needs." The summarizer will never call a tool. It has no use for the tool schemas. They send them anyway, because removing them would shorten the token sequence and knock every following token out of alignment with the cached copy. Waste a few tokens on purpose. Save the rest of the book.

The rule is not "send the model what it needs."

The rule is do not disturb the bytes that came before.

Append less, after you stop rewriting

Static history is the main saving. There is a second one, and it is almost as satisfying.

In a normal tool loop the model picks a function, round-trips, picks another. Every intermediate result lands back in the conversation whether it matters or not. The log grows. The static prefix gets heavier even when you never edit it. You stopped rewriting history and then invited every scratch note to live there forever.

DeepSeek's Code mode (programmatic tool calling) hands the model a generated TypeScript interface and one transport, run_code. The model writes a small program. The program loops, branches, filters, runs several reads. Only what it returns joins the log. The model curates its own context instead of drowning in it. Cloudflare made the same argument for Code Mode. Models have read millions of lines of real code and comparatively few canned tool-call traces, so ask them for the thing they have actually seen.

That second saving is append less, so the prefix you must keep still stays smaller. It is not a substitute for never rewriting what you already appended. First, stop editing page 3. Then stop adding pages you do not need.

Plugins cannot be allowed to touch the past

The README line is "everything is a plugin." The model adapter, the tools, the sandbox, the summarizer, the UI, even the agent loop, the thing most frameworks treat as the center of the universe, is a row in a configuration file.

That is only safe if unloading a component leaves nothing behind in the log. A plugin that rewrites a past tool result to "clean up" would bust the prefix for every step that follows. The same append-only rule that keeps the bill down is the rule that makes hot-swapping possible.

The kernel under that is Cordis, a plugin system where every registration is an effect, and every register function hands back the thing that undoes it. Nothing gets installed without a way to uninstall it. DeepSeek did not invent it. It grew out of the Koishi chatbot stack, and they vendored it rather than taking it as a floating dependency. The point for this article is smaller than the paper. A swap must not reach backward into history, or the cache dies.

The inspectable trajectory in the UI is the same log. You can see why a step went sideways because the bytes were never rewritten to make the story tidier. The design that keeps the bill down is the design that makes the incident readable. Cheap and honest. That is a rare combo.

The wrapper is the product

On the public Terminal-Bench 2.1 board, the same weights (Fable 5) score 83.8% under Claude Code and 80.4% under Terminus 2. Same model, same tasks, different wrapper. A few points decided by software with no weights in it at all. That is the gap between two harnesses that are both good. Between a good one and a careless one, the gap is the miss column.

DeepSeek does not have a row on that board yet. Treat launch-week scoreboards as the vendor's until somebody neutral reproduces them. The architecture is still the thing worth stealing.

If you need an agent that works this afternoon, this is not it. It is a v0.1 developer preview. The README promises compatibility-breaking changes. Pin a version. Use a disposable workspace. Do not wire production to it this week. Play with it. Do not marry it.

If you are building an agent loop on any model, read the reconstructable-requests note before you write another line that splices a summary into the middle of a message array. It is one file. It is written in plain English. It will change what you do with history.

The rule you want is not a cache flag.

Once a token has been sent to the model, do not go back and change it.

Thank You!

If you want to support me, please follow me on Spotify or SoundCloud!

Please also feel free to check out my Portfolio Site

Looking for a web developer? I'm available for hire! To inquire, please fill out a contact form.

This story was originally published at blog.designly.biz on August 17, 2026.

Why await Doesn't Make JavaScript Run in Order

Jay @ Designly — Sun, 16 Aug 2026 22:06:08 +0000

A lot of developers learn async/await and walk away with one idea:

I used await, so everything waits.

That sentence is almost true — and the "almost" is where the bugs live.

await pauses one async function. It does not pause the rest of your program. Timers still fire. Event handlers still run. Other async functions keep moving. JavaScript is still taking turns.

Once you see that, a lot of "why did this log first?" moments stop being mysterious.

The assumption

Here's the mental model that gets people in trouble:

await doSomething();
// nothing else in the entire program can happen until this finishes

That would be convenient. It is also not how JavaScript works.

await is local. It only tells this function to pause at this line and come back later. Everything else in the program is free to keep running.

A short surprising example

Two functions. One setTimeout. A few console.log calls.

function later(label, ms) {
  return new Promise((resolve) => {
    setTimeout(() => {
      console.log(label);
      resolve();
    }, ms);
  });
}

async function loadUser() {
  console.log('loadUser: start');
  await later('loadUser: done', 1000);
  console.log('loadUser: after await');
}

async function loadSettings() {
  console.log('loadSettings: start');
  await later('loadSettings: done', 200);
  console.log('loadSettings: after await');
}

console.log('program: start');
loadUser();
loadSettings();
console.log('program: after both calls');

If await froze the whole program, you would expect something like this:

loadUser starts
the program waits a full second
loadUser finishes
loadSettings starts
then the rest of the logs appear

That is not what happens.

What actually logs, and when

Here is the timeline:

0ms     program: start
0ms     loadUser: start
0ms     loadSettings: start
0ms     program: after both calls
200ms   loadSettings: done
200ms   loadSettings: after await
1000ms  loadUser: done
1000ms  loadUser: after await

loadUser() hits await and steps aside. loadSettings() starts immediately. The next line in the main script runs immediately too. A fifth of a second later, the faster timer wins — even though we called the slower function first.

The order of the function calls is not the order of the finish times.

What `await` actually pauses

An async function always returns a Promise. When that function hits await, three things happen:

The current function pauses at that line.
JavaScript records "come back here when this Promise settles."
Control returns to whoever called the function.

That last part is the one people miss.

async function loadUser() {
  await later('loadUser: done', 1000);
  // this line waits
}

loadUser();
// this line does not wait

loadUser() is paused. The caller is not.

If you want the caller to wait, the caller has to await too:

await loadUser();
await loadSettings();

Now loadSettings() will not start until loadUser() finishes. That is sequential on purpose — because you chained the waits, not because await stopped the whole program.

How other code keeps running

While loadUser() is paused, JavaScript is still doing work.

In the example above, that work is a setTimeout. In a real app, it is usually one of these:

another async function you already started
a click handler
a fetch() that finishes first
a React/Svelte effect
the next line after you forgot to await

You do not need a deep event-loop lecture to use this well. One picture is enough:

Call loadUser()
  → hits await
  → loadUser is parked
  → JavaScript looks for other work
  → loadSettings() runs
  → timers and network calls keep ticking
  → whichever Promise finishes first gets to resume

await is a bookmark, not a freeze frame.

When sequential `await`s are right

Sometimes you do want one thing to finish before the next thing starts. That is what sequential awaits are for.

Use them when the second call needs the first result:

async function loadDashboard(userId) {
  const user = await fetchUser(userId);
  const projects = await fetchProjects(user.teamId);

  return { user, projects };
}

You cannot fetch the projects until you know the team id. Waiting in order is the correct design.

The same rule applies to writes that must happen in sequence:

await createCustomer(form);
await sendWelcomeEmail(form.email);

If the customer row is not there yet, the email step should not run.

When `Promise.all()` is better

If the tasks do not depend on each other, waiting in a line wastes time.

This version looks tidy and is often slower than it needs to be:

async function loadPage() {
  const user = await fetchUser();
  const settings = await fetchSettings();
  const notifications = await fetchNotifications();

  return { user, settings, notifications };
}

Each request sits around until the previous one finishes. If each call takes 300ms, you pay about 900ms.

These three requests do not need each other. Start them together:

async function loadPage() {
  const [user, settings, notifications] = await Promise.all([
    fetchUser(),
    fetchSettings(),
    fetchNotifications()
  ]);

  return { user, settings, notifications };
}

Now the slowest request sets the wait time, not the sum of all three. If they all take 300ms, you wait about 300ms.

That is the same idea as the first example. loadUser() and loadSettings() overlapped because we started both without waiting. Promise.all() makes that overlap explicit — and it gives you the results in a predictable array when every Promise has finished.

One caveat: Promise.all() rejects as soon as any Promise rejects. If you want each request to succeed or fail on its own, use Promise.allSettled() instead.

A rule of thumb you can remember

await pauses this function. It does not pause JavaScript.

If the next line needs the result, await it.

If two tasks can run at the same time, start both, then await Promise.all().

If you called an async function and did not await it, you only started it. The rest of your code will keep going.

That last sentence is the whole article in one line. The surprising logs are just that idea showing up on a timeline.

This story was originally published at blog.designly.biz on August 16, 2026.

How to Automate Scheduled X Posts with Codex and xurl

Jay @ Designly — Sun, 16 Aug 2026 21:23:36 +0000

Most social-media automation tutorials stop at “call the API on a cron job.” That works, but it leaves the hard questions unanswered. Which account is the automation using? How does it avoid posting the same story twice? What happens when an API request times out after X has already accepted the post? And where should an AI agent’s editorial freedom end?

I recently built a scheduled X publishing workflow with Codex and xurl, the official command-line client for the X API. The result is not just a timer attached to an AI prompt. It is a small publishing system with four distinct layers:

An X developer application with read-and-write user authentication.
xurl, which stores the credentials and communicates with the X API.
A fixed-account Codex skill that verifies the identity before every write.
A Codex scheduled task that researches, checks history, drafts, and publishes.

That separation is the important part. Codex can make editorial decisions, but it cannot casually choose an account or improvise the publishing command. The skill owns the deterministic write boundary, while the scheduled task owns timing and editorial policy.

In this article, I’ll show you how to build the same architecture.

X developer settings, API packages, Codex features, and command-line options can change. The workflow below was verified in August 2026, but you should check the current upstream documentation before using it in production.

What You Will Need

Before starting, you will need:

Codex on a Mac with access to Scheduled tasks.
An X developer account and an application with read-and-write permissions.
Homebrew.
A dedicated or clearly identified X account for the automation.
A local project containing the source material or editorial context the agent should use.

You should also decide what the automation is allowed to publish before you give it access to an account. A good editorial policy is specific enough to reject a story, not merely broad enough to describe a topic.

For example, I built one version of this workflow for a health-news account. Its policy covered metabolic health, nutrition research, and evidence quality. It also required the agent to distinguish association from causation, label animal studies and preprints, avoid personalized medical advice, and prefer primary sources. Those rules mattered just as much as the code.

Install xurl

Install the official X Developer Platform CLI with Homebrew:

brew install --cask xdevplatform/tap/xurl

Then verify that it is available:

command -v xurl
xurl version

The xurl project supports OAuth 2.0 user authentication, multiple applications and accounts, shortcuts for common X actions, media uploads, and raw X API requests. Most importantly for this workflow, it gives us simple commands for identifying the authenticated user, reading account history, and creating a post.

Create an X Developer Application

Open the X Developer Console and create an application for the account you intend to manage.

Configure user authentication with these general settings:

Setting	Value
App permissions	Read and write
App type	Web App, Automated App, or Bot
Callback URI	`http://localhost:8080/callback`
Website URL	A valid website you control
Environment	A production-capable API package

The callback URI must match exactly. xurl uses http://localhost:8080/callback by default, although it can store a different redirect URI for an application if necessary.

When X asks how you will use its data, describe the real first-party workflow. A suitable statement might explain that the application will create original or scheduled posts, read the account’s own history to prevent duplicates, and retain only minimal operational data such as post IDs, source URLs, timestamps, and publishing status.

Know Which Credential You Need

X exposes several credentials that look interchangeable but are not:

An OAuth 2.0 Client ID and Client Secret are used for the user authorization flow in this tutorial.
A Consumer Key and Consumer Secret belong to OAuth 1.0a.
A Bearer Token is commonly used for app-only authentication and is not a substitute for the user context needed to publish as your account.

Save the OAuth 2.0 Client ID and Client Secret privately. Never paste them into a Codex conversation, a Markdown file, a screenshot, or your source repository.

Authorize the Account Locally

Credential setup should happen in a private Terminal controlled by you, not inside an agent session. This zsh pattern prevents the literal secret from being recorded in shell history:

read "XURL_CLIENT_ID?Client ID: "
read -s "XURL_CLIENT_SECRET?Client Secret: "; echo

xurl auth apps add my-x-app \
  --client-id "$XURL_CLIENT_ID" \
  --client-secret "$XURL_CLIENT_SECRET" \
  --redirect-uri http://localhost:8080/callback

unset XURL_CLIENT_ID XURL_CLIENT_SECRET

Now authorize the intended account. Replace my_handle with the handle without the @ character:

xurl auth oauth2 --app my-x-app my_handle
xurl auth default my-x-app my_handle

The OAuth command opens a browser. Sign in to the correct X account and approve the requested access.

Next, verify the setup without publishing anything:

xurl auth status
xurl whoami --username my_handle
xurl posts my_handle -n 100 --username my_handle

The whoami result must contain the exact account you expect. If it does not, stop. Do not “test” the configuration by sending a post from an uncertain identity.

Also, never ask an agent to inspect or print anything under ~/.xurl/. That directory contains authentication material. Avoid xurl --verbose in an agent session as well, because verbose request output can expose sensitive headers.

Put a Fixed-Account Skill in Front of the API

Codex skills package repeatable instructions and optional executable logic. According to the OpenAI skill documentation, a skill is a directory with a required SKILL.md file and optional scripts, references, assets, and interface metadata.

For this workflow, create a personal skill named something like xurl-post:

xurl-post/
├── SKILL.md
├── agents/
│   └── openai.yaml
└── scripts/
    └── post.py

You can invoke $skill-creator in Codex and describe what you want:

Create a personal skill named xurl-post. Use the locally installed xurl CLI
to publish finalized text and optional uploaded media from my_handle on X.
Support fully automated use, but verify the account before every write.

Why use a script instead of putting the command directly in SKILL.md? Because this is exactly where deterministic behavior is valuable. Research and writing benefit from judgment. Account selection and argument construction do not.

The wrapper script should enforce the following rules:

Resolve the local xurl executable.
Run xurl whoami --username my_handle before every post.
Parse the returned JSON and require an exact username match.
Refuse the write if authentication or identity verification fails.
Pass the finished post as a direct process argument, never through shell interpolation.
Publish with xurl post TEXT --username my_handle.
Support repeated --media-id values for media that has already been uploaded.
Provide a --dry-run mode that checks identity and request construction without posting.
Never blindly retry a failed or interrupted publish.

The final rule deserves emphasis. If a request reaches X but the response is lost, the command may look like it failed even though the post exists. An automatic retry can therefore create a duplicate. After an ambiguous result, read the newest account history before doing anything else.

Your skill instructions should also define authorization clearly. A request to publish, post, send, or automate finalized copy can authorize a write. A request to draft, revise, review, or preview should not.

Test the Publishing Boundary Without Posting Garbage

Do not publish “test 123” to a production account just to see whether the integration works.

Instead, validate the skill with its dry-run mode or with a simulated xurl executable. Test at least these cases:

The expected account is authenticated and the request is constructed correctly.
A different account is authenticated and the script refuses to continue.
whoami fails or returns malformed data.
The post contains quotation marks, apostrophes, URLs, emoji, and line breaks.
One or more media IDs are passed as separate arguments.

Once those tests pass, use one real, editorially valid post as the end-to-end production test.

Give the Scheduled Task a Complete Editorial Workflow

The skill knows how to publish safely, but it should not decide what to publish. That belongs in the scheduled task’s saved prompt.

A dependable prompt should tell Codex to perform the following sequence on every run:

Read the project’s current articles or other source material to refresh its understanding of the site’s subjects and voice.
Retrieve the X account’s accessible post history.
Search for recent stories from authoritative, preferably primary, sources.
Compare the publication date with the date of the underlying study, release, or event.
Reject exact and semantic duplicates.
Draft one concise, source-linked post that accurately represents the evidence.
Invoke $xurl-post exactly once.
Report the source, final text, history check, and returned post ID or URL.
Skip the run if research, history retrieval, or factual verification fails.

The saved prompt must be self-contained. Do not rely on the agent remembering a policy you mentioned in a different conversation.

Here is a reusable starting point:

On every run, read the articles in this project to refresh the site's subjects
and voice. Retrieve the full accessible post history for @my_handle before
choosing a topic. Find one timely story from an authoritative primary source
that fits the editorial policy below. Compare the source publication date with
the date of the underlying event or research. Reject exact duplicates and
semantically equivalent prior posts, even if their wording or URLs differ.

Write one concise, accurate, source-linked X post. Invoke $xurl-post exactly
once without requesting interactive confirmation. Report the source, exact
published text, duplicate check, and resulting post ID or URL. If history
retrieval, research, or factual verification fails, skip the run and explain
why. Never retry an ambiguous publishing result without first checking the
newest account history.

Editorial policy:
- [Your topic boundaries]
- [Your source-quality requirements]
- [Claims or language to avoid]
- [When to label uncertainty]
- [Any required disclosures]

In Codex, create the scheduled task in plain language and attach it to the relevant project. For example:

Create a scheduled task for this project that runs every day at 8:00 AM,
1:00 PM, and 6:00 PM Central. Use the complete research, duplicate-checking,
editorial, and publishing workflow in the prompt above.

Use the Codex Scheduled interface to review, edit, pause, resume, or remove the task. Background tasks can make file, network, and application changes according to their permissions, so keep the task’s sandbox and command rules as narrow as the workflow allows. OpenAI’s current Scheduled tasks documentation is the best place to check the latest behavior and requirements.

Duplicate Prevention Should Fail Closed

Preventing identical text is easy. Preventing repeated stories is harder.

Before researching or publishing, retrieve up to 100 recent posts:

xurl posts my_handle -n 100 --username my_handle

If the API response provides a pagination token, continue through as much history as your access permits. Build a duplicate index from more than the post text:

Canonical source URLs with tracking parameters removed.
DOI or study title.
Named event, product release, or policy announcement.
The core factual claim.
Semantically equivalent prior posts with different wording or links.

For each candidate story, search history using distinctive title terms, the source domain, named entities, and the main claim. A new article about an old study is not necessarily a new story.

Most importantly, make duplicate checking fail closed. If account history cannot be retrieved or checked reliably, the task should skip the run. Missing one scheduled post is much cheaper than eroding trust with duplicates.

This rule proved its value in my own health-news workflow. One run found a timely story, discovered that an equivalent post already existed, and skipped publishing. That was not a failed run; it was the system working correctly.

Test the Whole Workflow in Stages

Before leaving the task unattended, test it in increasingly consequential stages:

Run the research and duplicate check without publishing.
Verify that the chosen source is primary and the proposed claim matches it.
Run the skill in dry-run mode.
Authorize one real publish.
Confirm the returned post ID at https://x.com/my_handle/status/POST_ID.
Inspect the first several scheduled runs in the Codex Scheduled interface.

Pause the task immediately if it drifts from the editorial policy, repeats stories, relies on weak sources, or overstates what a source supports.

Automation does not eliminate editorial responsibility. It merely moves that responsibility into the prompt, the skill boundary, and the monitoring process.

Troubleshooting

xurl Cannot Find the Account

Reauthorize using the explicit handle, then reset the defaults:

xurl auth oauth2 --app my-x-app my_handle
xurl auth default my-x-app my_handle
xurl whoami --username my_handle

Posting Returns 403

Confirm that the X application has Read and write permission and belongs to a usable production API package. If you changed its scopes, repeat OAuth so the new authorization receives the updated permissions.

If authentication succeeds but whoami returns client-forbidden or client-not-enrolled, check the application’s package and production enrollment in the X Developer Console. The current xurl README includes up-to-date enrollment troubleshooting.

Codex Cannot Reach api.x.com

The sandbox may block network access until a narrow permission is granted. Perform the first read-only and publishing tests interactively, then allow only the commands the scheduled workflow actually needs. Do not approve arbitrary shell or scripting access just to make unattended posting convenient.

A Publish May Have Succeeded Before an Error

Do not retry immediately. Fetch the newest posts and compare the exact text, canonical source URL, and core claim. Retry only after confirming X did not create the post.

The Scheduled Task Does Not Run

Check that:

The task is active in Codex Scheduled.
The selected project remains available.
xurl is still available in the task environment.
OAuth has not expired or been revoked.
The task has the narrow network and local permissions it needs.

How to Shut It Down Safely

Pause the scheduled task before changing credentials, account settings, or the publishing skill.

To remove the integration completely, revoke the application in X and clear local xurl authentication from your private Terminal:

xurl auth clear --all

If a Client Secret, token, or authentication header ever appears in chat, logs, screenshots, or documentation, rotate or revoke it immediately. Deleting the copied text is not enough; the exposed credential must no longer be valid.

Final Thoughts

The best part of this architecture is not that an AI can post on a schedule. The best part is that each component has one clear job.

xurl owns authentication. The Codex skill owns identity verification and the write operation. The scheduled prompt owns research and editorial judgment. Account history provides a feedback loop for duplicate prevention and ambiguous failures.

That separation turns a fragile cron job into a publishing workflow you can reason about. The agent is free to decide that there is nothing worth posting today—and the safest automation is often the one that knows when to do nothing.

Sources

This story was originally published at blog.designly.biz on August 16, 2026.

Don’t Waste Your Money on GitHub Actions—Do This Instead!

Jay @ Designly — Wed, 08 Oct 2025 16:21:12 +0000

GitHub Actions is convenient, but it’s not cheap. Runner minutes add up quickly, builds are often slow, and you don’t always need the complexity of a full CI/CD platform.

If your main goal is fast, repeatable builds and deployments, there’s a better way: use a disposable EC2 build server that spins up only when you need it, runs your build, and shuts down immediately after.

You get dedicated hardware, predictable builds, and pay just pennies per run.

Here’s how I set it up.

Step 1: Spin Up an Ubuntu EC2 Instance

Launch a new Ubuntu Server in AWS.

Instance type:
- t3.medium works for lighter projects.
- For serious builds, I use a c7i-flex.2xlarge (~$0.60/hr).
Key tip: You’ll only keep it running for minutes at a time, so the hourly rate is irrelevant — builds cost cents.
Copy the Instance ID (e.g. i-0123456789abcdef0). You’ll need it for automation.

Step 2: Configure the Instance

SSH in and prepare it for builds.

2.1 Install Nginx (for health checks)

sudo apt update && sudo apt install -y nginx

Leave the default site running on port 80. We’ll use this later to check when the server is fully booted.

2.2 Install GitHub CLI

sudo apt install -y gh

This will allow the build user to authenticate with GitHub easily.

2.3 Create a Non-Privileged User

We don’t want to build as root. Create a web user with a home directory:

sudo adduser --disabled-password --gecos "" web

Switch into it:

sudo su - web

2.4 Install Node.js and Package Manager

Install NVM (Node Version Manager):

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash

Load NVM into the current shell:

export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"

Install Node.js (LTS):

nvm install --lts

Install your package manager globally (example with pnpm):

npm install -g pnpm

2.5 Generate SSH Keys

Still as the web user, run:

ssh-keygen

Press enter through the prompts — defaults are fine.

2.6 Add Build Server’s Key to Deployment Destination

If your builds deploy to another server (e.g. staging or prod), you need to allow the build server to connect.

On the build server:

cat ~/.ssh/id_rsa.pub

Copy that key and add it to your deployment server’s ~/.ssh/authorized_keys.

2.7 Authenticate with GitHub

Authenticate with GitHub CLI:

gh auth login

Choose:

GitHub.com
SSH
Paste your token if prompted

Test:

gh repo list

2.8 Allow Local Machine SSH Access

For convenience, let your local machine connect to the build server without typing a password.

On your local machine:

cat ~/.ssh/id_rsa.pub

On the build server (as web):

mkdir -p ~/.ssh
nano ~/.ssh/authorized_keys

Paste the key, then:

chmod 700 ~/.ssh
chmod 600 ~/.ssh/authorized_keys

Now you can SSH straight in:

ssh web@your-server-ip

Step 3: Automate the Local Workflow

Manually starting/stopping the instance is painful. Let’s automate it.

Save this as scripts/remote-build.sh in your repo and make it executable:

chmod +x scripts/remote-build.sh

#!/bin/bash
set -euo pipefail

if [ $# -lt 1 ]; then
    echo "Usage: $0 <environment> [--keep-running]"
    exit 1
fi

ENVIRONMENT=$1
KEEP_RUNNING=false
if [ $# -gt 1 ] && [ "$2" == "--keep-running" ]; then
    KEEP_RUNNING=true
fi

# Replace with your details
INSTANCE_ID="YOUR_INSTANCE_ID"
HOSTNAME="your-build-server.example.com"
export AWS_PROFILE=your-aws-profile

echo "Checking for uncommitted git changes..."
if ! git diff-index --quiet HEAD --; then
    echo "❌ Uncommitted changes found."
    exit 1
fi
echo "✅ Working directory clean."

spinner() {
    local pid=$1
    local delay=0.1
    local spinstr='|/-\'
    while kill -0 $pid 2>/dev/null; do
        local temp=${spinstr#?}
        printf " [%c]  " "$spinstr"
        local spinstr=$temp${spinstr%"$temp"}
        sleep $delay
        printf "\b\b\b\b\b\b"
    done
    wait $pid
    return $?
}

STATE=$(aws ec2 describe-instances     --instance-ids $INSTANCE_ID     --query "Reservations[*].Instances[*].State.Name"     --output text)

if [ "$STATE" != "running" ]; then
    echo "▶️ Starting instance..."
    aws ec2 start-instances --instance-ids $INSTANCE_ID >/dev/null
    echo -n "⏳ Waiting..."
    aws ec2 wait instance-running --instance-ids $INSTANCE_ID &
    spinner $!
    echo " done ✅"
fi

PUBLIC_IP=$(aws ec2 describe-instances     --instance-ids $INSTANCE_ID     --query "Reservations[*].Instances[*].PublicIpAddress"     --output text)
echo "🌐 Instance at $PUBLIC_IP"

if [ "$STATE" != "running" ]; then
    echo -n "🔄 Waiting for $HOSTNAME..."
    (
        while ! curl -s -f -o /dev/null "http://$HOSTNAME:80" 2>/dev/null; do
            sleep 2
        done
    ) &
    spinner $!
    echo " ready ✅"
fi

echo "🔄 Syncing .env file..."
scp .env your-ssh-alias:/path/to/project/.env

echo "🛠 Running remote build pipeline..."
ssh -tt your-ssh-alias "cd /path/to/project && pnpm build:remote"

if [ "$KEEP_RUNNING" = true ]; then
    echo "⏸ Leaving instance running."
else
    echo "🛑 Stopping instance..."
    aws ec2 stop-instances --instance-ids $INSTANCE_ID >/dev/null
    echo -n "⏳ Waiting..."
    aws ec2 wait instance-stopped --instance-ids $INSTANCE_ID &
    spinner $!
    echo " stopped ✅"
fi

echo "🎉 Build + deploy complete for '$ENVIRONMENT'."

Step 4: Automate the Remote Workflow

The remote build steps don’t need to live outside your repo. Keep them version-controlled. Within the scripts folder:

#!/bin/bash
set -euo pipefail

# --- Load Node Version Manager (NVM) ---
export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"

cd /path/to/project

# --- Checkout correct branch based on environment ---
if [ "$1" = "prod" ]; then
    echo "🔄 Switching to main branch for production..."
    git checkout main
else
    echo "🔄 Switching to dev branch for $1..."
    git checkout dev
fi

# --- Update repository ---
echo "🔄 Pulling latest code..."
git pull

# --- Generate environment variable types (optional, if you use it) ---
echo "🔄 Generating environment types..."
pnpm generate:env-types

# --- Install dependencies ---
echo "📦 Installing dependencies..."
pnpm install --dangerously-allow-all-builds

# --- Build project ---
echo "🏗 Building for $1..."
pnpm build:$1

# --- Deploy project ---
echo "🚀 Deploying to $1..."
pnpm deploy:$1

In package.json, add:

{
  "scripts": {
    "build:remote": "bash scripts/remote-build.sh"
  }
}

Your scripts/remote-build-steps.sh handles:

Checking out the right branch
Pulling latest code
Installing dependencies
Building and deploying

Now every build run uses the version of the script committed in your repo — no drift, no surprises.

Lastly, we need a deploy script:

#!/bin/bash
set -euo pipefail
# ------------------------------------------------------------
# Deploy Script
# ------------------------------------------------------------
# Stops the app service on the remote host, syncs the latest
# build output and config files, installs dependencies, then
# restarts the service.
#
# Usage:
#   ./deploy.sh
# ------------------------------------------------------------

# --- Config ---
REMOTE_HOST=your-ssh-alias
REMOTE_DIR=/path/to/remote/app
SERVICE_NAME=your-service-name

# --- Stop service ---
ssh $REMOTE_HOST "sudo service $SERVICE_NAME stop"

# --- Sync build output ---
rsync -avzr --delete .next/standalone/ $REMOTE_HOST:$REMOTE_DIR \
  --exclude 'node_modules' \
  --exclude 'pnpm-lock.yaml'

# --- Copy env + package.json ---
scp .env.runtime $REMOTE_HOST:$REMOTE_DIR/.env
scp package.json $REMOTE_HOST:$REMOTE_DIR/package.json

# --- Install + restart ---
ssh $REMOTE_HOST "cd $REMOTE_DIR && pnpm i --dangerously-allow-all-builds && sudo service $SERVICE_NAME start"

# --- Cleanup ---
rm -f .env.runtime

This deploy script handles deployments by stopping the running service, syncing the latest build output and configuration, installing dependencies, and restarting the service. To make this work without constant password prompts, you’ll need to configure NOPASSWD entries in your sudoers file for starting and stopping the app service. This ensures deployments run smoothly and without manual intervention.

Here's an example of what that might look like:

# Allow user 'web' to manage the app service without password
web ALL=(ALL) NOPASSWD: /usr/sbin/service your-service-name start
web ALL=(ALL) NOPASSWD: /usr/sbin/service your-service-name stop
web ALL=(ALL) NOPASSWD: /usr/sbin/service your-service-name restart

Step 5: Test the Pipeline

Run from your local machine:

./scripts/remote-build.sh prod

Example output:

Checking for uncommitted git changes...
✅ Working directory clean.
▶️ Starting instance...
⏳ Waiting... done ✅
🌐 Instance at 3.88.192.42
🔄 Waiting for build.example.com... ready ✅
🔄 Syncing .env file...
🛠 Running remote build pipeline...
🔄 Checking out main branch...
📦 Installing dependencies...
🏗 Building for prod...
🚀 Deploying to prod...
🛑 Stopping instance...
⏳ Waiting... stopped ✅
🎉 Build + deploy complete for 'prod'.

That’s a full production build and deploy in minutes — and the server shuts itself down when done.

Step 6: Compare Costs

Here’s why this is better than GitHub Actions.

GitHub Actions:
- Linux runners: $0.008/minute
- A 30-minute build = $0.24
- 100 builds/month = $24.00
EC2 Build Server:
- c7i-flex.2xlarge: ~$0.60/hour
- A 10-minute build = $0.10
- 100 builds/month = $10.00

That’s less than half the cost — and your builds are faster.

Hidden Bonuses

Short builds save even more — A 5-minute build is ~$0.05.
Next.js Turbopack — With next build --turbopack, builds can be dramatically faster than Webpack, so you’ll pay pennies per run while getting near-instant build feedback.
No concurrency limits — Run multiple EC2s if you need parallel builds.
Faster cold starts — EC2 boots in ~30–60s, often faster than waiting for Actions to assign a runner.
Optional caching — Leave the instance running if you want dependency caches to persist between builds.

Thank You!

If you want to support me, please follow me on Spotify or SoundCloud!

Please also feel free to check out my Portfolio Site

Looking for a web developer? I'm available for hire! To inquire, please fill out a contact form.

Filling the Memory Gap: Building MCPMem to Fix AI Assistant Forgetfulness

Jay @ Designly — Fri, 29 Aug 2025 03:29:01 +0000

Filling the Memory Gap: Building MCPMem to Fix AI Assistant Forgetfulness

How I hacked together a semantic memory system for AI assistants with the Model Context Protocol

The Problem: Assistants With Goldfish Memory

You’ve probably run into this: you’re mid-project, bouncing ideas off Cursor, Claude, or whatever AI assistant you like. After hours of hashing through architecture choices and debugging strategies, you start a fresh session and… everything’s gone.

No history. No context. No sense of continuity. You’re left re-explaining the same project details that should have been “obvious” from earlier conversations.

That’s the context window problem. AI assistants don’t actually remember anything — they just replay what’s in the current conversation buffer. Once that buffer’s gone, so is your context.

Why the Current Fixes Don’t Cut It

Tools try to patch this problem, but none of them really solve it:

File context injection → fine for raw code, useless for design decisions
Project summaries → stale as soon as the code changes
Chat history → bounded by token limits and resets every new session
Manual notes → slow, brittle, not semantic

What we actually need is memory that sticks — and more importantly, memory that understands meaning instead of just matching keywords.

Introducing MCPMem!

That’s why I built it: a Model Context Protocol (MCP) server that gives AI assistants a way to store and retrieve memories semantically.

Why it’s different

Stores and searches by meaning (via OpenAI embeddings)
Persists across sessions (your assistant actually remembers)
MCP-native — integrates with any MCP-capable assistant
Fast vector search via SQLite + sqlite-vec
Minimal setup, works out of the box

It’s basically a lightweight memory layer you can drop in and instantly upgrade your assistant.

Under the Hood

1. Semantic Embeddings

Every memory gets embedded with OpenAI’s text-embedding-3-small, so searches return relevant context even if the words don’t match exactly.

2. SQLite Vector Search

Memories and embeddings live in SQLite with sqlite-vec. Queries come back in milliseconds, even across thousands of entries.

3. MCP Integration

Because it’s an MCP server, assistants can call it directly as part of the flow. Store, search, and retrieve are just standard MCP commands.

How It Feels in Practice

Project knowledge base: store architecture decisions, bug fixes, team agreements — pull them up later with semantic queries.
Learning log: stash notes, patterns, gotchas — search them when you hit similar problems.
Team memory: assistants can keep track of past discussions, design calls, and decisions without rehashing them.

Setup

It’s dead simple:

npm install -g mcpmem
export OPENAI_API_KEY=your-key-here
mcpmem store "Remember: use strict TypeScript mode"
mcpmem search "typescript config"

Or wire it into your MCP config for Cursor/Claude:

{
  "mcpServers": {
    "mcpmem": {
      "command": "npx",
      "args": ["mcpmem"],
      "env": {
        "OPENAI_API_KEY": "sk-svcacct-...",
        "OPENAI_MODEL": "text-embedding-3-small",
        "MCPMEM_DB_PATH": "/Users/johndoe/mcpmem/mcpmem.db"
      }
    }
  }
}

What Changed for Me

Before MCPMem

Explaining the same context repeatedly
Losing details between sessions
Wasting time writing notes I’d never search

After MCPMem

My assistant remembers context across chats
Semantic search brings back the right info fast
Project knowledge actually compounds over time

Lessons Learned

Semantic > keyword search. It feels like cheating once you’ve used it.
MCP is a surprisingly clean way to extend assistants.
You don’t need Pinecone or a massive vector DB — SQLite does just fine.
UX trumps everything. If memory isn’t seamless, you won’t use it.

Roadmap

Local embedding generation (no API calls needed)
Memory clustering and tagging
Import/export for team knowledge bases
Multi-modal memory (code, docs, images)

If you’re sick of AI tools that reset every conversation, MCPMem gives them something closer to real memory.

👉 GitHub repo
👉 NPM

Thank you for reading! Please visit my portfolio site when you have some free time!

https://yaa.bz

Also, read my blog:

https://blog.designly.biz

I post regular articles about full-stack development and systems administration.

Building a Multi-Modal GPT Agent in TypeScript with OpenAI

Jay @ Designly — Mon, 04 Aug 2025 00:52:53 +0000

OpenAI has made building multi-modal APIs a breeze by providing built-in function calling (they call it "tools"). You tell ChatGPT what it can do and what parameters it can use, and then it makes the decision on which tools to call and how to use them. It's absolutely amazing!

In this article, we're going to walk through building a multi-modal GPT agent in TypeScript using OpenAI’s API. We’ll use my open-source GPTAgent project as a foundation (link at bottom of article), explaining its purpose, architecture, and how to extend it with new capabilities. By the end, you’ll understand how to integrate OpenAI’s function-calling with custom tools, handle text/image/audio inputs, and build your own powerful CLI-based AI assistant.

Introduction

GPTAgent is an educational TypeScript/Node.js project that showcases how to augment a GPT-4 model with external tools via OpenAI’s function calling feature. In plain terms, it’s a command-line chatbot that can call functions to perform tasks such as fetching web pages, searching the web, checking the weather, and geocoding addresses. These tools act as the model’s “eyes and hands,” letting it retrieve live information and perform computations beyond its built-in knowledge. The project’s goal is to be small enough to understand yet complete enough to extend – making it a great starting point for building your own multi-modal agent.

What do we mean by “multi-modal”? In this context, it means the agent isn’t limited to plain text input/output. It can handle different modalities of information by invoking specialized tools. Text is the primary mode, but with the right tools, the agent can also work with images (e.g. analyzing an image file) or audio (e.g. transcribing speech). We’ll see how GPTAgent’s design supports this kind of extensibility.

Project Structure and Key Components

GPTAgent’s codebase is organized into clear components that each handle a piece of the system’s functionality:

CLI and Entry Point – A command-line interface gathers user input and displays the assistant’s responses with formatting.
OpenAI API Integration – A module that communicates with OpenAI’s Chat Completion API, sending conversation messages and available tool definitions (functions) for the model to use.
Tool Definitions & Registry – A registry where each external tool is defined (name, description, JSON schema for parameters) and paired with a handler function that executes the tool’s action.
Tool Bridge (Agent Orchestrator) – The “agent loop” that ties everything together: it feeds user prompts to the model, intercepts the model’s tool calls, executes them via the registry, and returns results back to the model until a final answer is produced.

Let’s explore each part in detail, with code snippets and explanations.

CLI and Entry Point

The entry point of the application is a simple script that starts the CLI loop. In src/index.ts, the agent checks for a prompt passed as a command-line argument. If found, it runs once and exits; otherwise it enters an interactive loop, repeatedly prompting the user for input until they type “.” to quit:

// src/index.ts
const prompt = process.argv[2];
if (prompt) {
  await runCli(prompt);
  process.exit(0);
}
while (true) {
  const input = await getUserInput('Enter your request (or "." to exit): ');
  if (input.trim() === '.') {
    process.exit(0);
  }
  await runCli(input);
}

In this loop, getUserInput() simply reads a line from stdin (using Node’s readline) and runCli() processes the request. The CLI is implemented in src/lib/client/cli.ts, which handles user interaction niceties:

It colors prompts and outputs using the chalk library for better readability.
It converts any HTML formatting from the assistant into ANSI-colored text using cli-html, since the model’s answers are formatted in HTML (more on that soon).
It maintains a conversation history in data/history.json on disk. This means each new question you ask is appended to a persistent history, so the agent remembers context across turns. (The history file is auto-created and updated on each response.)

When you run the CLI, you’ll see something like:

Enter your request (or "." to exit): How’s the weather in Tokyo today?

The CLI will then show a spinner (“Thinking…”) while the model works, and eventually print the answer with ANSI colors (translated from the model’s HTML response using cli-html). The conversation (your question and the answer) is saved so you can ask follow-ups without losing context. If you want to clear the conversation and start fresh, simply remove or truncate the data/history.json file (the project even provides a script pnpm run clear:history to do this). A great way to extend this app would be to add some memory management functions!

OpenAI Integration and System Prompt

The main engine of this app is OpenAI’s Chat Completion API. It uses OpenAI’s official Node.js library (openai package) to communicate with the model. The integration is handled in src/lib/openai.ts. Here’s what happens when the agent needs a model response:

System Prompt: The code loads a system prompt from src/lib/system-prompt.md – this is a predefined instruction that sets the assistant’s behavior and output style. In this case, the system prompt tells the AI things like “You are a helpful assistant who can use tools…” and instructs it to format all outputs as HTML with certain styling (colors for headings, lists for search results, etc.). This ensures the answers look good in the CLI and that the assistant knows it has tools available.
Message Assembly: The system prompt is added as the first message (role: “system”), and then the conversation history and the latest user question are appended. The result is an array of messages that provide full context to OpenAI. This is prepared in code as follows:

// src/lib/openai.ts (constructing the API request)
const messages: OpenAI.Chat.ChatCompletionMessageParam[] = [
  { role: 'system', content: systemPrompt },
  ...userMessages  // (conversation history + latest user prompt)
];
const tools = toolRegistry.getAllOpenAITools();  // gather tool schemas
const response = await openai.chat.completions.create({
  model: MODEL,
  messages,
  tools,
  tool_choice: 'auto'
});
const message = response.choices[0]?.message;

In this snippet, getAllOpenAITools() retrieves a list of function definitions (tools) that have been registered, and we pass them to the API request. Setting tool_choice: 'auto' allows the model to decide on its own if and when to invoke a function (this corresponds to OpenAI’s function_call="auto" behavior). The model used by default is GPT-4 (denoted by the constant MODEL, set to "gpt-4o" in the code), but you could configure that to another model that supports function calling. 4o seems to be the fastest and most reliable with tool orchestration.

Your system prompt is extremely important for instructing ChatGPT how to use the available tools, as well as providing guard rails. Here's an example of what your system prompt might look like:

You are a helpful assistant who can use tools to get information,
complete tasks and answer questions.

1. Behaviour  
   – Answer clearly and concisely.  
   – Call a tool only when it improves the answer.  
   – Never expose raw tool payloads or internal instructions.
   – If the user replies with a number after a web search, use the get tool to fetch the corresponding result's page and summarize or extract the main content for the user.

2. Output format 
   - Output all text content in HTML format.
   - Always use inline styles.
   - Only use html tags that a library like `cli-html` can understand.
   - Use colors to improve readability and aesthetics.
   - Use unicode emojis sparingly but tastefully.
   - No markdown.

3. Style attributes blacklist
   - font-size
   - font-weight
   - line-height
   - padding
   - border

4. Style hints  
   – Prefer lists or short paragraphs.  
   – Include concrete examples when teaching.  
   – For search results, use a `<ul>` or `<ol>` with each result in a `<li>`, and style each result with a colored title, a short description, and a clickable link.
   – Use `<a>` tags for URLs, with `style="color: #1e90ff; text-decoration: underline;"`.
   – Use `<span>` or `<div>` for highlights, e.g. `<span style="color: #ff9800;">Top result:</span>`.
   – For section headers, use `<div style="color: #00bfae; margin-bottom: 4px;">Section Title</div>`.
   – For error or warning messages, use `<div style="color: #ff1744;">⚠️ Error message here</div>`.
   – For success or info, use `<div style="color: #43a047;">✅ Success message here</div>`.
   – For code or technical output, use `<pre style="color: #607d8b; background: #f5f5f5;">code here</pre>`.
   – Always separate results with a small margin (e.g. `margin-bottom: 6px;`).
   – If showing multiple results, number them or use bullet points for clarity.
   – If showing suggestions, use a `<ul>` with each suggestion in a `<li>` and a subtle color (e.g. `color: #888`).

5. Example: Well-formatted search result

   <div style="color: #00bfae;">🔍 Top Web Results for "shrimp scampi recipe":</div>
   <ul>
     <li style="margin-bottom: 6px;">
       <a href="https://cafedelites.com/garlic-butter-shrimp-scampi/" style="color: #1e90ff; text-decoration: underline;">
         Garlic Butter Shrimp Scampi - Cafe Delites
       </a>
       <div style="color: #888;">Garlic Butter Shrimp Scampi can be enjoyed as an appetizer or main dish. Pair with pasta, zucchini noodles, or cauliflower!</div>
     </li>
     <li style="margin-bottom: 6px;">
       <a href="https://www.thepioneerwoman.com/food-cooking/recipes/a10039/16-minute-meal-shrimp-scampi/" style="color: #1e90ff; text-decoration: underline;">
         Easy Shrimp Scampi Recipe - The Pioneer Woman
       </a>
       <div style="color: #888;">This shrimp scampi recipe is light, fresh, and ready in just 15 minutes.</div>
     </li>
   </ul>
   <div style="color: #43a047;">Tip: Click a title to view the full recipe.</div>

6. General
   – Avoid dense blocks of text; break up information visually.
   – Use color and spacing to guide the user's eye.
   – Never use raw JSON or tool payloads in output.

Function (Tool) Calling: When OpenAI processes the request, it has the option to return a function call instead of a final answer. For example, if the user asked “What’s the weather in Tokyo?” the model might decide it needs to use the check_weather tool. In that case, the API response will indicate a function call (with the tool name and arguments) rather than a text answer. The app will detect this and handle it through the tool bridge (explained next). If the model doesn’t need any tool and can answer from its knowledge, it will just return a normal answer immediately. But since the weather is ephemeral, we will need to make some API requests.
API Requests: Since the openmeteo API only accepts latitude and longitude coordinates, we must first use the geocode tool the convert our location search to coordinates. Amazingly, ChatGPT handles this intuitively. It can deduce based on the tool definitions and the parameters they can accept that this order of operations must occur.
HTML Output: Notably, the system prompt tells the model to output answers in HTML format with specific inline styles. This is purely for formatting in the terminal. The CLI converts that HTML into colored console text. (For example, search results are formatted as a list with blue underlined links, warnings are red, etc., according to the guidelines in the prompt.) This is a nice touch to make the CLI output more readable, but it doesn’t affect the logic of tool usage. This is a sort of hack because I could not get ChatGPT to output ANSI colors and other CLI formatting.

Debugging: If you set an environment variable DEBUG=1, GPTAgent will log detailed debug info from tool handlers to a debug.log file. This can be useful to see what URLs were fetched or what data was returned by an API call during a tool execution. The logging is done via a helper printLog() which checks process.env.DEBUG and appends messages to the log file.

Tool Definitions and the Registry

What glues everything together are the tools. A tool is essentially a function that the AI can call. Each tool has two parts: a definition (metadata describing the tool for the AI, including its name, description, and JSON schema for parameters) and a handler (the TypeScript function that actually runs when the tool is invoked). Each tool has it's own directory making the tool system modular and extensible.

All tools live under src/lib/tools/ in the repository. Let’s break down how a tool is defined and registered.

Tool Definition: Our app provides a couple of helper functions to define tools easily. For example, here is a simplified version of the “Get Web Page” tool definition (get) which fetches a web page’s HTML:

// src/lib/tools/get/def.ts
export interface GetPageParams { url: string; }
export interface GetPageReturn { url: string; html: string; error?: string; }

export const getTool = createToolType<GetPageParams, GetPageReturn>(
  'get',
  'Fetch the HTML content of a web page using Playwright. Input a URL and receive the full HTML.',
  createOpenAIToolSchema(
    'get',
    'Fetch the HTML content of a web page using Playwright. Input a URL and receive the full HTML.',
    {
      url: { type: 'string', description: 'The URL of the web page to fetch.' }
    },
    ['url']
  )
);
export { getHandler } from './handler';

Let’s unpack this snippet:

We define TypeScript interfaces for the tool’s input parameters and return value (GetPageParams and GetPageReturn in this case). Here, the tool takes a single string parameter url and will return either the page’s html content (plus the final url and an optional error message).
We call createToolType<Params, Return>(name, description, openaiToolSchema) to create the tool object. The name is how the model refers to the tool ("get" in this case), and the description is a brief instruction for the model about what the tool does. This description is important – the model uses it to decide when a tool might be relevant.
We generate an OpenAI tool schema via createOpenAIToolSchema(...). This produces a JSON schema object describing the function’s expected parameters. We provide:
- The same name and a more detailed description.
- A properties object defining each parameter (here, just url of type string).
- A required list (here, ['url'] to mark that parameter as required).

This schema follows OpenAI’s function calling format – effectively it’s what gets sent in the API call so the model knows the function signature.

Finally, we export the tool (getTool) and also re-export the corresponding handler for convenience. (We’ll see handlers next.)

Under the hood, the tool definition is stored as a ToolType object which includes the openaiTool (JSON schema) along with the name and description. Later, when we register the tool, the registry will extract openaiTool to send to OpenAI, and keep track of the actual handler function to call when needed.

Tool Handler: The handler is the function that performs the tool’s action. It must match the signature ToolHandler<Params, Return> – essentially a function that takes the parameters and returns (or resolves to) the result object. Handlers can be asynchronous (and most are, since they often call external APIs).

For our get example, the handler uses Playwright (a headless browser) to fetch the page content. It blocks images, styles, and other assets for efficiency, and if the page text is very large, it uses Mozilla’s Readability library to extract the main text content. A brief snippet:

// src/lib/tools/get/handler.ts (simplified)
export const getHandler: ToolHandler<GetPageParams, GetPageReturn> = async ({ url }) => {
  printLog(`🌐 Connecting to ${url}`);
  try {
    const { chromium } = await import('playwright');
    const browser = await chromium.launch({ headless: true });
    const context = await browser.newContext();
    // Block images, styles, etc. to focus on text content
    await context.route('**/*', route => {
      const type = route.request().resourceType();
      return ['image', 'stylesheet', 'font', 'media'].includes(type)
        ? route.abort() : route.continue();
    });
    const page = await context.newPage();
    await page.goto(url, { waitUntil: 'domcontentloaded', timeout: 20000 });
    const textContent = await page.evaluate(() => document.body.innerText.trim());
    const title = await page.title();
    await browser.close();
    // If content is very long, extract readable portion
    const finalText = textContent.length > 45000
      ? await extractReadable(await page.content())
      : textContent;
    printLog('🌐 Extracted', `${(finalText.length/1024).toFixed(1)} KB text`);
    return { url, html: finalText, meta: { title } };
  } catch (err) {
    const msg = err instanceof Error ? err.message : String(err);
    printLog('🌐 Error:', msg);
    return { url, html: '', error: msg };
  }
};

(The actual code is more extensive, but this gives an idea. It launches a browser, fetches the URL, and returns the page text.)_ The key point is that the handler does the real work, and returns a JavaScript object containing the result data. The assistant never sees this raw object directly; instead, the result will be fed back into the model in the conversation (after being JSON-stringified, as we’ll see in the tool bridge logic).

The app comes with several built-in tools, each defined and implemented similarly:

web_search – Uses a local SearxNG meta-search instance to perform web searches (so as not to rely on Google’s API directly). It returns a list of search results, and the assistant is instructed to ask the user to pick one if needed.
get – (As shown above) fetches the content of a webpage via Playwright.
check_weather – Uses Open-Meteo’s API to get current weather for a location. This actually first does a geocoding lookup (to convert city names to coordinates) and then retrieves weather data. It can handle ambiguous locations by returning multiple matches for the user to clarify.
forward_geocode / reverse_geocode – These call a geocoding API (maps.co) to convert addresses to coordinates or vice-versa. They require an API key (provided via GEOCODE_API_KEY in your .env file) and demonstrate simple REST API usage via fetch().

All these tool definitions are registered in one place, which we’ll discuss next.

Tool Registry: GPTAgent maintains a registry (in src/lib/tool-registry.ts) to keep track of available tools. The ToolRegistryManager class has methods to register a tool, execute a tool by name, and retrieve the list of OpenAI tool schemas to send to the API:

// src/lib/tool-registry.ts (key parts)
class ToolRegistryManager {
  private registry: Map<string, ToolRegistryEntry> = new Map();
  register(tool: ToolType, handler: ToolHandler) {
    this.registry.set(tool.name, { tool, handler });
  }
  execute(name: string, params: ToolParameters): Promise<ToolExecutionResult> {
    const entry = this.registry.get(name);
    if (!entry) {
      return { success: false, error: `Tool '${name}' not found` };
    }
    try {
      const result = await entry.handler(params);
      return { success: true, data: result };
    } catch (error) {
      return { success: false, error: error.message || String(error) };
    }
  }
  getAllOpenAITools(): ChatCompletionTool[] {
    return Array.from(this.registry.values()).map(entry => entry.tool.openaiTool);
  }
  // ... (other helper methods)
}
export const toolRegistry = new ToolRegistryManager();

When we register a tool, we give it the ToolType (which contains the name & schema) and the handler function. The registry stores them together in a map keyed by tool name. Later, to execute a tool call, we just look up by name and invoke the handler with the provided parameters. The result is wrapped in a { success: ..., data: ... } or an error message, which will be passed back to the AI.

The registry also provides getAllOpenAITools(), which as we saw collects all tool schemas to send in the API request.

The Tool Bridge (Agent Orchestration Loop)

Now we come to the core “agent loop” that coordinates between the language model and the tools. GPTAgent’s Tool Bridge (implemented in src/lib/tool-bridge.ts) is essentially the controller that manages the conversation flow with the model, intercepts any tool requests, executes them, and feeds results back until the model is ready to give the final answer.

Key aspects of the Tool Bridge:

It’s a singleton class (ToolBridge.getInstance() ensures only one instance) – this avoids re-initializing tools multiple times.
An initialize() method registers all the built-in tools with the registry once. In our project, initialize() is called at the start of each CLI run (see toolBridge.initialize() in runCli(). The registration looks like:

// During ToolBridge.initialize()
toolRegistry.register(checkWeatherTool, checkWeatherHandler);
toolRegistry.register(forwardGeocodeTool, forwardGeocodeHandler);
toolRegistry.register(reverseGeocodeTool, reverseGeocodeHandler);
toolRegistry.register(webSearchTool, webSearchHandler);
toolRegistry.register(getTool, getHandler);
console.log('🔧 Assistant Bridge initialized with tools:', toolRegistry.getAllToolNames());

This simply loads each tool’s definition and handler, and stores them in the registry After initialization, the set of tools is fixed for that run (in the future, one could imagine dynamic plugins, but not in this simple design).

The conversation loop: The main method runAssistantWithTools(messages) implements a loop that repeatedly calls the OpenAI API and responds to tool requests. Pseudocode for this loop is:

Send the current messages (system prompt + history + latest user query + any tool results so far) to OpenAI.
Get the assistant’s response.

- If the response includes any tool calls, for each call: execute the tool via the registry and capture the result.

- Append the assistant’s tool call **message** and the tool’s result message to the conversation.

- Loop back to step 1 with the updated conversation (so the model can now see the results of the tool and decide what to do next).

If the response has no tool call (i.e. it’s a final answer), break the loop and return that answer.

In code, it looks like this (simplified for clarity):

// src/lib/tool-bridge.ts
async runAssistantWithTools(messages: ChatCompletionMessageParam[]): Promise<ChatCompletionMessageParam> {
  this.initialize();  // ensure tools are registered
  let currentMessages = messages;
  while (true) {
    const assistantResponse = await runAssistant(currentMessages);
    if (assistantResponse.tool_calls && assistantResponse.tool_calls.length > 0) {
      // The model wants to use one or more tools
      const toolResults: ToolResultMessage[] = [];
      for (const toolCall of assistantResponse.tool_calls) {
        const result = await this.executeToolCall(toolCall);
        toolResults.push(result);
      }
      // Append the function call and its result to the conversation
      currentMessages = [
        ...currentMessages,
        assistantResponse,
        ...toolResults
      ];
      // Loop again, now with tool results included, to get next response
    } else {
      // No more tool calls; this is the final answer
      return assistantResponse;
    }
  }
}

The loop continues as long as the AI requests more tools, allowing multi-step tool use. It’s a simple form of an agent, orchestrating between the AI planner (the GPT model) and the execution environment (our tool handlers). The user does not see any of the intermediate JSON – they only see the final HTML-formatted answer, which often incorporates the retrieved information (e.g. quoting a snippet from a web page or reporting the weather result).

Getting Started: Installation and Usage

Now that we’ve covered how the system works, you might want to try it out or integrate it into your own project. Here’s how to get GPTAgent up and running locally:

Prerequisites: You’ll need Node.js (v18+) and PNPM (the package manager) installed. GPTAgent also uses Docker to run the SearxNG search engine locally, so install Docker and Docker Compose (Docker Desktop on Windows/Mac works). Ensure Docker is running before you start the agent.
Clone the Repository: Grab the code from GitHub:

git clone https://github.com/designly1/gptagent.git cd gptagent

Install Dependencies: The project uses PNPM. Install the Node packages and required browser binaries for Playwright:

pnpm install       # install all NPM dependencies (or "pnpm add" as per project docs)
pnpm exec playwright install  # set up Playwright (installs browser engines)

Set Up Environment Variables: Copy or create a .env file in the project root (there’s an example in the docs) and provide your API keys and settings:

# .env file
OPENAI_API_KEY="sk-..."           # **required** for OpenAI API
GEOCODE_API_KEY="..."             # required for geocoding tools (get from maps.co or Open-Meteo)
SEARXNG_HOSTNAME=localhost        # SearxNG search config (if using the provided Docker, use these defaults)
SEARXNG_BASE_URL=http://localhost:8080/
SEARXNG_SECRET=<32_char_hex_key>  # set a secret key for SearxNG API access
DEBUG=0                           # set to 1 to enable debug logging (optional)

The OPENAI_API_KEY is mandatory – you can get one from your OpenAI account. The other keys are for specific tools: GEOCODE_API_KEY for the weather/geocoding (Open-Meteo’s geocoding requires a free API key), and the SearxNG settings are prefilled if you use the included Docker setup. Make sure to provide a 32-character secret (you can generate one with openssl rand -hex 16 on Linux/Mac.

Now we can launch the CLI in development mode:

pnpm dev

The dev script will spin up the Docker container for SearxNG (for web search) and then start the Node.js CLI tool. You should see Docker pulling/updating the SearxNG image on first run. Once running, the prompt Enter your request: will appear.

Try typing a question or command for the agent. For example:

Enter your request: Search the web for "TypeScript VS Code tips" and give me a summary.

The assistant will likely use the web_search tool (you’ll briefly see a “Thinking...” spinner) and then possibly fetch a result with get. Finally, it will print an answer with a list of top results or a summary. The text may be colored and formatted according to the system prompt’s HTML rules.

You can also run a one-off command without interactive mode by providing it as an argument. For example:

pnpm dev "What's the weather in Tokyo and who is the mayor of Tokyo?"

This will run the agent for that single prompt, print the answer, and exit (shutting down the Docker container afterward).

Conversation Persistence: As mentioned, the agent remembers past conversation turns by reading/writing data/history.json. If you run another prompt (in interactive mode or separate calls), it will include your previous Q&A as context. This is useful for follow-up questions. If you want to reset context, you can delete that file or run pnpm run clear:historyGitHub to clear it.
Testing: The repository includes a very minimal test setup (using Vitest) as a placeholder. Running pnpm test will execute any tests. Currently, there’s just a dummy test fileGitHub, but you can write your own tests for new tools or functionalities you add.

With the agent up and running, you have a baseline multi-modal GPT assistant. It already handles text-based web and API queries. Next, we’ll explore how to extend it to new modalities like images and audio.

Extending the Agent with New Tools (e.g. Image and Audio Support)

One of the best aspects of GPTAgent’s design is how straightforward it is to add new tools. By creating and registering a new tool, you can teach the AI to handle new kinds of input or perform new tasks – making the agent more multi-modal. Let’s walk through an example of adding an Image Captioning tool that allows the assistant to analyze an image file and describe it. We’ll also discuss how you could add an Audio Transcription tool in a similar way.

Example: Adding an Image Analysis Tool

Suppose we want the agent to handle user requests like “Describe what’s in the image at ./cat_photo.jpg.” We can create a tool called caption_image that takes a file path to an image and returns a textual description of that image.

1. Define the Tool (name, input, output) – Create a new directory src/lib/tools/image-caption/ and add a def.ts file for our tool definition:

// src/lib/tools/image-caption/def.ts
import { createToolType, createOpenAIToolSchema } from '@/lib/tool-utils';
import type { ToolType } from '@/lib/types';

export interface ImageCaptionParams { imagePath: string; }
export interface ImageCaptionResult { caption: string; }

export const imageCaptionTool: ToolType<ImageCaptionParams, ImageCaptionResult> =
  createToolType<ImageCaptionParams, ImageCaptionResult>(
    'caption_image',  // tool name
    'Analyze an image file and return a descriptive caption.',
    createOpenAIToolSchema(
      'caption_image',
      'Analyze an image file and return a descriptive caption.',
      {
        imagePath: {
          type: 'string',
          description: 'Path to an image file to analyze (local path or URL).'
        }
      },
      ['imagePath']
    )
);
export { imageCaptionHandler } from './handler';

Here we define the expected input (imagePath) and output (caption). The OpenAI schema tells the model that this function exists, its purpose, and that it requires a string path to an image file. We keep the name and descriptions clear so the model will know when to use it (for instance, if it sees words like “image” or “photo” in the user query, it might consider this tool).

2. Implement the Tool Handler – Next, in src/lib/tools/image-caption/handler.ts, we write the actual logic for generating a caption from an image. This could be done in various ways: calling an external API, using a pre-trained model, or even leveraging OpenAI’s image capabilities (though as of this writing the image-to-text capability of GPT-4 is not widely available via API). For our example, let’s assume we have a function generateCaptionForImage(buffer) that returns a caption string (you would implement this with an ML library or an API like Azure Cognitive Services, AWS Rekognition, or a local ML model).

// src/lib/tools/image-caption/handler.ts
import fs from 'fs';
import type { ToolHandler } from '@/lib/types';
import type { ImageCaptionParams, ImageCaptionResult } from './def';

export const imageCaptionHandler: ToolHandler<ImageCaptionParams, ImageCaptionResult> =
  async ({ imagePath }) => {
    // Read the image file (binary)
    const fileData = fs.readFileSync(imagePath);
    if (!fileData) {
      throw new Error(`Image file not found: ${imagePath}`);
    }

    // TODO: call your image analysis function or API.
    // For example, this could be an API call:
    // const caption = await callImageCaptionAPI(fileData);
    // Or a local ML model inference:
    // const caption = runLocalModelOnImage(fileData);
    const caption = "<description of the image>";

    return { caption };
};

This handler reads the file from disk (note: in a real scenario, you should handle errors and maybe file size limits). It then passes the data to some caption-generating process. Here we left it as a placeholder – you could integrate an API like CLIP+GPT, or a pretrained captioning model. The output is a simple object { caption: "...text..." }.

3. Register the Tool – With the definition and handler created, the last step is to register this new tool in the Tool Bridge so the agent knows about it. Open src/lib/tool-bridge.ts and find the initialize() method where other tools are registered. Add a line for caption_image:

 async initialize(): void {
   if (this.isInitialized) return;
   toolRegistry.register(checkWeatherTool, checkWeatherHandler);
   toolRegistry.register(forwardGeocodeTool, forwardGeocodeHandler);
   toolRegistry.register(reverseGeocodeTool, reverseGeocodeHandler);
   toolRegistry.register(webSearchTool, webSearchHandler);
   toolRegistry.register(getTool, getHandler);
+  toolRegistry.register(imageCaptionTool, imageCaptionHandler);
   console.log('🔧 Assistant Bridge initialized with tools:', toolRegistry.getAllToolNames());
   this.isInitialized = true;
 }

Now our tool is part of the agent’s repertoire. The next time you run the CLI, the toolRegistry.getAllToolNames() output should include "caption_image" as well.

4. Run and Test – Rebuild or restart the agent (pnpm dev again). Try a prompt that involves an image. For example:

Enter your request: I have an image at "./test-images/cat.jpg". Describe what's in the image.

When GPT-4 sees this prompt and the list of available tools, it will likely choose to call caption_image (because the tool’s description fits the request). The function call might look like: caption_image({"imagePath": "./test-images/cat.jpg"}). The agent will execute our handler, which reads the file and returns a caption like "A small grey cat sitting on a windowsill." (assuming our caption generator did that). The model then receives that result and can incorporate it into the final answer it returns to the user, for instance:

“It looks like the image contains a small grey cat sitting on a windowsill, looking out at the view 😊.”

Congratulations – you’ve just extended the agent to handle images! 🎉

Note on file paths and modalities: In a CLI environment, providing an image or audio file to the agent typically means supplying a file path or URL that the tool can access. In our example, we used a local file path. You could also design the tool to accept an image URL (and then have the handler fetch that URL and analyze the image bytes). This might be easier if you expect users to provide links. For audio, similarly, a tool could accept a file path or URL to an .mp3/.wav file.

Adding an Audio Transcription Tool (Whisper example)

Following the same pattern, you can add an audio tool. Let’s briefly outline a transcription tool using OpenAI’s Whisper (speech-to-text):

Define a transcribe_audio tool with a parameter like audioPath: string and return type { transcript: string; }.
Implement the handler to read the audio file and call OpenAI’s transcription API. The OpenAI Node library supports this via openai.audio.transcriptions.create() – you’d pass the file buffer and model (e.g. "whisper-1"). This returns a text transcript.
Register transcribe_audio in the Tool Bridge.

Now your agent can handle requests like “Here’s an audio clip of a meeting (./meeting.mp3); summarize what was discussed.” The model would call transcribe_audio on the file, get the text transcript, then possibly use other tools or its own capabilities to summarize it, and finally respond with a summary to the user. This chains multiple modalities: audio input → text transcript (via tool) → answer.

General Tips for New Tools

Keep Tool Descriptions Precise: The tool’s name and description should clearly indicate its purpose. The AI decides to use a tool based on how well the user’s request matches that description. Avoid overly broad descriptions; be specific about when it should be used (e.g. “transcribe an audio file to text” or “fetch stock prices given a ticker symbol”).
Parameter Schema: Define the JSON schema carefully. Use required fields appropriately and validate types in your handler. The model will provide arguments that match this schema. If something is missing or invalid, your handler should handle it (e.g. throw an error or return an error message object, which the assistant can then relay as an apology or prompt for correction).
Security and Access: Be mindful of what you allow the AI to do. Tools that access the file system (like our image example) should be constrained (perhaps only allow certain directories) to avoid any unwanted access. Similarly, if exposing internet access or other powerful capabilities, consider the implications and possibly implement safeties or user confirmation steps.
Testing Tools: It’s a good idea to test your tool handlers in isolation. You can call them directly in a Node REPL or write a small unit test to ensure they work (for example, feed a sample image to imageCaptionHandler and see that it returns a sensible caption). Once the handler logic is solid, test it via the AI by asking in the CLI – sometimes you may need to tweak the tool description to get the model to use it reliably.

By following the pattern of the existing tools, you can continue to extend your GPT agent with all sorts of functionality: database queries, sending emails, controlling IoT devices, and so on. Each new modality or capability just requires wrapping it as a function that the AI can invoke.

Next Steps and Resources

With your multi-modal GPT agent up and running, there are plenty of directions to explore from here:

Experiment with the Existing Tools: Try queries that combine tools. For example, “Find the current weather in Paris and then search the web for local news in Paris.” This might invoke both the weather and search tools in one go. Studying the model’s chain-of-thought (visible if you check debug.log or add logging) can be enlightening.
Add More Modalities: We showed examples for image captioning and audio transcription. You could also add an image generation tool (using OpenAI’s DALL-E API or Stable Diffusion via an API) to create images from text prompts. Another idea is a text-to-speech tool to have the assistant read out answers (using, say, Amazon Polly or Google TTS). Each new capability makes the agent more interactive and useful.
Enhance Memory or Context: The current implementation keeps a simple JSON log of the entire conversation and sends it in every request. This works for short sessions, but for longer ones you might hit context length limits. Consider integrating a vector database to store and retrieve summary embeddings, or implement a strategy to summarize old parts of the conversation.
Interface and Deployment: The CLI is merely for demonstration purposes, but you could wrap this agent in a web server (express.js) to provide a web UI or an API endpoint. Dockerizing the whole app (along with SearxNG) could make it easier to deploy. Since GPTAgent is open source, you can also fork the repository and customize it to your needs.

Further Reading & Resources:

The full source code of GPTAgent is available on GitHub. It’s well-documented with a detailed README that echoes much of what we discussed, and inline comments in code for deeper insight. Exploring the code is one of the best ways to learn how it works.
OpenAI Function Calling Documentation – Understanding how OpenAI’s API handles function (tool) calling is crucial. Read OpenAI’s guide on function calling to see how it expects function definitions and how the model decides to call them. GPTAgent’s approach is built around these principles.
OpenAI Whisper API – If you plan to integrate audio, check out OpenAI’s Whisper for speech-to-text. The Whisper API docs show how to send audio files for transcription.
Playwright & Web Scraping – The get tool uses Playwright. If you want to modify or extend web browsing (for example, allowing JavaScript execution or handling login for certain sites), see Playwright’s documentation for capabilities. Just be mindful of terms of service when scraping content.
Multi-modal ML Models – Keep an eye on developments in GPT-4’s vision abilities. In the future, OpenAI might allow direct image inputs to the model. When that happens, some of our tool-based approaches (like the image caption tool) might be replaceable with a direct model call. Until then, the tool approach is a powerful way to bridge that gap.

Thank You!

If you want to support me, please follow me on Spotify or SoundCloud!

Please also feel free to check out my Portfolio Site

Looking for a web developer? I'm available for hire! To inquire, please fill out a contact form.

Use React-Email to Send Beautiful Emails in Sveltekit

Jay @ Designly — Fri, 20 Jun 2025 17:25:46 +0000

Let's face it, creating email templates is a pain. 😩 Only God know why email clients don't simply follow modern web standards (for styling anyway). For this reason, many devs opt to outsource this to services that provide both no-code email templates as well as mass distribution services. But that's a terrible waste of money. You can do it yourself!

For React / Next.js users, there is a fantastic package called react-email that allows crafting emails from a set of standard (headless) components that you can fully style with plain css, styled components or even TailwindCSS. React-email takes the guess work out of remembering the complex system of tables and ridiculous gymnastics needed to craft emails that will look both beautiful as well as consistent in all email clients.

There's a new player in town in the full-stack web framework market called Sveltekit. Well, it's not exactly new. It's now on major version 5. I call it new in the sense that I now consider it fully production ready. In the following months and years, I truly believe we are going to see a mass exodus of React / Next.js developers migrating to Sveltekit. It's unbelievably fast and ships far less code to the client--and it's just so much fun to use!

One of the current problems that Sveltekit is facing is it's going through some growing pains. There were a lot of breaking changes in the 4 to 5 transition that caused many of the NPM packages for Svelte/Sveltekit to become broken as well. Some of these packages have also been all but abandoned by their creators, which is, unfortunately, an all-to-common occurrence. One of the aforementioned packages was svelte-email, the Sveltekit-equivalent of react-email. Too bad.

But I have some great news: running React inside of Sveltekit (even server side) is super easy! I know, it's mind-blowing right? 🤯

So with that being said, in this tutorial, I'm going to show you how to:

Bootstrap a fresh Sveltekit project
Install React and React-email dependencies
Use AWS Simple Email Service to send our email for nearly free

A couple of things to bear in mind, though, before we begin: this project is designed to work only on Node.js servers. This will not work using Sveltekit-Cloudflare adapter. It may work on Vercel, but I have not tested it. Links to the demo project source code and other resources are available at the bottom of this article.

Ok, let's get started!

Bootstrapping Sveltekit

Whether you're new to Sveltekit or have previous experience with it, there is a new CLI tool called sv that is recommend by Sveltekit to spin up a new project. It's as easy as:

pnpx sv create svelte-react-email

It will provide you with a series of options. The one's I'm using for this project is:

Sveltekit minimal
Yes, using Typescript syntax
prettier
eslint
tailwindcss
sveltekit-adapters
devtools-json
adapter: node
pnpm

Install Dependencies

We'll need React, React-Email and AWS to create our email system:

pnpm i react react-email @react-email/components @react-email/render \
@aws-sdk/client-ses

And if you're using Typescript:

pnpm i -D @types/node @types/react

React-email does use the sharp library to render emails, so you may get an approve-builds notice when using pnpm.

Next we need to tell Typescript that we're using React JSX. Add the following to your tsconfig.json:

{
    "jsx": "react-jsx"
}

Lastly, let's create a .env file to hold our AWS credentials:

AWS_ACCESS_KEY_ID="your key ID"
AWS_SECRET_ACCESS_KEY="your secret access key"

After adding environment variables in Sveltekit, you'll want to run pnpm prepare, which creates both types as well as an importable constant to use in your code, which I personally think is a much better (and more type-safe) system.

Creating our Mailing Library

Let's create a new file in src/lib/server/email.tsx:

import React from 'react';
import { render } from '@react-email/render';
import CodeEmail from '../emails/CodeEmail';

import { SendEmailCommand, SESClient } from '@aws-sdk/client-ses';

import { AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY } from '$env/static/private';

function getClient() {
    return new SESClient({
        credentials: {
            accessKeyId: AWS_ACCESS_KEY_ID,
            secretAccessKey: AWS_SECRET_ACCESS_KEY
        },
        region: 'us-east-2'
    });
}

const Source = 'ACME Inc. <noreply@example.com>';

interface SendCodeEmailProps {
    email: string;
    code: string;
    intro?: string;
}

export async function sendCodeEmail({ email, code, intro }: SendCodeEmailProps) {
    const client = getClient();
    const html = await render(<CodeEmail code={code} intro={intro} />);
    const command = new SendEmailCommand({
        Source,
        Destination: {
            ToAddresses: [email]
        },
        Message: {
            Subject: {
                Data: 'Your XiSMS Code'
            },
            Body: {
                Html: {
                    Data: html
                }
            }
        }
    });
    const response = await client.send(command);
    return response;
}

interface SendEmailProps {
    email: string;
    subject: string;
    reactComponent: React.ReactElement;
}

export async function sendEmail({ email, subject, reactComponent }: SendEmailProps) {
    const client = getClient();
    const html = await render(reactComponent);
    const command = new SendEmailCommand({
        Source,
        Destination: {
            ToAddresses: [email]
        },
        Message: {
            Subject: {
                Data: subject
            },
            Body: {
                Html: {
                    Data: html
                }
            }
        }
    });
    const response = await client.send(command);
    return response;
}

This will give us a function that we can simply pass our recipients, subject and React-Email component to to send our emails.

Creating Email Components

Now that our mailing library is complete and ready to accept and send emails, the next step is to create a template that we will reuse for all our emails:

// src/lib/emails/EmailTemplate.tsx

import { Html, Container, Section, Text } from '@react-email/components';
import React from 'react';

interface EmailTemplateProps {
    children: React.ReactNode;
}

export default function EmailTemplate({ children }: EmailTemplateProps) {
    return (
        <Html lang="en">
            <Section style={{ backgroundColor: '#1a202c', color: '#fff', padding: '40px 0' }}>
                <Container
                    style={{
                        maxWidth: 600,
                        margin: '0 auto',
                        background: '#2d3748',
                        borderRadius: 8,
                        boxShadow: '0 2px 8px rgba(0,0,0,0.08)',
                        padding: 32
                    }}
                >
                    {/* Header */}
                    <Section
                        style={{ borderBottom: '1px solid #334155', paddingBottom: 16, marginBottom: 32 }}
                    >
                        <Text style={{ fontSize: 24, fontWeight: 'bold', color: '#60a5fa', margin: 0 }}>
                            ACME Inc
                        </Text>
                    </Section>
                    {/* Main Content */}
                    {children}
                    {/* Footer */}
                    <Section style={{ borderTop: '1px solid #334155', marginTop: 40, paddingTop: 16 }}>
                        <Text style={{ fontSize: 12, color: '#94a3b8', margin: 0 }}>
                            © {new Date().getFullYear()} ACME Inc. All rights reserved.
                        </Text>
                        <Text style={{ fontSize: 12, color: '#94a3b8', margin: 0 }}>
                            <a
                                href="https://example.com/terms"
                                style={{ color: '#94a3b8', textDecoration: 'underline', marginRight: 12 }}
                            >
                                Terms
                            </a>
                            <a
                                href="https://example.com/privacy"
                                style={{ color: '#94a3b8', textDecoration: 'underline', marginRight: 12 }}
                            >
                                Privacy
                            </a>
                            <a
                                href="https://example.com/contact"
                                style={{ color: '#94a3b8', textDecoration: 'underline' }}
                            >
                                Contact
                            </a>
                        </Text>
                    </Section>
                </Container>
            </Section>
        </Html>
    );
}

Now that we have a template with our header and footer, let's create an email for sending one-time codes:

// src/lib/emails/CodeEmail.tsx

import { Section, Text, Container } from '@react-email/components';
import EmailTemplate from './EmailTemplate';
import React from 'react';

interface CodeEmailProps {
    intro?: string;
    code: string;
}

export default function CodeEmail({ intro, code }: CodeEmailProps) {
    return (
        <EmailTemplate>
            <Section>
                <Container>
                    {intro && <Text style={{ fontSize: 18, marginBottom: 32 }}>{intro}</Text>}
                    <Text style={{ fontSize: 18, marginBottom: 10 }}>Your code is:</Text>
                    <Text
                        style={{
                            fontSize: 32,
                            fontWeight: 'bold',
                            letterSpacing: 2,
                            color: '#fff',
                            background: '#1e293b',
                            padding: '16px 32px',
                            borderRadius: 6,
                            display: 'inline-block',
                            marginBottom: 32
                        }}
                    >
                        {code}
                    </Text>
                    <Text style={{ fontSize: 14, color: '#cbd5e1', marginTop: 16 }}>
                        If you did not request this code, you can safely ignore this email.
                    </Text>
                </Container>
            </Section>
        </EmailTemplate>
    );
}

Testing

Ok, that wasn't too painful, was it? Now let's create a simple form in Svelte with a server-side form action to test our email:

<script lang="ts">
    // src/routes/+page.svelte

    import { enhance } from '$app/forms';
    import { cn } from '$lib/css-tools';

    let { form } = $props();
    let email = $state('');
    let loading = $state(false);
    let success = $state('');
</script>

<div class="flex flex-col justify-center items-center bg-gray-50 p-4 min-h-screen">
    <div class="bg-white shadow-lg p-8 rounded-lg w-full max-w-md text-center">
        <h1 class="mb-4 font-bold text-gray-900 text-3xl">Email Testing Dashboard</h1>
        <p class="mb-8 text-gray-600">
            Use this interface to test your email templates and sending functionality.
        </p>

        <form
            method="POST"
            use:enhance={() => {
                loading = true;
                success = '';
                return async ({ result, update }) => {
                    await update();
                    console.log(result);
                    if (result.type === 'success' && result.data?.success) {
                        success = 'Email sent successfully';
                    }
                    loading = false;
                };
            }}
            class="flex flex-col gap-4"
        >
            <input type="email" name="email" placeholder="joe@example.com" bind:value={email} />
            <button
                type="submit"
                class={cn(
                    'flex items-center justify-center rounded-lg bg-blue-600 px-6 py-3 hover:bg-blue-700',
                    'font-medium text-white focus:ring-2 focus:ring-blue-500 focus:ring-offset-2 focus:outline-none',
                    'transition-colors duration-200',
                    {
                        'cursor-not-allowed opacity-50': loading
                    }
                )}
                disabled={loading}
            >
                {#if loading}
                    <svg class="mr-3 w-5 h-5 text-white animate-spin" viewBox="0 0 24 24">
                        <circle
                            class="opacity-25"
                            cx="12"
                            cy="12"
                            r="10"
                            stroke="currentColor"
                            stroke-width="4"
                            fill="none"
                        />
                        <path
                            class="opacity-75"
                            fill="currentColor"
                            d="M4 12a8 8 0 018-8V0C5.373 0 0 5.373 0 12h4zm2 5.291A7.962 7.962 0 014 12H0c0 3.042 1.135 5.824 3 7.938l3-2.647z"
                        />
                    </svg>
                    <span>Loading...</span>
                {:else}
                    <span>Send Test Email</span>
                {/if}
            </button>
            {#if success}
                <p class="text-green-500">{success}</p>
            {/if}
            {#if form?.error}
                <p class="text-red-500">{form.error}</p>
            {/if}
        </form>
    </div>
</div>

And lastly, our action handler:

// src/routes/+page.server.ts

import { fail, type Actions } from '@sveltejs/kit';
import { sendCodeEmail } from '$lib/server/email';

export const actions = {
    default: async ({ request }) => {
        const formData = await request.formData();
        const email = formData.get('email') as string;
        if (typeof email !== 'string' || email.length < 3) {
            return fail(400, {
                success: false,
                error: 'Email is required'
            });
        }

        try {
            const result = await sendCodeEmail({
                email: email,
                code: '123456',
                intro: 'Further verification is required to access your account.'
            });

            console.log(result);

            return {
                success: true
            };
        } catch (error: unknown) {
            console.error('Error processing email request:', error);
            return fail(500, {
                success: false,
                error: 'Failed to process email request'
            });
        }
    }
} satisfies Actions;

That's it! Now just enter your email, click the button and you should receive a beautifully formatted email. Try it in both a desktop mail client as well as web clients like Gmail or Yahoo! mail.

Resources

Thank You!

If you want to support me, please follow me on Spotify or SoundCloud!

Please also feel free to check out my Portfolio Site

Looking for a web developer? I'm available for hire! To inquire, please fill out a contact form.

Create a Universal Button With React + TailwindCSS

Jay @ Designly — Sun, 04 May 2025 01:18:55 +0000

As your project grows in size, component reusability becomes more and more important. There are times when it makes sense to make universal components, and there are times when you need more specialized components. Knowing when to use which is crucial.

If you try to make too many universal components that do too many things, then your product will end up with a lot of bloat. But if you use too few universal components, you will go crazy keeping track of them all.

Today we're going to learn how to create a very useful component: a React universal button component that can be either a <button> or <a> element depending on the props passed to it. We will also be using TailwindCSS for styling.

The demo project (link at bottom) was spun up using pnpm create vite@latest, selecting React + Typescript template.

We'll also need to install Tailwind and some additional utilities:

pnpm i -D tailwindcss @tailwindcss/vite tailwind-merge clsx

Next, we'll add Tailwind to our vite.config.ts:

import { defineConfig } from "vite";
import react from "@vitejs/plugin-react-swc";
import tailwindcss from "@tailwindcss/vite";

// https://vite.dev/config/
export default defineConfig({
  plugins: [react(), tailwindcss()],
});

Then replace everything in index.css with:

@import "tailwindcss";

Now we need to create a helper function to help us deal with variable Tailwind classes (src/lib/cn.ts):

import { clsx, type ClassValue } from "clsx";
import { twMerge } from "tailwind-merge";

export function cn(...inputs: ClassValue[]) {
  return twMerge(clsx(inputs));
}

If this looks familiar, it's the same function that ShadCN uses to merge class names.

Next, we'll create our button component at src/components/button.tsx:

import { cn } from "../lib/cn";
import type { ButtonHTMLAttributes, AnchorHTMLAttributes } from "react";

type ButtonAsButton = ButtonHTMLAttributes<HTMLButtonElement> & {
  type: "button";
  title: string;
};

type ButtonAsAnchor = AnchorHTMLAttributes<HTMLAnchorElement> & {
  type: "a";
  href: string;
  title: string;
};

type ButtonProps = ButtonAsButton | ButtonAsAnchor;

export default function Button(props: ButtonProps) {
  const { className, type, ...rest } = props;

  const classes = cn(
    "bg-blue-500 hover:brightness-120 cursor-pointer transition-all duration-200 ease-in-out text-white px-4 py-2 rounded-md text-center",
    className
  );

  if (type === "button") {
    return <button className={classes} {...(rest as ButtonAsButton)} />;
  }

  return <a className={classes} {...(rest as ButtonAsAnchor)} />;
}

This component does several useful things:

It provides strict type safety based on the type attribute
It provides a default base style that you can use as your default button
It allows any other Tailwind background color to be used without having to specify a hover background color, thanks to brightness-120 class
We return a <button> or <a> element depending on type prop. You could also supply a React Router or Next.js <Link> component as well.

Below are several examples of various ways this component can be used:

import { useState } from "react";

import Button from "./components/button";

export default function App() {
  const [displayText, setDisplayText] = useState("Choose your button wisely!");

  return (
    <>
      <main className="flex flex-col justify-center items-center bg-zinc-900 h-screen text-gray-50">
        <img
          src="https://cdn.designly.biz/images/designly-logo-trans.svg"
          alt="Designly Logo"
          className="mb-6 w-96"
        />
        <h1 className="mb-6 font-bold text-2xl">
          React + Tailwind CSS - Universal Button Demo
        </h1>
        <p className="mb-6 text-gray-500 text-xl">{displayText}</p>
        <div className="gap-6 grid md:grid-cols-4 grild-cols-2">
          <Button
            type="button"
            title="Default Button"
            onClick={() => {
              setDisplayText("Default Button, a safe choice!");
            }}
          >
            Default Button
          </Button>
          <Button
            type="button"
            className="bg-red-500"
            title="Red Button"
            onClick={() => {
              setDisplayText("Red Button, a risky choice!");
            }}
          >
            Red Button
          </Button>
          <Button
            type="button"
            className="bg-green-600"
            title="Green Button"
            onClick={() => {
              setDisplayText("Green Button, NO NOT THAT ONE!");
            }}
          >
            Green Button
          </Button>
          <Button
            type="a"
            className="bg-indigo-500"
            title="Link Button"
            href="https://blog.designly.biz"
            target="_blank"
            onClick={() => {
              setDisplayText("Link Button, it's a link and a button!");
            }}
          >
            Link Button
          </Button>
        </div>
      </main>
    </>
  );
}

Thank You!

If you want to support me, please follow me on Spotify or SoundCloud!

Current Projects

Snoozle.io- An AI app that generates bedtime stories for kids ❤️
react-poptart - A React Notification / Alerts Library (under 20kB)
Spectravert - A cross-platform video converter (ffmpeg GUI)
Smartname.app - An AI name generator for a variety of purposes

Looking for a web developer? I'm available for hire! To inquire, please fill out a contact form.

Full-Stack Next.js 15 Development Using Zod, Typescript, tRPC, react-query, and Sequelize ORM

Jay @ Designly — Wed, 01 Jan 2025 02:52:49 +0000

I've been developing web apps since the 90's (think Perl and cgi-bin). Since then I must have gone through a hundred different frameworks, platforms and libraries. But now I think I've found the perfect stack for Next.js development. Let's take a look at the key components:

Zod

Zod is a very flexible schema/validation library. The best feature Zod has over other libraries is the ability to infer types from the schema, so you can build your schema in one place and not have to create separate interfaces and types. Zod will integrate heavily into our stack.

tRPC

tRPC stands for Typescript Remote Procedure Call. It consists of a front-end context and client that is coupled with a back-end router and handlers. The reason we will be using tRPC is for its robust Typescript and Zod integration.

React-Query

We will be using react-query and the tRPC react-query plugin to handle managing our data state.

Sequelize

While not as popular as Prism or Drizzle, Sequelize is an underrated ORM. Sequelize works with all the most popular SQL dialects and its great for those who prefer old-school object-oriented programming. Sequelize allows you to fully extend the model, write your own methods and custom hooks. Sequelize is also fully Typescript compatible.

Ok then, let's get started coding. This is going to be a long one, so buckle up buckaroo!

All the code for the examples in this article will be provided in a GitHub repo. Link at the bottom.

Setup Project and Install Dependencies

Let's fire up a Next.js (version 15.2 at time of writing):

pnpx create-next-app@latest next-trpc-sequelize

Now let's install our dependencies:

pnpm i @tanstack/react-query@^4.36.1 @trpc/client@^10.45.2 @trpc/react-query@^10.45.2 @trpc/server@^10.45.2 colors lodash-es pg pg-hstore sequelize superjson zod

And now we'll need some dev dependencies as well:

pnpm i -D @next/env @types/lodash-es @types/pg @types/sequelize tsx

Setting Up the Database

You'll need a Postgres database for this project. If you already have a Postgres dev server, go ahead and create a database for our project. If you're a docker user (which you should be), you can use this docker-compose:

services:
     db:
          image: postgres
          restart: always
          environment:
               POSTGRES_PASSWORD: 'aaaa'
               POSTGRES_DB: 'test'
          ports:
               - '6000:5432'
          volumes:
               - test_dbdata:/var/lib/postgresql/data

volumes:
     test_dbdata:

To spin up this database, simply run: docker compose up -d.

Now let's create a .env.local file containing our connection string:

DB_STRING="postgresql://postgres:aaaa@localhost:6000/test"

Defining Our Schemas

Our stack begins with building our Zod schemas. In this project example, we're going to build a very basic blog site. We will have a Post model and an Author model. We will create a one-to-many relationship between Post and Author.

Before we get started with our schemas, let's write a couple helper functions to save on a lot of typing. Create a file at: src/zod/helpers.ts:

// src/zod/helpers.ts

import { z } from "zod";

export const enumKeys = <T extends Record<string, string>>(e: T) =>
  Object.keys(e) as [keyof T, ...Array<keyof T>];

export function zOptional<T extends z.ZodTypeAny>(schema: T) {
  return z
    .union([schema, z.literal("")])
    .transform((value) => (value === "" ? undefined : value))
    .optional();
}

export function zOptionalObject<T extends z.ZodRawShape>(schema: T) {
  return z.object(schema).partial();
}

Now let's create the schema for our Author model at src/zod/author.ts:

// src/zod/author.ts

import { z } from 'zod';
import { zOptional } from './helpers';

export const authorConstraints = {
    name: {
        min: 3,
        max: 50,
    },
    email: {
        min: 3,
        max: 50,
    },
    bio: {
        min: 0,
        max: 255,
    },
    website: {
        min: 0,
        max: 100,
    },
};

export const authorSchema = z.object({
    id: z.string().uuid(),
    name: z.string().min(authorConstraints.name.min).max(authorConstraints.name.max),
    email: z.string().email().min(authorConstraints.email.min).max(authorConstraints.email.max),
    bio: zOptional(z.string().min(authorConstraints.bio.min).max(authorConstraints.bio.max)),
    website: zOptional(z.string().url().min(authorConstraints.website.min).max(authorConstraints.website.max)),
    createdAt: z.date(),
    updatedAt: z.date(),
});

export type T_Author = z.infer<typeof authorSchema>;

export const authorCreateSchema = authorSchema.omit({
    id: true,
    createdAt: true,
    updatedAt: true,
});

export type T_AuthorCreate = z.infer<typeof authorCreateSchema>;

Note that we have two schemas, one to define the complete model and another to to define the required props to create a new record. As you can see, we can simply export the type using z.infer. Pretty cool huh? Here's what the author type looks like:

type T_Author = {
    id: string;
    name: string;
    email: string;
    createdAt: Date;
    updatedAt: Date;
    bio?: string | undefined;
    website?: string | undefined;
}

Ok, now let's do the same for the Post model src/zod/post.ts:

// src/zod/post.ts

import { z } from 'zod';

import { authorSchema } from './author';

export const postConstraints = {
    title: {
        min: 3,
        max: 200,
    },
    slug: {
        min: 3,
        max: 255,
    },
    content: {
        min: 3,
        max: 10000,
    },
};

export const postSchema = z.object({
    id: z.string().uuid(),
    title: z.string().min(postConstraints.title.min).max(postConstraints.title.max),
    slug: z.string().min(postConstraints.slug.min).max(postConstraints.slug.max),
    content: z.string().min(postConstraints.content.min).max(postConstraints.content.max),
    authorId: z.string().uuid(),
    createdAt: z.date(),
    updatedAt: z.date(),
});

export type T_Post = z.infer<typeof postSchema>;

export const postCreateSchema = postSchema.omit({
    id: true,
    slug: true,
    createdAt: true,
    updatedAt: true,
});

export type T_PostCreate = z.infer<typeof postCreateSchema>;

export const postExtendedSchema = postSchema.extend({
    author: authorSchema,
});

export type T_PostExtended = z.infer<typeof postExtendedSchema>;

Note how we can create a relation by importing the authorSchema and assigning it as a prop value to our postSchema. Here's what our inferred type looks like:

type T_PostExtended = {
    id: string;
    title: string;
    slug: string;
    content: string;
    authorId: string;
    createdAt: Date;
    updatedAt: Date;
    author: {
        id: string;
        createdAt: Date;
        updatedAt: Date;
        name: string;
        email: string;
        bio?: string | undefined;
        website?: string | undefined;
    };
}

Setting up Sequelize and Building Our Models

First, we'll need a create a Sequelize config file at src/db/sequelize.ts:

// src/db/sequelize.ts

import { Sequelize, Options } from 'sequelize';
import pg from 'pg';
import c from 'colors';
import { loadEnvConfig } from '@next/env';

loadEnvConfig(process.cwd());

const USE_SSL = false;
const IS_DEV = process.env.NODE_ENV !== 'production';
const DB_STRING = process.env.DB_STRING || '';

const logQuery = (query: string) => {
    console.log(c.green(new Date().toLocaleString()));
    console.log(c.blue(query));
};

const makeConfig = () => {
    const config: Options = {
        dialect: 'postgres',
        dialectModule: pg,
        logging: IS_DEV ? logQuery : false,
    };

    if (USE_SSL) {
        config.dialectOptions = {
            ssl: {
                require: true,
                rejectUnauthorized: false,
            },
        };
    }

    return config;
};

const sequelize = new Sequelize(DB_STRING, makeConfig());

export default sequelize;

A few things to note here. We're using the colors library and a custom logging function to print queries to the console log in development mode. This is great for debugging. Next, we use the @next/env library to load our environment for using our config and models outside of Next.js. We'll need this for our migration script.

// src/db/sequelize.ts

import { Sequelize, Options } from 'sequelize';
import pg from 'pg';
import c from 'colors';
import { loadEnvConfig } from '@next/env';

if (process.env.NODE_ENV === 'development') {
    loadEnvConfig(process.cwd());
}

const USE_SSL = false;
const IS_DEV = process.env.NODE_ENV !== 'production';
const DB_STRING = process.env.DB_STRING || '';

const logQuery = (query: string) => {
    console.log(c.green(new Date().toLocaleString()));
    console.log(c.blue(query));
};

const makeConfig = () => {
    const config: Options = {
        dialect: 'postgres',
        dialectModule: pg,
        logging: IS_DEV ? logQuery : false,
    };

    if (USE_SSL) {
        config.dialectOptions = {
            ssl: {
                require: true,
                rejectUnauthorized: false,
            },
        };
    }

    return config;
};

const sequelize = new Sequelize(DB_STRING, makeConfig());

export default sequelize;

Now let's define our Author sequelize model src/models/author.ts:

// src/models/author.ts

import { DataTypes, Model } from 'sequelize';
import sequelize from '@/db/sequelize';

import { authorConstraints } from '@/zod/author';
import type { T_Author, T_AuthorCreate } from '@/zod/author';

export default class Author extends Model<T_Author, T_AuthorCreate> implements T_Author {
    declare id: T_Author['id'];
    declare name: T_Author['name'];
    declare email: T_Author['email'];
    declare bio: T_Author['bio'];
    declare website: T_Author['website'];
    declare createdAt: T_Author['createdAt'];
    declare updatedAt: T_Author['updatedAt'];
}

Author.init(
    {
        id: {
            type: DataTypes.UUID,
            defaultValue: DataTypes.UUIDV4,
            primaryKey: true,
        },
        name: {
            type: DataTypes.STRING,
            allowNull: false,
            validate: {
                len: [authorConstraints.name.min, authorConstraints.name.max],
            },
        },
        email: {
            type: DataTypes.STRING,
            allowNull: false,
            validate: {
                isEmail: true,
                len: [authorConstraints.email.min, authorConstraints.email.max],
            },
        },
        bio: {
            type: DataTypes.STRING,
            allowNull: true,
            validate: {
                len: [authorConstraints.bio.min, authorConstraints.bio.max],
            },
        },
        website: {
            type: DataTypes.STRING,
            allowNull: true,
            validate: {
                isUrl: true,
                len: [authorConstraints.website.min, authorConstraints.website.max],
            },
        },
        createdAt: {
            type: DataTypes.DATE,
            defaultValue: DataTypes.NOW,
        },
        updatedAt: {
            type: DataTypes.DATE,
            defaultValue: DataTypes.NOW,
        },
    },
    {
        sequelize,
        modelName: 'Author',
        tableName: 'authors',
        timestamps: true,
        underscored: true,
        indexes: [
            {
                unique: true,
                fields: ['email'],
            },
        ],
    },
);

As you can see, we extend the Sequelize Model class, which takes two generic arguments, one for the complete model and one for creation. We also implement the T_Author type as well. Next we need to declare our properties but we refer to the T_Author type. Lastly, we initialize the model by defining our Postgres columns.

Note that we're using the underscored option as this automatically handles converting from camel case to snake case. Postgres columns don't like to be camel case. One thing to note is that when you're using underscore, you must refer to the column in the snake case format when defining indexes. Here we've defined an index for email that is unique, so validation will fail if a duplicate email address is inserted.

Next, let's do the same thing for our Post model src/models/post.ts:

// src/models/post.ts

import { DataTypes, Model } from 'sequelize';
import sequelize from '@/db/sequelize';
import { kebabCase } from 'lodash-es';

import { postConstraints } from '@/zod/post';
import type { T_Post, T_PostCreate, T_PostExtended } from '@/zod/post';
import type Author from './author';

export default class Post extends Model<T_Post, T_PostCreate> implements T_Post {
    // Properties
    declare id: T_Post['id'];
    declare title: T_Post['title'];
    declare slug: T_Post['slug'];
    declare content: T_Post['content'];
    declare authorId: T_Post['authorId'];
    declare createdAt: T_Post['createdAt'];
    declare updatedAt: T_Post['updatedAt'];

    // Associations
    declare author: Author;

    // Static Methods
    static async findBySlug(slug: string): Promise<T_PostExtended | null> {
        const post = await Post.findOne({
            where: {
                slug,
            },
            include: [
                {
                    association: 'author',
                },
            ],
        });

        if (!post) return null;

        return post.toJSON() as T_PostExtended;
    }
}

Post.init(
    {
        id: {
            type: DataTypes.UUID,
            defaultValue: DataTypes.UUIDV4,
            primaryKey: true,
        },
        title: {
            type: DataTypes.STRING(postConstraints.title.max),
            allowNull: false,
            validate: {
                len: [postConstraints.title.min, postConstraints.title.max],
            },
        },
        slug: {
            type: DataTypes.STRING(postConstraints.slug.max),
            allowNull: false,
            validate: {
                len: [postConstraints.slug.min, postConstraints.slug.max],
            },
        },
        content: {
            type: DataTypes.STRING(postConstraints.content.max),
            allowNull: false,
            validate: {
                len: [postConstraints.content.min, postConstraints.content.max],
            },
        },
        authorId: {
            type: DataTypes.UUID,
            allowNull: false,
        },
        createdAt: {
            type: DataTypes.DATE,
            defaultValue: DataTypes.NOW,
        },
        updatedAt: {
            type: DataTypes.DATE,
            defaultValue: DataTypes.NOW,
        },
    },
    {
        sequelize,
        modelName: 'Post',
        tableName: 'posts',
        timestamps: true,
        paranoid: false,
        underscored: true,
        indexes: [
            {
                unique: true,
                fields: ['slug'],
            },
        ],
        hooks: {
            beforeValidate: (post: Post) => {
                if (!post.slug) {
                    post.slug = kebabCase(post.title);
                }
            },
            beforeBulkCreate: (posts: Post[]) => {
                posts.forEach(post => {
                    if (!post.slug) {
                        post.slug = kebabCase(post.title);
                    }
                });
            },
        },
    },
);

Hopefully you are beginning to see the power of Sequelize in this model class. We import the Zod inferred types as before, but we also import the Author model as a type to declare as an association.

Next, we create a unique slug index, which is mostly how we'll be referencing our posts. Lastly, let's create some custom hooks to automagically create our slugs using lodash/kebabCase. These custom hooks are a very powerful feature of Sequelize.

Also note that we can define custom static and instance methods, such as the findBySlug() method.

Ok, now that we have our models, we need to aggregate them in and index and define our relations. Create a file at src/models/index.ts:

// src/models/index.ts

import Post from './post';
import Author from './author';

Post.belongsTo(Author, {
    foreignKey: 'authorId',
    as: 'author',
});

Author.hasMany(Post, {
    foreignKey: 'authorId',
    as: 'posts',
});

export { Post, Author };

This creates a one-to-many relationship between Author and Post. So posts have only one author and authors have many posts.

Note that you must import your models from this index file and not from the original file or the associations will not be defined.

Writing a Migration Script

Ok, now let's write a script that will sync our models with the database and insert some dummy data. Create a file in src/db/migrate.ts:

// src/db/migrate.ts

import { Author, Post } from '@/models';
import sequelize from './sequelize';

import type { T_PostCreate } from '@/zod/post';
import type { T_AuthorCreate } from '@/zod/author';

(async () => {
    await sequelize.drop({
        cascade: true,
    });

    await Author.sync({ force: true, alter: true });
    await Post.sync({ force: true, alter: true });

    const authors: T_AuthorCreate[] = [
        {
            name: 'Jay',
            email: 'jay@example.com',
            bio: 'I am a software engineer.',
            website: 'https://blog.designly.biz',
        },
    ];

    await Author.bulkCreate(authors);

    const author = await Author.findOne({
        where: {
            email: 'jay@example.com',
        },
    });
    if (!author) throw new Error('Author not found.');

    const posts: T_PostCreate[] = [
        {
            title: 'Hello, World!',
            content: 'This is my first post.',
            authorId: author.id,
        },
    ];

    await Post.bulkCreate(posts);

    process.exit(0);
})();

This is an auto-executing script. Now let's add it to our scripts in package.json:

"scripts": {
    "migrate": "tsx ./src/db/migrate.ts"
}

Now let's run it: pnpm migrate.

You should get a list of timestamped SQL statements in the server console log. If you get an error, please check your configuration and try again.

Configuring tRPC Server

And now for the hard part... well it's not really hard, just a lot of boilerplate. tRPC is divided into the following components:

A client context that wraps the entire app
Routers that handle get requests, creation and mutations
Handlers that plug into the routers' methods
An API route that handles all tRPC requests

First, let's create a function that sets up our tRPC server src/trpc/index.ts:

// src/trpc/index.ts

import { initTRPC } from '@trpc/server';
import superjson from 'superjson';

export default function getTrpc() {
    return initTRPC.create({
        transformer: superjson,
    });
}

Note that we plugin superjson to format our output as JSON. tRPC is flexible and you can format your output however you like.

Next, we'll write our handlers. Let's create one for our Author model src/trpc/handlers/author/get.ts:

// src/trpc/handlers/author/get.ts

import { Author } from '@/models';

export async function handlerGetAuthor({ input }: { input: string }) {
    const author = await Author.findByPk(input);

    if (!author) {
        return null;
    }

    return author.toJSON();
}

Input is provided by the router we will create shortly. Input can be any type: a string, a number, and object or array.

Now let's make one for our Post model src/trpc/handlers/post/get.ts:

// src/trpc/handlers/post/get.ts

import { Post } from '@/models';

export async function handlerGetPost({ input }: { input: string }) {
    const post = await Post.findBySlug(input);

    return post;
}

Next, we need to create a router for each model type. Then we'll plug these handlers in to each method src/trpc/routers/author.ts:

import { z } from 'zod';
import getTrpc from '..';
import { handlerGetAuthor } from '../handlers';

export const t = getTrpc();

export const authorRouter = t.router({
    get: t.procedure.input(z.string()).query(handlerGetAuthor),
});

As you can see the input() method takes a Zod schema. You could define a more complex schema that includes perhaps a search term, pagination and filters. We call the query() method and plug in the handler. This sets up the router to accept a GET request from our main router handler (which we'll handle shortly).

Ok now let's make a router for our Post model src/trpc/routers/post.ts:

// src/trpc/routers/post.ts

import { z } from 'zod';
import getTrpc from '..';
import { handlerGetPost } from '../handlers';

export const t = getTrpc();

export const postRouter = t.router({
    getBySlug: t.procedure.input(z.string()).query(handlerGetPost),
});

Now we need to take our routers and combine them into a single router object that we'll pass to a Next.js route enpoint src/routers/index.ts:

// src/trpc/routers/index.ts

import getTrpc from '..';

// Routers
import { authorRouter } from './author';
import { postRouter } from './post';

const t = getTrpc();

export const trpcRouter = t.router({
    author: authorRouter,
    post: postRouter,
});

export type AppRouter = typeof trpcRouter;

Lastly, we need to create our tRPC endpoint. This endpoint will catch all tRPC requests src/app/api/trpc/[trpc]/route.ts:

// src/app/api/trpc/[trpc]/route.ts

import { NextRequest } from 'next/server';
import { fetchRequestHandler } from '@trpc/server/adapters/fetch';
import { trpcRouter } from '@/trpc/routers';

const t = (req: NextRequest) => {
    return fetchRequestHandler({
        endpoint: '/api/trpc',
        req,
        router: trpcRouter,
        createContext: () => ({}),
    });
};

export { t as GET, t as POST, t as PUT, t as DELETE, t as PATCH };

So here we pass our NextRequest to a function that returns the fetch adapter, to which we pass our router and the request object. Lastly, we export that function as each type of HTTP verb as this handler will handle all requests of every type.

Ok! 😮‍💨 I did say there would be a lot of boilerplate, but I think it will be worth it. Now adding more models, routers and handlers will be pretty strait-forward. So that's it for the server. Now on to the client!

Configuring tRPC Client

Setting up the client it much easier and less code than the server. We simply need to create a client context that will wrap our app src/trpc/provider.ts:

// src/trpc/provider.tsx

import React, { useState } from 'react';
import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
import { createTRPCReact } from '@trpc/react-query';
import { httpBatchLink } from '@trpc/client';
import superjson from 'superjson';

import type { AppRouter } from './routers';

export const trpc = createTRPCReact<AppRouter>();

const trpcClient = trpc.createClient({
    links: [
        httpBatchLink({
            url: '/api/trpc',
        }),
    ],
    transformer: superjson,
});

export default function TrpcProvider({ children }: { children: React.ReactNode }) {
    const [queryClient] = useState(() => new QueryClient());

    return (
        <QueryClientProvider client={queryClient}>
            <trpc.Provider client={trpcClient} queryClient={queryClient}>
                {children}
            </trpc.Provider>
        </QueryClientProvider>
    );
}

Once again, we use superjson to transform our input to JSON. We're also using react-query to handle our state and cache. It's a really nice setup!

Now, how I normally setup my Next.js apps is I create a "providers" client component to handle all my client-side context providers src/app/providers.tsx:

// src/app/providers.tsx

'use client';

import React from 'react';
import TrpcProvider from '@/trpc/provider';

export default function Providers({ children }: { children: React.ReactNode }) {
    return <TrpcProvider>{children}</TrpcProvider>;
}

Lastly, we'll wrap the entire app in layout.tsx:

export default function RootLayout({
    children,
}: Readonly<{
    children: React.ReactNode;
}>) {
    return (
        <html lang="en">
            <body className={`${geistSans.variable} ${geistMono.variable} antialiased`}>
                <Providers>{children}</Providers>
            </body>
        </html>
    );
}

Now all we have to do is make a client component and make our tRPC request:

'use client';

import React from 'react';

import { trpc } from '@/trpc/provider';

export default function HomeView() {
    const { data } = trpc.post.getBySlug.useQuery('hello-world');

    return (
        <div>
            <h1>Welcome to your Next.js app!</h1>
            <pre>{JSON.stringify(data, null, 4)}</pre>
        </div>
    );
}

Pretty cool huh? Here's what the type of data comes out to be:

const data: {
    title: string;
    id: string;
    createdAt: Date;
    updatedAt: Date;
    author: {
        id: string;
        name: string;
        email: string;
        createdAt: Date;
        updatedAt: Date;
        bio?: string | undefined;
        website?: string | undefined;
    };
    slug: string;
    content: string;
    authorId: string;
} | null | undefined

So as you can see, we have end-to-end type safety coupled with Zod form validation. Our types start at Zod, then pass to the model and then pass to tRPC. Making changes to the model is as simple as updating the Zod schema and declaring and initializing the column in the model file.

If you liked this article, please let me know! I plan on doing a follow up article where we'll integrate ChadCN, react-hook-form, Zod and tRPC to effortlessly handle our forms. Let me know in the comments if this is something you'd like to read!

GitHub repo: https://github.com/designly1/next-trpc-sequelize.

Thank You!

If you want to support me, please follow me on Spotify!

Current Projects

Snoozle.io- An AI app that generates bedtime stories for kids ❤️
react-poptart - A React Notification / Alerts Library (under 20kB)
Spectravert - A cross-platform video converter (ffmpeg GUI)
Smartname.app - An AI name generator for a variety of purposes

Looking for a web developer? I'm available for hire! To inquire, please fill out a contact form.

How to Create a Scroll Progress Bar in Next.js/React

Jay @ Designly — Sun, 27 Oct 2024 22:42:58 +0000

Sometimes the simplest addition to a website can make a huge impact on the user experience. Progress bars are one of those things. People like to have visual feedback from the app they are interfacing with. It makes it seem more responsive and animated.

Having a progress bar for the scroll position of the page or even a div element is no different. It's not strictly necessary, but it adds a pleasing visual effect to the page. And the best part is that we can accomplish this with very little code and zero dependencies. So why not give it a try?

There will be a link to a demo site as well as its GitHub repository at the bottom of this article. The project was bootstrapped using npx create-next-app@latest, which as of the writing of this article is version 15. I am also using TailwindCSS for styling. You could just as easily use create-react-app as well, as there is nothing Next.js-specific about this example.

Now on to the coding!

Creating Our Reusable Component

First, let's create the actual progress bar component that we will be able to import into any app:

// src/components/ScrollProgress.tsx

'use client';

import React, { useEffect, useState } from 'react';

interface Props {
    containerRef?: React.RefObject<HTMLDivElement>;
    className?: string;
    height?: number;
}

export default function ScrollProgress(props: Props) {
    // Props
    const { containerRef, className = '', height = 7 } = props;

    // State
    const [scrollProgress, setScrollProgress] = useState(0);

    // Effects
    useEffect(() => {
        const handleScroll = () => {
            /**
             * Determine the target element to calculate scroll progress.
             * If a containerRef is provided, use that element; otherwise, use the document element.
             */
            const target = containerRef?.current || document.documentElement;

            // Calculate the scroll progress based on the target element's scroll position
            const { scrollTop, scrollHeight, clientHeight } = target;
            const totalHeight = scrollHeight - clientHeight;
            const progress = (scrollTop / totalHeight) * 100;

            // Update the scroll progress state
            setScrollProgress(progress);
        };

        const target = containerRef?.current || window;

        // Add a scroll event listener to the target element
        target.addEventListener('scroll', handleScroll);

        return () => {
            // Remove the scroll event listener when the component is unmounted
            target.removeEventListener('scroll', handleScroll);
        };
    }, [containerRef]);

    return (
        <div
            className={`fixed top-0 left-0 w-full bg-primary ${className}`}
            style={{ width: `${scrollProgress}%`, height: `${height}px`, zIndex: 99999 }}
        />
    );
}

This component accepts three props:

containerRef: optional ref to use if we are attaching to a div
className: additional class names to pass to the progress bar
height: optional height (thickness) of the progress bar

The color is determined by the bg-primary class, which you can either extend in tailwind.config.json or by using daisyui, a Tailwind plugin.

If we do not supply a containerRef, then the scroll event will be attached to the document by default.

Using the Component

Now that we have our component, here's how you can add it to your app. In this example, we are going to place it in layout.tsx because I am using Next.js App Router:

import type { Metadata } from 'next';
import localFont from 'next/font/local';
import './globals.css';

import ScrollProgress from '@/components/ScrollProgress';
import Header from '@/components/Header';
import Footer from '@/components/Footer';
import { Next13NProgress } from 'nextjs13-progress';

const geistSans = localFont({
    src: './fonts/GeistVF.woff',
    variable: '--font-geist-sans',
    weight: '100 900',
});
const geistMono = localFont({
    src: './fonts/GeistMonoVF.woff',
    variable: '--font-geist-mono',
    weight: '100 900',
});

export const metadata: Metadata = {
    title: 'A Halloween Horror Story',
    description: 'A spooky tale of web development gone awry.',
};

export default function RootLayout({
    children,
}: Readonly<{
    children: React.ReactNode;
}>) {
    return (
        <html lang="en">
            <body className={`${geistSans.variable} ${geistMono.variable} antialiased bg-black hw-bg`}>
                <main className="min-h-screen flex flex-col text-base-content">
                    <ScrollProgress />
                    <Header />
                    {children}
                    <Footer />
                </main>
                <Next13NProgress color="#f28c18" height={7} />
            </body>
        </html>
    );
}

Resources

Thank You!

If you want to support me, please follow me on Spotify!

Current Projects

Snoozle.io- An AI app that generates bedtime stories for kids ❤️
react-poptart - A React Notification / Alerts Library (under 20kB)
Spectravert - A cross-platform video converter (ffmpeg GUI)
Smartname.app - An AI name generator for a variety of purposes

Looking for a web developer? I'm available for hire! To inquire, please fill out a contact form.

Push Notifications in Next.js with Web-Push: A Provider-Free Solution

Jay @ Designly — Mon, 14 Oct 2024 00:25:51 +0000

Push notifications are an important way to stay engaged with your users. SMS messages are too personal (and restrictive), and email is often too slow and prone to being filtered out.

When done properly (and not abused), push notifications offer value to both the user and the app owner.

In this article, I'm going to show you how to implement web-push, a simple push notification library in a Next.js app. This process will include:

Installing dependencies
Generating VAPID keys
Creating a push notification provider context
Creating server actions for subscribing and unsubscribing
Creating a service worker to handle incoming push notifications

This solution works on almost all modern mobile and desktop browsers. It also works with iOS devices in PWA mode (i.e. add to home screen).

Furthermore, a demo site and link to the code repo are in the links at the bottom of this article.

Now let's get to coding!

Installing Dependencies

Our production deps:

npm i web-push uuid js-cookie

And if you're using Typescript (which you should), you'll need:

npm i -D @types/web-push @types/uuid @types/js-cookie

Generating VAPID keys

VAPID stands for Voluntary APplication server IDentification. VAPID consists of a public/private key pair. A user subscribes to push notifications using the public key. You would then typically store that subscription in a database. Then when your application wants to send a message, the subscription is looked up, and a JWT is created using the private key. This assures that only servers that know the secret key are allowed to send push notifications to the subscribing service worker.

Thankfully, web-push has a handy little function for generating our VAPID keys:

// scripts/generateVapidKeys.js
const webpush = require('web-push');
const vapidKeys = webpush.generateVAPIDKeys();

console.log(`NEXT_PUBLIC_VAPID_PUBLIC_KEY="${vapidKeys.publicKey}"`);
console.log(`VAPID_PRIVATE_KEY="${vapidKeys.privateKey}"`);

You can then run this script in the terminal:

node scripts/generateVapidKeys.js

Then copy and paste the output into your .env file. You will also need to set the VAPID subject as well, which can either be a mailto: URL or a web URL:

NEXT_PUBLIC_VAPID_PUBLIC_KEY="BLtKReMOK8VqC7pNK1xy36KPK4xJLeY_w6VSL7dogZ9mh7isbNWzHlw3icDcN9aXQbYYFL2aWJcJfbL2RQfwnoQ"
VAPID_PRIVATE_KEY="arjM-nfI8m83-mCw8dGcZPlN9XAvcqYp0ix1brMqkJo"
NEXT_PUBLIC_VAPID_SUBJECT="mailto:admin@example.com"

For more information on the VAPID specification, refer to the links below.

Creating Our Provider Context

We will use the React context API to encapsulate the functions for subscribing and unsubscribing, as well as managing registration of the service worker. It will also display a little popup at the bottom of the screen asking the user to subscribe. By creating a provider context and inserting it in our layout.tsx, we can be assured that the service worker and management functions, and state variables will be available site-wide.

'use client';

// lib/client/push-notifications/provider.tsx

import React, { createContext, useContext, useState, useEffect, FunctionComponent } from 'react';
import SubscribePrompt from '@/components/SubscribePrompt';

// utils
import { urlBase64ToUint8Array } from '../../format';
import { v4 as uuidv4 } from 'uuid';
import Cookies from 'js-cookie';

// actions
import { subscribeUser, unsubscribeUser, checkSubscription } from './actions';

// types
import type WebPush from 'web-push';

interface PushNotificationsContext {
    isSupported: boolean;
    subscribeToPush: () => void;
    unsubscribeFromPush: () => void;
    isSubscribed: boolean;
    loadingMessage: string | null;
    deviceId: string | null;
}

interface PushNotificationsProviderProps {
    children: React.ReactNode;
}

const PushNotificationsContext = createContext<PushNotificationsContext>({
    isSupported: false,
    subscribeToPush: () => {},
    unsubscribeFromPush: () => {},
    isSubscribed: false,
    loadingMessage: null,
    deviceId: null,
});

export const DEVICE_ID_KEY = 'device_id';
const DONT_ASK_KEY = 'push_dont_ask';
const SUBSCRIBE_PROMPT_DELAY = 2000; // 1 second

export const PushNotificationsProvider: FunctionComponent<PushNotificationsProviderProps> = ({ children }) => {
    const [subscription, setSubscription] = useState<PushSubscription | null>(null);
    const [subscriptionLoaded, setSubscriptionLoaded] = useState<boolean>(false);
    const [isSupported, setIsSupported] = useState<boolean>(false);
    const [showPrompt, setShowPrompt] = useState<boolean>(false);
    const [deviceId, setDeviceId] = useState<string | null>(null);
    const [loadingMessage, setLoadingMessage] = useState<string | null>(null);

    const isSubscribed = !!subscription;

    /**
     * Check if browser supports service workers and push notifications
     * and then register the service worker
     */
    useEffect(() => {
        if ('serviceWorker' in navigator && 'PushManager' in window) {
            setIsSupported(true);
            (async () => {
                const registration = await navigator.serviceWorker.register('/sw.js', {
                    scope: '/',
                    updateViaCache: 'none',
                });
                const sub = await registration.pushManager.getSubscription();
                setSubscription(sub);
                setSubscriptionLoaded(true);
            })();
        }
    }, []);

    /**
     * Check if there is a device id in cookies
     * If not, generate a new one and store it
     */
    useEffect(() => {
        const storedDeviceId = Cookies.get(DEVICE_ID_KEY);
        if (!storedDeviceId) {
            const newDeviceId = uuidv4();
            Cookies.set(DEVICE_ID_KEY, newDeviceId, { expires: 365 });
            setDeviceId(newDeviceId);
        } else {
            setDeviceId(storedDeviceId);
        }
    }, []);

    /**
     * Check if current client subscription is still valid
     * in the database
     */
    useEffect(() => {
        if (deviceId && subscription) {
            (async () => {
                const res = await checkSubscription({ deviceId });
                if (!res.success) {
                    subscription?.unsubscribe();
                    setSubscription(null);
                }
            })();
        }
    }, [deviceId, subscription]);

    /**
     * Determine if the user should be prompted to subscribe
     */
    useEffect(() => {
        if (!subscription && subscriptionLoaded && deviceId) {
            // Delay the prompt to give time for the user to interact with the page
            setTimeout(async () => {
                // Check if the user has requested not to be asked again
                const dontAsk = Cookies.get(DONT_ASK_KEY);
                if (!dontAsk) {
                    setShowPrompt(true);
                }
            }, SUBSCRIBE_PROMPT_DELAY);
        }
    }, [subscription, subscriptionLoaded, deviceId]);

    async function subscribeToPush() {
        if (!deviceId) return;

        const registration = await navigator.serviceWorker.ready;
        const sub = await registration.pushManager.subscribe({
            userVisibleOnly: true,
            applicationServerKey: urlBase64ToUint8Array(process.env.NEXT_PUBLIC_VAPID_PUBLIC_KEY!),
        });
        setSubscription(sub);
        setLoadingMessage('Subscribing...');
        await subscribeUser({ sub: sub as unknown as WebPush.PushSubscription, deviceId });
        setLoadingMessage(null);

        Cookies.remove(DONT_ASK_KEY);
    }

    async function unsubscribeFromPush() {
        if (!deviceId) return;

        setLoadingMessage('Unsubscribing...');
        await subscription?.unsubscribe();
        setSubscription(null);
        await unsubscribeUser({ deviceId });
        setLoadingMessage(null);
    }

    async function dontAsk() {
        Cookies.set(DONT_ASK_KEY, 'true', { expires: 365 });
        setShowPrompt(false);
    }

    return (
        <PushNotificationsContext.Provider
            value={{ isSupported, subscribeToPush, unsubscribeFromPush, isSubscribed, loadingMessage, deviceId }}
        >
            {children}
            {showPrompt && isSupported && !subscription ? (
                <SubscribePrompt
                    onSubscribe={() => {
                        subscribeToPush();
                        setShowPrompt(false);
                    }}
                    onCancel={() => {
                        setShowPrompt(false);
                    }}
                    onDontAsk={dontAsk}
                />
            ) : null}
        </PushNotificationsContext.Provider>
    );
};

export const usePushNotifications = (): PushNotificationsContext => {
    const context = useContext(PushNotificationsContext);
    if (!context) {
        throw new Error('usePushNotifications must be used within PushNotificationsProvider');
    }
    return context;
};

Here's how this works:

We check the cookies to see if a device ID is set
If no device ID, we create on using UUIDv4
We check to see if serviceWorker and PushManager are supported by the client
We register the service worker
We check for an existing subscription, if exists, we set it to the state variable
We create a usePushNotifications hook to expose certain state variables and methods

Creating Our Server Actions

We will be relying on server actions to handle subscribing and unsubscribing from push notifications. The purpose of these server actions is to handle storing the subscription object in a database for later retrieval.

'use server';

// lib/client/push-notifications/actions.ts

import webpush, { PushSubscription } from 'web-push';

type T_KvListKeyItem = {
    name: string;
    expiration: number;
};

interface I_KvListResponse {
    success: boolean;
    keys: {
        list_complete: boolean;
        keys: T_KvListKeyItem[];
        cacheStatus: string | null;
    };
}

interface I_SubscribeUser {
    sub: PushSubscription;
    deviceId: string;
}

export async function subscribeUser(props: I_SubscribeUser): Promise<ApiResponse> {
    const { sub, deviceId } = props;

    try {
        // logic to store subscription in database

        return { success: true };
    } catch (err) {
        console.error(err);
        return { success: false, message: 'Failed to subscribe user' };
    }
}

interface I_UnsubscribeUser {
    deviceId: string;
}

export async function unsubscribeUser(props: I_UnsubscribeUser): Promise<ApiResponse> {
    const { deviceId } = props;

    try {
        // logic to remove subscription from database

        return { success: true };
    } catch (err) {
        console.error(err);
        return { success: false, message: 'Failed to unsubscribe user' };
    }
}

interface I_CheckSubscription {
    deviceId: string;
}

export async function checkSubscription(props: I_CheckSubscription): Promise<ApiResponse> {
    const { deviceId } = props;
    const prefix = `${KV_PREFIX}${deviceId}`;

    try {
        // logic to retrieve subscription from database

        if (sub) {
            return { success: true };
        }

        return { success: false, message: 'Subscription does not exist' };
    } catch (err) {
        console.error(err);
        return { success: false, message: 'Failed to check subscription' };
    }
}

export interface I_SendPushNotification {
    deviceId: string;
    title: string;
    body: string;
    url: string;
    badge?: string;
}

export async function sendPushNotification(props: I_SendPushNotification): Promise<ApiResponse> {
    const { deviceId, title, body, url, badge } = props;

    try {
        if (!deviceId || !title || !body || !url) {
            throw new Error('Invalid parameters');
        }

        // logic to retrieve subscriptions from database

        webpush.setVapidDetails(
            process.env.NEXT_PUBLIC_VAPID_SUBJECT!,
            process.env.NEXT_PUBLIC_VAPID_PUBLIC_KEY!,
            process.env.VAPID_PRIVATE_KEY!,
        );

        const payload = JSON.stringify({
            title,
            body,
            url,
            badge,
        });

        await Promise.all(
            subs.map(async sub => {
                await webpush.sendNotification(sub, payload);
            }),
        );

        return { success: true };
    } catch (err) {
        console.error(err);
        return { success: false, message: 'Failed to send push notification' };
    }
}

In a production app, you would likely want to tie a device ID as well as a user ID to the subscription stored in the database. Then when you want to send a notification to all of the user's registered devices, the Promise.all() example will make more sense.

Creating the Service Worker

A service worker is required to handle receiving push notifications from the server, as well as handling the click response from the user. Having a service worker allows your PWA to receive push notification even when the user is not actively using it.

self.addEventListener('push', function (event) {
    if (event.data) {
        const data = event.data.json();
        const { title, body, primaryKey, badge, url } = data;
        const options = {
            body,
            icon: '/android-chrome-192x192.png',
            badge: badge || '/push-badge.png',
            vibrate: [100, 50, 100],
            data: {
                dateOfArrival: Date.now(),
                primaryKey,
                url,
            },
        };
        event.waitUntil(self.registration.showNotification(title, options));
    }
});

self.addEventListener('notificationclick', function (event) {
    const data = event.notification.data;
    const { url } = data;
    event.notification.close();

    if (url) {
        event.waitUntil(clients.openWindow(url));
    }
});

Here we have two event handlers, push and notificationclick. In the push handler we receive the payload from the server. The payload can contain any data you would like to send along with the notification, such as a custom ID, url or badge URL.

FYI: the difference between the icon and the badge is the icon is typically your logo icon, while the badge a small (32x32) monochrome icon that is typically used to indicate the purpose of the notification. A badge might be an icon of a lock for a security notification, for example.

When a user clicks or taps on a notification, the notificationclick handler is triggered. The data from our payload becomes available via the event data. In this example we open the provided URL in a new window (or tab).

Resources

Thank You!

If you want to support me, please follow me on Spotify!

Current Projects

Snoozle.io- An AI app that generates bedtime stories for kids ❤️
react-poptart - A React Notification / Alerts Library (under 20kB)
Spectravert - A cross-platform video converter (ffmpeg GUI)
Smartname.app - An AI name generator for a variety of purposes

Looking for a web developer? I'm available for hire! To inquire, please fill out a contact form.

DEV Community: Jay @ Designly

Open Knowledge Format vs RAG: Why Your Agent Should Read a Wiki

What the folder actually is

A morning question and four files

When agents write the wiki

The haystack is still a haystack

Start with the files you already have

Thank You!

How DeepSeek Harness Saves Tokens by Not Editing History

Two columns on one price list

A 100-step bill

The sensible choices point the wrong way

They made rewriting unexpressible

Compaction is where append-only gets hard

Append less, after you stop rewriting

Plugins cannot be allowed to touch the past

The wrapper is the product

Thank You!

Why await Doesn't Make JavaScript Run in Order

The assumption

A short surprising example

What actually logs, and when

What await actually pauses

How other code keeps running

When sequential awaits are right

When Promise.all() is better

A rule of thumb you can remember

How to Automate Scheduled X Posts with Codex and xurl

What You Will Need

Install xurl

Create an X Developer Application

Know Which Credential You Need

Authorize the Account Locally

Put a Fixed-Account Skill in Front of the API

Test the Publishing Boundary Without Posting Garbage

Give the Scheduled Task a Complete Editorial Workflow

Duplicate Prevention Should Fail Closed

Test the Whole Workflow in Stages

Troubleshooting

xurl Cannot Find the Account

Posting Returns 403

Codex Cannot Reach api.x.com

A Publish May Have Succeeded Before an Error

The Scheduled Task Does Not Run

How to Shut It Down Safely

Final Thoughts

Sources

Don’t Waste Your Money on GitHub Actions—Do This Instead!

Step 1: Spin Up an Ubuntu EC2 Instance

Step 2: Configure the Instance

2.1 Install Nginx (for health checks)

2.2 Install GitHub CLI

2.3 Create a Non-Privileged User

2.4 Install Node.js and Package Manager

2.5 Generate SSH Keys

2.6 Add Build Server’s Key to Deployment Destination

2.7 Authenticate with GitHub

2.8 Allow Local Machine SSH Access

Step 3: Automate the Local Workflow

Step 4: Automate the Remote Workflow

Step 5: Test the Pipeline

Step 6: Compare Costs

Hidden Bonuses

Thank You!

Filling the Memory Gap: Building MCPMem to Fix AI Assistant Forgetfulness

Filling the Memory Gap: Building MCPMem to Fix AI Assistant Forgetfulness

The Problem: Assistants With Goldfish Memory

Why the Current Fixes Don’t Cut It

Introducing MCPMem!

Why it’s different

Under the Hood

1. Semantic Embeddings

2. SQLite Vector Search

3. MCP Integration

How It Feels in Practice

Setup

What Changed for Me

Lessons Learned

Roadmap

Building a Multi-Modal GPT Agent in TypeScript with OpenAI

What `await` actually pauses

When sequential `await`s are right

When `Promise.all()` is better