I came across Matt Silverlock's dotfiles and realized this could be automated. The idea is simple - version control your configuration so one command reproduces your entire environment on a new machine.

My dotfiles now handle everything from Xcode Command Line Tools to VS Code extensions. What used to take hours now happens while I make a crisp beverage.

What it does

1. Checks prerequisites - Verifies macOS and internet connection
2. Installs Xcode CLT - The foundation for everything else
3. Installs Homebrew - Package manager
4. Installs packages - From a Brewfile with CLI tools and apps
5. Sets up mise - Manages Node, Bun, pnpm, Python versions
6. Configures zsh - oh-my-zsh with plugins and theme
7. Generates SSH keys - Ed25519 keys with commit signing
8. Symlinks dotfiles - GNU Stow links configs into place
9. Sets up secrets - API token configuration
10. Installs editor extensions - VS Code and Cursor
11. Imports Raycast settings - Window management and shortcuts

The script is idempotent - safe to run multiple times, skipping what's already installed.

Work mode

The --work flag separates personal from work setups, given I don't need certain tools or apps on a work laptop, but I want a consistent environment for non-sensitive configurations.

Running sh install.sh --work swaps the Brewfile:

• Brewfile - Core tools for everyone
• Brewfile.personal - Personal stuff
• Brewfile.work - Work-specific stuff

CLI tools that make a difference

These tools fundamentally change how I work in the terminal:

• bat - Syntax-highlighting cat
• delta - Beautiful git diffs
• fd - Intuitive find replacement
• fzf - Fuzzy finder bound to Ctrl+T and Ctrl+R
• ripgrep - Fast search respecting .gitignore
• zoxide - Smarter cd that learns your directories

Managing configuration with Stow

GNU Stow manages the dotfiles by creating symlinks from ~ back to the repo. Edit ~/.zshrc and the change is immediately in version control.

Stow has a .stow-local-ignore file that prevents certain files from being linked. I use it to skip the README, install scripts, and anything else that shouldn't live in ~:

\.git
\.gitignore
README.md
install.sh
Brewfile

My .zshrc configures fzf with custom previews, integrates zoxide, and activates mise. Everything is configured exactly how I like it, on every machine.

Should you do this?

If you set up more than one Mac every couple of years, yes. The investment pays for itself quickly. It's also very comforting.

Start small - fork my repo or Matt's, and edit it to your liking. You could just use Homebrew, your shell, and your editor, and add more as you find repetitive tasks.

The site has been completely rebuilt. The new charliegleason.com is a proper pnpm monorepo running Astro on Cloudflare Workers, with Durable Objects for real-time features and a real session-based authentication system. No more symlinks, either.

The architecture

The monorepo has four packages:

• @charliegleason/web - The Astro SSR site, deployed as a Cloudflare Worker.
• @charliegleason/visitor-counter - A Durable Object that tracks real-time visitors via WebSocket.
• @charliegleason/lastfm-tracker - A Durable Object that broadcasts what I'm listening to on Last.fm via WebSocket.
• @charliegleason/private - Protected content that never leaves the private repo.

Each package has its own wrangler.jsonc and its own deploy step. You find them all on GitHub: charliegleason/charliegleason.com.

Authentication flow

The auth system is deliberately simple. Password-based, session-stored, no OAuth dance.

The flow: visit a protected route, middleware redirects you to /login, and you enter the password. A session gets created in Cloudflare KV with a 7-day TTL, a cookie gets set, and you're redirected back to where you were trying to go. KV handles expiration automatically.

I'm using Effect for the session management, mostly because I wanted typed error handling without a bunch of try/catch nesting. The createSession function is a good example of what that looks like:

export const createSession = (
  kv: KVNamespace,
  userId: string,
): Effect.Effect<string, KVError> =>
  Effect.gen(function* () {
    const sessionId = crypto.randomUUID();
    const now = Date.now();

    const session: Session = {
      userId,
      createdAt: now,
      expiresAt: now + SESSION_DURATION_MS,
    };

    yield* Effect.tryPromise({
      try: () =>
        kv.put(`session:${sessionId}`, JSON.stringify(session), {
          expirationTtl: SESSION_DURATION_SECONDS,
        }),
      catch: (error) =>
        new KVError({
          operation: "put",
          key: `session:${sessionId}`,
          message: "Failed to create session",
          cause: error,
        }),
    });

    yield* Effect.logDebug(`Created session: ${sessionId}`);
    return sessionId;
  });

A UUID session ID, a JSON blob in KV, and a TTL that means I never have to clean up stale sessions. If you're thinking "that's a key-value store with extra steps," you're right, but the extra steps have types.

Protected routes injection

This is the part I'm most pleased with. Instead of the old symlink-and-sync approach, I (read: the robots) wrote an Astro integration that scans the private content directory at build time and uses injectRoute to register protected pages:

export default function protectedRoutes(
  options: ProtectedRoutesOptions = {},
): AstroIntegration {
  return {
    name: "protected-routes",
    hooks: {
      "astro:config:setup": ({ injectRoute, config, logger }) => {
        const rootDir = fileURLToPath(config.root);
        const protectedDir = options.protectedDir || "../private/content";
        const contentDir = join(rootDir, protectedDir);

        if (!existsSync(contentDir)) {
          logger.info("No protected content directory found");
          logger.info("This is expected in public mirror builds");
          return;
        }

        const routes = findAstroFiles(contentDir, contentDir);

        for (const route of routes) {
          logger.info(`Injecting protected route: ${route.pattern}`);
          injectRoute({
            pattern: route.pattern,
            entrypoint: route.entrypoint,
          });
        }
      },
    },
  };
}

The key detail: when the private package isn't there - like in public mirror builds - it logs a friendly message and moves on. No crash, no build failure. The public site builds and deploys perfectly fine without the protected content. The private monorepo builds with everything.

Durable Objects for real-time features

I wanted a live visitor counter and a now-playing widget. Both felt like natural fits for Durable Objects - they're stateful, long-lived, and need to broadcast to multiple clients.

Visitor counter

The visitor counter is ridiculous simple. The count is the number of open WebSocket connections. No database, no persistence needed. Someone connects, the count goes up. Someone disconnects, the count goes down. Everyone gets a broadcast.

export class VisitorCounter extends DurableObject<Env> {
  async fetch(request: Request): Promise<Response> {
    const upgradeHeader = request.headers.get("Upgrade");
    if (upgradeHeader !== "websocket") {
      return new Response("Expected WebSocket", { status: 426 });
    }

    const webSocketPair = new WebSocketPair();
    const [client, server] = Object.values(webSocketPair);

    this.ctx.acceptWebSocket(server);
    this.broadcast();

    return new Response(null, {
      status: 101,
      webSocket: client,
    });
  }

  async webSocketClose(ws: WebSocket, code: number, reason: string): Promise<void> {
    ws.close(code, reason);
    this.broadcast();
  }

  private getCount(): number {
    return this.ctx.getWebSockets().length;
  }

