DEV Community: Dale Nguyen

Free Model Providers to Use with Hermes Agent

Dale Nguyen — Fri, 29 May 2026 04:12:02 +0000

Hermes Agent by NousResearch is an open-source AI agent that does something most frameworks do not: it learns from experience. It creates skills during use, refines its memory across sessions, and supports parallel subagents and a built-in cron scheduler. You can run it on a $5 VPS, a GPU cluster, or serverless infrastructure.

The part that makes it immediately approachable is its provider flexibility. Hermes supports 200+ models across a growing list of providers, and you switch between them with a single command — no code changes. That means you can get started entirely on free tiers before committing to a paid API.

This post covers which free providers work with Hermes Agent and how to get up and running with each.

Installing Hermes Agent

curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash
source ~/.bashrc
hermes

That drops you into the interactive CLI. Run hermes setup to walk through the full configuration wizard, or hermes setup --portal to connect via Nous Portal (their own hosted service with OAuth, which consolidates all your API keys into one subscription).

Switching providers

Once installed, switching providers is a single command:

hermes model

Or inline during a conversation: /model [provider:model]

No config file edits, no restarts. This is what makes free-tier exploration practical — you can try a model, hit a rate limit, and switch to another in seconds.

Free providers supported by Hermes Agent

Nous Portal

Nous Portal is Hermes's native provider. It consolidates model access, web search, image generation, and TTS under one subscription. If you want the tightest integration with Hermes and the Nous ecosystem, this is the starting point. Check their current free tier on signup.

OpenRouter

OpenRouter is the most flexible free option. It gives you access to 200+ models — including Llama 4, DeepSeek, Gemma, and Mistral — through a single API key. The free tier covers 27+ models (marked with a :free suffix) at 200 requests per day and 20 requests per minute.

Because Hermes supports OpenRouter natively, you can point it at any of those free models immediately. This is the best option if you want to compare how Hermes behaves across different underlying models without managing multiple accounts.

NVIDIA NIM

NVIDIA NIM gives you free API credits on signup with no credit card required. The catalog includes 80+ models — Llama 4, Qwen, Mistral, and NousResearch's own Hermes 3 model — at roughly 40 requests per minute. Credits do not expire.

NIM is the best free option if you specifically want to run a NousResearch model underneath Hermes Agent, since it hosts the Hermes 3 fine-tune directly.

Hugging Face

Hugging Face Inference Providers gives every account monthly free credits routed across a network of inference providers (Groq, Together, SambaNova, and others). Hermes Agent supports HuggingFace natively.

The free tier is best for trying niche or smaller models. Cold starts can be slow on the free tier, so it is less suitable for long interactive sessions but fine for batch tasks or evaluation.

NovitaAI

NovitaAI is a cost-efficient inference provider with a generous free tier for new accounts. Hermes supports it natively. It is worth trying if OpenRouter and NVIDIA NIM rate limits become a bottleneck during heavy agent development.

Kimi / Moonshot

Kimi (by Moonshot AI) offers a free tier with long-context models. Hermes Agent lists it as a supported provider. Particularly useful if your agent tasks involve processing large documents or long conversation histories that would exhaust the context windows of other free-tier models.

Provider comparison at a glance

Provider	Free Tier	Best for with Hermes
Nous Portal	Check on signup	Tightest Hermes integration
OpenRouter	200 req/day, 27+ free models	Model variety, easy switching
NVIDIA NIM	Credits on signup, no expiry	Running NousResearch models
Hugging Face	Monthly credits	Niche models, batch tasks
NovitaAI	Free credits on signup	Alternative when hitting rate limits
Kimi / Moonshot	Free tier	Long-context tasks

Tips for running Hermes on free tiers

Rate limits compound in agentic loops. Hermes's learning loop and subagent features can make many model calls per task. At 20 req/min (OpenRouter free), a multi-step task hits the ceiling quickly. Use hermes model to switch to a provider with a higher limit mid-session, or configure a fallback provider.

Use NVIDIA NIM for NousResearch models specifically. If you want the model that Hermes was designed around — the Hermes 3 fine-tune — NIM hosts it directly at nousresearch/hermes-3-llama-3.1-70b. The free credits cover meaningful development without hitting a daily request cap.

OpenRouter first for exploration. Its unified free tier across 27+ models is the fastest way to understand how Hermes Agent behaves with different underlying models. No separate accounts, one key, switch with /model.

Run hermes doctor when something breaks. The built-in diagnostics command checks your provider configuration and surfaces misconfigurations before you spend time debugging the wrong thing.

Summary

Hermes Agent is one of the few open-source agents with a genuine learning loop built in, and its multi-provider support means you are not locked into any single API. To get started for free: install Hermes, run hermes setup, and connect OpenRouter or NVIDIA NIM — both work out of the box with no credit card. Switch models with hermes model as you explore what works best for your use case.

Building a Personal Assistant in Zo Computer and Adding Hermes as a Second Assistant

Dale Nguyen — Sun, 24 May 2026 14:03:23 +0000

Zo Computer works well as a personal operating system for life admin, creative work, learning, and day-to-day coordination. If you set it up intentionally, it can feel less like a chat app and more like a real assistant that lives with your files, routines, and preferences.

The good news is that getting started costs nothing. Zo has a free tier that is a perfect place to test a personal assistant setup before committing to anything. On the Hermes side, NVIDIA offers free API credits through their developer platform, so you can run Hermes against a capable model without paying for API usage upfront. That means you can build out the full two-assistant setup described in this post for free.

A strong pattern is to use Zo as your main personal assistant and Hermes as a second assistant that handles a different lane of work. Zo stays close to your files, your rules, your automations, and your personal workflows. Hermes becomes the extra pair of hands: a separate agent for focused tasks, parallel research, and longer-running jobs.

Why a personal assistant in Zo is useful

Zo is especially good for personal use because it can sit near the center of your life instead of scattered across separate apps. That means you can keep the things an assistant needs in one place:

notes and documents
recurring routines
calendar-aware tasks
saved preferences and rules
files you want the assistant to work from
automations that run without you micromanaging them

The real advantage is continuity. A personal assistant becomes much more useful when it can remember your style, keep track of ongoing projects, and work from the same environment every day.

What "personal assistant" should mean in Zo

A good assistant in Zo should do more than answer questions. It should help you actually move things forward.

That usually means:

drafting messages, notes, and documents
organizing ideas into something usable
turning vague thoughts into a plan
reminding you about routines and deadlines
summarizing information from files or the web
handling repeatable life admin tasks
keeping track of preferences so you do not repeat yourself

If you treat Zo like a small command center, it stops being a generic chatbot and starts becoming a trusted helper.

The cleanest setup: one main assistant, one second assistant

The best setup is usually not "one AI that does everything." It is:

Zo as your primary assistant
Hermes as your second assistant

That split is useful because the assistants can have different jobs.

Zo as the primary assistant

Use Zo for:

personal life management
writing and editing
working directly from your files
scheduling and recurring routines
decisions that need your preferences
things you want tightly integrated with your Zo workspace

Hermes as the second assistant

Use Hermes for:

parallel research
long-running work
independent task handling
a separate memory stream
a different working style
conversations or jobs you want isolated from your main assistant

This is the important idea: the second assistant should not be a clone of the first. It should be a specialist.

How Hermes fits in

Hermes is designed as an autonomous agent with a built-in learning loop. According to its documentation, it can keep improving through use, remember across sessions, and work through messaging platforms like Telegram. It is meant to live somewhere persistent, such as a local machine, a VPS, or another hosted environment.

That makes Hermes a good second assistant when you want another agent running in parallel with Zo instead of replacing Zo.

Basic Hermes installation path

The easiest way to get started is to simply ask Zo to do it for you. Open a Zo chat and type something like:

"Install Hermes on my machine"

Zo will handle the setup steps, walk you through any configuration it needs, and get Hermes running without you having to touch the terminal. This is the fastest path if you are already inside Zo.

If you prefer to install manually, the official Hermes docs show a straightforward install flow for Linux, macOS, and WSL2:

curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash

For native Windows, the docs also provide a PowerShell installer. After installation, Hermes can be configured to run in the environment you want and connected to messaging tools like Telegram.

The practical setup pattern is:

install Hermes
choose where it will run
connect its messaging or command interface
give it a clear role
keep Zo as the main personal assistant

How to divide work between Zo and Hermes

If you want the setup to feel sane, give each assistant a clear job.

Zo handles the personal layer

Zo should own:

your personal notes
your tasks and routines
files you keep locally
preferences and recurring habits
writing that needs your voice
decisions that depend on your context

Hermes handles the parallel layer

Hermes should own:

research you want to run in the background
tasks that can be broken into substeps
experiments
alternate drafts or viewpoints
work that benefits from isolation

This division prevents the assistants from stepping on each other.

A simple working model

Here is a practical way to think about it:

Zo is the assistant that knows you.
Hermes is the assistant that helps you scale.

Zo keeps your life organized. Hermes helps you get more done.

That combination is especially useful when you are juggling creative work, learning, and admin at the same time. One assistant can stay close to your personal system while the other handles the overflow.

Tips for making the setup actually useful

1. Give each assistant a role

Do not let both assistants do the same job. That creates noise. Be explicit:

Zo = personal coordinator
Hermes = second operator

2. Keep preferences in one place

The more you repeat yourself, the less useful the system feels. Store your standards, defaults, and routines where the assistant can reuse them.

3. Use the assistant for real workflows

Do not use it only for chat. Make it draft, organize, summarize, and schedule. Real utility comes from repeatable workflows.

4. Keep the assistant close to your files

Your files are the memory of the system. The assistant gets more useful when it can work from documents, notes, and living records instead of starting from scratch each time.

5. Treat the second assistant like an aide, not a boss

Hermes should support your system, not replace your judgment. The best assistant setup is still human-led.

Example use case

A good two-assistant workflow might look like this:

Zo manages your personal planning, drafts, and routines.
Hermes runs a background research task, collects notes, and returns a concise summary.
You review both outputs and decide what to do next.

That is the sweet spot: one assistant keeps your life coherent, and the other adds throughput.

Bottom line

If you want a personal assistant inside Zo Computer, start by making Zo the center of your daily system: files, rules, routines, drafts, and reminders. Then add Hermes as a second assistant for parallel work, deeper automation, and independent tasks.

The result is not just "two AIs." It is a better division of labor:

Zo for your personal operating system
Hermes for your extra capacity

That is the setup that actually feels like having help.

If you want to try Zo Computer, you can sign up using my invite link (affiliate link).

Securing Your MCP Server with Firebase Auth: A Production Walkthrough

Dale Nguyen — Fri, 15 May 2026 16:10:31 +0000

Model Context Protocol (MCP) servers let AI assistants interact with real user data. That means auth isn't optional — it's the difference between a useful tool and a data breach. This post walks through exactly how Can Tax Pro secures its Python MCP server with Firebase Authentication, supporting both Firebase ID tokens (for direct access) and a custom OAuth 2.0 flow (for third-party clients like Claude.ai).

Architecture Overview

The system has three moving parts:

Browser / Claude.ai Client
       │
       │  Authorization: Bearer <token>
       ▼
  MCP Server (Python/FastMCP on Cloud Run)
       │
       │  Firebase Admin SDK
       ▼
  Firestore (data isolated by userId)

The MCP server accepts two token types:

Firebase ID tokens — issued by Firebase Authentication, verified cryptographically
Custom OAuth tokens (ctpo_*) — issued by the web app's OAuth server, stored as hashes in Firestore

The web app itself acts as the OAuth authorization server for third-party integrations.

Step 1: Initialize Firebase Admin SDK

The server initializes Firebase Admin once at startup, with environment-aware credential resolution:

# main.py
import firebase_admin
from firebase_admin import credentials, auth as firebase_auth, firestore

if not firebase_admin._apps:
    sa_json = os.environ.get("FIREBASE_SERVICE_ACCOUNT")
    project_id = os.environ.get("FIREBASE_PROJECT_ID")
    if sa_json:
        cred = credentials.Certificate(json.loads(sa_json))
        firebase_admin.initialize_app(cred, {"projectId": project_id})
    else:
        firebase_admin.initialize_app(options={"projectId": project_id})

Locally: set FIREBASE_SERVICE_ACCOUNT to your service account JSON.
On Cloud Run: omit it entirely — the SDK picks up Application Default Credentials (ADC) automatically via Workload Identity.

This means no secrets in production. Your Cloud Run service account just needs the Firebase Admin SDK Administrator Service Agent IAM role.

Step 2: Token Resolution

Two resolver functions handle each token type:

OAuth Tokens (`ctpo_*`)

Custom tokens are never stored in plaintext. The server hashes them with SHA-256 and looks up the hash in Firestore:

def resolve_oauth_token(bearer_token: str) -> str:
    token_hash = hashlib.sha256(bearer_token.encode()).hexdigest()
    doc = db.collection("oauthTokens").document(token_hash).get()
    if not doc.exists:
        raise ValueError("Invalid or revoked OAuth token")
    data = doc.to_dict()
    expires_at = data.get("expiresAt")
    if expires_at and expires_at < datetime.now(timezone.utc):
        raise ValueError("OAuth token expired")
    return data["userId"]

The Firestore document stores userId, expiresAt, clientId, and a refreshTokenHash. Revocation is instant — delete the document and the token stops working on the next request.

Firebase ID Tokens

Firebase handles the hard part:

def resolve_id_token(id_token: str) -> str:
    decoded = firebase_auth.verify_id_token(id_token)
    return decoded["uid"]

verify_id_token checks the signature against Google's public keys and validates claims (expiry, issuer, audience). It caches the public keys locally so it doesn't make a network call on every request.

Step 3: The Auth Middleware

A Starlette BaseHTTPMiddleware wraps every request. It tries the OAuth path first, then falls back to Firebase ID tokens:

class AuthMiddleware(BaseHTTPMiddleware):
    async def dispatch(self, request: Request, call_next):
        # Skip auth for public endpoints
        if request.url.path in _PUBLIC_PATHS:
            return await call_next(request)

        auth_header = request.headers.get("Authorization", "")
        if not auth_header.startswith("Bearer "):
            return Response(
                status_code=401,
                headers={"WWW-Authenticate": 'Bearer realm="tax-mcp"'},
            )

        token = auth_header.removeprefix("Bearer ").strip()
        token_set = _user_id_var.set("")

        try:
            # Try OAuth token first
            if token.startswith("ctpo_"):
                user_id = resolve_oauth_token(token)
            else:
                user_id = resolve_id_token(token)
            _user_id_var.set(user_id)
            return await call_next(request)
        except Exception as e:
            return Response(
                status_code=401,
                content=str(e),
                headers={"WWW-Authenticate": 'Bearer realm="tax-mcp"'},
            )
        finally:
            _user_id_var.reset(token_set)

