DEV Community: Jay @ Designly

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!

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.

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.

Build a powerful password meter with Cloudflare Workers, Next.js, and zxcvbn.

Jay @ Designly — Wed, 25 Sep 2024 02:13:56 +0000

Password security is a concern that is all-to-often either completely overlooked or woefully implemented. Thankfully, there's a really great library I discovered that takes all of the guess work out of scoring passwords. It's called zxcvbn. It's so named because users often use sequential keys on the keyboard to make their passwords more memorable.

There's just one problem with zxcvbn, the bundle size is nearly 800kB! That's a deal breaker for any front-end code.

As you may have already guessed from the title, I have a great solution to this problem: CloudFlare Workers! We're going to create a password scoring microservice! 🤗 CloudFlare Workers are blazing fast edge functions and once you set this up, you'll be able to use it for any future projects as well.

We're going to start by creating a worker using CloudFlare's wrangler cli tool. Setting it up and publishing it will take less than 5 minutes. Lastly, we'll create a create-next-app project (you could do create-react-app as well) and create a really slick front-end password feedback component based on the zxcvbn result we get from our service.

Setting Up Our CloudFlare Worker

Getting started with CloudFlare is a no-brainer. I'm going to assume you already have a free CloudFlare account.

npm create cloudflare@latest zxcvbn-worker

Choose whether you want to use Typescript (I recommend so), git for version control (yes) and then opt in to go ahead and deploy your app. You'll need to go through the authentication process, then select your team account and it will be live in less than 30 seconds.

We only need to install one dependency:

npm i zxcvbn
npm i -D @types/zxcvbn

Next, open up the project in your favorite editor and edit index.ts:

// index.ts

import { checkPasswordStrength } from './lib/pw';

interface I_CheckPasswordReqestBody {
    password: string;
}

// Function to generate CORS headers
function getCommonHeaders() {
    return {
        'Access-Control-Allow-Origin': '*',
        'Access-Control-Allow-Methods': 'POST, OPTIONS',
        'Access-Control-Allow-Headers': 'Content-Type',
        'Cache-Control': 'no-store',
        'Content-Type': 'application/json',
    };
}

export default {
    async fetch(request, env, ctx): Promise<Response> {
        // Handle CORS preflight request
        if (request.method === 'OPTIONS') {
            return new Response(null, {
                headers: getCommonHeaders(),
            });
        }

        // Allow only POST requests
        if (request.method !== 'POST') {
            return new Response(null, { status: 405, headers: getCommonHeaders() });
        }

        try {
            // Parse the request body
            const body = (await request.json()) as I_CheckPasswordReqestBody;
            const { password } = body;

            // Check if the password field is missing or empty
            if (!password) {
                return new Response(JSON.stringify({ error: 'Password is required' }), {
                    status: 400,
                    headers: {
                        ...getCommonHeaders(),
                    },
                });
            }

            // Check the password strength
            const result = checkPasswordStrength(password);

            return new Response(JSON.stringify(result), {
                headers: {
                    ...getCommonHeaders(),
                },
            });
        } catch (error) {
            return new Response(JSON.stringify({ error: 'Invalid request' }), {
                status: 400,
                headers: {
                    ...getCommonHeaders(),
                },
            });
        }
    },
} satisfies ExportedHandler<Env>;

Lastly, we'll need to create our helper function:

// lib/pw.ts

import zxcvbn from 'zxcvbn';

export type T_CheckPasswordStrengthResult = ReturnType<typeof zxcvbn>;

export function checkPasswordStrength(password: string): T_CheckPasswordStrengthResult {
    return zxcvbn(password);
}

That be it! Simply run npx wrangler deploy and test with Thunder Client or Postman.

Integrating with Our Front-End

Go ahead and spin up either a React or Next.js app and open the project up in your favorite editor.

I have some additional dependencies for the demo app (link at bottom), but the only one you really need is @types/zxcvbn, if you're using Typescript, of course (which you should). If you don't understand some of the Tailwind classes, that is because I'm using DaisyUI, a super-duper light plugin for Tailwind. DaisyUI offers themes and semantic color schemes (i.e. primary, secondary, error, etc.)

First, we'll create our password feedback component that we'll be able to use in any form that has a password:

// src/components/PasswordFeedback.tsx

import React from 'react';
import { FaRegTimesCircle, FaRegCheckCircle } from 'react-icons/fa';
import type { ZXCVBNResult } from 'zxcvbn';

interface Props {
    zxcvbn: ZXCVBNResult | null;
    minScore: number;
    className?: string;
    isLoading: boolean;
}

// Define color stops for each score level
const colors = ['#FF0000', '#FF4400', '#FFA200', '#FFFF00', '#37FF00'];
const words = ['Weak', 'Fair', 'Good', 'Strong', 'Very Strong'];