  private broadcast(): void {
    const count = this.getCount();
    const message = JSON.stringify({ count });
    for (const ws of this.ctx.getWebSockets()) {
      try { ws.send(message); } catch {}
    }
  }
}

WebSocket hibernation means Cloudflare isn't charging me for idle connections, and the global singleton pattern means everyone sees the same count. It's the kind of feature that's disproportionately fun relative to the effort involved.

Last.fm tracker

The Last.fm tracker is slightly more involved. The frontend connects directly to the tracker Worker via WebSocket - it doesn't go through the main Astro app at all. When a connection comes in, the Durable Object immediately sends the current track (if it has one) and starts polling. Every 30 seconds, an Alarm fires, hits the Last.fm API, and checks if the track has changed. If it has, it broadcasts to all connected clients. If not, it does nothing.

The current track gets stored in Durable Object storage so it survives cold starts - when the DO spins back up, it restores from storage in the constructor before accepting any connections. The Last.fm API response includes a nowplaying attribute, which gets passed through as an isNowPlaying flag. The frontend uses that to show "Listening to" with animated equalizer bars when music is playing, or "Last played" with static bars when it's not.

One nice detail: the Alarm only reschedules itself if there are active WebSocket connections. No listeners, no polling. It starts up again when someone connects.

Hosting on Cloudflare

Everything runs on Cloudflare's edge. The main Astro site is a Worker. Sessions live in KV. The Durable Objects are deployed as independent Workers with service bindings connecting them to the main app.

The wrangler.jsonc for the web app ties it all together:

{
  "name": "astro-charliegleason-com",
  "kv_namespaces": [{ "binding": "SESSION", "id": "..." }],
  "durable_objects": {
    "bindings": [
      { "name": "VISITOR_COUNTER", "class_name": "VisitorCounter", "script_name": "visitor-counter" },
      { "name": "LASTFM_TRACKER", "class_name": "LastFmTracker", "script_name": "lastfm-tracker" }
    ]
  }
}

One thing that tripped me up: deployment order matters. The Durable Object Workers need to exist before the web app can bind to them. GitHub Actions handles the sequencing - Durable Objects deploy first, then the web app. I learned this the hard way, which is how I learn most things.

The public mirror

The mental model has completely flipped from the old approach. Previously, the public repo was the source of truth - the private repo consumed it via npm link and sync-directory. Now the private monorepo is the source of truth, and git subtree push mirrors apps/web/ to the public repo. Protected content never leaves the private repo. It never gets committed to the public mirror. It's a much cleaner separation.

Wrapping up

The old system worked, but the new setup works better. It's a real monorepo with real auth, real-time features, and a deployment pipeline that doesn't make me nervous. It's the kind of rebuild where the end result looks simple, which I think means it was worth doing.

This is how I set it up to work with opencode, the open source AI coding assistant that makes it easy to use various LLM providers, including your own.

The architecture

The setup looks like this:

[Laptop] → opencode → HTTPS → [Cloudflare Access] → [Cloudflare Tunnel] → [Windows PC:11434] → Ollama → 4090 GPU

Your laptop talks to Cloudflare over HTTPS, Cloudflare authenticates the request, then forwards it through an encrypted tunnel to your Windows PC (or whatever machine you're running whatever service on). From opencode's perspective, it's just hitting an HTTPS endpoint. From your PC's perspective, it's just receiving local requests.

No port forwarding, no dynamic DNS, no exposing your home network to the internet. Easy as.

Why this is useful

Running LLMs locally is nice. You get full control over the model, no API costs, and reasonable speed if you have decent hardware. But "local" usually means you're sitting at that specific machine.

Cloudflare Tunnel lets you access your local Ollama instance from anywhere - at a coffee shop, your phone, or shared with others. All without the usual networking hassles.

Part 1: Windows PC setup

Let's start by getting Ollama running properly on the Windows machine, but these instructions should work for any other service you want to expose.

Installing Ollama

Download the Windows installer from ollama.com and run it. It'll install natively and automatically use CUDA if you have an NVIDIA GPU.

Choosing a model

For coding with tool calling support, Qwen3 works well. The 30B MoE version fits comfortably in 24GB VRAM:

ollama pull qwen3-coder:30b

[!NOTE] A note on model choice: I initially tried Qwen 2.5 Coder but ran into issues with tool calling in Ollama. Qwen3 handles it much better. Also avoid the VL (vision-language) variants if you're tight on memory.

Allowing network access

By default, Ollama only listens on localhost. To accept connections from the tunnel, set an environment variable.

[!NOTE] Ollama does have a setting to expose itself to the network, so you can also try that. I probably should have, on reflection.

In PowerShell (as administrator):

[Environment]::SetEnvironmentVariable("OLLAMA_HOST", "0.0.0.0:11434", "Machine")

Restart the Ollama service after setting this. You can do this byfinding the Ollama service in Task Manager or in your running applications.

Installing cloudflared

The tunnel software is called cloudflared. Install it with winget:

winget install --id Cloudflare.cloudflared

If you're on a Mac, you can use brew:

brew install cloudflared

Or you download it from the Cloudflare downloads page.

Authenticating cloudflared

Run this to authenticate with your Cloudflare account:

cloudflared tunnel login

This opens your browser. Select the domain you want to use for the tunnel (you'll need a domain in your Cloudflare account).

Creating the tunnel

Create a named tunnel:

cloudflared tunnel create ollama-tunnel

Note the UUID that gets printed out. You'll need it in the config file.

Configuring the tunnel

Create a config file at C:\Users\<username>\.cloudflared\config.yml:

tunnel: <TUNNEL_UUID>
credentials-file: C:\Users\<username>\.cloudflared\<TUNNEL_UUID>.json

ingress:
  - hostname: ollama.yourdomain.com
    service: http://localhost:11434
  - service: http_status:404

Replace <TUNNEL_UUID> with the UUID from the previous step, and ollama.yourdomain.com with your actual domain.

The ingress rules tell cloudflared where to route requests. Anything hitting ollama.yourdomain.com gets forwarded to localhost:11434 (where Ollama is listening).

Adding DNS

This creates the DNS record that points your domain to the tunnel:

cloudflared tunnel route dns ollama-tunnel ollama.yourdomain.com

Running the tunnel

Test it first:

cloudflared tunnel run ollama-tunnel

You can also install it as a Windows service so it starts automatically.

There you go, your very own tunnel to the outside world.

Part 2: Cloudflare Access setup

Cloudflare Tunnel creates a secure connection between Cloudflare's edge and your PC, but by default anyone who knows the URL can use it. Cloudflare Access adds authentication.

Generating a service token

Since opencode uses API calls, we need a token that can authenticate without a browser.

Go to Access → Service Auth → Service Tokens, then click Create Service Token.

Name it something like opencode-laptop.

You'll get two values: CF-Access-Client-Id and CF-Access-Client-Secret. Copy both and keep them somewhere safe. You'll need them on your laptop.

These tokens provide full API access, so treat them like passwords. If they leak, rotate them immediately.

Creating an Access application

Go to your Cloudflare Dashboard → Zero Trust → Access controls → Applications, then click "Add an application" and choose "Self-hosted."

Application name:    Ollama API
Session duration:    24 hours (or whatever you prefer)
Application domain:  ollama.yourdomain.com

Creating the right policy

Next we need to define who can access our tunnel.

When you create an access policy, there are different actions you can choose. For browser-based access, you'd use "Allow" and authenticate with email or SSO.

Policy name:         Service Token Access
Action:              Service Auth (not "Allow")
Include rule:
 - Selector:         Service Token
 - Value:            Select your service token (the one you made earlier)

Without the Service Auth action, API requests get redirected to a browser login page and fail. This took me longer to figure out than I'd like to admit.

Part 3: Laptop setup

Now we configure opencode to use the remote Ollama instance.

Installing opencode

On macOS:

brew install anomalyco/tap/opencode

Configuring opencode

Create or edit ~/.config/opencode/opencode.json:

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "ollama-remote": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Ollama (Remote)",
      "options": {
        "baseURL": "https://ollama.yourdomain.com/v1",
        "headers": {
          "CF-Access-Client-Id": "<YOUR_CLIENT_ID>",
          "CF-Access-Client-Secret": "<YOUR_CLIENT_SECRET>"
        }
      },
      "models": {
        "qwen3-coder": {
          "name": "Qwen 3 Coder 30B"
        }
      }
    }
  }
}