Public paths (/health, /.well-known/oauth-protected-resource) bypass auth — necessary for health checks and OAuth discovery.

Step 4: Thread-Safe User Context

Tools shouldn't take a user_id parameter — that would pollute every signature and make testing awkward. Instead, use a ContextVar to propagate identity through the async call stack:

# _context.py
from contextvars import ContextVar

_user_id_var: ContextVar[str] = ContextVar("user_id")

def get_user_id() -> str:
    try:
        return _user_id_var.get()
    except LookupError:
        raise RuntimeError("User context not set — request did not pass through auth middleware.")

Every tool calls get_user_id() to scope its Firestore queries:

# tools/income.py
from .._context import get_user_id

@mcp.tool()
def list_income(tax_year_id: str) -> list[dict]:
    docs = (
        db.collection("users")
          .document(get_user_id())
          .collection("taxYears")
          .document(tax_year_id)
          .collection("incomeEntries")
          .stream()
    )
    return [{"id": d.id, **d.to_dict()} for d in docs]

ContextVar is async-safe — each concurrent request gets its own context, so there's no cross-contamination between users even under high concurrency.

The middleware resets the var in a finally block, which is critical: without cleanup, the context leaks to the next request on a reused coroutine.

Step 5: The OAuth 2.0 Server (Web App Side)

For third-party clients (Claude.ai, etc.), the web app implements an OAuth 2.0 authorization server. Here's the flow:

1. Client → GET /oauth/authorize?client_id=...&code_challenge=...
2. User logs in (Firebase Auth)
3. Server → redirect with authorization_code
4. Client → POST /oauth/token with code + code_verifier
5. Server → { access_token: "ctpo_...", refresh_token: "ctpr_..." }

Token generation (TypeScript, server-side):

// server/routes/oauth/token.post.ts
import { createHash, randomBytes } from "crypto";

const accessToken = "ctpo_" + randomBytes(32).toString("hex");
const tokenHash = createHash("sha256").update(accessToken).digest("hex");

await db.collection("oauthTokens").doc(tokenHash).set({
  userId: session.userId,
  clientId: session.clientId,
  expiresAt: new Date(Date.now() + 60 * 60 * 1000), // 1 hour
  createdAt: new Date(),
});

return { access_token: accessToken, token_type: "bearer", expires_in: 3600 };

The ctpo_ prefix lets the MCP server route to the right resolver without trying Firebase first. Only the hash ever touches the database.

PKCE (Proof Key for Code Exchange) protects the authorization code flow. The client sends a code_challenge (SHA-256 of a random code_verifier) in step 1, then proves ownership by sending the raw code_verifier in step 4. The server hashes it and compares:

const verifierHash = createHash("sha256")
  .update(body.code_verifier)
  .digest("base64url");

if (verifierHash !== session.codeChallenge) {
  throw createError({ statusCode: 400, message: "Invalid code_verifier" });
}

Step 6: Client-Side (Browser)

The Angular/Analog web app attaches Firebase ID tokens to outbound API requests via an HTTP interceptor:

// auth.interceptor.ts
export const authInterceptor: HttpInterceptorFn = (req, next) => {
  const auth = inject(Auth);
  return from(auth.currentUser?.getIdToken() ?? Promise.resolve(null)).pipe(
    switchMap((token) => {
      if (!token) return next(req);
      return next(req.clone({
        setHeaders: { Authorization: `Bearer ${token}` },
      }));
    }),
  );
};

getIdToken() auto-refreshes the token when it's close to expiry, so you never send a stale JWT.

Step 7: Firestore Security Rules

The MCP server uses the Admin SDK, which bypasses all Firestore security rules. The get_user_id() context is your authorization layer. But rules provide defense-in-depth for direct client SDK access:

rules_version = '2';
service cloud.firestore {
  match /databases/{database}/documents {
    match /users/{userId}/{document=**} {
      allow read, write: if request.auth != null && request.auth.uid == userId;
    }
    match /oauthTokens/{tokenId} {
      allow read, write: if false; // Server-only
    }
  }
}

OAuth token documents are locked to server-only access. Users can never read or write them directly.

Step 8: OAuth Discovery Endpoint

Well-behaved OAuth clients (including Claude.ai) auto-discover server capabilities. Expose the RFC 9728 metadata endpoint:

@app.get("/.well-known/oauth-protected-resource")
async def oauth_protected_resource():
    return JSONResponse({
        "resource": "https://your-mcp-server.run.app",
        "authorization_servers": ["https://your-web-app.com"],
        "bearer_methods_supported": ["header"],
    })

This tells clients where to find the authorization server and how to present tokens. It's a public endpoint (no auth required) — make sure it's in _PUBLIC_PATHS.

Step 9: Local Testing

Don't rely on a real Firebase project for unit tests. Seed a test token directly:

# test_auth.py
import hashlib
from firebase_admin import firestore
from datetime import datetime, timezone, timedelta

TEST_TOKEN = "ctpo_localtest_" + "a" * 48
TEST_TOKEN_HASH = hashlib.sha256(TEST_TOKEN.encode()).hexdigest()

def seed_test_token(db, user_id: str):
    db.collection("oauthTokens").document(TEST_TOKEN_HASH).set({
        "userId": user_id,
        "clientId": "test-client",
        "expiresAt": datetime.now(timezone.utc) + timedelta(hours=1),
    })

def cleanup(db):
    db.collection("oauthTokens").document(TEST_TOKEN_HASH).delete()

Then test the three critical paths: no token → 401, invalid token → 401, valid token → 200.

Security Properties

Property	How it's achieved
Token confidentiality	Only SHA-256 hashes stored; raw tokens never persist
Revocation	Delete Firestore doc; effective immediately
Expiry	Enforced server-side on every request
Multi-user isolation	`ContextVar` scopes every Firestore query to `userId`
No key management in prod	Cloud Run Workload Identity + ADC
Code injection protection	PKCE on OAuth code exchange
Defense in depth	Firestore rules lock down client SDK access

Summary

Securing an MCP server with Firebase Auth comes down to four things:

Middleware that validates tokens before any tool runs
ContextVar to propagate user identity without polluting tool signatures
Hash-only storage for custom OAuth tokens
Workload Identity to eliminate service account key management in production

The dual-token design (Firebase ID tokens for direct use, custom OAuth tokens for third-party clients) keeps the server flexible while maintaining a single, auditable auth path. Every request either has a valid, unexpired token mapping to a real user, or it gets a 401.

Building MCP Apps with Angular

Dale Nguyen — Sat, 25 Apr 2026 03:43:44 +0000

If you've been building MCP servers, you know the drill: your tool returns JSON, the host renders it as text, and the user squints at a timestamp string. MCP Apps change that — they let your server ship an interactive UI that the host renders in an iframe, right inside the conversation.

MCP Apps are built on the Model Context Protocol — an open standard. They're not tied to Claude or any specific AI provider. Any host that implements the MCP Apps specification (Claude Desktop, custom chat clients, or other AI assistants that adopt MCP) can render your UI. You build it once, and it works everywhere MCP is supported.

This post walks through building MCP Apps with Angular. We'll start with a single tool, add a second tool with its own UI, and then show how to share code between them without bloating either bundle.

How MCP Apps Work (Quick Recap)

View (Angular App) <--PostMessageTransport--> Host (AppBridge) <--MCP Client--> MCP Server

Server registers tools and resources. Each tool can point to a resource URI containing the UI.
Host (the chat client) fetches that resource and renders it in a sandboxed iframe.
View is your Angular app running inside that iframe. It uses the App class from @modelcontextprotocol/ext-apps to communicate with the host.

The key insight: your UI is bundled into a single self-contained HTML file using Vite and vite-plugin-singlefile. The host doesn't need to know it's Angular — it just loads HTML.

Project Structure

basic-server-angular/
├── mcp-app.html              # HTML entry point for UI #1
├── greeting-app.html         # HTML entry point for UI #2
├── src/
│   ├── main.ts               # Angular bootstrap for UI #1
│   ├── app.component.ts      # Get Time component
│   ├── greeting-main.ts      # Angular bootstrap for UI #2
│   ├── greeting.component.ts # Greeting component
│   ├── shared/
│   │   └── mcp-app-setup.ts  # Shared App + theming setup
│   └── global.css            # Host-aware CSS variables
├── server.ts                 # MCP server (registers tools + resources)
├── main.ts                   # Server entry point (HTTP + stdio)
└── vite.config.ts            # Builds each HTML into a single file

Step 1: The Server

Every MCP App starts on the server side. You register a tool (what the LLM calls) and a resource (the HTML that gets rendered). They're linked by a resource URI.

// server.ts
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import type { CallToolResult, ReadResourceResult } from "@modelcontextprotocol/sdk/types.js";
import fs from "node:fs/promises";
import path from "node:path";
import {
  registerAppTool,
  registerAppResource,
  RESOURCE_MIME_TYPE,
} from "@modelcontextprotocol/ext-apps/server";

const DIST_DIR = import.meta.filename.endsWith(".ts")
  ? path.join(import.meta.dirname, "dist")
  : import.meta.dirname;

export function createServer(): McpServer {
  const server = new McpServer({
    name: "Basic MCP App Server (Angular)",
    version: "1.0.0",
  });

  const resourceUri = "ui://get-time/mcp-app.html";

  // Register the tool — this is what the LLM calls
  registerAppTool(server, "get-time", {
    title: "Get Time",
    description: "Returns the current server time as an ISO 8601 string.",
    inputSchema: {},
    _meta: { ui: { resourceUri } }, // Links this tool to its UI
  }, async (): Promise<CallToolResult> => {
    const time = new Date().toISOString();
    return { content: [{ type: "text", text: time }] };
  });

  // Register the resource — the bundled HTML for this tool's UI
  registerAppResource(server, resourceUri, resourceUri, {
    mimeType: RESOURCE_MIME_TYPE,
  }, async (): Promise<ReadResourceResult> => {
    const html = await fs.readFile(
      path.join(DIST_DIR, "mcp-app.html"),
      "utf-8",
    );
    return {
      contents: [{ uri: resourceUri, mimeType: RESOURCE_MIME_TYPE, text: html }],
    };
  });

  return server;
}

The _meta.ui.resourceUri is the glue. When the host calls this tool, it reads that field to know which resource to fetch and render.

Step 2: The HTML Entry Point

Each UI needs an HTML file at the project root. This is the Vite entry point that gets bundled into a single self-contained file.

<!-- mcp-app.html -->
<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <meta name="color-scheme" content="light dark">
  <title>Get Time App</title>
  <link rel="stylesheet" href="/src/global.css">
</head>
<body>
  <app-root></app-root>
  <script type="module" src="/src/main.ts"></script>
</body>
</html>

Step 3: The Angular App

The bootstrap is minimal — Angular 19+ with zoneless change detection:

// src/main.ts
import "@angular/compiler";
import { bootstrapApplication } from "@angular/platform-browser";
import { provideZonelessChangeDetection } from "@angular/core";
import { AppComponent } from "./app.component";
import "./global.css";

bootstrapApplication(AppComponent, {
  providers: [provideZonelessChangeDetection()],
}).catch((err) => console.error(err));

Now the component itself. The App class from @modelcontextprotocol/ext-apps is the bridge between your Angular code and the host:

// src/app.component.ts
import { Component, type OnInit, signal } from "@angular/core";
import {
  App,
  applyDocumentTheme,
  applyHostStyleVariables,
  applyHostFonts,
  type McpUiHostContext,
} from "@modelcontextprotocol/ext-apps";
import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js";

function extractText(result: CallToolResult): string {
  return result.content?.find((c) => c.type === "text")!.text;
}

@Component({
  selector: "app-root",
  template: `
    <main
      [style.padding-top.px]="hostContext()?.safeAreaInsets?.top"
      [style.padding-right.px]="hostContext()?.safeAreaInsets?.right"
      [style.padding-bottom.px]="hostContext()?.safeAreaInsets?.bottom"
      [style.padding-left.px]="hostContext()?.safeAreaInsets?.left"
    >
      <p><strong>Server Time:</strong> <code>{{ serverTime() }}</code></p>
      <button (click)="handleGetTime()">Get Server Time</button>
    </main>
  `,
})
export class AppComponent implements OnInit {
  private app: App | null = null;
  hostContext = signal<McpUiHostContext | undefined>(undefined);
  serverTime = signal("Loading...");

  async ngOnInit() {
    const instance = new App({ name: "Get Time App", version: "1.0.0" });

    instance.ontoolresult = (result) => {
      this.serverTime.set(extractText(result));
    };

    instance.onhostcontextchanged = (params) => {
      const ctx = { ...this.hostContext(), ...params };
      this.hostContext.set(ctx);
      if (ctx.theme) applyDocumentTheme(ctx.theme);
      if (ctx.styles?.variables) applyHostStyleVariables(ctx.styles.variables);
      if (ctx.styles?.css?.fonts) applyHostFonts(ctx.styles.css.fonts);
    };

    await instance.connect();
    this.app = instance;

    const ctx = instance.getHostContext();
    this.hostContext.set(ctx);
    if (ctx?.theme) applyDocumentTheme(ctx.theme);
    if (ctx?.styles?.variables) applyHostStyleVariables(ctx.styles.variables);
    if (ctx?.styles?.css?.fonts) applyHostFonts(ctx.styles.css.fonts);
  }

  async handleGetTime() {
    if (!this.app) return;
    try {
      const result = await this.app.callServerTool({
        name: "get-time",
        arguments: {},
      });
      this.serverTime.set(extractText(result));
    } catch {
      this.serverTime.set("[ERROR]");
    }
  }
}

A few things to note:

App class — this is the SDK's main entry point. You create one, wire up callbacks, and call connect(). That's it.
ontoolresult — fires when the host sends a tool result. This is how data flows from the server to your UI.
callServerTool() — lets the UI call tools on the server. The host proxies this through the MCP client.
onhostcontextchanged — the host pushes theme and style updates. The helper functions (applyDocumentTheme, etc.) apply them as CSS variables on document, so your component styles just work.
safeAreaInsets — the host tells you how much padding to leave for its chrome. Use it on your root container.