export default function PasswordFeedback({ zxcvbn, className = '', minScore, isLoading }: Props) {
    // Calculate the score index (0-4)
    const score = zxcvbn ? Math.min(zxcvbn.score, 4) : 0;

    // Create gradient stops based on score
    const gradientStops = colors
        .map((color, index) => `${color} ${(index / 4) * 100}%`)
        .slice(0, score + 1)
        .join(', ');

    // Width of the filled portion of the bar
    const widthPercentage = (score / 4) * 100;

    const feedbackDisplay = zxcvbn ? zxcvbn.crack_times_display.offline_slow_hashing_1e4_per_second : '_______';

    return (
        <div className={`flex flex-col ${className}`}>
            <div className="text-sm">
                <span className="font-bold">Password Strength:</span> {words[score]}
            </div>
            <div className="flex items-center gap-2 w-full mt-1">
                <div className="w-full h-4 bg-gray-200 rounded overflow-hidden relative">
                    <div
                        className="h-full"
                        style={{
                            width: `${widthPercentage}%`,
                            background: `linear-gradient(to right, ${gradientStops})`,
                        }}
                    ></div>
                </div>
                <div className="text-xl">
                    {score < minScore ? (
                        <FaRegTimesCircle className="text-red-500" />
                    ) : (
                        <FaRegCheckCircle className="text-green-500" />
                    )}
                </div>
            </div>
            <div className="text-xs text-gray-500 mt-1">
                {isLoading ? (
                    <>
                        <div className="flex items-center gap-2">
                            <div className="loading loading-xs" />
                            <span>Checking password strength...</span>
                        </div>
                    </>
                ) : (
                    <>
                        Your password would take&nbsp;
                        <span className="font-bold">{feedbackDisplay}</span>
                        &nbsp;to crack.
                    </>
                )}
            </div>
            {zxcvbn && zxcvbn.feedback.suggestions.length > 0 ? (
                <div className="text-xs text-gray-800 mt-4">
                    <span className="font-bold">Suggestions:</span>
                    <ul className="list-disc list-inside mt-2">
                        {zxcvbn.feedback.suggestions.map((suggestion, index) => (
                            <li key={index}>{suggestion}</li>
                        ))}
                    </ul>
                </div>
            ) : (
                <div className="h-12" />
            )}
        </div>
    );
}

This component accepts the zxcvbn response object and displays a nifty little password meter based on the score (0-4). It also displays any suggestions and the verbose "your password will take XX years to crack". All of this comes from zxcvbn!

Next, here is our helper function:

import type { ZXCVBNResult } from 'zxcvbn';

export default async function checkPasswordStrength(password: string): Promise<ZXCVBNResult> {
    const url = 'https://url-of-your-cloudflare-worker.com';
    const response = await fetch(url, {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ password }),
    });
    return await response.json();
}

Lastly, we'll put it all together in our form view:

'use client';

// Components
import React, { useState, useCallback, useEffect } from 'react';
import PasswordFeedback from '@/components/PasswordFeedback';

// Utilities
import checkPasswordStrength from '@/lib/passwordStrength';
import { debounce } from 'lodash-es';
import { usePoptart } from 'react-poptart';

// Types
import type { ZXCVBNResult } from 'zxcvbn';

const minScore = 3;

export default function HomeView() {
    const poptart = usePoptart();

    // State
    const [password, setPassword] = useState('');
    const [zxcvbn, setZxcvbn] = useState<ZXCVBNResult | null>(null);
    const [score, setScore] = useState<number>(0);
    const [error, setError] = useState<string | null>(null);
    const [isLoading, setIsLoading] = useState(false);

    // This function checks the password strength using the CloudFlare endpoint
    const handleCheckPasswordStrength = async (password: string) => {
        setIsLoading(true);
        try {
            const result = await checkPasswordStrength(password);
            setZxcvbn(result);
            setScore(result.score);
        } catch (err) {
            console.error(err);
        } finally {
            setIsLoading(false);
        }
    };

    // This is a debounced version of the password strength checker
    // eslint-disable-next-line react-hooks/exhaustive-deps
    const debouncedCheckPasswordStrength = useCallback(debounce(handleCheckPasswordStrength, 500), []);

    // Effects
    useEffect(() => {
        if (password) {
            debouncedCheckPasswordStrength(password);
        } else {
            setZxcvbn(null);
            setScore(0);
        }
    }, [password, debouncedCheckPasswordStrength]);

    const handleChange = (event: React.ChangeEvent<HTMLInputElement>) => {
        setPassword(event.target.value);
        setError(null);
    };

    const handleSubmit = (event: React.FormEvent<HTMLFormElement>) => {
        event.preventDefault();
        if (score < minScore) {
            const message = 'Password is too weak';
            setError(message);
            poptart.push({ message, type: 'error' });
        } else {
            setError(null);
            poptart.push({ message: 'Password is strong!', type: 'success' });
        }
    };

    // Render
    return (
        <form className="w-full max-w-lg m-auto flex flex-col gap-6 p-6 border-2 rounded-xl" onSubmit={handleSubmit}>
            <h1 className="text-2xl font-bold text-center">Password Strength Checker</h1>
            <label className="form-control w-full">
                <div className="label">
                    <span className="label-text">Password</span>
                </div>
                <input
                    type="password"
                    placeholder="Enter password"
                    className="input input-bordered w-full"
                    value={password}
                    onChange={handleChange}
                />
                <div className="label">
                    <span className="label-text-alt text-error">{error}</span>
                </div>
            </label>
            <PasswordFeedback zxcvbn={zxcvbn} minScore={minScore} isLoading={isLoading} />
            <button className="btn btn-primary" type="submit">
                Submit
            </button>
        </form>
    );
}

Here I'm using useCallback along with lodash.debounce to debounce the calls to the worker so we're not going crazy. It leaves a little bit of a delay after you finish typing, but I think it's quite acceptable UX-wise.

The component is relatively good on cumulative layout shift (CLF). The suggestions (if any) might extend the height a small amount, but other than that it's pretty solid!

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.

Clean Up Your Hard Drive: A Script to Delete All Your node_modules Directories

Jay @ Designly — Tue, 24 Sep 2024 00:25:41 +0000

If you're like me, you have a GitHub directory in your Documents folder with tens or possibly hundreds of repos that use the Node Package Manager. Also, if you're like me, you tend to work on several projects simultaneously. And, once again, if you're like me, you tend to forget about the node_modules directory when you're either done working on the project, or don't plan to for quite some time.