Replace the placeholder values with your actual domain and service token credentials.

The baseURL uses /v1 because Ollama exposes an OpenAI-compatible API at that path. The headers include your Cloudflare Access credentials, which get sent with every request.

Testing it

First, test the API directly:

curl -X POST https://ollama.yourdomain.com/api/generate \
  -H "CF-Access-Client-Id: <YOUR_CLIENT_ID>" \
  -H "CF-Access-Client-Secret: <YOUR_CLIENT_SECRET>" \
  -H "Content-Type: application/json" \
  -d '{"model": "qwen3-coder", "prompt": "Say hello", "stream": false}'

If you get a JSON response with generated text, it's working.

Then try opencode:

opencode

You should see your remote model available as an option.

Troubleshooting

Here are the issues I ran into and how I fixed them.

Tool calls failing

If the model generates responses but tool calls don't work, check your context window. Tool calling needs at least 16K context. Make sure your Modelfile has PARAMETER num_ctx 16384 or higher.

Also double-check you're using Qwen3, not Qwen 2.5 Coder. The latter has known issues with tool calling in Ollama.

Connection refused

If you can't connect at all, verify the OLLAMA_HOST environment variable is set to 0.0.0.0:11434. Then restart the Ollama service.

Check the tunnel is running:

cloudflared tunnel info ollama-tunnel

401/403 errors or redirects

If you're getting authentication errors, verify your service token headers are correct in the opencode config.

Also double-check that your Access policy uses "Service Auth" action, not "Allow." This was my mistake - I had created an email-based policy initially, which doesn't work for API requests.

Model crashes with memory errors

If you see "memory layout cannot be allocated" errors, reduce the context size in your Modelfile. Try 8192 instead of 16384.

You can also check VRAM usage with:

nvidia-smi

If you're maxing out, consider using a smaller model or a more aggressive quantization.

Slow responses

This is normal for large models. The 30B model takes a few seconds to start generating, especially on the first request after loading the model into VRAM.

I typically see around 70 tokens per second with the Q4 quantization on a 4090, which is fast enough for coding.

Security considerations

A few things to keep in mind.

Service tokens bypass browser authentication. If someone gets your tokens, they have full access to your Ollama instance. Don't commit them to git, don't share screenshots with them visible, and rotate them if you suspect they've leaked.

The tunnel credentials (the JSON file in .cloudflared) should also stay private. They're what allow cloudflared to connect to your specific tunnel.

If your laptop has a static IP, you can add IP restrictions in Cloudflare Access for an extra layer of security.

What's next

This setup has been surprisingly reliable. The tunnel can reconnect automatically if my home internet drops, and Cloudflare's edge handles the authentication before anything reaches my PC.

Latency is good - usually under 100ms - which is barely noticeable compared to the time the model takes to generate responses.

The same pattern works for other services too. I've used Cloudflare Tunnel to expose Jupyter notebooks, local web servers, and various development tools. It's become my default way of accessing home-hosted services remotely.

Now go put that gaming GPU to work.

MCP is Anthropic's open protocol for connecting AI assistants to external data sources and tools. Instead of Claude having a fixed set of capabilities, you can extend it with custom servers that provide new tools, resources, and prompts. Think of it as a plugin system, but standardized and interoperable.

This is a walkthrough of building a weather MCP server from scratch, getting it running on Cloudflare's edge network, and hooking it up to Claude Desktop so you can ask about weather anywhere in the world.

Try it now

Want to see it in action before building your own? I've deployed a working version you can use right away. Add this to your Claude Desktop config:

{
  "mcpServers": {
    "weather": {
      "url": "https://weather-mcp-server.superhighfives.workers.dev/mcp"
    }
  }
}

The full source code is available at github.com/superhighfives/weather-mcp.

What we're building

A simple weather MCP server that can be used to get the current weather and forecast for any city in the world. Our server will provide two tools:

• get-current-weather - Current conditions for any city
• get-forecast - Multi-day forecasts (1-7 days)

We'll use the Open-Meteo API for weather data (it's free and doesn't require authentication), TypeScript for type safety, and Cloudflare Workers for deployment. The whole thing will run on the edge with sub-100ms response times globally.

Prerequisites

Before starting, make sure you have:

• Node.js 18 or later - The MCP SDK and Wrangler require modern Node.js features
• npm or yarn - For installing dependencies
• A Cloudflare account - Free tier is sufficient (sign up here)
• Claude Desktop - To test your MCP server (download here)

You can verify your Node.js version with:

node --version

If you're on an older version, update Node.js before proceeding.

Setting up the project

Start by creating a new directory and initializing a Node.js project:

mkdir weather-mcp-server
cd weather-mcp-server
npx wrangler init

Wrangler is Cloudflare's CLI for deploying Workers. You'll need to select a directory. Choose the Hello World example, and then Worker only, with the language set to TypeScript.

Maybe grab a coffee while you wait.

Update the wrangler.jsonc file with "compatibility_flags": ["nodejs_compat"]. The nodejs_compat flag enables Node.js APIs in the Workers runtime.

{
	"$schema": "node_modules/wrangler/config-schema.json",
	"name": "weather-mcp-example",
	"main": "src/index.ts",
	"compatibility_date": "2025-11-06",
	"compatibility_flags": ["nodejs_compat"],
	"observability": {
		"enabled": true
	}
}

Once that's done, install your dependencies:

npm install @modelcontextprotocol/sdk @types/node agents typescript zod

Here's what each package does:

• @modelcontextprotocol/sdk - The official MCP SDK for building servers
• @types/node - TypeScript type definitions for Node.js
• agents - Cloudflare's MCP framework that handles HTTP transport
• typescript - Type safety and compilation
• zod - Runtime schema validation for tool inputs

Building the MCP server