Step 4: Adding a Second UI

Here's where it gets interesting. Say you want a "Greet" tool with its own UI. Each tool gets its own HTML entry point, its own Angular app, and its own resource registration.

Server: Register Both Tools

// server.ts — inside createServer()

// Tool #1: Get Time
const timeResourceUri = "ui://get-time/mcp-app.html";
registerAppTool(server, "get-time", {
  title: "Get Time",
  description: "Returns the current server time.",
  inputSchema: {},
  _meta: { ui: { resourceUri: timeResourceUri } },
}, async (): Promise<CallToolResult> => {
  return { content: [{ type: "text", text: new Date().toISOString() }] };
});
registerAppResource(server, timeResourceUri, timeResourceUri, {
  mimeType: RESOURCE_MIME_TYPE,
}, async (): Promise<ReadResourceResult> => {
  const html = await fs.readFile(path.join(DIST_DIR, "mcp-app.html"), "utf-8");
  return { contents: [{ uri: timeResourceUri, mimeType: RESOURCE_MIME_TYPE, text: html }] };
});

// Tool #2: Greet
const greetResourceUri = "ui://greet/greeting-app.html";
registerAppTool(server, "greet", {
  title: "Greet",
  description: "Returns a personalised greeting.",
  inputSchema: {
    name: z.string().optional().default("World").describe("Name to greet"),
  },
  _meta: { ui: { resourceUri: greetResourceUri } },
}, async ({ name }: { name?: string }): Promise<CallToolResult> => {
  const greeting = `Hello, ${name || "World"}! Welcome to the MCP Apps SDK.`;
  return { content: [{ type: "text", text: greeting }] };
});
registerAppResource(server, greetResourceUri, greetResourceUri, {
  mimeType: RESOURCE_MIME_TYPE,
}, async (): Promise<ReadResourceResult> => {
  const html = await fs.readFile(path.join(DIST_DIR, "greeting-app.html"), "utf-8");
  return { contents: [{ uri: greetResourceUri, mimeType: RESOURCE_MIME_TYPE, text: html }] };
});

Greeting Component

// src/greeting.component.ts
import { Component, type OnInit, signal } from "@angular/core";
import { FormsModule } from "@angular/forms";
import {
  App,
  applyDocumentTheme,
  applyHostStyleVariables,
  applyHostFonts,
  type McpUiHostContext,
} from "@modelcontextprotocol/ext-apps";
import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js";

@Component({
  selector: "greeting-root",
  imports: [FormsModule],
  template: `
    <main
      [style.padding-top.px]="hostContext()?.safeAreaInsets?.top"
      [style.padding-right.px]="hostContext()?.safeAreaInsets?.right"
      [style.padding-bottom.px]="hostContext()?.safeAreaInsets?.bottom"
      [style.padding-left.px]="hostContext()?.safeAreaInsets?.left"
    >
      <div>
        <label><strong>Your name:</strong></label>
        <input type="text" [(ngModel)]="nameText" placeholder="Enter your name">
        <button (click)="handleGreet()">Get Greeting</button>
      </div>
      @if (greeting()) {
        <div class="greeting-display">{{ greeting() }}</div>
      }
    </main>
  `,
})
export class GreetingComponent implements OnInit {
  private app: App | null = null;
  hostContext = signal<McpUiHostContext | undefined>(undefined);
  greeting = signal("");
  nameText = "";

  async ngOnInit() {
    const instance = new App({ name: "Greeting App", version: "1.0.0" });
    instance.ontoolresult = (result) => {
      this.greeting.set(result.content?.find((c) => c.type === "text")!.text);
    };
    instance.onhostcontextchanged = (params) => {
      const ctx = { ...this.hostContext(), ...params };
      this.hostContext.set(ctx);
      if (ctx.theme) applyDocumentTheme(ctx.theme);
      if (ctx.styles?.variables) applyHostStyleVariables(ctx.styles.variables);
      if (ctx.styles?.css?.fonts) applyHostFonts(ctx.styles.css.fonts);
    };
    await instance.connect();
    this.app = instance;
    const ctx = instance.getHostContext();
    this.hostContext.set(ctx);
    if (ctx?.theme) applyDocumentTheme(ctx.theme);
    if (ctx?.styles?.variables) applyHostStyleVariables(ctx.styles.variables);
    if (ctx?.styles?.css?.fonts) applyHostFonts(ctx.styles.css.fonts);
  }

  async handleGreet() {
    if (!this.app) return;
    try {
      const name = this.nameText.trim() || "World";
      const result = await this.app.callServerTool({ name: "greet", arguments: { name } });
      this.greeting.set(result.content?.find((c) => c.type === "text")!.text);
    } catch {
      this.greeting.set("[ERROR]");
    }
  }
}

Step 5: Sharing Code Between UIs

You probably noticed that both components have identical App setup and theming boilerplate. That's a great candidate for extraction — and since each HTML is a separate Vite entry point, Vite's tree-shaking ensures each bundle only includes what it actually imports.

// src/shared/mcp-app-setup.ts
import {
  App,
  applyDocumentTheme,
  applyHostStyleVariables,
  applyHostFonts,
  type McpUiHostContext,
} from "@modelcontextprotocol/ext-apps";
import type { WritableSignal } from "@angular/core";
import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js";

export function extractText(result: CallToolResult): string {
  return result.content?.find((c) => c.type === "text")!.text;
}

function applyContext(ctx: McpUiHostContext): void {
  if (ctx.theme) applyDocumentTheme(ctx.theme);
  if (ctx.styles?.variables) applyHostStyleVariables(ctx.styles.variables);
  if (ctx.styles?.css?.fonts) applyHostFonts(ctx.styles.css.fonts);
}

export async function createMcpApp(
  name: string,
  hostContext: WritableSignal<McpUiHostContext | undefined>,
  onToolResult?: (result: CallToolResult) => void,
): Promise<App> {
  const app = new App({ name, version: "1.0.0" });
  if (onToolResult) app.ontoolresult = onToolResult;
  app.onhostcontextchanged = (params) => {
    const ctx = { ...hostContext(), ...params } as McpUiHostContext;
    hostContext.set(ctx);
    applyContext(ctx);
  };
  await app.connect();
  const ctx = app.getHostContext();
  hostContext.set(ctx);
  if (ctx) applyContext(ctx);
  return app;
}

Both components import createMcpApp and extractText from the shared module. Since they're in separate Vite builds, tree-shaking still applies — each bundle only pulls in what it calls.

Step 6: The Build

// vite.config.ts
import { defineConfig } from "vite";
import { viteSingleFile } from "vite-plugin-singlefile";

const INPUT = process.env.INPUT;
if (!INPUT) throw new Error("INPUT environment variable is not set");

export default defineConfig({
  plugins: [viteSingleFile()],
  build: {
    rollupOptions: { input: INPUT },
    outDir: "dist",
    emptyOutDir: false, // Key: don't wipe previous builds
  },
});

{
  "scripts": {
    "build": "tsc --noEmit && cross-env INPUT=mcp-app.html vite build && cross-env INPUT=greeting-app.html vite build && tsc -p tsconfig.server.json && bun build server.ts --outdir dist --target node"
  }
}

Each HTML file produces a fully self-contained output (all JS, CSS, and Angular runtime inlined). The two bundles are completely independent.

Theming: Looking Native in Any Host