If this sounds like you, then this script is for you! It's written in bash, which you can run on Linux or Mac, but to run it on Windows, you'll want to go ahead and download the Cmder (link at bottom) console emulator, which gives you all the GNU tools we know and love, like ls, nano, rm, find, and, of course sh.

Alright, here's the code:

#!/bin/bash

# Initialize dry-run flag to false
DRY_RUN=false

# Initialize exclusion file to empty
EXCLUDE_FILE=""

trim_string() {
    echo "$1" | awk '{$1=$1};1'
}

# Manually parse command-line options
while [ "$#" -gt 0 ]; do
    case "$1" in
    -d)
        DRY_RUN=true
        shift
        ;;
    -e)
        EXCLUDE_FILE="$2"
        shift 2
        ;;
    *)
        # Assume the remaining argument is the parent directory
        PARENT_DIR="$1"
        shift
        ;;
    esac
done

# Check if the parent directory is provided
if [ -z "$PARENT_DIR" ]; then
    echo "Usage: $0 [-d] [-e exclude_file] <parent_directory>"
    exit 1
fi

# Read the exclusion list into an array
EXCLUDE_DIRS=()
if [ -n "$EXCLUDE_FILE" ]; then
    echo "Reading exclusion list from $EXCLUDE_FILE"
    while read -r exclude; do
        echo "Excluding: $exclude"
        EXCLUDE_DIRS+=("$exclude")
    done <"$EXCLUDE_FILE"
fi