Jump into src/index.ts and delete whatever code is there. You can then start with the imports:

import { createMcpHandler } from "agents/mcp";
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { z } from "zod";

The MCP SDK provides the core server functionality, agents/mcp handles the HTTP transport for Cloudflare Workers, and Zod lets us define type-safe schemas for tool inputs.

Weather codes and helper functions

We'll need to add some types for the weather data. Open-Meteo returns data with the following structure:

interface GeocodingResponse {
  results?: Array<{
    latitude: number;
    longitude: number;
    name: string;
  }>;
}

interface WeatherResponse {
  current: {
    temperature_2m: number;
    relative_humidity_2m: number;
    weathercode: number;
    windspeed_10m: number;
    winddirection_10m: number;
  };
}

interface ForecastResponse {
  daily: {
    time: string[];
    temperature_2m_max: number[];
    temperature_2m_min: number[];
    weathercode: number[];
    precipitation_probability_max: number[];
  };
}

Open-Meteo returns numeric weather codes (part of the WMO standard), so we need to map them to readable descriptions:

const WEATHER_CODES: Record<number, string> = {
  0: "Clear sky",
  1: "Mainly clear",
  2: "Partly cloudy",
  3: "Overcast",
  45: "Foggy",
  48: "Depositing rime fog",
  51: "Light drizzle",
  53: "Moderate drizzle",
  55: "Dense drizzle",
  61: "Slight rain",
  63: "Moderate rain",
  65: "Heavy rain",
  71: "Slight snow",
  73: "Moderate snow",
  75: "Heavy snow",
  77: "Snow grains",
  80: "Slight rain showers",
  81: "Moderate rain showers",
  82: "Violent rain showers",
  85: "Slight snow showers",
  86: "Heavy snow showers",
  95: "Thunderstorm",
  96: "Thunderstorm with slight hail",
  99: "Thunderstorm with heavy hail",
};

function getWeatherDescription(code: number): string {
  return WEATHER_CODES[code] || "Unknown";
}

Geocoding cities to coordinates

Open-Meteo needs latitude and longitude, so we'll use their geocoding API to convert city names:

async function geocodeCity(cityName: string): Promise<{
  latitude: number;
  longitude: number
}> {
  const url = `https://geocoding-api.open-meteo.com/v1/search?name=${encodeURIComponent(
    cityName
  )}&count=1&language=en&format=json`;

  const response = await fetch(url);
  if (!response.ok) {
    throw new Error(`Geocoding API error: ${response.statusText}`);
  }

  const data = await response.json() as GeocodingResponse;

  if (!data.results || data.results.length === 0) {
    throw new Error(`City "${cityName}" not found`);
  }

  const result = data.results[0];
  return {
    latitude: result.latitude,
    longitude: result.longitude,
  };
}

This searches for the city name and returns the first match. In a production app you might want to handle multiple matches or be more specific about which city you mean (there are multiple Portlands, for example).

Fetching current weather

Now we can fetch the actual weather data:

async function getCurrentWeather(latitude: number, longitude: number) {
  const url = `https://api.open-meteo.com/v1/forecast?latitude=${latitude}&longitude=${longitude}&current=temperature_2m,relative_humidity_2m,weathercode,windspeed_10m,winddirection_10m`;

  const response = await fetch(url);
  if (!response.ok) {
    throw new Error(`Weather API error: ${response.statusText}`);
  }

  const data = await response.json() as WeatherResponse;
  const current = data.current;

  return {
    temperature: current.temperature_2m,
    weathercode: current.weathercode,
    windspeed: current.windspeed_10m,
    winddirection: current.winddirection_10m,
    humidity: current.relative_humidity_2m,
  };
}

The current parameter in the URL specifies which fields we want. Open-Meteo has dozens of options - precipitation, UV index, visibility, etc. We're keeping it simple with temperature, humidity, wind, and conditions.

Fetching forecasts

For multi-day forecasts, we need a slightly different endpoint:

async function getWeatherForecast(
  latitude: number,
  longitude: number,
  days: number
) {
  const url = `https://api.open-meteo.com/v1/forecast?latitude=${latitude}&longitude=${longitude}&daily=weathercode,temperature_2m_max,temperature_2m_min,precipitation_probability_max&timezone=auto&forecast_days=${days}`;

  const response = await fetch(url);
  if (!response.ok) {
    throw new Error(`Weather API error: ${response.statusText}`);
  }

  const data = await response.json() as ForecastResponse;
  const daily = data.daily;

  const forecast = [];
  for (let i = 0; i < daily.time.length; i++) {
    forecast.push({
      date: daily.time[i],
      temperature_max: daily.temperature_2m_max[i],
      temperature_min: daily.temperature_2m_min[i],
      weathercode: daily.weathercode[i],
      precipitation_probability: daily.precipitation_probability_max[i],
    });
  }

  return forecast;
}

The daily endpoint returns arrays of values, one for each day. We're transforming this into an array of objects to make it easier to work with.

Creating the MCP server

Now we can create our MCP server instance:

const server = new McpServer({
  name: "weather-server",
  version: "1.0.0",
});

Adding the current weather tool

Tools in MCP are defined with a name, description, input schema (using Zod), and a handler function:

server.tool(
  "get-current-weather",
  "Get the current weather for a specific city. Returns temperature, conditions, humidity, and wind information.",
  {
    city: z.string().describe("Name of the city (e.g., 'London', 'New York', 'Tokyo')"),
  },
  async ({ city }) => {
    try {
      const coords = await geocodeCity(city);
      const weather = await getCurrentWeather(coords.latitude, coords.longitude);

      return {
        content: [
          {
            type: "text",
            text: JSON.stringify(
              {
                city,
                coordinates: coords,
                current: {
                  temperature: `${weather.temperature}°C`,
                  conditions: getWeatherDescription(weather.weathercode),
                  humidity: `${weather.humidity}%`,
                  wind: {
                    speed: `${weather.windspeed} km/h`,
                    direction: `${weather.winddirection}°`,
                  },
                },
              },
              null,
              2
            ),
          },
        ],
      };
    } catch (error) {
      const errorMessage = error instanceof Error ? error.message : String(error);
      return {
        content: [
          {
            type: "text",
            text: `Error: ${errorMessage}`,
          },
        ],
        isError: true,
      };
    }
  }
);

The handler calls our geocoding and weather functions, then formats the response as JSON. The content array can contain multiple items - text, images, or other content types. We're just using text here.

Error handling is important. If the city isn't found or the API is down, we return an error response instead of throwing, which gives Claude a helpful message to show the user.

Adding the forecast tool

The forecast tool is similar but takes an additional parameter for the number of days:

server.tool(
  "get-forecast",
  "Get weather forecast for a specific city. Returns daily forecasts with high/low temperatures and conditions.",
  {
    city: z.string().describe("Name of the city (e.g., 'London', 'New York', 'Tokyo')"),
    days: z
      .number()
      .min(1)
      .max(7)
      .describe("Number of days to forecast (1-7)")
      .default(3),
  },
  async ({ city, days }) => {
    try {
      const coords = await geocodeCity(city);
      const forecast = await getWeatherForecast(
        coords.latitude,
        coords.longitude,
        Math.min(Math.max(days, 1), 7)
      );

      return {
        content: [
          {
            type: "text",
            text: JSON.stringify(
              {
                city,
                coordinates: coords,
                forecast: forecast.map((day) => ({
                  date: day.date,
                  temperature: {
                    max: `${day.temperature_max}°C`,
                    min: `${day.temperature_min}°C`,
                  },
                  conditions: getWeatherDescription(day.weathercode),
                  precipitation_probability: `${day.precipitation_probability}%`,
                })),
              },
              null,
              2
            ),
          },
        ],
      };
    } catch (error) {
      const errorMessage = error instanceof Error ? error.message : String(error);
      return {
        content: [
          {
            type: "text",
            text: `Error: ${errorMessage}`,
          },
        ],
        isError: true,
      };
    }
  }
);

Zod handles validation automatically. If someone asks for 10 days, it'll clamp to 7. If they don't specify, it defaults to 3 days.

Adding a resource

Resources in MCP are static content that the server can provide. They're useful for documentation or contextual information:

server.resource(
  "weather-info",
  "weather://info",
  {
    name: "Weather Service Information",
    description: "Information about the weather service and API",
    mimeType: "text/plain",
  },
  async () => ({
    contents: [
      {
        uri: "weather://info",
        mimeType: "text/plain",
        text: `Weather MCP Server (Cloudflare Workers Edition)

This server provides weather information using the Open-Meteo API.

Available Tools:
1. get-current-weather - Get current weather for any city
2. get-forecast - Get weather forecast for 1-7 days

Data Source: Open-Meteo (https://open-meteo.com/)
- Free weather API with no authentication required
- Provides current conditions and forecasts
- Data updated regularly from meteorological services

Example Usage:
- "What's the weather in London?"
- "Get me a 5-day forecast for Tokyo"
- "What's the current temperature in New York?"

Deployment: Cloudflare Workers (Global Edge Network)
- Low latency worldwide
- Automatic scaling
- Highly available`,
      },
    ],
  })
);

Claude can read this resource to understand what the server does and how to use it. It's optional but helpful for more complex servers.

Cloudflare Workers integration

Now we need to make this work as a Cloudflare Worker. The agents package provides a helper that wraps our MCP server with HTTP transport:

const mcpHandler = createMcpHandler(server, {
  route: "/mcp",
});

This creates a request handler that speaks the MCP protocol over HTTP. Claude will POST to this endpoint with JSON-RPC requests.

Finally, export the Worker fetch handler:

export default {
  async fetch(request: Request, env: any, ctx: any): Promise<Response> {
    const url = new URL(request.url);

    // Handle MCP requests
    if (url.pathname === "/mcp") {
      return mcpHandler(request, env, ctx);
    }

    // Health check endpoint
    if (url.pathname === "/health") {
      return new Response(
        JSON.stringify({
          status: "healthy",
          server: "weather-mcp-server",
          version: "1.0.0",
          endpoint: "/mcp",
        }),
        {
          headers: { "Content-Type": "application/json" },
        }
      );
    }

    // Root endpoint with information
    if (url.pathname === "/") {
      return new Response(
        `Weather MCP Server - Cloudflare Workers

Available Endpoints:
  POST /mcp     - MCP endpoint
  GET  /health  - Health check

To connect with Claude Desktop or other MCP clients, use the /mcp endpoint.

Example configuration:
{
  "mcpServers": {
    "weather": {
      "url": "https://your-worker.your-subdomain.workers.dev/mcp"
    }
  }
}

Documentation: https://modelcontextprotocol.io/
Source: https://github.com/cloudflare/agents
`,
        {
          headers: { "Content-Type": "text/plain" },
        }
      );
    }

    return new Response("Not Found", { status: 404 });
  },
};

We're setting up three routes:

• /mcp - The actual MCP endpoint
• /health - Health check for monitoring
• / - Documentation and usage info

This makes it easy to verify the server is running and see how to connect to it.

Deploying to Cloudflare Workers

If you haven't already, authenticate with Cloudflare:

wrangler login

This will open your browser and ask you to log in. Once you're done, deploy:

npm run deploy

Wrangler will bundle your code and push it to Cloudflare's edge network. You'll get a URL like https://weather-mcp-server.your-subdomain.workers.dev.

Visit that URL in your browser and you should see the documentation page. Try https://your-worker-url/health to verify it's working.

Using with Claude Desktop

Now for the fun part - connecting it to Claude.

On macOS, Claude Desktop's config file is at:

~/Library/Application Support/Claude/claude_desktop_config.json

On Windows, it's at:

%APPDATA%\Claude\claude_desktop_config.json