:root {
  color-scheme: light dark;
  --color-text-primary: light-dark(#1f2937, #f3f4f6);
  --color-background-primary: light-dark(#ffffff, #1a1a1a);
  --color-accent: #2563eb;
  --border-radius-md: 6px;
  --spacing-unit: var(--font-text-md-size);
}

When the host sends style updates via onhostcontextchanged, the helper functions overwrite these variables on the document root. Your Angular component styles reference the variables (var(--color-accent), var(--spacing-md)), so they adapt automatically — no theme prop drilling needed.

Recap

Server: register a tool + resource pair per UI, linked by a resource URI
HTML: one entry point per UI, each bootstrapping its own Angular app
Component: create an App instance, wire up callbacks, call connect()
Shared code: extract common setup into a shared module — Vite tree-shakes per entry point
Build: run Vite once per HTML file into the same dist/ directory
Theming: use host CSS variables with fallbacks, apply updates via onhostcontextchanged

The full source is available in the ext-apps examples.

How I Almost Got Pwned - A Tale of Supply Chain Attacks and GitHub Actions Gone Wrong

Dale Nguyen — Fri, 12 Sep 2025 02:35:15 +0000

Or: "That time someone tried to turn my innocent Node.js repo into a credential-harvesting machine"

So there I was, minding my own business with my trusty old Node.js REST API project, when I noticed something weird in the package-lock.json file from one of a PR from a random contributor - and another contributor actually approved the PR right after that. What started as a routine dependency check turned into a rabbit hole that led me straight into the middle of a supply chain attack campaign that was actively targeting developers like us.

Buckle up, because this is a story about how modern software development can go sideways fast, and why that "helpful" pull request might not be so helpful after all.

What Even Is a Supply Chain Attack?

It’s when hackers sneak bad stuff (malware, credential stealers, you name it) into your dependencies, build scripts, or CI/CD pipelines—any link where code, secrets, and environments touch. Think: “If I can poison upstream, why bother attacking thousands of repos individually?” Welcome to modern risk!

It's insidious because these are the tools we trust implicitly. When lodash releases an update, we don't usually audit every line of code, right? We just npm update and move on with our lives.

The Smoking Gun: The Lockfile Had Been Tampered With

It all started when I was reviewing the package-lock.json from the pull request. I noticed something that made my developer spidey-senses tingle - together with the recent NPM hack news on Sep 2025:

// BEFORE (Normal, secure)
"@types/body-parser": {
  "version": "1.17.0",
  "requires": {
    "@types/connect": "3.4.32",
    "@types/node": "10.12.18"
  }
}

// AFTER (Sus as hell)
"@types/body-parser": {
  "version": "1.17.0",
  "dependencies": {
    "@types/connect": "*",
    "@types/node": "*"
  }
}

Those little asterisks? Those are wildcards that basically tell npm "give me whatever version you feel like." It's like ordering food and telling the waiter "surprise me" – except the surprise might be malware.

This change completely bypasses version pinning, which is one of our main defenses against supply chain attacks. With wildcards, if any of those packages gets compromised later, you'll automatically pull the malicious version on your next install.

Enter the "Helpful" Contributor

Then I found the smoking gun: a pull request from September 5, 2025, submitted by a user called harshitcodez19. The PR looked innocent enough – just adding some CI/CD with GitHub Actions. How thoughtful!

name: Build on PR
# Heello this is a ymk file made up for cICD
on:
  push:
    branches:
      - main # ← Wait, my repo uses 'master'
  pull_request:
    branches:
      - main # ← This is wrong too...

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Use Node.js
        uses: actions/setup-node@v3
        with:
          node-version: '20'

      - name: Install Dependencies
        run: npm install # ← Should be 'npm ci' for security

      - name: Run Build
        run: npm run build

At first glance, this looks like a newbie trying to be helpful. The typos in the comment ("Heello", "ymk", "cICD") make it seem like someone who's just learning. The branch configuration is wrong, so it wouldn't even run.

But here's the thing – this is exactly how the GhostAction campaign operates.

The GhostAction Campaign: When GitHub Actions Turn Evil

The timing of this PR wasn't coincidental. September 5, 2025 was when security researchers first detected the GhostAction campaign – a sophisticated supply chain attack targeting GitHub repositories.

Here's how GhostAction works:

Reconnaissance: Attackers identify repositories with outdated dependencies
Social Engineering: Submit "helpful" PRs adding CI/CD workflows
Intentional Sabotage: Include obvious mistakes to avoid immediate execution
Patience: Wait for maintainers to "fix" the obvious issues
Exploitation: When the workflow runs, it harvests secrets and credentials

The genius is in the plausible deniability. The PR looks like a well-meaning but inexperienced contributor. The "mistakes" make it seem harmless. But once those workflows run with the right permissions, game over.

The Attack Vector Breakdown

Let's dissect what would have happened if I'd merged this PR:

# The branch misconfiguration prevents immediate execution
on:
  push:
    branches:
      - main # My repo uses 'master', so this won't trigger

This gives the attacker time. If I had "fixed" the obvious branch issue and merged it, the workflow would then:

- name: Install Dependencies
  run: npm install # Pulls wildcarded dependencies

With those wildcards in my lockfile, npm install would fetch the latest versions of @types/node and @types/connect. If those packages had been compromised (which is exactly what the broader npm hack was doing), my CI environment would install malware with full access to:

GitHub secrets
AWS credentials
Database connection strings
API keys
Deploy tokens

Basically, everything you need to completely own my infrastructure.

The Broader Context: The Great NPM Hack of 2025

This attack was part of a much larger campaign according to OX Security's research.

The attackers were:

Compromising legitimate package maintainer accounts
Injecting malicious code into trusted packages
Specifically targeting CI/CD environments
Using GitHub Actions to exfiltrate credentials

My old lockfile, with packages from 2018-2019, was the perfect target. Outdated dependencies are like old locks – they work until someone with the right tools shows up.

Red Flags I Should Have Caught Earlier

Looking back, there were several warning signs:

1. The Contributor Profile

harshitcodez19 had minimal contribution history
Random username pattern typical of throwaway accounts
No established relationship with my project

2. The "Mistakes" Were Too Convenient

Wrong branch names that prevent immediate execution
Typos that create plausible deniability
Using npm install instead of the more secure npm ci

3. The Timing

Submitted on September 5, 2025 (exact GhostAction detection date)
My lockfile wildcards appeared around the same timeframe
Coincided with broader npm supply chain compromises

What Could Have Gone Wrong

If this attack had succeeded, here's what the attacker could have done:

# In my compromised CI environment:
echo $AWS_SECRET_ACCESS_KEY  # Exfiltrate cloud credentials
echo $DATABASE_URL          # Steal database access
echo $DEPLOY_TOKEN          # Compromise deployment pipeline

# Then pivot to:
# - Deploy backdoors to production
# - Access customer data
# - Crypto mining on my infrastructure
# - Lateral movement to other systems

The blast radius from a successful CI compromise is enormous because CI environments typically have elevated permissions to deploy, test, and integrate with other services.

Best Practices: How to Not Get Pwned

Here's what I learned and what you should do to protect yourself:

1. Lockfile Hygiene

# Always use npm ci in production/CI
npm ci  # Uses exact lockfile versions

# Never use npm install in CI
npm install  # Can update versions unexpectedly

// Keep your lockfile pinned
"dependencies": {
  "@types/node": "10.12.18",  // ✅ Exact version
  "@types/connect": "*"       // ❌ Wildcard = danger
}

2. CI/CD Security

# Secure GitHub Actions workflow
name: Secure Build
on:
  pull_request:
    branches: [master] # Correct branch names

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4 # Latest version

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'npm' # Cache for performance

      # Use npm ci for reproducible builds
      - name: Install dependencies
        run: npm ci

      # Audit before building
      - name: Security audit
        run: npm audit --audit-level=critical

      - name: Build
        run: npm run build

3. Dependency Management

# Regular maintenance
npm outdated        # Check for updates
npm audit          # Security vulnerabilities
npm audit fix      # Auto-fix where possible

# Keep dependencies current
npm update         # Update within semver ranges

4. PR Review Guidelines

When reviewing PRs that touch CI/CD or dependencies:

Who is the contributor? Do they have a history with your project?
Why are they making this change? Unsolicited CI/CD PRs are suspicious
What permissions would this grant? Review secrets and environment access
Are there obvious "mistakes"? Sometimes bugs are features for attackers

5. Repository Protection

# .github/dependabot.yml
version: 2
updates:
  - package-ecosystem: 'npm'
    directory: '/'
    schedule:
      interval: 'weekly'
    reviewers:
      - 'your-username'

Enable branch protection rules:

Require PR reviews for CI/CD changes
Require status checks to pass
Restrict who can modify workflows

The Human Element

The scariest part of supply chain attacks isn't the technical sophistication – it's how they exploit our human nature. We want to be helpful to contributors. We want to trust the tools we use daily. We want to merge that PR that "fixes" an obvious mistake.

But in the age of automated attacks and compromised packages, a little paranoia goes a long way. That friendly contributor might be a bot. That helpful PR might be reconnaissance. That simple typo fix might be setting up a backdoor.

Lessons Learned

Trust but verify: Even helpful PRs need scrutiny
Keep dependencies updated: Old packages are attractive targets
Use lockfiles properly: Pin versions and use npm ci
Secure your CI/CD: It's the crown jewel attackers want
Stay informed: Follow security researchers and vulnerability databases

The Silver Lining

While getting targeted by a supply chain attack was unsettling, it was also educational. It reminded me that security isn't just about writing secure code – it's about securing the entire development pipeline.

The npm ecosystem is incredibly powerful, but that power comes with responsibility. Every npm install is a vote of trust in hundreds of package maintainers. Every GitHub Action workflow is a potential attack vector.

But don't let this scare you away from open source. The community is what makes JavaScript development amazing. Just be smart about it. Audit your dependencies. Review your workflows. Trust but verify.

And maybe, just maybe, be a little suspicious when harshitcodez19 offers to help with your CI/CD pipeline.

Stay safe out there, fellow developers. The supply chain attackers are getting creative, but so are we.

References

Mastering Email Rate Limits — A Deep Dive into Resend API and Cloud Run Debugging

Dale Nguyen — Sun, 07 Sep 2025 14:11:09 +0000

How we solved persistent rate limiting issues and implemented robust batch email functionality for our AI-powered learning platform

The Challenge: When Emails Start Failing

Picture this: You've built a beautiful lesson scheduling system that sends personalized daily lessons to your users. Everything works perfectly in development, but in production, you start seeing mysterious email failures:

This was exactly the situation we faced with DailyMastery, our AI-powered learning platform. Despite having a solid architecture built with Nx monorepo, Fastify microservices, and deployed on Google Cloud Run, our email delivery system was hitting Resend's rate limits consistently.

Understanding the Problem

The Initial Architecture

Our system had a straightforward approach:

Lesson scheduler triggered by Cloud Scheduler (3x daily)
Individual API calls to Resend for each lesson email
No rate limiting protection
Basic error handling

// The problematic approach
for (const lesson of lessons) {
  const emailResult = await this.emailService.sendEmail({
    to: user.email,
    subject: lesson.title,
    html: lessonContent,
  })
  // Rate limits hit here when processing multiple users rapidly
}

The Root Cause

Resend enforces a 2 requests per second rate limit across all endpoints. When our scheduler processed multiple users with multiple lessons each, we quickly exceeded this limit, causing cascading failures.

The Investigation: Debugging Cloud Run Like a Pro

Step 1: Enhanced Logging Strategy

The first step was implementing comprehensive logging to understand exactly what was happening:

async sendEmail(options: EmailOptions): Promise<{ success: boolean; error?: string; messageId?: string }> {
  try {
    console.log('Attempting to send email via Resend:', {
      to: options.to,
      subject: options.subject,
      htmlLength: options.html?.length || 0
    });

    const result = await this.resend.emails.send(emailData);
    console.log('Resend API response:', result);

    // Critical: Check if Resend returned an error (they don't throw exceptions!)
    if (result.error) {
      console.error('Resend API returned error:', result.error);
      return {
        success: false,
        error: result.error.message || JSON.stringify(result.error),
      };
    }

    return {
      success: true,
      messageId: result.data?.id
    };
  } catch (error) {
    console.error('Failed to send email via Resend:', error);
    return {
      success: false,
      error: error instanceof Error ? error.message : 'Unknown error',
    };
  }
}

Step 2: Cloud Run Log Analysis Techniques

You can view logs in the Google Cloud console, but if you like the terminal approach, then here are the essential Cloud Run debugging commands we used:

# Real-time log monitoring during issues
gcloud logging read "resource.type=cloud_run_revision AND resource.labels.service_name=lesson-scheduler" \
  --limit=50 --format="value(timestamp,textPayload)" | head -20

# Filter for specific errors
gcloud logging read "resource.type=cloud_run_revision AND resource.labels.service_name=lesson-scheduler" \
  --limit=100 | grep -E "(rate_limit|429|Failed)"

# Check logs from specific time range
gcloud logging read "resource.type=cloud_run_revision AND resource.labels.service_name=lesson-scheduler AND timestamp>=\"2025-09-03T16:00:00Z\"" \
  --limit=50

The Solution: Multi-Layer Rate Limiting Strategy

Layer 1: Proper Error Detection

The first critical insight: Resend doesn't throw exceptions for rate limits. They return error objects:

// Before: Missing rate limit detection
const result = await this.resend.emails.send(emailData)
return { success: true, messageId: result.data?.id } // Wrong!

// After: Comprehensive error checking
const result = await this.resend.emails.send(emailData)

if (result.error) {
  console.error('Resend API returned error:', result.error)
  return {
    success: false,
    error: result.error.message || JSON.stringify(result.error),
  }
}

if (!result.data) {
  return {
    success: false,
    error: 'No data returned from Resend API',
  }
}

return {
  success: true,
  messageId: result.data.id,
}

Layer 2: Intelligent Batch Email Implementation with Auto-Chunking

Resend offers a batch API that can send up to 100 emails in a single request. Here's our implementation with smart fallback and automatic chunking for larger batches:

async sendBatchLessonEmails(
  emails: BatchEmailOptions[]
): Promise<{ success: boolean; error?: string; messageIds?: string[]; sentCount?: number; failedCount?: number }> {
  try {
    if (emails.length === 0) {
      return { success: true, messageIds: [], sentCount: 0, failedCount: 0 };
    }

    console.log(`Sending batch of ${emails.length} lesson emails`);

    // Automatic chunking: Split into batches of 100 (Resend limit)
    const batchSize = 100;
    const batches: BatchEmailOptions[][] = [];
    for (let i = 0; i < emails.length; i += batchSize) {
      batches.push(emails.slice(i, i + batchSize));
    }

    let totalSent = 0;
    let totalFailed = 0;
    const allMessageIds: string[] = [];
    const errors: string[] = [];

    // Process each chunk sequentially with rate limiting
    for (let i = 0; i < batches.length; i++) {
      const batch = batches[i];
      console.log(`Sending batch ${i + 1}/${batches.length} with ${batch.length} emails`);

      const result = await this.emailService.sendBatchEmails(batch);

      if (result.success) {
        totalSent += batch.length;
        if (result.messageIds) {
          allMessageIds.push(...result.messageIds);
        }
        console.log(`✅ Batch ${i + 1} sent successfully (${batch.length} emails)`);
      } else {
        totalFailed += batch.length;
        errors.push(`Batch ${i + 1} failed: ${result.error || 'Unknown error'}`);
        console.error(`❌ Batch ${i + 1} failed: ${result.error}`);
      }

      // Add delay between batches to avoid rate limiting
      if (i < batches.length - 1) {
        console.log('⏳ Waiting 1 second between batches to avoid rate limiting...');
        await new Promise(resolve => setTimeout(resolve, 1000));
      }
    }

    const overallSuccess = totalFailed === 0;

    return {
      success: overallSuccess,
      messageIds: allMessageIds,
      sentCount: totalSent,
      failedCount: totalFailed,
      error: errors.length > 0 ? errors.join('; ') : undefined,
    };
  } catch (error) {
    console.error('Error sending batch lesson emails:', error);
    return {
      success: false,
      error: error instanceof Error ? error.message : 'Unknown error',
      sentCount: 0,
      failedCount: emails.length,
    };
  }
}

Layer 3: Architectural Refactoring

We completely restructured our email sending flow:

// Old approach: Send emails immediately during processing
for (const user of users) {
  for (const lesson of lessons) {
    await sendEmail(user, lesson) // Rate limit hit here
  }
}

// New approach: Prepare first, then batch send
const allPreparedEmails: PreparedEmail[] = []

// Phase 1: Prepare all emails
for (const user of users) {
  for (const lesson of lessons) {
    const preparedEmail = await this.prepareLessonEmail(user, lesson)
    if (preparedEmail) {
      allPreparedEmails.push({ email: preparedEmail, user, lesson })
    }
  }
}

// Phase 2: Batch send with intelligent chunking and accurate tracking
if (allPreparedEmails.length > 0) {
  console.log(`🚀 Sending ${allPreparedEmails.length} emails in optimized batches`)

  const emailsToSend = allPreparedEmails.map((pe) => pe.email)

  // The EmailCoordinator handles chunking internally for 100+ email limits
  const batchResult = await this.emailCoordinator.sendBatchLessonEmails(emailsToSend)

  if (batchResult.success) {
    // Only mark lessons as sent based on actual successful send count
    const successfulEmails = allPreparedEmails.slice(0, batchResult.sentCount)
    await this.markLessonsAsSent(successfulEmails)
  }
}

Layer 4: Smart Retry Logic

For critical emails like admin reports, we implemented retry logic:

async sendSummaryReport(result: SchedulerResult): Promise<void> {
  // Add delay to avoid rate limiting after lesson emails
  console.log('⏳ Waiting 3 seconds to avoid rate limiting...');
  await new Promise(resolve => setTimeout(resolve, 3000));

  const emailResult = await this.emailService.sendEmail({
    to: this.reportingEmail,
    subject: `📊 Lesson Scheduler Report - ${result.timeSlot}`,
    html: htmlContent,
  });

  if (!emailResult.success) {
    // Retry logic for rate limits
    if (emailResult.error?.includes('rate_limit_exceeded') ||
        emailResult.error?.includes('Too many requests')) {
      console.log('⏳ Rate limited - waiting 10 seconds and retrying...');
      await new Promise(resolve => setTimeout(resolve, 10000));

      const retryResult = await this.emailService.sendEmail({
        to: this.reportingEmail,
        subject: `📊 Lesson Scheduler Report - ${result.timeSlot} (Retry)`,
        html: htmlContent,
      });

      if (retryResult.success) {
        console.log('✅ Summary report sent successfully on retry');
      }
    }
  }
}

Key Debugging Techniques for Cloud Run

1. Structured Logging

Use consistent emoji prefixes and structured data:

// Good logging practices
console.log('🚀 BATCH EMAIL MODE: Sending emails', { count: emails.length })
console.log('✅ Email sent successfully', { messageId, recipient })
console.log('❌ Email failed', { error: error.message, recipient })
console.log('⏳ Rate limiting delay', { delayMs: 600 })

2. Revision Tracking

Always verify your code is actually deployed:

# Check current revision
gcloud run services describe lesson-scheduler \
  --region=us-central1 \
  --format="value(status.latestReadyRevisionName)"

# List recent revisions with images
gcloud run revisions list --service=lesson-scheduler \
  --format="table(metadata.name,status.conditions[0].status,spec.containers[0].image)"

3. Real-time Monitoring

Set up log streaming during debugging:

# Stream logs in real-time
gcloud beta logging tail "resource.type=cloud_run_revision AND resource.labels.service_name=lesson-scheduler"

# Filter for errors only
gcloud beta logging tail "resource.type=cloud_run_revision AND resource.labels.service_name=lesson-scheduler" \
  --filter="severity>=ERROR"

Results and Performance Impact

Before Optimization

❌ Cascading failures due to rate limits
❌ Poor user experience with missed lessons
❌ Manual intervention required daily

After Optimization

✅ 0% email failure rate
✅ Automatic handling of up to 100 emails per batch
✅ Zero manual intervention required

Performance Metrics

Final Test Results:
- totalUsers: 1
- emailsSent: 3
- emailsFailed: 0
- errorCount: 0
- processingTime: 7.048s
- batchEmailsUsed: true

Best Practices Learned

1. Email Service Design Patterns

interface EmailService {
  // Always return structured results
  sendEmail(options: EmailOptions): Promise<{
    success: boolean
    error?: string
    messageId?: string
  }>

  // Batch operations with fallback
  sendBatchEmails(emails: BatchEmailOptions[]): Promise<{
    success: boolean
    error?: string
    messageIds?: string[]
    sentCount?: number
    failedCount?: number
  }>
}

2. Rate Limiting Strategies

Batch First: Use batch APIs when available
Automatic Chunking: Split large batches into 100-email chunks automatically
Intelligent Delays: 600ms between individual requests (< 2 req/sec) and 1s between batch chunks
Accurate Tracking: Only mark operations as successful based on actual send counts
Exponential Backoff: Longer delays for retries
Circuit Breaker: Fail fast on repeated rate limits

Conclusion

Building a robust email delivery system requires understanding both your email provider's limitations and your cloud platform's deployment mechanics. Our journey from 30% failure rates to 0% taught us that:

Rate limiting is real - Plan for it from day one
Batch APIs are game-changers - Use them when available
Docker caching can bite you - Structure your builds carefully
Comprehensive logging saves time - Invest in good observability
Fallback strategies are essential - Always have a Plan B

The combination of Resend's batch API, intelligent fallback logic, proper rate limiting, and robust Cloud Run debugging techniques transformed our email delivery from a daily headache into a reliable, scalable system.

Remember: In production systems, it's not just about making it work—it's about making it work reliably, even when things go wrong.

This blog post is based on our real-world experience building DailyMastery, an AI-powered learning platform. The techniques described here are battle-tested in production and have been processing thousands of lesson emails daily without issues.

SupaWP Storage Filter Hooks - Seamless Supabase Storage Integration for WordPress

Dale Nguyen — Sat, 06 Sep 2025 04:05:16 +0000

Building modern WordPress applications often requires robust file storage solutions that scale beyond traditional media library limitations. Today, we're excited to introduce SupaWP Storage Filter Hooks – a powerful new feature that brings seamless Supabase Storage integration directly to your WordPress plugins and themes.

What Are SupaWP Storage Filter Hooks?

SupaWP Storage Filter Hooks are a set of WordPress filter hooks that provide a standardized, developer-friendly way to integrate Supabase Storage into any WordPress application. Instead of writing custom storage code for each project, you can now leverage these hooks to upload, delete, and manage files in Supabase Storage with just a few lines of code.

Prerequisites

Before diving into the implementation, ensure you have:

WordPress site with SupaWP plugin v1.3.4 or higher installed and configured
Supabase project with Storage enabled
Basic knowledge of WordPress filters and PHP
Supabase Storage bucket configured

The Three Essential Hooks

1. `supawp_upload_image_to_supabase`

Upload images directly to Supabase Storage with automatic validation and security:

// Upload a user profile image
$image_url = apply_filters('supawp_upload_image_to_supabase', $file, $fileName, 'user-images');

if (!empty($image_url)) {
    // Success! Save the URL to your database
    update_user_meta($user_id, 'profile_image_url', $image_url);
    return array('success' => true, 'url' => $image_url);
}

2. `supawp_delete_image_from_supabase`

Remove files from Supabase Storage with proper cleanup:

// Delete a user's profile image
$success = apply_filters('supawp_delete_image_from_supabase', $image_url, 'user-images');

if ($success) {
    // File deleted successfully
    delete_user_meta($user_id, 'profile_image_url');
}

3. `supawp_get_storage_config`

Access Supabase Storage configuration and verify setup:

// Check if storage is properly configured
$config = apply_filters('supawp_get_storage_config');

if (!empty($config)) {
    echo "Storage URL: " . $config['url'];
    echo "Authentication: Configured ✓";
}

Simple File Upload Implementation

Here's a basic implementation using the SupaWP Storage Filter Hooks:

<?php
/**
 * Simple File Upload with SupaWP Storage
 */
class Simple_SupaWP_Upload {

    public static function init() {
        add_shortcode('simple_file_upload', array('Simple_SupaWP_Upload', 'upload_shortcode'));
        add_action('wp_ajax_upload_to_supabase', array('Simple_SupaWP_Upload', 'handle_upload'));
    }

    public static function upload_shortcode() {
        $current_user = wp_get_current_user();
        if (!$current_user->ID) {
            return '<p>Please log in to upload files.</p>';
        }

        ob_start();
        ?>
        <form id="upload-form" enctype="multipart/form-data">
            <input type="file" name="user_file" accept=".jpg,.jpeg,.png,.webp" required>
            <button type="submit">Upload File</button>
        </form>

        <div id="upload-result"></div>

        <script>
            document.getElementById('upload-form').addEventListener('submit', function(e) {
                e.preventDefault();

                const formData = new FormData(this);
                formData.append('action', 'upload_to_supabase');
                formData.append('nonce', '<?php echo wp_create_nonce('upload_nonce'); ?>');

                fetch('<?php echo admin_url('admin-ajax.php'); ?>', {
                    method: 'POST',
                    body: formData
                })
                .then(response => response.json())
                .then(data => {
                    document.getElementById('upload-result').innerHTML =
                        data.success ? 'Upload successful!' : 'Upload failed: ' + data.data;
                });
            });
        </script>
        <?php
        return ob_get_clean();
    }

    public static function handle_upload() {
        check_ajax_referer('upload_nonce', 'nonce');

        if (!isset($_FILES['user_file'])) {
            wp_send_json_error('No file provided');
        }

        $file = $_FILES['user_file'];
        $user_id = get_current_user_id();

        // Generate file path
        $extension = pathinfo($file['name'], PATHINFO_EXTENSION);
        $fileName = "users/{$user_id}/" . time() . ".{$extension}";

        // Upload using SupaWP hook
        $url = apply_filters('supawp_upload_image_to_supabase', $file, $fileName, 'user-content');

        if ($url) {
            wp_send_json_success(array('url' => $url));
        } else {
            wp_send_json_error('Upload failed');
        }
    }
}

add_action('supawp_init', array('Simple_SupaWP_Upload', 'init'));

Advanced Implementation Examples

E-commerce Product Gallery

function upload_product_images($product_id, $files) {
    $uploaded_urls = array();

    foreach ($files as $file) {
        $fileName = "products/{$product_id}/" . time() . ".jpg";
        $url = apply_filters('supawp_upload_image_to_supabase', $file, $fileName, 'products');

        if ($url) {
            $uploaded_urls[] = $url;
        }
    }

    update_post_meta($product_id, '_gallery_urls', $uploaded_urls);
    return $uploaded_urls;
}

User Document Management

function upload_user_document($user_id, $file) {
    if (!current_user_can('upload_files')) {
        return false;
    }

    $fileName = "documents/{$user_id}/" . time() . ".pdf";
    $url = apply_filters('supawp_upload_image_to_supabase', $file, $fileName, 'documents');

    if ($url) {
        update_user_meta($user_id, 'document_url', $url);
        return $url;
    }

    return false;
}

Integration with Popular Plugins

Contact Form 7 Integration

function handle_contact_form_upload($contact_form) {
    $submission = WPCF7_Submission::get_instance();
    $files = $submission->uploaded_files();

    if (isset($files['resume'])) {
        $fileName = "resumes/" . time() . "_resume.pdf";
        $url = apply_filters('supawp_upload_image_to_supabase', $files['resume'], $fileName, 'resumes');

        if ($url) {
            update_option('latest_resume', $url);
        }
    }
}
add_action('wpcf7_mail_sent', 'handle_contact_form_upload');

WooCommerce Integration

function sync_product_to_supabase($product_id) {
    $product = wc_get_product($product_id);
    $image_id = $product->get_image_id();

    if ($image_id) {
        $image_path = get_attached_file($image_id);
        $file = array(
            'tmp_name' => $image_path,
            'name' => basename($image_path),
            'size' => filesize($image_path)
        );

        $fileName = "products/{$product_id}.jpg";
        $url = apply_filters('supawp_upload_image_to_supabase', $file, $fileName, 'products');

        if ($url) {
            update_post_meta($product_id, '_supabase_image', $url);
        }
    }
}
add_action('woocommerce_process_product_meta', 'sync_product_to_supabase');

Security Best Practices

Row Level Security (RLS) Policies

Set up proper RLS policies in your Supabase dashboard:

-- Users can only upload to their own folders
CREATE POLICY "Users upload own files" ON storage.objects
FOR INSERT WITH CHECK (
    bucket_id = 'user-content' AND
    (storage.foldername(name))[1] = auth.uid()::text
);

-- Users can only view their own files
CREATE POLICY "Users view own files" ON storage.objects
FOR SELECT USING (
    bucket_id = 'user-content' AND
    (storage.foldername(name))[1] = auth.uid()::text
);

-- Users can only delete their own files
CREATE POLICY "Users delete own files" ON storage.objects
FOR DELETE USING (
    bucket_id = 'user-content' AND
    (storage.foldername(name))[1] = auth.uid()::text
);

Simple File Validation

function validate_file($file) {
    // Check file size (5MB limit)
    if ($file['size'] > 5242880) {
        return false;
    }

    // Check file type
    $allowed_types = array('jpg', 'png', 'pdf');
    $extension = pathinfo($file['name'], PATHINFO_EXTENSION);

    return in_array($extension, $allowed_types);
}

Performance Optimization

Batch Upload

function batch_upload($files, $user_id) {
    $results = array();

    foreach ($files as $file) {
        $fileName = "users/{$user_id}/" . time() . ".jpg";
        $url = apply_filters('supawp_upload_image_to_supabase', $file, $fileName, 'user-content');

        $results[] = array(
            'name' => $file['name'],
            'url' => $url,
            'success' => !empty($url)
        );
    }

    return $results;
}

Using Your File Upload System

Once your code is in place:

Add the shortcode to any page or post: [simple_file_upload]
Ensure users are logged in for security
Configure your Supabase Storage with appropriate buckets

Example usage:

[simple_file_upload]

Common Supabase Storage Query Filters

When working with uploaded files, you can query them using various filters:

// Get user's files from database
$user_files = apply_filters('supawp_get_data_from_supabase', 'files', array(
    'user_id' => 'eq.' . $user_id,
    'order' => 'created_at.desc'
));

// Filter by file size
$large_files = apply_filters('supawp_get_data_from_supabase', 'files', array(
    'file_size' => 'gt.1000000'
));

Troubleshooting Common Issues

Troubleshooting

// Check if storage is configured
$config = apply_filters('supawp_get_storage_config');
if (empty($config)) {
    echo "Storage not configured";
}

Common Issues

Storage not configured - Check SupaWP settings
Upload fails - Verify file size and type limits
Permission denied - Check Supabase RLS policies
Files not showing - Ensure bucket is public

Conclusion

SupaWP Storage Filter Hooks revolutionize file management in WordPress by providing seamless integration with Supabase's powerful storage infrastructure. With enterprise-grade security, global CDN distribution, and a developer-friendly API, you can build sophisticated file management systems with minimal code.

Key benefits of this integration:

Zero Configuration Complexity - SupaWP handles authentication and API communication
Enterprise Security - Automatic RLS integration and secure file handling
Global Performance - Leverage Supabase's worldwide CDN network
WordPress Native - Uses familiar WordPress filter patterns
Scalable Architecture - No server storage limitations

Whether you're building a simple profile system, complex document management, or e-commerce product galleries, SupaWP Storage Filter Hooks provide the foundation for modern, scalable WordPress applications.

Resources

Ready to transform your WordPress file management? Download SupaWP v1.3.4+ and start building with Supabase Storage today!

Learn with Daily Mastery - From AI Generation to Email Delivery

Dale Nguyen — Thu, 04 Sep 2025 04:00:42 +0000

One of the biggest challenges in online education isn't creating content—it's delivering the right content to the right person at the right time. When building DailyMastery, we needed to solve a complex scheduling problem: how do you deliver personalized, AI-generated lessons to users across different time zones, preferences, and learning schedules?

Our solution is a high-performance lesson scheduling system that processes thousands of users daily, generates personalized content on-the-fly, and delivers beautiful email lessons at precisely the right moment. Here's how we built it.

The Challenge: Personalization at Scale

Traditional learning platforms send the same content to everyone. But true personalization requires:

Individual content generation: Each lesson tailored to specific goals and progress
Time-based delivery: Respecting user preferences for morning, afternoon, or evening learning
Scalable processing: Handling growing user bases without performance degradation
Reliability: Ensuring lessons are delivered consistently, even when individual components fail

Architecture Overview: From User Preferences to Inbox

Our lesson scheduling system consists of several coordinated services:

1. User Selection Engine

The system starts by identifying which users should receive lessons for each time slot:

Selection Criteria:

Users must have preferences.studyTime matching the time slot ('morning', 'afternoon', 'evening')
Users must have preferences.notifications.dailyReminders enabled
Users must have active study plans with lessons scheduled for today

Time Slots:

06:00 UTC (Morning): Targets users who prefer early learning
12:00 UTC (Afternoon): Catches lunch-break learners
18:00 UTC (Evening): Reaches after-work studiers

2. AI Content Generation Pipeline

Once we identify users, each lesson goes through our AI enhancement process:

Process Flow:

Lesson Retrieval: Get scheduled lesson from database with original template content
AI Enhancement: Use Google Cloud Vertex AI with Gemini to expand and personalize the content
Quality Validation: Ensure AI-generated content meets quality standards
Fallback Strategy: Use original template if AI generation fails

Content Personalization:
The AI considers user context including:

Learning objectives and goals
Current progress and difficulty level
Preferred learning style and time commitment
Previous lesson feedback and engagement

3. Batch Processing for Scale

To handle thousands of users efficiently, we use sophisticated batch processing:

Concurrency Control:

const pLimit = (await import('p-limit')).default
const limit = pLimit(10) // Process up to 10 users concurrently

const promises = userGroups.map((userGroup) => limit(() => this.processUserGroup(userGroup)))

await Promise.allSettled(promises)

Error Resilience:
Individual user failures don't stop the entire batch. Each user's processing is isolated, logged, and reported separately.

The Lesson Processor: Heart of the System

Our LessonProcessorService handles the complex task of managing lesson content:

Active Plan Discovery

The system performs comprehensive scans to find all active study plans:

async getActivePlans(): Promise<UserPlanGroup[]> {
  // Scan all users with active plans
  // Find today's scheduled lessons
  // Group by user for efficient processing
}

AI Content Generation

Each lesson is enhanced with AI-generated content:

Quality Metrics:

Content length and depth analysis
Learning objective alignment
Engagement potential scoring
Readability assessment

Performance Tracking:

AI generation time per lesson
Success/failure rates
Content quality improvement over time
User engagement correlation

Database Integration

Seamless integration with Firestore for lesson management:

Atomic updates for lesson content
Timestamp tracking for delivery status
Progress tracking for user analytics
Batch operations for efficiency

Email Delivery: The Final Mile

Our EmailCoordinatorService handles the critical task of email delivery:

Personalized Templates

Each email is personalized based on:

Time-based greetings: 🌅 "Good morning" vs ☀️ "Good afternoon" vs 🌙 "Good evening"
Study plan context: Extracted plan names and goals
Progress indicators: Current lesson number and completion status
Engagement elements: Interactive exercises and progress tracking

Responsive Design

Our TemplateEngineService creates mobile-friendly emails with:

Maximum width of 600px for optimal display
Modern gradient designs and professional styling with CSS animations
Clear call-to-action buttons for lesson engagement
Progress visualization and success metrics
Time-based personalized greetings and content adaptation
Professional email templates with comprehensive fallback support

Delivery Reliability

Email delivery includes comprehensive error handling:

Detailed error logging for failed deliveries
Retry mechanisms for transient failures
Admin alerting for critical delivery issues
Success rate monitoring and reporting
Batch email API with intelligent fallback to individual sends
Rate limiting protection (2 requests per second compliance)

Real-Time Processing Flow

Here's what happens when our scheduler processes the morning time slot:

1. Trigger Processing (06:00 UTC)

POST /schedule/06:00

2. User Discovery

Query database for morning-preference users
Filter for active daily reminders
Identify today's scheduled lessons

3. Batch Processing

Group users for efficient processing
Apply concurrency limits (10 concurrent users)
Process each user's lessons independently

4. Content Generation

For each user:

Retrieve scheduled lessons from database
Generate AI-enhanced content
Update lesson records with new content
Mark lessons as processed

5. Email Delivery

Render personalized HTML templates
Send via Resend email service
Track delivery status and metrics
Update lesson records with sent timestamps

6. Reporting and Monitoring

Generate processing summary
Send admin reports via email
Log performance metrics
Alert on critical errors

Performance Metrics and Monitoring

Our system tracks comprehensive metrics:

Processing Performance

Total processing time per time slot
Average time per user
Concurrency efficiency metrics
Database operation latency

Content Quality

AI generation success rates (target: >95%)
Content length and complexity metrics
User engagement correlation with AI content
Fallback usage rates

Email Delivery

Email send success rates (target: >99%)
Template rendering performance
User engagement rates (opens, clicks, completions)
Bounce and complaint rates

Future Enhancements

We're continuously improving the scheduling system:

Advanced Personalization

Learning pattern analysis: Adapt timing based on user engagement patterns
Content difficulty adjustment: Dynamic complexity scaling based on progress
Multi-modal delivery: Support for SMS, push notifications, and in-app delivery

Performance Optimization

Predictive scaling: Auto-scaling based on user growth patterns
Content pre-generation: Cache frequently used AI-generated content
Global distribution: Multi-region deployment for reduced latency

Analytics and Insights

Learning effectiveness metrics: Correlation between delivery timing and retention
Content performance analysis: A/B testing for AI-generated vs template content
User journey optimization: Personalized scheduling based on individual success patterns

Lessons Learned

Building a personalized lesson scheduling system taught us:

Technical Insights

Batch processing with concurrency limits provides the best balance of speed and reliability
Comprehensive error handling at every level is essential for user trust
AI content generation requires robust fallback strategies for reliability
Email delivery is more complex than it appears - template rendering, personalization, and deliverability all matter

Product Insights

Time-based personalization significantly improves engagement compared to generic scheduling
AI-enhanced content shows measurably higher completion rates than template-based lessons
Processing transparency builds user confidence - users appreciate knowing when their lessons are being prepared
Reliable delivery is table stakes - users expect lessons to arrive consistently

Getting Started

If you're building your own personalized delivery system, consider:

Start with reliable basics: Get consistent delivery working before adding AI enhancement
Design for failure: Assume every external service will fail and plan accordingly
Monitor everything: Comprehensive logging and metrics are essential for debugging and optimization
Test with real load: Batch processing behaves differently at scale

Our lesson scheduling system demonstrates that personalized, AI-powered education delivery is not only possible but can be built reliably and efficiently with the right architecture and attention to detail.

Fixing Next.js Authentication Redirects - Preserving Deep Links After Login

Dale Nguyen — Fri, 29 Aug 2025 14:34:06 +0000

The Problem

In our learning platform DailyMastery, we send personalized lesson emails to users with direct links to specific lessons, like:

https://dailymastery.io/dashboard/lessons/sample-lesson-detail

However, we discovered a frustrating user experience issue: when users clicked these lesson links from their emails, they would be redirected to login (which is correct for unauthenticated users), but after successful authentication, instead of landing on the specific lesson page, they would end up on the generic dashboard.

This broke the seamless experience we wanted to provide - users had to manually navigate to find their intended lesson after logging in.

Understanding the Authentication Flow

Let's break down what was happening:

The Original (Broken) Flow:

User clicks lesson link: https://dailymastery.io/dashboard/lessons/sample-lesson-detail
Middleware intercepts: Detects no authentication token
Redirect to login: https://dailymastery.io/login (❌ Original URL lost!)
User authenticates: Successfully logs in with Google
Post-login redirect: Goes to default /dashboard (❌ Not the intended lesson)

The Root Cause

Our Next.js middleware was correctly protecting routes but wasn't preserving the original destination URL when redirecting unauthenticated users to the login page.

Here's the problematic middleware code:

// ❌ BEFORE: Lost the original URL
export function middleware(request: NextRequest) {
  if (request.nextUrl.pathname.startsWith('/dashboard')) {
    const token = request.cookies.get('firebase-token')?.value

    if (!token) {
      // This loses the original URL!
      return NextResponse.redirect(new URL('/login', request.url))
    }
  }

  return NextResponse.next()
}

The Solution: Preserving Deep Links

The fix required two components working together:

1. Enhanced Middleware (Capturing the Original URL)

We modified the middleware to capture the full original URL and pass it as a query parameter:

// ✅ AFTER: Preserves the original URL
export function middleware(request: NextRequest) {
  if (request.nextUrl.pathname.startsWith('/dashboard')) {
    const cookieToken = request.cookies.get('firebase-token')?.value
    const headerToken = request.headers.get('authorization')?.replace('Bearer ', '')
    const token = cookieToken || headerToken

    if (!token) {
      // 🎯 Key fix: Preserve original URL with query params
      const loginUrl = new URL('/login', request.url)
      loginUrl.searchParams.set('redirect', request.nextUrl.pathname + request.nextUrl.search)
      return NextResponse.redirect(loginUrl)
    }
  }

  return NextResponse.next()
}

Key improvements:

request.nextUrl.pathname captures the path (/dashboard/lessons/sample-lesson-detail)
request.nextUrl.search captures any query parameters
Combined as redirect parameter in the login URL

2. Smart Login Page (Reading and Using the Redirect)

Our login page was already set up to handle redirects, but let's look at the key parts:

// login/page.tsx
function LoginForm() {
  const router = useRouter()
  const searchParams = useSearchParams()

  useEffect(() => {
    if (!loading && user) {
      // 🎯 Check for redirect parameter first, fallback to dashboard
      const redirectUrl = searchParams.get('redirect')
      router.push(redirectUrl || '/dashboard')
    }
  }, [user, loading, router, searchParams])

  const signInWithGoogle = async () => {
    try {
      const result = await signInWithPopup(auth, provider)
      const idToken = await result.user.getIdToken()

      // Store auth token
      document.cookie = `firebase-token=${idToken}; path=/; max-age=86400; secure; samesite=strict`

      // 🎯 Redirect to original destination after login
      const redirectUrl = searchParams.get('redirect')
      router.push(redirectUrl || '/dashboard')
    } catch (error) {
      setError(error.message)
    }
  }
}

The Fixed Flow

Now the authentication flow works perfectly:

The New (Working) Flow:

User clicks lesson link: https://dailymastery.io/dashboard/lessons/sample-lesson-detail
Middleware intercepts: Detects no authentication token
Smart redirect: https://dailymastery.io/login?redirect=/dashboard/lessons/sample-lesson-detail (✅ URL preserved!)
User authenticates: Successfully logs in with Google
Post-login redirect: Goes to the original lesson URL (✅ Perfect user experience!)

Testing the Fix

To test this, you can:

Create a protected route: Any URL under /dashboard/*
Visit while logged out: The middleware will redirect you
Check the URL: Should be /login?redirect=/dashboard/your-original-path
Complete authentication: Should redirect back to your original destination

Key Takeaways

1. Middleware Should Preserve Context

When redirecting users for authentication, always preserve where they were trying to go:

// Bad: Loses context
return NextResponse.redirect(new URL('/login', request.url))

// Good: Preserves user intent
const loginUrl = new URL('/login', request.url)
loginUrl.searchParams.set('redirect', request.nextUrl.pathname + request.nextUrl.search)
return NextResponse.redirect(loginUrl)

2. Login Pages Should Check for Redirects

Your authentication success handler should always check for intended destinations:

// Bad: Always goes to same place
router.push('/dashboard')

// Good: Respects user's original intent
const redirectUrl = searchParams.get('redirect')
router.push(redirectUrl || '/dashboard')

3. Handle Edge Cases

Consider various scenarios:

Query parameters in original URLs
Relative vs absolute URLs
Security validation of redirect URLs (prevent open redirects)
Fallback behaviors when redirects fail

Security Considerations

When implementing redirect preservation, be mindful of open redirect vulnerabilities. In our case, we're safe because:

We only redirect within our own domain
The middleware controls what URLs get set as redirects
We validate that redirects start with /dashboard (our protected routes)

For additional security, you could add validation:

const validateRedirectUrl = (url: string): boolean => {
  // Only allow internal redirects to specific paths
  return url.startsWith('/dashboard') || url.startsWith('/profile')
}

// In login handler:
const redirectUrl = searchParams.get('redirect')
const safeRedirectUrl = redirectUrl && validateRedirectUrl(redirectUrl) ? redirectUrl : '/dashboard'
router.push(safeRedirectUrl)

Conclusion

This seemingly small fix dramatically improved our user experience. Users clicking lesson links in emails now seamlessly land on their intended lessons after authentication, rather than getting lost on a generic dashboard.

The solution demonstrates how proper state preservation in authentication flows is crucial for maintaining user intent and creating smooth, professional web applications.

Technologies used: Next.js 15, TypeScript, Firebase Auth, Next.js Middleware

Building a Next.js Landing Page with Google Sheets Integration and Google Cloud Run Deployment

Dale Nguyen — Wed, 20 Aug 2025 15:55:31 +0000

Building a modern landing page that captures potential user emails is essential for any startup or product launch. In this comprehensive guide, I'll walk you through creating a Next.js 15 landing page that collects emails in Google Sheets and deploys seamlessly to Google Cloud Run.

What We'll Build

By the end of this tutorial, you'll have:

A responsive Next.js 15 landing page with TypeScript
Email signup form with validation and loading states
Google Sheets integration to store collected emails
Dockerized application ready for production
Automated deployment to Google Cloud Run
Cost-effective, scalable infrastructure

Prerequisites

Node.js 20+ and pnpm installed
Google Cloud Platform account
Basic knowledge of React and TypeScript
Docker installed (for local testing)

Project Setup

1. Initialize the Next.js Project

# Create Next.js project with TypeScript
npx create-next-app@latest landing --typescript --tailwind --app

cd landing

2. Install Dependencies

# Install Google APIs client
pnpm add googleapis

# Install development dependencies
pnpm add -D @types/node

Building the Email Signup Component

1. Create the Email Signup Component

Create src/app/components/email-signup/email-signup.tsx:

'use client'

import { useState, useEffect } from 'react'

const EmailSignup = () => {
  const [email, setEmail] = useState('')
  const [status, setStatus] = useState<'idle' | 'loading' | 'success' | 'error'>('idle')
  const [message, setMessage] = useState('')

  const validateEmail = (email: string): boolean => {
    const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/
    return emailRegex.test(email)
  }

  const handleSubmit = async (e: React.FormEvent) => {
    e.preventDefault()

    if (!validateEmail(email)) {
      setStatus('error')
      setMessage('Please enter a valid email address')
      return
    }

    setStatus('loading')
    setMessage('')

    try {
      const response = await fetch('/api/v1/email-signup', {
        method: 'POST',
        headers: {
          'Content-Type': 'application/json',
        },
        body: JSON.stringify({ email }),
      })

      if (response.ok) {
        setStatus('success')
        setMessage('Thank you for subscribing!')
        setEmail('')
      } else {
        throw new Error('Subscription failed')
      }
    } catch (error) {
      setStatus('error')
      setMessage('Something went wrong. Please try again.')
    }
  }

  return (
    <section className="relative py-24 bg-gradient-to-br from-blue-600 via-purple-600 to-indigo-700">
      <div className="container relative z-10">
        <div className="text-center max-w-2xl mx-auto">
          <h2 className="mb-6 text-3xl md:text-4xl font-bold text-white">Stay updated with the latest</h2>
          <p className="mb-10 text-xl text-blue-100">Get the latest updates delivered to your inbox.</p>

          <form onSubmit={handleSubmit} className="flex flex-col sm:flex-row gap-4 max-w-md mx-auto mb-8">
            <input
              type="email"
              required
              className="flex-1 px-6 py-4 text-lg bg-white/10 backdrop-blur-sm border border-white/20 rounded-2xl text-white placeholder:text-blue-200 focus:outline-none focus:ring-2 focus:ring-white/50"
              placeholder="Enter your email"
              value={email}
              onChange={(e) => setEmail(e.target.value)}
              disabled={status === 'loading'}
            />
            <button
              type="submit"
              disabled={status === 'loading'}
              className="px-8 py-4 bg-white text-blue-600 rounded-2xl font-semibold hover:bg-blue-50 disabled:opacity-50 transition-all"
            >
              {status === 'loading' ? 'Subscribing...' : 'Subscribe'}
            </button>
          </form>

          {message && (
            <p className={`mb-6 text-lg font-medium ${status === 'success' ? 'text-green-400' : 'text-red-400'}`}>
              {message}
            </p>
          )}
        </div>
      </div>
    </section>
  )
}

export default EmailSignup

Google Sheets Integration

1. Create Google Sheets Service

Create src/lib/google-sheets.ts:

import { google } from 'googleapis'

export interface EmailSignupData {
  email: string
  timestamp: string
  source?: string
}

class GoogleSheetsService {
  private auth
  private sheets

  constructor() {
    // Use Application Default Credentials (Cloud Run provides this automatically)
    this.auth = new google.auth.GoogleAuth({
      scopes: ['https://www.googleapis.com/auth/spreadsheets'],
    })

    this.sheets = google.sheets({ version: 'v4', auth: this.auth })
  }

  async saveEmailSignup(data: EmailSignupData): Promise<void> {
    const spreadsheetId = process.env.GOOGLE_SHEETS_ID

    if (!spreadsheetId) {
      throw new Error('Google Sheets ID not configured')
    }

    const values = [[data.email, data.timestamp, data.source || 'landing-page']]

    try {
      await this.sheets.spreadsheets.values.append({
        spreadsheetId,
        range: 'Sheet1!A:C',
        valueInputOption: 'USER_ENTERED',
        requestBody: {
          values,
        },
      })
    } catch (error) {
      console.error('Error saving to Google Sheets:', error)
      throw error
    }
  }

  async setupSheet(): Promise<void> {
    const spreadsheetId = process.env.GOOGLE_SHEETS_ID

    if (!spreadsheetId) {
      throw new Error('Google Sheets ID not configured')
    }

    try {
      // Add headers if sheet is empty
      const response = await this.sheets.spreadsheets.values.get({
        spreadsheetId,
        range: 'Sheet1!A1:C1',
      })

      if (!response.data.values || response.data.values.length === 0) {
        await this.sheets.spreadsheets.values.update({
          spreadsheetId,
          range: 'Sheet1!A1:C1',
          valueInputOption: 'USER_ENTERED',
          requestBody: {
            values: [['Email', 'Timestamp', 'Source']],
          },
        })
      }
    } catch (error) {
      console.error('Error setting up Google Sheets:', error)
      throw error
    }
  }
}

export const googleSheetsService = new GoogleSheetsService()

2. Create API Route

Create src/app/api/v1/email-signup/route.ts:

import { NextRequest, NextResponse } from 'next/server'
import { googleSheetsService } from '../../../../lib/google-sheets'

export async function POST(request: NextRequest) {
  try {
    const body = await request.json()
    const { email } = body

    // Validate email
    if (!email || typeof email !== 'string') {
      return NextResponse.json({ error: 'Email is required' }, { status: 400 })
    }

    const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/
    if (!emailRegex.test(email)) {
      return NextResponse.json({ error: 'Invalid email format' }, { status: 400 })
    }

    // Save to Google Sheets
    try {
      await googleSheetsService.saveEmailSignup({
        email,
        timestamp: new Date().toISOString(),
        source: 'landing-waitlist',
      })
      console.log('Email saved to Google Sheets:', email)
    } catch (sheetsError) {
      console.error('Failed to save to Google Sheets:', sheetsError)
      // Continue with success response even if sheets fails
    }

    return NextResponse.json({ message: 'Email subscribed successfully' }, { status: 200 })
  } catch (error) {
    console.error('Email signup error:', error)
    return NextResponse.json({ error: 'Internal server error' }, { status: 500 })
  }
}

Dockerization for Production

1. Configure Next.js for Standalone Output

Update next.config.js:

/** @type {import('next').NextConfig} */
const nextConfig = {
  // Enable standalone output for Docker
  output: 'standalone',

  // Enable compression in production
  compress: true,

  // Optimize for production
  experimental: {
    optimizePackageImports: ['lucide-react'],
  },
}

module.exports = nextConfig

2. Create Dockerfile

Create Dockerfile:

# Minimal production image for built Next.js app
FROM node:20-alpine AS production

WORKDIR /app

# Copy the standalone build (includes dependencies, server, and app)
COPY .next/standalone/ ./

# Copy static files
COPY public ./public
COPY .next/static ./.next/static

# Set environment
ENV NODE_ENV=production
ENV PORT=3000

# Create a non-root user
RUN addgroup -g 1001 -S nodejs && \
    adduser -S nextjs -u 1001

# Change ownership of the application files
RUN chown -R nextjs:nodejs /app

USER nextjs

# Expose port
EXPOSE 3000

# Start the standalone server
CMD ["node", "server.js"]

3. Build and Test Locally

# Build the Next.js application
npm run build

# Build Docker image
docker build -t landing-page .

# Test locally
docker run -p 3000:3000 -e GOOGLE_SHEETS_ID=your-sheet-id landing-page

Google Cloud Setup

1. Create Google Cloud Resources

# Login to Google Cloud
gcloud auth login

# Set your project
gcloud config set project YOUR-PROJECT-ID

# Enable required APIs
gcloud services enable run.googleapis.com
gcloud services enable sheets.googleapis.com

# Create a service account
gcloud iam service-accounts create workwrite-sheets \
    --display-name="WorkWrite Sheets Service Account"

# Grant Google Sheets access
gcloud projects add-iam-policy-binding YOUR-PROJECT-ID \
    --member="serviceAccount:workwrite-sheets@YOUR-PROJECT-ID.iam.gserviceaccount.com" \
    --role="roles/editor"

2. Create Google Sheet

Go to Google Sheets
Create a new spreadsheet
Copy the spreadsheet ID from the URL
Share the sheet with your service account email

3. Build and Push to Google Cloud Registry

# Configure Docker to use gcloud
gcloud auth configure-docker us-central1-docker.pkg.dev

# Create Artifact Registry repository
gcloud artifacts repositories create workwrite-repo \
    --repository-format=docker \
    --location=us-central1

# Build and tag image
docker build --platform linux/amd64 -t us-central1-docker.pkg.dev/YOUR-PROJECT-ID/workwrite-repo/workwrite-landing .

# Push to registry
docker push us-central1-docker.pkg.dev/YOUR-PROJECT-ID/workwrite-repo/workwrite-landing

Deployment to Google Cloud Run

1. Deploy with Cloud Run

gcloud run deploy workwrite-landing \
  --image us-central1-docker.pkg.dev/YOUR-PROJECT-ID/workwrite-repo/workwrite-landing \
  --region us-central1 \
  --platform managed \
  --allow-unauthenticated \
  --service-account workwrite-sheets@YOUR-PROJECT-ID.iam.gserviceaccount.com \
  --set-env-vars GOOGLE_SHEETS_ID=YOUR-SHEET-ID \
  --port 3000 \
  --memory 1Gi \
  --cpu 1 \
  --max-instances 10 \
  --timeout 300

2. Automated Deployment with Scripts

Create deployment scripts in your package.json:

{
  "scripts": {
    "docker:build": "docker build --platform linux/amd64 -t us-central1-docker.pkg.dev/YOUR-PROJECT-ID/workwrite-repo/workwrite-landing .",
    "docker:push": "docker push us-central1-docker.pkg.dev/YOUR-PROJECT-ID/workwrite-repo/workwrite-landing",
    "deploy": "npm run build && npm run docker:build && npm run docker:push && gcloud run deploy workwrite-landing --image us-central1-docker.pkg.dev/YOUR-PROJECT-ID/workwrite-repo/workwrite-landing --region us-central1"
  }
}

Advanced Features

1. Environment Variables

Create .env.local for development:

GOOGLE_SHEETS_ID=your-development-sheet-id

2. Error Handling and Monitoring

Add comprehensive error handling in your API routes:

export async function POST(request: NextRequest) {
  try {
    // ... your existing code
  } catch (error) {
    // Log error for monitoring
    console.error('Email signup error:', {
      error: error.message,
      timestamp: new Date().toISOString(),
      userAgent: request.headers.get('user-agent'),
    })

    return NextResponse.json({ error: 'Internal server error' }, { status: 500 })
  }
}

3. Rate Limiting

Implement rate limiting to prevent abuse:

import { NextRequest, NextResponse } from 'next/server'

const rateLimitMap = new Map()

export async function POST(request: NextRequest) {
  const ip = request.ip || 'unknown'
  const limit = 5 // 5 requests per minute
  const windowMs = 60 * 1000 // 1 minute

  if (!rateLimitMap.has(ip)) {
    rateLimitMap.set(ip, {
      count: 0,
      lastReset: Date.now(),
    })
  }

  const user = rateLimitMap.get(ip)

  if (Date.now() - user.lastReset > windowMs) {
    user.count = 0
    user.lastReset = Date.now()
  }

  if (user.count >= limit) {
    return NextResponse.json({ error: 'Too many requests' }, { status: 429 })
  }

  user.count += 1

  // ... rest of your code
}

Performance Optimizations

1. Image Optimization

Add optimized images with Next.js Image component:

import Image from 'next/image'

const Hero = () => (
  <section className="hero">
    <Image src="/hero-image.jpg" alt="Hero" width={800} height={600} priority className="rounded-lg" />
  </section>
)

2. SEO Optimization

Update src/app/layout.tsx with comprehensive metadata:

import type { Metadata } from 'next'

export const metadata: Metadata = {
  title: 'WorkWrite - AI-Powered Writing Platform',
  description: 'Transform your writing workflow with AI.',
  keywords: ['writing', 'AI', 'productivity'],
  openGraph: {
    type: 'website',
    locale: 'en_US',
    url: 'https://workwrite.com',
    title: 'WorkWrite - AI-Powered Writing Platform',
    description: 'Transform your writing workflow with AI.',
    images: [
      {
        url: '/og-image.jpg',
        width: 1200,
        height: 630,
        alt: 'WorkWrite',
      },
    ],
  },
}

Cost Optimization

1. Cloud Run Pricing

Google Cloud Run pricing is based on:

CPU and Memory: Pay per 100ms of usage
Requests: $0.40 per million requests
Networking: Egress charges apply

For a typical landing page:

Low traffic (1K visitors/month): ~$1-2/month
Medium traffic (10K visitors/month): ~$5-10/month
High traffic (100K visitors/month): ~$20-40/month

2. Optimization Tips

// next.config.js
const nextConfig = {
  // Compress responses
  compress: true,

  // Optimize bundle
  experimental: {
    optimizePackageImports: ['lucide-react'],
  },

  // Cache static assets
  headers: async () => [
    {
      source: '/(.*)\\.(js|css|png|jpg|jpeg|gif|ico|svg)',
      headers: [
        {
          key: 'Cache-Control',
          value: 'public, max-age=31536000, immutable',
        },
      ],
    },
  ],
}

Monitoring and Analytics

1. Google Analytics

Add Google Analytics to track conversions:

// src/app/layout.tsx
import Script from 'next/script'

export default function RootLayout({ children }) {
  return (
    <html>
      <head>
        <Script src="https://www.googletagmanager.com/gtag/js?id=GA_MEASUREMENT_ID" strategy="afterInteractive" />
        <Script id="google-analytics" strategy="afterInteractive">
          {`
            window.dataLayer = window.dataLayer || [];
            function gtag(){dataLayer.push(arguments);}
            gtag('js', new Date());
            gtag('config', 'GA_MEASUREMENT_ID');
          `}
        </Script>
      </head>
      <body>{children}</body>
    </html>
  )
}

2. Conversion Tracking

Track email signups:

// Declare gtag as a global function for TypeScript
declare global {
  interface Window {
    gtag: (
      command: 'config' | 'event' | 'js',
      targetId: string | Date,
      config?: {
        event_category?: string
        event_label?: string
        value?: number
        [key: string]: any
      },
    ) => void
  }
}

// In your email signup component
const trackConversion = () => {
  if (typeof gtag !== 'undefined') {
    gtag('event', 'sign_up', {
      event_category: 'engagement',
      event_label: 'email_signup',
    })
  }
}

const handleSubmit = async (e) => {
  // ... existing code

  if (response.ok) {
    trackConversion()
    // ... rest of success handling
  }
}

Security Best Practices

1. Environment Variables

Never commit sensitive data:

# .env.local (never commit)
GOOGLE_SHEETS_ID=your-actual-sheet-id

# For production, set in Cloud Run
gcloud run services update workwrite-landing \
  --set-env-vars GOOGLE_SHEETS_ID=your-production-sheet-id

2. Input Validation

Always validate user inputs:

import { z } from 'zod'

const emailSchema = z.object({
  email: z.string().email('Invalid email format'),
})

export async function POST(request: NextRequest) {
  try {
    const body = await request.json()
    const { email } = emailSchema.parse(body)

    // ... rest of your code
  } catch (error) {
    if (error instanceof z.ZodError) {
      return NextResponse.json({ error: error.errors[0].message }, { status: 400 })
    }
    // ... handle other errors
  }
}

Testing

1. Component Testing

// __tests__/email-signup.test.tsx
import { render, screen, fireEvent, waitFor } from '@testing-library/react'
import EmailSignup from '../src/app/components/email-signup/email-signup'

describe('EmailSignup', () => {
  test('submits email successfully', async () => {
    global.fetch = jest.fn(() =>
      Promise.resolve({
        ok: true,
        json: () => Promise.resolve({ message: 'Success' }),
      }),
    )

    render(<EmailSignup />)

    const input = screen.getByPlaceholderText('Enter your email')
    const button = screen.getByRole('button', { name: /subscribe/i })

    fireEvent.change(input, { target: { value: 'test@example.com' } })
    fireEvent.click(button)

    await waitFor(() => {
      expect(screen.getByText('Thank you for subscribing!')).toBeInTheDocument()
    })
  })
})

2. API Testing

// __tests__/api/email-signup.test.ts
import { POST } from '../../src/app/api/v1/email-signup/route'

describe('/api/v1/email-signup', () => {
  test('validates email format', async () => {
    const request = new Request('http://localhost', {
      method: 'POST',
      body: JSON.stringify({ email: 'invalid-email' }),
    })

    const response = await POST(request)
    const data = await response.json()

    expect(response.status).toBe(400)
    expect(data.error).toBe('Invalid email format')
  })
})

Conclusion

You now have a complete, production-ready Next.js landing page that:

Collects emails efficiently with a beautiful UI
Stores data in Google Sheets automatically
Scales automatically with Google Cloud Run
Costs minimal for low to medium traffic
Performs excellently with optimized builds
Monitors effectively with built-in analytics

This setup provides a solid foundation for any product launch or marketing campaign. The combination of Next.js 15, Google Sheets, and Cloud Run offers excellent developer experience with enterprise-grade scalability and reliability.

Next Steps

Add A/B testing for different signup copy
Implement email automation with services like SendGrid
Add more landing page sections (testimonials, features, pricing)
Set up CI/CD with GitHub Actions
Add real-time analytics dashboard

The architecture we've built is flexible and can grow with your product needs while maintaining excellent performance and cost efficiency.

Supabase WordPress Integration - Sync WordPress Posts and Pages to Supabase

Dale Nguyen — Wed, 20 Aug 2025 03:56:00 +0000

Are you looking to create a modern, scalable architecture for your WordPress site? Syncing your WordPress content to Supabase opens up powerful possibilities for headless websites, mobile apps, and real-time applications. In this comprehensive guide, we'll walk you through setting up automatic post and page synchronization from WordPress to Supabase using the SupaWP plugin.

Why Sync WordPress to Supabase?

Before diving into the setup, let's understand the benefits:

🚀 Performance: Lightning-fast content delivery through Supabase's edge network
📱 Multi-platform: Build mobile apps, SPAs, and JAMstack sites using the same content
🔄 Real-time: Instant content updates across all your applications
🔒 Security: Robust Row Level Security (RLS) policies protect your data
💰 Cost-effective: Pay only for what you use with Supabase's pricing model

Prerequisites

Before getting started, make sure you have:

WordPress site with admin access
Supabase account and project
SupaWP plugin installed (v1.3.2 or later)
Basic understanding of SQL for table setup

Step 1: Install and Configure SupaWP

Install the Plugin

Download the SupaWP plugin
Upload to your WordPress site via Plugins → Add New → Upload
Activate the plugin

Configure Basic Settings

Navigate to WordPress Admin → SupaWP and configure:

General Settings:

Supabase URL: Your project URL (e.g., https://your-project.supabase.co)
Supabase Anon Key: Your public API key

Security Settings (Critical):

Supabase Service Role Key: Your service role key for server-side operations
This key bypasses Row Level Security and should never be exposed to the frontend

⚠️ Security Note: Always configure the Service Role Key for production use. This ensures secure write operations from WordPress while maintaining public read access.

Step 2: Set Up Supabase Tables

Create the Posts Table

In your Supabase SQL editor, run this command to create the posts table:

CREATE TABLE public.wp_posts (
  id integer PRIMARY KEY,
  post_title text,
  post_content text,
  post_excerpt text,
  post_status text,
  post_type text,
  post_date timestamptz,
  post_modified timestamptz,
  permalink text,
  post_thumbnail text,
  author jsonb,
  taxonomies jsonb,
  custom_fields jsonb,
  synced_at timestamptz DEFAULT now()
);

Create the Pages Table

CREATE TABLE public.wp_pages (
  id integer PRIMARY KEY,
  post_title text,
  post_content text,
  post_excerpt text,
  post_status text,
  post_type text,
  post_date timestamptz,
  post_modified timestamptz,
  permalink text,
  post_thumbnail text,
  author jsonb,
  taxonomies jsonb,
  custom_fields jsonb,
  synced_at timestamptz DEFAULT now()
);

Step 3: Implement Row Level Security

Security is paramount when exposing your content through an API. Let's set up RLS policies that allow public read access while restricting write operations to WordPress only.

Enable RLS on Posts Table

-- Enable Row Level Security
ALTER TABLE public.wp_posts ENABLE ROW LEVEL SECURITY;

-- Allow public read access (anonymous users can read published posts)
CREATE POLICY "Allow public read access"
ON public.wp_posts FOR SELECT
TO anon
USING (post_status = 'publish');

-- Allow authenticated users to read all posts
CREATE POLICY "Allow authenticated read access"
ON public.wp_posts FOR SELECT
TO authenticated
USING (true);

-- Only service role can insert/update/delete (WordPress backend only)
CREATE POLICY "Service role can manage posts"
ON public.wp_posts FOR ALL
TO service_role
USING (true) WITH CHECK (true);

-- Deny all write operations for anonymous and authenticated users
CREATE POLICY "Deny public writes"
ON public.wp_posts FOR INSERT
TO anon, authenticated
WITH CHECK (false);

CREATE POLICY "Deny public updates"
ON public.wp_posts FOR UPDATE
TO anon, authenticated
USING (false);

CREATE POLICY "Deny public deletes"
ON public.wp_posts FOR DELETE
TO anon, authenticated
USING (false);

Apply the Same Security to Pages

Repeat the same RLS setup for the wp_pages table, replacing table references accordingly.

Step 4: Configure WordPress Sync Settings

Now let's configure which content types to sync:

Go to WordPress Admin → SupaWP → Sync Data tab
Select Post Types: Check "Posts" and "Pages"
Custom Post Types: Add any custom post types (comma-separated, e.g., product, event)
Click Save Settings

Step 5: Understanding the Sync Process

Once configured, SupaWP automatically handles synchronization:

What Gets Synced

The plugin captures comprehensive post data:

Basic Info: Title, content, excerpt, status, type
Metadata: Publish date, modified date, permalink
Media: Featured image URL (with retry mechanism for processing delays)
Author Data: Author information as JSON
Taxonomies: Categories, tags, and custom taxonomies
Custom Fields: All non-private custom fields

When Sync Happens

Automatic synchronization triggers on:

Creating a new post → Immediately synced to Supabase
Updating existing content → Updates the Supabase record
Moving to trash → Removes from Supabase
Permanent deletion → Removes from Supabase

Step 6: Using Your Synced Data

Frontend API Access

With your content synced, you can now access it from any frontend application:

import { createClient } from '@supabase/supabase-js'

const supabase = createClient('https://your-project.supabase.co', 'your-anon-key')

// Get all published posts
const { data: posts } = await supabase
  .from('wp_posts')
  .select('*')
  .eq('post_status', 'publish')
  .order('post_date', { ascending: false })

// Get a specific post by ID
const { data: post } = await supabase.from('wp_posts').select('*').eq('id', 123).single()

// Search posts by title
const { data: searchResults } = await supabase
  .from('wp_posts')
  .select('*')
  .textSearch('post_title', 'search term')
  .eq('post_status', 'publish')

Real-time Subscriptions

Take advantage of Supabase's real-time capabilities:

// Subscribe to new posts
const subscription = supabase
  .channel('wp_posts')
  .on('postgres_changes', { event: 'INSERT', schema: 'public', table: 'wp_posts' }, (payload) => {
    console.log('New post published:', payload.new)
    // Update your UI in real-time
  })
  .subscribe()

Step 7: Advanced Customization

Custom Data Modification

You can modify data before it's saved to Supabase:

// In your theme's functions.php
add_filter('supawp_before_saving_to_supabase', function($data) {
  // Add site information
  $data['site_url'] = get_site_url();

  // Add custom SEO data
  $data['seo_title'] = get_post_meta($data['id'], '_yoast_wpseo_title', true);

  // Sanitize content for API consumption
  if (isset($data['post_content'])) {
    $data['post_content'] = wp_strip_all_tags($data['post_content']);
  }

  return $data;
});

Sync Event Hooks

Monitor sync operations:

// Log successful syncs
add_action('supawp_after_saving_to_supabase', function($response_data, $original_data) {
  error_log('Post synced: ' . $original_data['post_title']);
}, 10, 2);

// Handle sync failures
add_action('supawp_sync_error', function($error, $post_data) {
  // Send notification to admin
  wp_mail(get_option('admin_email'), 'Sync Error', $error);
}, 10, 2);

Manual Sync Operations

Use SupaWP's filter system for custom operations:

// Manually sync specific post
$post_data = array(
  'id' => 123,
  'post_title' => 'Custom Post',
  'custom_field' => 'Additional data'
);
apply_filters('supawp_save_data_to_supabase', $post_data);

// Get data from Supabase
$posts = apply_filters('supawp_get_data_from_supabase', 'wp_posts', array(
  'post_status' => 'eq.publish',
  'limit' => '10'
));

Troubleshooting Common Issues

Posts Not Syncing

Check post type selection in SupaWP settings
Verify Service Role Key is configured (not just anon key)
Ensure tables exist in Supabase with correct naming convention

Permission Errors

Verify RLS policies allow service_role to write
Check service role key is correct and has proper permissions
Test connection from WordPress admin

Image Sync Issues

Enable WordPress debugging to see detailed error logs
Check featured image processing - some themes delay image processing
Verify image URLs are publicly accessible

Debug Logging

Enable WordPress debug logging:

// In wp-config.php
define('WP_DEBUG', true);
define('WP_DEBUG_LOG', true);

Check /wp-content/debug.log for SupaWP error messages.

Best Practices for Production

Performance Optimization

Index your tables for common query patterns:

   CREATE INDEX idx_wp_posts_status_date
   ON wp_posts(post_status, post_date DESC);

Use selective querying - only fetch fields you need
Implement caching in your frontend application

Security Considerations

Never expose service role key to frontend
Regularly rotate API keys
Monitor database access through Supabase dashboard
Use RLS policies to restrict data access appropriately

Monitoring and Maintenance

Set up monitoring for sync operations
Regular backups of Supabase data
Monitor API usage and costs
Keep SupaWP updated for latest features and security fixes

Use Cases and Examples

JAMstack Blog

Create a lightning-fast blog using Supabase as your content API:

// Next.js example
export async function getStaticProps() {
  const { data: posts } = await supabase
    .from('wp_posts')
    .select('id, post_title, post_excerpt, post_date, permalink')
    .eq('post_status', 'publish')
    .order('post_date', { ascending: false })
    .limit(10)

  return {
    props: { posts },
    revalidate: 60, // Revalidate every minute
  }
}

Mobile App Integration

Use the same content in your React Native app:

const [posts, setPosts] = useState([])

useEffect(() => {
  const fetchPosts = async () => {
    const { data } = await supabase.from('wp_posts').select('*').eq('post_status', 'publish')
    setPosts(data)
  }

  fetchPosts()
}, [])

Multi-site Content Distribution

Sync content from one WordPress site to multiple frontend applications, each with different presentation layers but the same content source.

Conclusion

Syncing WordPress to Supabase with SupaWP opens up a world of possibilities for modern web development. You get the familiar WordPress editing experience combined with the power and flexibility of Supabase's modern database and real-time capabilities.

The automatic synchronization ensures your content is always up-to-date across all platforms, while the robust security model keeps your data safe. Whether you're building a headless website, mobile app, or multi-platform content distribution system, this setup provides a solid foundation for scalable, modern applications.

Start with the basic setup outlined in this guide, then gradually explore the advanced customization options as your needs grow. The combination of WordPress's content management capabilities and Supabase's modern infrastructure creates a powerful platform for any content-driven application.

Resources

This guide covers SupaWP v1.3.2 and later. Features and configuration may vary in different versions.

I Built a Leadership Simulator for Aspiring Tech Leads (And Why The Soft Skills Matter Most)

Dale Nguyen — Sat, 09 Aug 2025 15:01:20 +0000

Let's be honest - I'm good at code, but the thought of managing people terrifies me.

I've been a senior developer for a while now, and everyone keeps asking when I'm going to "take the next step" to Tech Lead or Staff Engineer. The problem? While I'm confident about system design and code reviews, I have no idea how to handle stakeholder politics or motivate struggling team members.

So instead of continuing to put off the inevitable, I built something to help me (and hopefully others) practice.

What is it?

TechLeadPilot is a leadership simulator that puts you in realistic Tech Lead scenarios before you actually have to face them. Think "choose your own adventure" but for workplace situations that'll actually happen to you.

You might face scenarios like:

🔥 Your PM wants to ship without proper testing to hit a deadline
🤝 Two senior engineers can't agree on system architecture
📊 You need to explain why refactoring is worth 2 sprints to your director
😤 A team member keeps missing deadlines but won't admit they're struggling

How it works

Pick a scenario from the library
Read the situation and make your choice or write your response
Get AI feedback on your leadership approach
Learn what you did well and where you can improve

Why I built this

The idea of going from "senior engineer who codes in peace" to "tech lead who spends most of their time in meetings" is honestly pretty scary.

I know I'll need to:

Navigate office politics (ugh)
Influence people who don't report to me
Communicate complex technical stuff to non-technical people
Actually motivate and mentor team members
Make decisions when I don't have all the information

These seem like learnable skills, but I'd rather practice them in a simulator than figure them out by potentially screwing up with real people.

The tech stack

Since this is dev.to:

Frontend: Angular with Analog.js for SSR
Backend: Node.js API routes
Database: Firestore for user data and simulation results
AI: Google Vertex AI for generating personalized feedback
Hosting: Firebase (because it just works)

What's next?

I'm working on:

More scenario types (performance reviews sound terrifying)
Roleplay mode where the AI plays different characters
Progress tracking so I can see if I'm actually getting better at this

Try it out: https://techleadpilot.com/simulations

Fellow aspiring Tech Leads - what scenarios scare you the most? Always looking for new ideas to add!

DEV Community: Dale Nguyen

Free Model Providers to Use with Hermes Agent

Installing Hermes Agent

Switching providers

Free providers supported by Hermes Agent

Nous Portal

OpenRouter

NVIDIA NIM

Hugging Face

NovitaAI

Kimi / Moonshot

Provider comparison at a glance

Tips for running Hermes on free tiers

Summary

Building a Personal Assistant in Zo Computer and Adding Hermes as a Second Assistant

Why a personal assistant in Zo is useful

What "personal assistant" should mean in Zo

The cleanest setup: one main assistant, one second assistant

Zo as the primary assistant

Hermes as the second assistant

How Hermes fits in

Basic Hermes installation path

How to divide work between Zo and Hermes

Zo handles the personal layer

Hermes handles the parallel layer

A simple working model

Tips for making the setup actually useful

1. Give each assistant a role

2. Keep preferences in one place

3. Use the assistant for real workflows

4. Keep the assistant close to your files

5. Treat the second assistant like an aide, not a boss

Example use case

Bottom line

Securing Your MCP Server with Firebase Auth: A Production Walkthrough

Architecture Overview

Step 1: Initialize Firebase Admin SDK

Step 2: Token Resolution

OAuth Tokens (ctpo_*)

Firebase ID Tokens

Step 3: The Auth Middleware

Step 4: Thread-Safe User Context

Step 5: The OAuth 2.0 Server (Web App Side)

Step 6: Client-Side (Browser)

Step 7: Firestore Security Rules

Step 8: OAuth Discovery Endpoint

Step 9: Local Testing

Security Properties

Summary

Building MCP Apps with Angular

How MCP Apps Work (Quick Recap)

Project Structure

Step 1: The Server

Step 2: The HTML Entry Point

Step 3: The Angular App

Step 4: Adding a Second UI

Server: Register Both Tools

Greeting Component

Step 5: Sharing Code Between UIs

Step 6: The Build

Theming: Looking Native in Any Host

Recap

How I Almost Got Pwned - A Tale of Supply Chain Attacks and GitHub Actions Gone Wrong

What Even Is a Supply Chain Attack?

The Smoking Gun: The Lockfile Had Been Tampered With

Enter the "Helpful" Contributor

The GhostAction Campaign: When GitHub Actions Turn Evil

The Attack Vector Breakdown

The Broader Context: The Great NPM Hack of 2025

Red Flags I Should Have Caught Earlier

1. The Contributor Profile

2. The "Mistakes" Were Too Convenient

3. The Timing

What Could Have Gone Wrong

Best Practices: How to Not Get Pwned

1. Lockfile Hygiene

2. CI/CD Security

3. Dependency Management

4. PR Review Guidelines

5. Repository Protection

OAuth Tokens (`ctpo_*`)

1. `supawp_upload_image_to_supabase`

2. `supawp_delete_image_from_supabase`

3. `supawp_get_storage_config`