# Loop through each subdirectory in the parent directory
for directory in "$PARENT_DIR"/*; do
    # Skip if not a directory
    if [ ! -d "$directory" ]; then
        continue
    fi

    # Get the name of the subdirectory
    subdir_name=$(basename "$directory")
    trimmed_subdir_name=$(trim_string "$subdir_name")

    echo "Current subdir: $subdir_name"

    skip=false
    # Check if the subdirectory is in the exclusion list
    for exclude in "${EXCLUDE_DIRS[@]}"; do
        trimmed_exclude=$(trim_string "$exclude")
        if [ "$trimmed_subdir_name" = "$trimmed_exclude" ]; then
            skip=true
            break
        fi
    done

    if [ "$skip" = true ]; then
        echo "Skipping excluded directory: $subdir_name"
    else
        echo "Processing directory: $directory"

        # Delete or print node_modules
        if [ -d "$directory/node_modules" ]; then
            if [ "$DRY_RUN" = true ]; then
                echo "[Dry Run] Would delete node_modules in $directory"
            else
                echo "Deleting node_modules in $directory"
                rm -rf "$directory/node_modules"
            fi
        else
            echo "node_modules does not exist in $directory"
        fi

        # Delete or print package-lock.json
        if [ -f "$directory/package-lock.json" ]; then
            if [ "$DRY_RUN" = true ]; then
                echo "[Dry Run] Would delete package-lock.json in $directory"
            else
                echo "Deleting package-lock.json in $directory"
                rm -f "$directory/package-lock.json"
            fi
        else
            echo "package-lock.json does not exist in $directory"
        fi

        # Delete or print yarn.lock
        if [ -f "$directory/yarn.lock" ]; then
            if [ "$DRY_RUN" = true ]; then
                echo "[Dry Run] Would delete yarn.lock in $directory"
            else
                echo "Deleting yarn.lock in $directory"
                rm -f "$directory/yarn.lock"
            fi
        else
            echo "yarn.lock does not exist in $directory"
        fi

        # Delete or print pnpm-lock.yaml
        if [ -f "$directory/pnpm-lock.yaml" ]; then
            if [ "$DRY_RUN" = true ]; then
                echo "[Dry Run] Would delete pnpm-lock.yaml in $directory"
            else
                echo "Deleting pnpm-lock.yaml in $directory"
                rm -f "$directory/pnpm-lock.yaml"
            fi
        else
            echo "pnpm-lock.yaml does not exist in $directory"
        fi
    fi
done

echo "Done!"

Here's how you can call the script. Open up Cmder and type:

sh C:\path\to\your\script.sh -d

The -d flag does a dry run, so you can see how it's going to effect your directories before you willy-nilly start deleting directories.

There is also a -e option to supply a file with a list of excluded directories. You don't need the full directory path in the list, just the relative pathname. So, for example, if you were running the script on C:\github and you want to skip C:\github\project1 and C:\github\project2, you would create an exclude.txt file with the following:

project1
project2

Then you run the command:

sh C:\path\to\your\script.sh -e C:\path\to\exclude.txt

That's it! Hope you enjoy. I know your backup software will be really happy with you! 🤣🙃

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.

React: Simple Yet Elegant Toast Notifications

Jay @ Designly — Sun, 22 Sep 2024 23:55:52 +0000

Bundlephobia is really starting to catch on these days as developers become more conscious of the packages they choose to install. Some devs, in the interest in fast turnaround, choose to willy-nilly install the first package they find that'll get the job done. However, this can very quickly lead to severe bloat and tons of unnecessary code being shipped to the browser.

That is why the main theme of my blog has taken a real do-it-yourself approach to solving many user interface problems.

In today's article, we are going to learn how to create simple (but also really cool!) toaster notifications in React, using zero dependencies!

The examples in this article are taken directly from my current project react-poptart, an NPM package I published. These examples illustrate how you can architect your own notification system, but some parts of the code are missing (e.g. types, helper functions, etc.) For the full repo code, please visit the link at the bottom of the page. You are also more than welcome to simply install react-poptart in your app.

Using the React Context API

We want to turn our notification system into a global service for our app, so we're going to leverage the power of the React Context API. Doing so will allow us to make our notifications available to any child component.

// Provider.tsx
'use client';

import React, { createContext, useContext, useState } from 'react';
import Matrix from './Matrix';

import { getContrastColor, generateSecureString, deepMerge } from './helpers';

import { defaultConfig } from './constants';

import type {
    I_PoptartProviderProps,
    I_PoptartContext,
    I_PoptartItem,
    I_PoptartProps,
    I_PoptartConfig,
    I_PoptartUserConfig,
} from './types';

// Create the Poptart context
const PoptartContext = createContext<I_PoptartContext | undefined>(undefined);

export const PoptartProvider: React.FC<I_PoptartProviderProps> = ({ children, config: userConfig }) => {
    // Merge the default options with the user options
    const config = deepMerge<I_PoptartConfig, I_PoptartUserConfig>(defaultConfig, userConfig || {});

    // State
    const [poptarts, setPoptarts] = useState<I_PoptartItem[]>([]);

    // Methods
    const push = (props: I_PoptartProps): string => {
        const id = generateSecureString(64);

        const foregroundColor = getContrastColor({
            backgroundColor: config.colors[props.type || config.defaultType],
            lightColor: config.colors.textLight,
            darkColor: config.colors.textDark,
        });

        let duration = config.defaultDuration;
        if (props.duration !== undefined) {
            duration = props.duration;
        }

        setPoptarts(prev => [
            ...prev,
            {
                id,
                props,
                expires: new Date(Date.now() + duration),
                progress: duration > 0 ? 100 : 0,
                foregroundColor,
            },
        ]);

        if (duration > 0) {
            setTimeout(() => {
                dismiss(id);
            }, duration);
        }

        return id;
    };

    // Dismiss a poptart
    const dismiss = (id: string) => {
        setPoptarts(prev => prev.filter(poptart => poptart.id !== id));
    };

    return (
        <PoptartContext.Provider
            value={{
                poptarts,
                config,
                currentAlert,
                push,
                dismiss,
            }}
        >
            {children}
            <Matrix config={config} poptarts={poptarts} dismiss={dismiss} />
        </PoptartContext.Provider>
    );
};

export const usePoptart = (): I_PoptartContext => {
    const context = useContext(PoptartContext);
    if (!context) {
        throw new Error('usePoptart must be used within a PoptartProvider');
    }
    return context;
};

Here's how it works:

We establish a global state to store our notifications poptarts
We create a push method that appends a new poptart object to the stack.
We use a helper function to determine the correct contrasting color for the text based on the background color (this is makes contrast automatic!)
We set a timer to dismiss the poptart if a duration is set.
Each poptart is given a unique ID
We create a dismiss method to be able to programmatically dismiss poptart by their ID.

Building the Components

We're going to need a component to display our poptarts. We're going to call it Matrix and it will be imported directly into the Provider context.

import React from 'react';
import Poptart from './Poptart';

import { useAnimations } from './animations';

import { I_PoptartConfig, I_PoptartItem } from './types';

interface Props {
    config: I_PoptartConfig;
    poptarts: I_PoptartItem[];
    dismiss: (id: string) => void;
}

const Matrix: React.FC<Props> = props => {
    const { config, poptarts, dismiss } = props;

    // Inject the animation keyframes into the DOM
    useAnimations();

    const styleAdditions: React.CSSProperties = {};

    // Align the matrix based on config
    switch (config.defaultAlign) {
        case 'tl':
            styleAdditions.justifyContent = 'flex-start';
            styleAdditions.alignItems = 'flex-start';
            break;
        case 'tc':
            styleAdditions.justifyContent = 'flex-start';
            styleAdditions.alignItems = 'center';
            break;
        case 'tr':
            styleAdditions.justifyContent = 'flex-start';
            styleAdditions.alignItems = 'flex-end';
            break;
        case 'bl':
            styleAdditions.justifyContent = 'flex-end';
            styleAdditions.alignItems = 'flex-start';
            break;
        case 'bc':
            styleAdditions.justifyContent = 'flex-end';
            styleAdditions.alignItems = 'center';
            break;
        case 'br':
            styleAdditions.justifyContent = 'flex-end';
            styleAdditions.alignItems = 'flex-end';
            break;
        default:
            styleAdditions.justifyContent = 'flex-end';
            styleAdditions.alignItems = 'flex-end';
            break;
    }

    // Main container styles
    const containerStyles: React.CSSProperties = {
        position: 'fixed',
        inset: 0,
        pointerEvents: 'none',
        display: 'flex',
        flexDirection: 'column',
        gap: '20px',
        padding: '20px',
        zIndex: config.zIndex + 2,
        ...styleAdditions,
        ...config.styleOverrides.container,
    };

    return (
        <div className="poptart-container" style={containerStyles}>
            {poptarts.map((poptart) => (
                <Poptart key={poptart.id} dismiss={dismiss} config={config} {...poptart} />
            ))}
        </div>
    );
};

export default Matrix;

Here, we've created a <div> container that covers the whole screen. We allow the user to supply the base zIndex and then we add to it to create our layers. We use pointerEvents: 'none' to prevent the <div> from blocking click events to the rest of the app below.

The switch statement allows us to use a simple 2-letter code to set the spawn location of our notifications. This is all fully typed, too, so we'll get nice auto-completion.

The useAnimations hook simply injects our animation CSS keyframes directly into the DOM. For sake of brevity, that code is not included here, but feel free to peruse the repo (link at bottom).

Next, we import our <Poptart> component. This is the actual notification that will be displayed.

// Poptart.tsx

import React from 'react';
import Icon from './Icon';
import ProgressBar from './ProgressBar';

import type { I_PoptartItem, I_PoptartConfig } from './types';

interface Props extends I_PoptartItem {
    config: I_PoptartConfig;
    dismiss: (id: string) => void;
}

const Poptart: React.FC<Props> = superProps => {
    const { props, id, foregroundColor, config, dismiss } = superProps;
    const { message, onClick } = props;

    const type = props.type || config.defaultType;
    const backgroundColor = config.colors[type];
    const width = props.width || config.defaultWidth;
    const fontSize = config.fontSize;
    const paddingX = config.paddingX;
    const paddingY = config.paddingY;
    const progressBarHeight = config.progressBar.height;
    const duration = props.duration !== undefined ? props.duration : config.defaultDuration;
    const hasDuration = duration > 0;
    const animation = props.animation || config.defaultAnimation;
    const animationDuration = props.animationDuration || config.defaultAnimationDuration;

    const defaultPoptartStyle = config.defaultPoptartStyle === 'default' ? 'filled' : config.defaultPoptartStyle;
    let poptartStyle = defaultPoptartStyle;
    if (props.poptartStyle) {
        poptartStyle = props.poptartStyle === 'default' ? defaultPoptartStyle : props.poptartStyle;
    }
    const isInverted = poptartStyle === 'inverted';

    // Dynamic styles
    const dynamicStyles: React.CSSProperties = {
        backgroundColor: isInverted ? config.colors.invertedBackground : backgroundColor,
        color: isInverted ? backgroundColor : foregroundColor,
        width,
        maxWidth: '100%',
        paddingTop: `${paddingY}px`,
        paddingLeft: `${paddingX}px`,
        paddingRight: `${paddingX}px`,
        paddingBottom: `${paddingY + (hasDuration ? progressBarHeight : 0)}px`,
        borderRadius: '10px',
        overflow: 'hidden',
        cursor: 'pointer',
        position: 'relative',
        pointerEvents: 'auto',
        fontSize,
        boxShadow: '0 0 10px rgba(0, 0, 0, 0.2)',
        border: '1px solid rgba(0, 0, 0, 0.1)',
        animation: `${animation} ${animationDuration}s ease-out`,
        ...config.styleOverrides.poptart,
    };

    const innerStyle: React.CSSProperties = {
        display: 'flex',
        alignItems: 'center',
        gap: '10px',
    };

    const textStyle: React.CSSProperties = {
        wordBreak: 'break-word',
        hyphens: 'auto',
        overflowWrap: 'break-word',
        textShadow: isInverted ? `2px 2px 2px rgba(0, 0, 0, 0.1)` : `2px 2px 2px rgba(0, 0, 0, 0.3)`,
    };

    const handleClick = () => {
        dismiss(id);
        onClick && onClick();
    };

    const iconSize = fontSize * config.iconSizeFactor;

    return (
        <div className="poptart" style={dynamicStyles} onClick={handleClick}>
            <div className="poptart-inner" style={innerStyle}>
                <div className="poptart-icon" style={{ width: iconSize }}>
                    <Icon type={type} color={isInverted ? backgroundColor : foregroundColor} size={iconSize} />
                </div>
                <span className="poptart-message" style={textStyle}>
                    {message}
                </span>
            </div>
            {hasDuration ? (
                <ProgressBar
                    poptart={props}
                    height={config.progressBar.height}
                    backgroundColor={backgroundColor}
                    colorOverride={isInverted ? backgroundColor : undefined}
                    config={config}
                />
            ) : null}
        </div>
    );
};

export default Poptart;

Here, we create our base styles and then calculate user defined vs default config styles. We also allow all styles to be overridden.

Next, we create a simple <ProgressBar> component to display a cool countdown timer at the bottom:

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

import { getContrastColor } from './helpers';

import { I_PoptartConfig, I_PoptartProps } from './types';

interface ProgressBarProps {
    poptart: I_PoptartProps;
    height: number;
    backgroundColor: string;
    config: I_PoptartConfig;
    colorOverride?: string;
}

const ProgressBar: React.FC<ProgressBarProps> = ({ poptart, height, backgroundColor, config, colorOverride }) => {
    const color =
        colorOverride ??
        getContrastColor({
            backgroundColor,
            lightColor: config.progressBar.lightColor,
            darkColor: config.progressBar.darkColor,
        });

    const [width, setWidth] = useState(100);

    const duration = poptart.duration || config.defaultDuration;

    useEffect(() => {
        setTimeout(() => {
            setWidth(0);
        }, 100);
    }, []);

    const dynamicStyles: React.CSSProperties = {
        position: 'absolute',
        bottom: 0,
        left: 0,
        height: `${height}px`,
        backgroundColor: color,
        width: `${width}%`,
        transition: `width ${duration}ms linear`,
        ...config.styleOverrides.progressBar,
    };

    return <div className="poptart-progress" style={dynamicStyles} />;
};

export default ProgressBar;

The trick here is we set the CSS transition duration value via our duration variable. Easy huh?

There are a few more pieces to the puzzle to build your own notification library, but this is the basics of how to get started. Please feel free to browse through the entire repo.

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

Also, be sure to check out my new app called Snoozle! It's an app that generates bedtime stories for kids using AI and it's completely free to use!

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

How to Create a Full-Stack Blog with Payload CMS, Next.js and Turbo

Jay @ Designly — Tue, 03 Sep 2024 06:25:55 +0000

Today's article is going to be loaded! TL;DR: We're going to build a full-stack blog app using Next.js for the frontend and Payload CMS for the backend. And we'll package it all up nicely using Turborepo!

Payload CMS is what's called a headless CMS, which simply means that it's a content management system that does not have a user-facing frontend. It's only used for managing the content. Payload CMS is built on top of Express.js and React, so it's the perfect backend solution for a Next.js or React app.

Payload Features and Benefits:

Typescript friendly (can generate types based on model definitions)
Built-in GraphQL and REST server
Can export GraphQL schema automatically
GraphQL playground built-in
Can extend and modify any admin component as a React component
Cloud storage adapters for AWS, GCP, etc.
Built-in support for MongoDB and Postgres

The goal of Payload CMS is to be extremely minimalistic in its design and structure, while at the same time providing robust access to its inner workings in order to modify and extend everything to suit your needs. It does the arduous task of boilerplating a REST or GraphQL API for you, plus gives you the CMS to boot--and that's worth gold!

If this sounds like something that interests you, then let's get to coding!

I. Configuring Turborepo

Turborepo and Turbopack have been absolute game changers for me so we're going to use it on this project. One of the greatest benefits of using a monorepo for a project like this is the ability to share types and components between the two projects. I will be demonstrating some of that shortly.

If you don't already have turbo installed globally, I highly recommend doing so now:

npm i -g turbo

Turbo also has a nice little init script as well:

npx create-turbo@latest fullstack-blog

In a Turborepo, we keep our apps in the /apps folder. Let's create our Next.js and Payload apps now:

cd ./fullstack-blog
npx create-next-app@latest frontend
npx create-payload-app@latest backend

You'll need to have your MongoDB URI ready to run the install script for Payload. The format should be:

mongodb+srv://user:password@hostname/database

The only other thing you'll need to do before you can fire up the dev servers is change the listening port on next dev to next dev -p 3001 in frontend's package.json. That way Next.js will run on 3001, while Payload runs on its default port of 3000.

Now all you have to do is run npm run dev in the Turborepo root. You should see a nice fancy interface appear in the terminal console:

You can use the up/down arrow keys to switch between tasks. Press enter to interact with the console. You can issue commands like r to restart the dev sever.

II. Constructing our Backend

As with any ORM, we need to define our object models. They're called collections in Payload because it was primarily designed to be used with MongoDB. In MongoDB you don't have a table of data so much as you have a collection of documents stored in binary JSON format.

In Payload, collection definitions are stored in src/collections. You'll notice that there's already one in there called Users.ts. That's because in order to log into the CMS admin interface, you'll need a user account and password. Payload will ask you to create the first user account the first time you load the web interface at http://localhost:3000.

The email and password and other fields are built in to the special Users collection, but you can add any custom fields you like to the model. For the purposes of this demonstration, we're going to largely leave the Users model alone. The only thing we'll do is turn on useAPIKey and set the access control flags:

import { CollectionConfig } from "payload/types";

import { access } from "../lib/access";

const Users: CollectionConfig = {
  slug: "users",
  auth: {
    useAPIKey: true,
  },
  admin: {
    useAsTitle: "email",
    description: "A collection of users",
  },
  fields: [
    // Email added by default
    // Add more fields as needed
  ],
  access: {
    read: access,
    create: access,
    update: access,
    delete: access,
  },
};

export default Users;

As you can see I added the access prop to the collection. Each of the CRUD props takes a Boolean value. How you determine who and what can access your models is completely up to you. For the purposes of this demonstration, however, I wrote a little helper script that simply determines if we're logged in or not, since I'm the only user of the CMS:

import { AccessArgs } from "payload/config";

export function access({ req }: AccessArgs) {
  const { user } = req;

  return !!user;
}

Next, let's set up a collection for storing photos for our full-stack blog. We'll call it Photos:

import { CollectionConfig } from "payload/types";

import { access } from "../lib/access";

const Photos: CollectionConfig = {
  slug: "photos",
  admin: {
    useAsTitle: "title",
    description: "A collection of photos",
  },
  access: {
    read: () => true,
    create: access,
    update: access,
    delete: access,
  },
  fields: [
    {
      name: "title",
      label: "Title",
      type: "text",
      required: true,
    },
  ],
  upload: {
    staticURL: "https://cdn.designly.biz/blogtest/photos",
    adminThumbnail: "thumbnail",
    mimeTypes: ["image/jpeg", "image/png"],
  },
};

export default Photos;

Again, you'll notice the access control flags. This time I set read to an anonymous function that returns true because I want to have public read access for our blog client app to be able to fetch data. For other CRUD operations, we'll need a logged in user as before.

The only field we'll have is a title that we can use for the alt attribute or caption for our blog images.

Finally, take a look at the upload section. We have staticURL. This is the URL that gets prepended to the Photo object url prop when it's fetched from the API. In my example I have my CloudFront edge endpoint with a URL prefix. This is a CloudFront distribution with an S3 bucket as its origin server. For a complete (and still current) guide on how to set that up, please see the resource links below.

Now let's set up a collection for our blog posts:

import { CollectionConfig } from "payload/types";

import { slug } from "../fields/slug";
import { access } from "../lib/access";

const Blogs: CollectionConfig = {
  slug: "blogs",
  admin: {
    useAsTitle: "title",
    description: "A collection of blog posts",
  },
  access: {
    read: () => true,
    create: access,
    update: access,
    delete: access,
  },
  fields: [
    {
      name: "title",
      label: "Title",
      type: "text",
      required: true,
    },
    {
      name: "coverPhoto",
      label: "Cover Photo",
      type: "upload",
      relationTo: "photos",
      required: true,
      admin: {
        disableListColumn: true,
      },
    },
    slug(
      { trackingField: "title" },
      {
        required: true,
        admin: {
          readOnly: true,
          disableListColumn: true,
        },
      }
    ),
    {
      name: "excerpt",
      label: "Excerpt",
      type: "textarea",
      required: true,
      admin: {
        disableListColumn: true,
      },
    },
    {
      name: "content",
      label: "Content",
      type: "richText",
      required: true,
      admin: {
        disableListColumn: true,
      },
    },
    {
      name: "status",
      label: "Status",
      type: "select",
      defaultValue: "draft",
      options: [
        {
          label: "Draft",
          value: "draft",
        },
        {
          label: "Published",
          value: "published",
        },
      ],
    },
  ],
};

export default Blogs;

This is a very minimalist setup. In your own production blog, you might want to add other collections and relations like tags, authors or categories. I've omitted all that here for sake of brevity.

You might notice the imported SlugInput. That's actually a custom React component to handle automatic generation of the slug in real time as you're typing the title.

In order to create our own custom field like this, we first need to define a custom field. We'll keep these in src/fields:

import React from "react";
import { Field } from "payload/types";
import { merge } from "lodash";
import SlugInput from "../ui/SlugInput";

type Slug = (
  options?: { trackingField?: string },
  overrides?: Partial<Field>
) => Field;

export const slug: Slug = ({ trackingField = "title" } = {}, overrides) =>
  merge<Field, Partial<Field> | undefined>(
    {
      name: "slug",
      unique: true,
      type: "text",
      admin: {
        position: "sidebar",
        components: {
          Field: (props) => (
            <SlugInput trackingField={trackingField} {...props} />
          ),
        },
      },
    },
    overrides
  );

This file defines the constraints for our slug field. We must have it and it must be unique. Note that this file must be a .tsx file because we're supplying a JSX (React) component. The trackingField prop is the name (slug) of the field we're going to base the slug on.

Here's is the code for the React component that will be our slug input:

import React, { useEffect, useRef } from "react";
import { kebabCase } from "lodash";
import { TextInput, useFieldType } from "payload/components/forms";

import { TextField } from "payload/types";

export type SlugInputProps = TextField & {
  trackingField: string;
};

export default function SlugInput(props: SlugInputProps) {
  const {
    trackingField,
    required,
    admin: { readOnly },
  } = props;

  const { value: slugValue = "", setValue: setSlugValue } =
    useFieldType<string>({
      path: "slug",
    });

  const { value: trackingFieldValue } = useFieldType<string>({
    path: trackingField,
  });

  const prevTrackingFieldValueRef = useRef(trackingFieldValue);
  const stopTrackingRef = useRef(false);

  useEffect(() => {
    if (!trackingField || stopTrackingRef.current) {
      return;
    }
    if (trackingFieldValue === prevTrackingFieldValueRef.current) {
      return;
    }
    const prevSlugValue = kebabCase(prevTrackingFieldValueRef.current);
    prevTrackingFieldValueRef.current = trackingFieldValue;
    if (prevSlugValue !== slugValue) {
      return;
    }
    setSlugValue(kebabCase(trackingFieldValue));
  }, [trackingFieldValue]);

  return (
    <div>
      <TextInput
        name="slug"
        path="slug"
        label="Slug"
        description={
          slugValue
            ? `Auto generated based on ${trackingField}`
            : `Will be auto-generated from ${trackingField} when saved`
        }
        value={slugValue}
        onChange={(e) => {
          setSlugValue(e.target.value);
          stopTrackingRef.current = true;
        }}
        readOnly={readOnly}
        required={required}
      />
    </div>
  );
}

I owe the inspiration for this component to @Stupidism from GitHub. Link at the bottom.

Ok now that we have our collections all set up, we need to import them into the main Payload config file. We're also going to set up AWS S3 storage for our Photos collection:

// payload.config.ts

import path from "path";

import { payloadCloud } from "@payloadcms/plugin-cloud";
import { mongooseAdapter } from "@payloadcms/db-mongodb";
import { webpackBundler } from "@payloadcms/bundler-webpack";
import { slateEditor } from "@payloadcms/richtext-slate";
import { buildConfig } from "payload/config";
import { cloudStorage } from "@payloadcms/plugin-cloud-storage";
import { s3Adapter } from "@payloadcms/plugin-cloud-storage/s3";

// Collections
import Users from "./collections/Users";
import Blogs from "./collections/Blog";
import Photos from "./collections/Photo";

export default buildConfig({
  admin: {
    user: Users.slug,
    bundler: webpackBundler(),
  },
  editor: slateEditor({}),
  // List your collections here
  collections: [Users, Blogs, Photos],
  typescript: {
    outputFile: path.resolve(__dirname, "payload-types.ts"),
    declare: false,
  },
  graphQL: {
    schemaOutputFile: path.resolve(__dirname, "generated-schema.graphql"),
  },
  upload: {
    limits: {
      fileSize: 10000000, // 10MB
    },
  },
  plugins: [
    payloadCloud(),
    // AWS S3 config
    cloudStorage({
      collections: {
        photos: {
          prefix: "blogtest/photos",
          disableLocalStorage: true,
          adapter: s3Adapter({
            config: {
              credentials: {
                accessKeyId: process.env.AWS_ACCESS_KEY_ID,
                secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY,
              },
              region: "us-east-1",
            },
            bucket: "designly-cdn",
          }),
        },
      },
    }),
  ],
  db: mongooseAdapter({
    url: process.env.DATABASE_URI,
  }),
});

As you can see, you can change cloud storage options on a collection-specific basis by referring to its slug. Be sure to set disableLocalStorage to true if you're planning to host on a serverless platform. Note the prefix prop. If you remember, this is a the path of my static URL I had in my Photos collection. Here it's being used as the S3 object key prefix.

That's it for the setup. Now you can run npm run generate:types in the backend directory and you'll get all the types generated for our collections in a single file called payload-types.ts. I'll show you how you can import that into your Next.js project in the next section.

III. Constructing our Frontend

The first thing we'll want to do in our Next.js project is setup an additional path in our tsconfig.json file so we can import files from the backend directory:

"paths": {
  "@/*": ["./src/*"],
  "$/*": ["../backend/src/*"]
}

Next, we'll create a few utility functions to assist with fetching our blog posts:

import { ApolloClient, InMemoryCache, gql } from "@apollo/client";
import { Blog, Photo } from "$/payload-types";

const client = new ApolloClient({
  uri: "http://localhost:3000/api/graphql",
  cache: new InMemoryCache(),
});

export type PhotoCover = Pick<Photo, "url" | "title">;

export type BlogListItem = Pick<
  Blog,
  "id" | "slug" | "title" | "excerpt" | "createdAt"
> & { coverPhoto: PhotoCover };

export type BlogPost = Pick<
  Blog,
  "id" | "title" | "slug" | "excerpt" | "content" | "createdAt"
> & { coverPhoto: PhotoCover };

export async function getBlogs(): Promise<BlogListItem[]> {
  const query = gql`
    query GetBlogs {
      Blogs(where: { status: { equals: published } }) {
        docs {
          id
          slug
          title
          excerpt
          coverPhoto {
            url
            title
          }
          createdAt
        }
      }
    }
  `;

  const { data } = await client.query<{ Blogs: { docs: BlogListItem[] } }>({
    query,
  });

  return data?.Blogs?.docs || [];
}

export async function getBlog(slug: string): Promise<BlogPost | null> {
  const query = gql`
    query GetBlogBySlug($slug: String!) {
      Blogs(where: { slug: { equals: $slug }, status: { equals: published } }) {
        docs {
          id
          title
          slug
          coverPhoto {
            url
            title
          }
          excerpt
          content
          createdAt
        }
      }
    }
  `;

  const { data } = await client.query<{ Blogs: { docs: BlogPost[] } }>({
    query,
    variables: { slug },
  });

  return data?.Blogs?.docs[0] || null;
}

export async function getAllSlugs(): Promise<string[]> {
  const query = gql`
    query GetAllSlugs {
      Blogs(where: { status: { equals: published } }) {
        docs {
          slug
        }
      }
    }
  `;

  const { data } = await client.query<{ Blogs: { docs: { slug: string }[] } }>({
    query,
  });

  return data?.Blogs?.docs.map((doc) => doc.slug) || [];
}

First we'll define some narrowed down types based on our collection types and we're using Apollo client to make the GraphQL queries. We have three functions, the first is to get our list of blog articles for the home page, the second is to fetch a single article based on the slug, and the last is to get a complete list of slugs for all articles.

Next, we'll need a helper function to parse the Rich Text content of our blog article into JSX:

import React, { Fragment } from "react";
import escapeHTML from "escape-html";
import { Text } from "slate";

import { BlogPost } from "@/lib/blogs";

type Children = BlogPost["content"];

export const serialize = (children: Children) =>
  children.map((node, i) => {
    if (Text.isText(node)) {
      let text = (
        <span dangerouslySetInnerHTML={{ __html: escapeHTML(node.text) }} />
      );

      if (node.bold) {
        text = <strong key={i}>{text}</strong>;
      }

      if (node.code) {
        text = <code key={i}>{text}</code>;
      }

      if (node.italic) {
        text = <em key={i}>{text}</em>;
      }

      if (node.text === "") {
        text = <br />;
      }

      // Handle other leaf types here...

      return <Fragment key={i}>{text}</Fragment>;
    }

    if (!node) {
      return null;
    }

    switch (node.type) {
      case "h1":
        return <h1 key={i}>{serialize(node.children as Children)}</h1>;
      case "h2":
        return <h2 key={i}>{serialize(node.children as Children)}</h2>;
      case "h3":
        return <h3 key={i}>{serialize(node.children as Children)}</h3>;
      case "h4":
        return <h4 key={i}>{serialize(node.children as Children)}</h4>;
      case "h5":
        return <h5 key={i}>{serialize(node.children as Children)}</h5>;
      case "h6":
        return <h6 key={i}>{serialize(node.children as Children)}</h6>;
      case "blockquote":
        return (
          <blockquote key={i}>
            {serialize(node.children as Children)}
          </blockquote>
        );
      case "ul":
        return <ul key={i}>{serialize(node.children as Children)}</ul>;
      case "ol":
        return <ol key={i}>{serialize(node.children as Children)}</ol>;
      case "li":
        return <li key={i}>{serialize(node.children as Children)}</li>;
      case "link":
        return (
          <a href={escapeHTML(node.url as string)} key={i}>
            {serialize(node.children as Children)}
          </a>
        );

      default:
        return <p key={i}>{serialize(node.children as Children)}</p>;
    }
  });

This parser uses the slate library as that is the default editor that Payload uses for the Rich Text type. Payload also works with Lexical, but I have not tried it. I personally like to use markdown for my blog. I edit my articles in an app called Obsidian and then just paste the markdown into a plain text field in my CMS. You can use tools like react-markdown, remark-gfm, and react-syntax-highlighter.

Now you can create a blog content component for the frontend as easy as this:

import React from "react";

import { serialize } from "@/lib/renderer";

import { Blog } from "$/payload-types";

export type BlogContentProps = Pick<Blog, "content"> & { className?: string };

export default function BlogContent(props: BlogContentProps) {
  const { content, className = "" } = props;

  const jsx = serialize(content);

  return (
    <div className={`post-body flex flex-col gap-6 ${className}`}>{jsx}</div>
  );
}

I won't include all the components for the frontend here because this article is already way too long. However, I've posted the entire monorepo of this demonstration for everyone's enjoyment. Please see the link below!

Resources

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

Also, be sure to check out my new app called Snoozle! It's an app that generates bedtime stories for kids using AI and it's completely free to use!

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