Open that file (create it if it doesn't exist) and add your weather server:

{
  "mcpServers": {
    "weather": {
      "url": "https://weather-mcp-server.your-subdomain.workers.dev/mcp"
    }
  }
}

Replace your-subdomain with your actual Cloudflare Workers subdomain.

Restart Claude Desktop. You should see a little hammer icon indicating tools are available. Now you can ask:

• "What's the weather like in Tokyo?"
• "Give me a 5-day forecast for London"
• "What's the current temperature in San Francisco?"

Claude will call your weather tools, get the data, and format it into a natural response. You've just extended Claude with live weather data, running on Cloudflare's global network.

Why Cloudflare Workers

You might wonder why we're using Workers instead of running this locally. A few reasons:

Always available - Your MCP server is up 24/7, not just when your laptop is on. This matters if you're using Claude Desktop across multiple machines or sharing the server with others.

Global edge network - Cloudflare runs in 200+ locations worldwide. Requests are handled by the nearest datacenter, so weather queries are fast no matter where you are.

Automatic scaling - If you build something popular (or give the URL to your team), it'll handle the traffic without you doing anything. Workers scale from zero to millions of requests automatically.

Free tier is generous - 100,000 requests per day free. For a personal MCP server, that's effectively unlimited.

Stateless and simple - No databases to manage, no servers to patch, no Docker containers to maintain. It's just code that runs when needed.

Addendum: Running locally

For development, you can run the server locally with Wrangler's dev mode:

npm run dev

This starts a local server at http://localhost:8787. You can test the endpoints:

curl http://localhost:8787/health

To use it with Claude Desktop, update your config to point to localhost:

{
  "mcpServers": {
    "weather": {
      "url": "http://localhost:8787/mcp"
    }
  }
}

Restart Claude Desktop and it'll connect to your local server instead. This is useful for testing changes before deploying.

The nice thing about MCP over HTTP is you can switch between local and deployed just by changing the URL. When you're ready to go live, deploy to Workers and update the config. No code changes needed.

What's next

This is a basic weather server, but it shows the pattern for building MCP servers on Cloudflare Workers. You could extend it with:

• More weather data (UV index, air quality, hourly forecasts)
• Multiple weather sources (compare forecasts from different APIs)
• Historical weather data
• Weather alerts and warnings
• Caching to reduce API calls

The same pattern works for other kinds of data too. Want to give Claude access to your company's internal APIs? Want to build tools that read from databases or call external services? MCP servers on Workers are a solid foundation.

The combination of MCP's protocol, Cloudflare's agents package, and Workers' edge deployment makes it surprisingly straightforward to extend Claude with whatever capabilities you need. And unlike browser extensions or API wrappers, MCP servers work across all MCP clients - not just Claude Desktop.

Now go build something useful and tell Claude what the weather's like.

The workers-og package makes this surprisingly straightforward. It's inspired by Vercel's @vercel/og but designed specifically for Cloudflare Workers, handling WASM bundling differently so it actually works on Cloudflare's edge runtime.

What you'll need

Before you start, make sure you have Node.js and npm installed. That's pretty much it.

Setting up Wrangler

Wrangler is Cloudflare's command-line tool for working with Workers. Install it globally:

npm install -g wrangler

Then authenticate with your Cloudflare account:

wrangler login

This will open your browser and ask you to log in. Once you're done, you're ready to create a Worker.

Creating your Worker

Create a new Worker project:

wrangler init my-og-image-worker

This will walk you through a few setup questions.

Choose Hello World > Worker only > TypeScript.

Once that's done, navigate into your project and install workers-og:

cd my-og-image-worker
npm install workers-og

Writing the Worker

Open up your src/index.ts and replace the contents with this:

import { ImageResponse } from 'workers-og'

export default {
  async fetch(request: Request): Promise<Response> {
    const url = new URL(request.url)
    const title = url.searchParams.get('title') || 'Hello World'

    const html = `
      <div style="display: flex; flex-direction: column; align-items: center; justify-content: center; height: 630px; width: 1200px; font-family: sans-serif; background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);">
        <h1 style="font-size: 60px; font-weight: bold; margin: 0; color: white; padding: 40px; text-align: center;">
          ${title}
        </h1>
      </div>
    `

    return new ImageResponse(html, {
      width: 1200,
      height: 630,
    })
  },
}

That's it. The ImageResponse class takes your HTML and turns it into a PNG image. The dimensions (1200x630) are the standard size for Open Graph images, which is what shows up when you share a link on social media.

Testing locally

Run the development server:

wrangler dev

This will start a local server, usually at http://localhost:8787. Open that in your browser and you should see your generated image. Try adding ?title=Your Text Here to the URL to see it change.

The HTML you pass to ImageResponse gets parsed using Cloudflare's HTMLRewriter API, so you can use standard HTML and inline styles. It's not a full browser, so keep your styling simple - think flexbox and basic CSS properties.

Deploying

When you're ready to deploy, it's just:

wrangler deploy

Your Worker will be live on Cloudflare's edge network. You'll get a URL like https://my-og-image-worker.YOUR_SUBDOMAIN.workers.dev that you can use anywhere.

Making it more useful

The real power comes from making these images dynamic. You can pull in data from query parameters, fetch content from your site, or even grab data from a database.

Here's a slightly fancier example that uses multiple parameters:

import { ImageResponse } from 'workers-og'

export default {
  async fetch(request: Request): Promise<Response> {
    const url = new URL(request.url)
    const title = url.searchParams.get('title') || 'Hello World'
    const subtitle = url.searchParams.get('subtitle') || ''
    const theme = url.searchParams.get('theme') || 'purple'

    const gradients = {
      purple: 'linear-gradient(135deg, #667eea 0%, #764ba2 100%)',
      blue: 'linear-gradient(135deg, #0093E9 0%, #80D0C7 100%)',
      orange: 'linear-gradient(135deg, #FA8BFF 0%, #2BD2FF 50%, #2BFF88 100%)',
    }

    const html = `
      <div style="display: flex; flex-direction: column; align-items: center; justify-content: center; height: 100%; width: 100%; font-family: sans-serif; background: ${gradients[theme] || gradients.purple}">
        <h1 style="font-size: 60px; font-weight: bold; margin: 0; color: white; padding: 40px 80px 20px; text-align: center;">
          ${title}
        </h1>
        ${subtitle ? `<p style="font-size: 30px; color: white; opacity: 0.9; margin: 0; padding: 0 80px;">${subtitle}</p>` : ''}
      </div>
    `

    return new ImageResponse(html, {
      width: 1200,
      height: 630,
    })
  },
}

Now you can customize the output with URLs like:

• ?title=My Post&subtitle=A short description&theme=blue
• ?title=Another Post&theme=orange

A few notes

The workers-og library uses Satori under the hood for rendering, which means it's converting your HTML and CSS into an image without needing a browser. This is what makes it fast enough to run on the edge.

One thing to watch out for - not all CSS properties are supported. Stick to flexbox layouts, basic colors, and standard fonts. If you need custom fonts, you'll need to fetch them and pass them to the ImageResponse options, which I won't get into here but is covered in the workers-og documentation.

Also, because this is running on every request, you might want to think about caching. Cloudflare Workers have built-in caching support, or you could generate images at build time and serve them statically if they don't need to be dynamic.

Why this is useful

I use these for automatically generating social card images for blog posts. Instead of manually creating an image in Figma for every post, I can just point to a URL like /og-image?title=Post Title and get a consistent, on-brand image every time.

It's also handy for user-generated content. If you're building something where users create pages or profiles, you can generate unique social cards for each one without storing thousands of image files.

The whole thing runs on Cloudflare's edge network, so it's fast no matter where your visitors are, and you're only charged for the compute time when someone actually requests an image. Good times all round.

Getting it running

The setup is refreshingly simple. Just grab the package that matches your environment:

# For React projects
npm i @paper-design/shaders-react

# For vanilla JavaScript
npm i @paper-design/shaders

Examples that actually work

Let me show you a couple of ways I've been using Paper Shaders:

React: Animated mesh gradient

This one creates a flowing, organic background effect that works great for hero sections.

Here's what that looks like in action:

import { MeshGradient } from '@paper-design/shaders-react' // ^0.0.55

export default function App() {
  return (
    <div className="relative h-full">
      <MeshGradient
        colors={['#5100ff', '#00ff80', '#ffcc00', '#ea00ff']}
        distortion={1}
        swirl={0.8}
        speed={0.2}
        height='100%'
      />
      <div className="absolute inset-0 flex items-center justify-center">
        👋
      </div>
    </div>
  )
}

Vanilla JavaScript: Custom shader effect

For non-React projects, the vanilla JavaScript approach is just as straightforward:

import { createShader } from '@paper-design/shaders'

const canvas = document.querySelector('#shader-canvas')
const shader = createShader(canvas, {
  type: 'dithering',
  colors: ['#ff6b6b', '#4ecdc4', '#45b7d1'],
  intensity: 0.5,
  speed: 0.1
})

// Start the animation
shader.start()

The library comes with various shader effects - mesh gradients, dithering, dot orbit, warp effects, and more. Each one lets you tweak settings through props or configuration objects, so you can dial in exactly the look you're after.

Why I think you'll like it

Paper Shaders hits that sweet spot I'm always looking for - powerful enough for real work but simple enough that I can mess around with it on a weekend without getting bogged down in setup. The zero-dependency approach means you're not taking on technical debt, and the performance focus means your effects won't turn someone's phone into a space heater.

If you want to check it out, the documentation and examples at shaders.paper.design are pretty solid, and you can poke around the GitHub repository to see what's under the hood.

So I spent some time digging deeper into what's actually happening under the hood. If you're working with Claude Code, you can run /context to get something like this:

/context
  ⎿  ⛁ ⛀ ⛁ ⛁ ⛁ ⛁ ⛁ ⛁ ⛀ ⛀
     ⛀ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶   Context Usage
     ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶   claude-sonnet-4-20250514 • 17k/200k tokens (8%)
     ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶
     ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶   ⛁ System prompt: 3.2k tokens (1.6%)
     ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶   ⛁ System tools: 11.6k tokens (5.8%)
     ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶   ⛁ Custom agents: 69 tokens (0.0%)
     ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶   ⛁ Memory files: 743 tokens (0.4%)
     ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶   ⛁ Messages: 1.2k tokens (0.6%)
     ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶   ⛶ Free space: 183.3k (91.6%)

But what does all this actually mean? Let's break it down.

What is a context window?

A context window is basically the AI's working memory. An AI model can only process a finite amount of information at any given time, and this limit is measured in tokens - roughly equivalent to words, though punctuation and code symbols count too.

In the example above, Claude Sonnet 4 has a 200,000 token context window, and we're currently using 17,000 tokens (8% of the total capacity).

What's taking up space?

The context breakdown shows exactly where those tokens are going, using our example from above:

System Prompt (3.2k tokens)

This is Claude Code's "personality" - the instructions that tell Claude how to behave, what tools it has access to, and how to help with coding tasks. Think of it as the foundational rules that define how Claude operates.

System Tools (11.6k tokens)

These are all the functions Claude can use - reading files, running bash commands, searching through code, making git commits, and more. Each tool has a detailed internal specifications about what it does and how Claude can use it properly.

Custom Agents (69 tokens)

These are specialized sub-agents that can be launched for specific tasks like code review or complex multi-step operations. In this case, there aren't many loaded, hence the small token count. You can create your own custom agents by adding them to (.claude/agents/agent-name.md).

Memory Files (743 tokens)

This includes project-specific instructions like your CLAUDE.md file, which tells Claude about your project structure, development commands, and coding conventions. It's how Claude knows to run npm run dev instead of trying random commands and hoping for the best.

Messages (1.2k tokens)

The actual conversation - your questions, Claude's responses, and any code or file contents that have been discussed.

Why context windows matter

Once you understand how context works, a lot of Claude's behavior starts making sense:

Why Claude sometimes uses agents

When searching through large codebases, Claude might launch a specialized search agent rather than loading dozens of files into the main context. This keeps the context window clean and efficient.

Why Claude reads files strategically

Claude doesn't read every file in your project at once. Instead, it reads what's relevant to the current task, keeping context usage manageable.

Why conversations have limits

Eventually, if you have a very long conversation with lots of code, you'll approach that 200k token limit. When that happens, earlier parts of the conversation might get compressed or forgotten.

Why project memory matters

Files like CLAUDE.md stay loaded throughout the entire session, so Claude always knows your project's specific setup without having to rediscover it each time.

Making the most of context

Here are some tips to work effectively within context constraints:

• Be specific about what you need - instead of "fix my app," try "fix the authentication bug in UserService.ts"
• Use project memory - keep important project info in CLAUDE.md so it's always available
• Break down large tasks - if you're refactoring a huge feature, tackle it piece by piece
• Trust the agents - when Claude launches specialized agents for complex searches or tasks, it's to keep the main conversation context focused

Context windows are one of those invisible infrastructure pieces that make AI coding assistants work. Understanding how they function can help you work more effectively with Claude Code, and ultimately, get stuff done.

I used Replicate as a jumping off point, exploring models, learning their open-source tool Cog, and eventually contructing an offline pipeline to generate the final videos that made up the project.

When I finished it, I sent them a bit of a love letter to say thanks for making cool stuff.

And I got this back.

Anyway, in related news, I'm joining Replicate as a staff designer. Happy days. Here's to side projects and love letters.

😊

My site, charliegleason.com is built in Remix, and it's open-source. Which makes putting case studies about my work on enterprise software tricky.

I was talking to Glen Maddern, and he mentioned that given it's being deployed on Cloudflare Pages, I could just wrap the public site in a private repo and add the protected routes that way. Genius.

How does it work?

There's a couple of gotchas with this approach, but it's relatively straightforward.

• Create a new project with npm init
• Set up a folder structure that matches the repo you're going to be injecting these private routes into
• Install your public Remix site's GitHub repo as an NPM dependency with
  npm install git://github.com/USER_NAME/REPO_NAME.git#branch
  (usually main)
• Create a .dev.vars file in your private repo to manage any environment variables if you have them
• Use concurrently and sync-directory to sync your files to the node_modules/REPO_NAME, where repo is the name of your repository

You can see the package.json I use for this below:

{
  "name": "auth.charliegleason.com",
  "version": "1.0.0",
  "main": "index.js",
  "scripts": {
    "dev": "concurrently \"npm run sync:watch\" \"npm --prefix node_modules/charliegleason.com run dev\"",
    "postinstall": "npm run sync && npm --prefix node_modules/charliegleason.com install && cp .dev.vars node_modules/charliegleason.com",
    "sync": "npm run sync:files:routes && npm run sync:files:assets && npm run sync:files:data",
    "sync:watch": "concurrently \"npm run sync:files:routes -- -w\" \"npm run sync:files:assets -- -w\" \"npm run sync:files:data -- -w\"",
    "sync:files:routes": "syncdir routes node_modules/charliegleason.com/app/routes --exclude .DS_Store",
    "sync:files:data": "syncdir app/data node_modules/charliegleason.com/app/data --exclude .DS_Store",
    "sync:files:assets": "syncdir public node_modules/charliegleason.com/public --exclude .DS_Store",
    "update": "npm install git://github.com/superhighfives/charliegleason.com.git#main && npm install"
  },
  "dependencies": {
    "charliegleason.com": "github:superhighfives/charliegleason.com#main",
    "concurrently": "^8.2.2",
    "sync-directory": "^6.0.5"
  }
}

Breaking it down

So, what does each of these scripts actually do? Let's go through step-by-step.

npm run dev

Start watching files, and sync when they change. Start the dev server.

concurrently \"npm run sync:watch\" \"npm --prefix node_modules/charliegleason.com run dev\""

npm run postinstall

Run the initial sync, install the dependencies for the public repo, and copy your local .dev.vars into it.

npm run sync && npm --prefix node_modules/charliegleason.com install && cp .dev.vars node_modules/charliegleason.com"

npm run sync

Sync your various files, but don't worry about doing it concurrently.

npm run sync:files:routes && npm run sync:files:assets && npm run sync:files:data

npm run sync:watch

Sync your various files, but this time, also watch them. (There's probably a more succinct way of doing this, but it's for a personal project, so.)

concurrently \"npm run sync:files:routes -- -w\" \"npm run sync:files:assets -- -w\" \"npm run sync:files:data -- -w\"

npm run sync:files:routes,data,assets

For each directory you want to sync, add syncdir PRIVATE_REPO_FOLDER PUBLIC_REPO_FOLDER. I ran into some issues with .DS_Store files getting copied over on Mac and causing mayhem, so I excluded them.

syncdir routes node_modules/charliegleason.com/app/routes --exclude .DS_Store

npm run update

Force an update for the public repo if you run into any weirdness with stuff not updating. Not strictly necessary, but I came across it a couple times.

npm install git://github.com/superhighfives/charliegleason.com.git#main && npm install

One of the nice little features of this setup is that you can easily work on the public and private stuff at the same time. Because it's all just package.json under the hook, you can take advantage of npm link. Let's say we've got two repos, charliegleason.com and a private repo. You can jump into the ~/Development/charliegleason.com repo and run npm link. Then jump into the private repo and run npm link "charliegleason.com". Boom. Magic. ✨

The only thing to watch our for here is that your private files will end up inside your public repo locally, so just make sure you don't commit anything on the public side that you don't want to.

Deployment

When you're ready to deploy your site, you'll need to set up a new Cloudflare Pages project on the Cloudlare dashboard.

Navigate to Workers & Pages > Create Application > Pages > Connect to Git.

Use the following settings:

Build command

npm --prefix node_modules/REPO_NAME run build && ln -s node_modules/REPO_NAME/functions functions

[!NOTE]
You'll need to update the REPO_NAME with the name of your repo. In the example screenshot, the repo is charliegleason.com.

This will build your public repo on Cloudflare, and create a symbolic link of your functions directory to the root, where Cloudflare expects it.

Build output directory

node_modules/REPO_NAME/public

[!NOTE]
Again, update the repo name.

On deploy, Cloudflare will run the postinstall script inside your package.json, handling the syncing of assets and routes you defined earlier. It'll then build the public repo with the private assets and routes.

And just like that, you'll be serving your private routes alongside your public ones. Everyone wins!

I'm hosting the site on Cloudflare Pages, which makes it super fast at the edge™. I installed the Satori WASM requirements, added Resvg to save it as a PNG, and then assumed the pose of a man awaiting success.

I got a lot of errors.

It turns out, Vite handles WASM files in a specific way, and Cloudflare expects WASM files in a certain way. The result was a weekend spent noodling on regular expressions. And a library that will do it for you.

👉 vite-plugin-wasm-module-workers

It will, in essence, take this:

import satori, { init as initSatori } from 'satori/wasm'
import { Resvg, initWasm as initResvg } from '@resvg/resvg-wasm'
import initYoga from 'yoga-wasm-web'

import YOGA_WASM from 'yoga-wasm-web/dist/yoga.wasm?url'
import RESVG_WASM from '@resvg/resvg-wasm/index_bg.wasm?url'
Then, in our default function:

export async function createOGImage(title: string, requestUrl: string) {
const { default: resvgwasm } = await import(
/_ @vite-ignore _/ `${RESVG_WASM}?module`
)
const { default: yogawasm } = await import(
/_ @vite-ignore _/ `${YOGA_WASM}?module`
)

  try {
    if (!initialised) {
      await initResvg(resvgwasm)
      await initSatori(await initYoga(yogawasm))
      initialised = true
    }
  } catch (e) {
    initialised = true
  }

  // more fancy code

And turn it into this, on build:

import YOGA_WASM from './assets/yoga-CP4IUfLV.wasm'
import RESVG_WASM from './assets/index_bg-Blvrv-U2.wasm'
let initialised = false

async function createOGImage(title, requestUrl) {
  const resvgwasm = RESVG_WASM
  const yogawasm = YOGA_WASM
  try {
    if (!initialised) {
      await initWasm(resvgwasm)
      await init(await initYoga(yogawasm))
      initialised = true
    }
  } catch (e) {
    initialised = true
  }

  // more fancy build code

Who are you, and what do you do?

I'm Charlie Gleason, a designer, developer, and musician. I push around pencils and pixels at

What hardware do you use?

For most things, I use my trusty Intel MacBook Pro, the last of its kind, which I spent a silly amount of money on during the pandemic right before Apple announced an entirely new architecture. Good times all round in 2020.

I use an Apple Studio Display, a wireless Magic Keyboard with a number pad, and a Magic Mouse.

When doing 3D modelling I use a Logitech G502 wireless mouse because 3D modelling is a lot easier with three buttons and a scroll wheel. I also lose the wireless dongle once a week, and it drives me bananas.

For all things AI and machine learning, I have a Teenager Engineering designed Computer-1 case in day-glo orange, housing an AMD Ryzen 9 3900X with an Nvidia 3060, running Ubuntu. I use Tailscale to make managing my home network easier.

For ideation and design stuff, I tend to sketch ideas out with a pen and paper. (Actually, that's a lie. That's pretty rare. I think I'm faster in Figma than I am at actually drawing things out, and it's infinitely more malleable. So I usally just throw boxes in Figma.)

For music I use a whole ton of bits and pieces I've collected over the years. The key pieces, beyond my laptop, are Ableton's Push 3, Focusrite's Scarlett 2i2, and a Radial DI and microphone splitter. I spend a lot of time trying not to buy an OP-1 Field or an Elektron Digitone. Also, I love Radial Engineering—their stuff could fall out of a plane and it would still work.

And what software?

For design I use Figma, as mentioned. For development, VS Code. The real secret sauce for development is the Operator Mono font, though. It's really pretty.

Oh, I also recently moved from Chrome to Arc, which has some really interesting ideas around the browser and managing tabs.

For terminal stuff, I use oh-my-zsh, powerlevel10k, and a bunch of utilities like zfz and bat.

For backups and moving files around rclone is great. The feature set alone is proof of the power of open-source.

For notes, I use VSCode or IA Writer, but I've previously loved using Bear.

For music I use Ableton with Fabfilter's creative plugins. I love the design of Fabfilter. It has a super clean, clear UI, which is beyond a rarity for software plugins.

What would be your dream setup?

The older I get the more I've realised that the amount of stuff you have doesn't really correlate to your level of personal happiness. And technology changes so rapidly that whatever your dream is, it'll be superseded in a year anyway.

So I think my dream setup is whatever I have right now, that generally meets my needs. In life, as in product design, perfect is the enemy of good. If it works well, then the rest is just gravy.

I'm a designer and developer who loves the intersection of creativity and code. This site is where I share technical implementations, creative coding experiments, and the occasional tool or resource I've found useful.

You'll find posts about things like generating OG images with Satori, building authentication patterns in Remix, and the value of side projects. Most posts include working code examples, links to demos, and reflections on what worked (and what didn't).

The site itself is open-source and built with React Router 7, Cloudflare Workers, and a bunch of other bits and pieces. You can find the source code on GitHub, and you can subscribe via RSS to get updates when I publish something new.