Forem: teaganga

Using Docker Compose Profiles to unit tests part of the application

teaganga — Fri, 20 Feb 2026 09:26:10 +0000

Compose profiles let you group services so you can start only a subset of your stack for specific scenarios (e.g., lightweight testing vs. full production).

In your docker-compose.yml, add a profiles list to each service you want to group:

services:
  postgres:
    profiles: ["core"]
    ...

  jobrunner:
    profiles: ["core"]

  nextjs:
    profiles: ["full"]

  authserver:
    profiles: ["full"]

How it works

docker compose up (no --profile)
Starts only services without a profiles key.
In the example above, nothing would start unless you define a default (non-profiled) service.
docker compose --profile core up
Starts only services tagged with core (postgres, jobrunner).
Ideal for a lightweight testing stack.
docker compose --profile full up
Starts only services tagged with full (nextjs, authserver).
Multiple profiles are supported:

  docker compose --profile core --profile full up

This allows you to maintain one Compose file while running minimal stacks for testing or the full environment as needed.

If a service should always run, omit the profiles key. It will start regardless of profile flags.

Multiple Databases and Profiles

Docker Compose does not allow multiple services with the same name—even across different profiles.

If you need both a production database and a unit test database, give them unique service names and assign each to its own profile:

services:
  app-db:
    profiles: ["prod"]

  unit-test-db:
    profiles: ["test"]

Database Configuration Strategy

Your application containers use one DATABASE_URL at a time.
Each profile startup determines which database the app connects to.
For example:
- In a test profile, set DATABASE_URL to unit-test-db.
- In a prod profile, set DATABASE_URL to app-db.

There is no runtime toggling — each profile spin-up decides which database your app connects to based on the environment variables provided at startup.

Alternative Approach

Instead of profiles, you can maintain separate Compose files:

docker-compose.test.yml
docker-compose.prod.yml

Each file can hardcode the correct database host.

This provides clearer separation but requires maintaining multiple files.

Concrete Example with `unit-test-db` and `app-db`

Below is a clean, complete working example.

1️⃣ `docker-compose.yml`

services:
  # -----------------
  # Databases
  # -----------------

  unit-test-db:
    image: postgres:15
    container_name: unit-test-db
    profiles: ["test"]
    environment:
      POSTGRES_USER: test
      POSTGRES_PASSWORD: test
      POSTGRES_DB: testdb
    ports:
      - "5433:5432"

  app-db:
    image: postgres:15
    container_name: app-db
    profiles: ["prod"]
    environment:
      POSTGRES_USER: prod
      POSTGRES_PASSWORD: prod
      POSTGRES_DB: proddb
    ports:
      - "5432:5432"

  # -----------------
  # Application
  # -----------------

  app:
    build: .
    depends_on:
      - unit-test-db
      - app-db
    environment:
      DATABASE_URL: ${DATABASE_URL}

2️⃣ What `DATABASE_URL` Should Look Like

Inside Docker, the hostname is the service name.

Test profile → connect to `unit-test-db`

postgresql://test:test@unit-test-db:5432/testdb

Prod profile → connect to `app-db`

postgresql://prod:prod@app-db:5432/proddb

3️⃣ Running with Different Environment Variable Sets

✅ Option A — Use Separate `.env` Files (Recommended)

`.env.test`

DATABASE_URL=postgresql://test:test@unit-test-db:5432/testdb

`.env.prod`

DATABASE_URL=postgresql://prod:prod@app-db:5432/proddb

Start test stack

docker compose --profile test --env-file .env.test up

Start prod stack

docker compose --profile prod --env-file .env.prod up

This is the cleanest and most maintainable approach.

✅ Option B — Inline Environment Variables

Test

DATABASE_URL=postgresql://test:test@unit-test-db:5432/testdb \
docker compose --profile test up

Prod

DATABASE_URL=postgresql://prod:prod@app-db:5432/proddb \
docker compose --profile prod up

4️⃣ What Actually Starts

When you run:

docker compose --profile test up

Only:

unit-test-db
app

will start.

When you run:

docker compose --profile prod up

Only:

app-db
app

will start.

Clean Mental Model

Profile	DB Container	DATABASE_URL host
test	unit-test-db	unit-test-db
prod	app-db	app-db

The service name becomes the DNS hostname inside Docker’s network.

Each profile launch defines:

Which database container runs
Which DATABASE_URL your app uses

There is no live switching — environment selection happens at startup.

How to Add Vitest to a Cloudflare Worker Project (TypeScript)

teaganga — Sun, 25 Jan 2026 08:02:06 +0000

Cloudflare Workers are fast, lightweight, and TypeScript-friendly — but testing them often feels confusing at first.
This guide walks through adding Vitest to an existing Cloudflare Worker project, explains why each step exists, and clears up common confusions (like jsdom, coverage packages, and where tests should live).

By the end, you’ll have:

Vitest running cleanly
A sensible folder structure
Zero unnecessary dependencies
A setup that fits Cloudflare Workers (not browsers)

Starting Point: Existing Worker Project

Assume your project looks like this:

.
├── package.json
├── package-lock.json
├── public/
│   └── index.html
├── src/
│   └── index.ts
├── tsconfig.json
├── worker-configuration.d.ts
└── wrangler.jsonc

This is a TypeScript Cloudflare Worker, likely using Wrangler.

Why Vitest?

Vitest is a modern test runner built on Vite. It’s a great fit because:

TypeScript works out of the box
Very fast startup and watch mode
Jest-style API (describe, it, expect)
Minimal configuration
Works cleanly with Worker / Node-style environments

For new TypeScript projects, Vitest is usually the best choice.

Step 1: Install Vitest (and Only What You Need)

Run this once:

npm install -D vitest @vitest/coverage-v8

What this actually installs

vitest
The test runner itself. This is required.
@vitest/coverage-v8
Optional but useful. It enables code-coverage reporting using V8’s native engine.

Both are installed as dev dependencies (-D) because:

tests run locally or in CI
they are never deployed to Cloudflare

❌ What you do not need

You might see advice to install jsdom.
Do not install it for Cloudflare Workers.

Workers:

do not have document or window
are not browser environments

So skip:

npm install -D jsdom   ❌

Step 2: Add a Vitest Config

Create vitest.config.ts at the project root:

import { defineConfig } from 'vitest/config'

export default defineConfig({
  test: {
    environment: 'node'
  }
})

Why `environment: 'node'`?

Cloudflare Workers behave much closer to Node-style runtimes than browsers.

No DOM
No window
No document

Using node avoids fake browser APIs and keeps tests honest.

Step 3: Add Test Scripts

Update package.json:

{
  "scripts": {
    "test": "vitest",
    "test:run": "vitest run",
    "test:coverage": "vitest run --coverage"
  }
}

When to use which

npm test → watch mode (great during development)
npm run test:run → one-off run (CI-friendly)
npm run test:coverage → generates coverage stats

Step 4: Where Should Tests Live?

Put tests inside src/, next to the code they test.

Recommended structure

src/
├── index.ts
├── index.test.ts

As the project grows:

src/
├── handlers/
│   ├── auth.ts
│   └── auth.test.ts
├── utils/
│   ├── math.ts
│   └── math.test.ts

Why this works best

Tests stay close to the code
Imports are simple (./index)
Easy to refactor
Vitest finds these files automatically

Vitest already looks for:

**/*.test.ts
**/*.spec.ts

No extra configuration needed.

Step 5: Example Test

`src/index.ts`

export function add(a: number, b: number) {
  return a + b
}

`src/index.test.ts`

import { describe, it, expect } from 'vitest'
import { add } from './index'

describe('add', () => {
  it('adds two numbers', () => {
    expect(add(2, 3)).toBe(5)
  })
})

Run it:

npm test

Or once:

npx vitest run

Step 6: Make Sure Tests Aren’t Deployed

Ensure your tsconfig.json excludes test files:

{
  "include": ["src/**/*.ts"],
  "exclude": ["src/**/*.test.ts", "src/**/*.spec.ts"]
}

This guarantees:

test files are never bundled
Workers stay lean

Summary

✅ Use Vitest for Cloudflare Workers
✅ Install vitest (coverage optional)
❌ Do not install jsdom
📁 Put tests inside src/
⚙️ Use environment: 'node'
🚀 You’re production-ready and CI-friendly

This setup is minimal, modern, and scales cleanly as your Worker grows.

Debugging Cloudflare Workers with VS Code: Queue Handlers Edition (Part 4)

teaganga — Wed, 10 Dec 2025 13:47:55 +0000

In Part 3, I showed you how to test queues, cron, and HTTP handlers locally. But here's the question I kept asking: can I actually debug this stuff with breakpoints?

Short answer: Yes, absolutely. And it works better than I expected.

Let me show you how to set it up.

The Setup: VS Code + Wrangler Dev + Debugger

When you run wrangler dev, it starts a Node.js process that runs your Worker. VS Code's debugger can attach to that process, which means you can:

✅ Set breakpoints in your queue() handler
✅ Set breakpoints in your scheduled() handler
✅ Set breakpoints in your fetch() handler
✅ Inspect variables, step through code, everything

Here's how to set it up.

Step 1: Run Wrangler in Debug Mode

Start Wrangler with the inspect flag:

wrangler dev --remote=false --inspect

Important flags:

--remote=false - runs locally (not in Cloudflare's dev environment)
--inspect - enables the Node.js debugger on port 9229

You should see output like:

Debugger listening on ws://127.0.0.1:9229/...
For help, see: https://nodejs.org/en/docs/inspector
⎔ Starting local server...
[wrangler:inf] Ready on http://localhost:8787

That Debugger listening line means you're good to go.

Step 2: Configure VS Code

Create or update .vscode/launch.json in your project:

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Attach to Wrangler",
      "type": "node",
      "request": "attach",
      "port": 9229,
      "skipFiles": ["<node_internals>/**"],
      "sourceMaps": true,
      "resolveSourceMapLocations": [
        "${workspaceFolder}/**",
        "!**/node_modules/**"
      ]
    }
  ]
}

What this does:

Attaches VS Code's debugger to the Wrangler process
Skips Node.js internal files (you don't want to debug Node itself)
Enables source maps so breakpoints work with TypeScript

Step 3: Start Debugging

Run Wrangler in a terminal:

   wrangler dev --remote=false --inspect

Open VS Code's Debug panel (Cmd+Shift+D on Mac, Ctrl+Shift+D on Windows)
Select "Attach to Wrangler" from the dropdown
Press the green play button (or press F5)

You should see "Debugger attached" in your terminal, and VS Code's debug toolbar appears.

Step 4: Set Breakpoints and Trigger Queue Messages

Now the magic happens. Let's debug a queue handler:

// src/index.ts
export default {
  async queue(batch, env, ctx) {
    console.log(`[queue] Received ${batch.messages.length} messages`);

    for (const message of batch.messages) {
      // 👈 Set a breakpoint on this line
      const { type, data } = message.body;

      console.log(`[queue] Processing ${type}`);

      // 👈 And another one here
      await processJob(env, data);

      message.ack();
    }
  }
};

Set breakpoints:

Click in the gutter (left of line numbers) in VS Code
A red dot appears - that's your breakpoint

Trigger a queue message:

wrangler queues send my-jobs '{"type": "test", "data": "hello"}'

🎉 Your breakpoint hits!

VS Code pauses execution, and you can:

Inspect message.body
Check the value of env bindings
Step through the code line by line
See the call stack

This is incredibly useful for debugging complex queue logic.

Debugging All Three Handler Types

HTTP Handlers (`fetch`)

Set a breakpoint in your fetch handler:

export default {
  async fetch(request, env, ctx) {
    const url = new URL(request.url);

    // 👈 Breakpoint here
    if (url.pathname === '/api/trigger') {
      await env.JOB_QUEUE.send({ type: 'manual' });
      return new Response('Queued');
    }
  }
};

Then hit the endpoint:

curl http://localhost:8787/api/trigger

The debugger pauses, and you can inspect the request object, headers, etc.

Scheduled Handlers (`scheduled`)

Set a breakpoint in your scheduled handler:

export default {
  async scheduled(event, env, ctx) {
    // 👈 Breakpoint here
    const time = new Date(event.scheduledTime);
    console.log('[scheduled] Running at', time);

    await env.JOB_QUEUE.send({ type: 'cron' });
  }
};

Trigger it by pressing s in the Wrangler terminal (or use the /__scheduled endpoint).

The debugger pauses, and you can see the event.scheduledTime value.

Queue Handlers (`queue`)

We already covered this above, but here's a more complex example:

export default {
  async queue(batch, env, ctx) {
    for (const message of batch.messages) {
      try {
        // 👈 Breakpoint here to inspect message structure
        const job = parseJobMessage(message.body);

        // 👈 Another breakpoint to step through processing
        await processJob(env, job);

        // 👈 Breakpoint to verify ack is called
        message.ack();

      } catch (error) {
        // 👈 Breakpoint to debug failures
        console.error('Job failed:', error);
        message.retry();
      }
    }
  }
};

Send messages:

wrangler queues send my-jobs '{"id": 1}'
wrangler queues send my-jobs '{"id": 2}'

You can step through each message in the batch and see exactly what's happening.

Advanced Debugging Techniques

1. Conditional Breakpoints

Right-click a breakpoint in VS Code → "Edit Breakpoint" → "Expression"

message.body.id === 42

Now the breakpoint only hits for messages with id: 42. Super useful when debugging batches.

2. Logpoints

Don't want to stop execution? Use a logpoint instead:

Right-click → "Add Logpoint"

Message {message.id} has data: {message.body}

This logs without pausing, like console.log but without modifying your code.

3. Watch Expressions

In VS Code's Debug panel, add Watch expressions:

message.attempts
env.DATABASE_URL
batch.messages.length

These update automatically as you step through code.

4. Debug Console

While paused, you can run code in the Debug Console:

// Check if a binding exists
> env.MY_QUEUE
Queue { ... }

// Inspect message body
> JSON.stringify(message.body, null, 2)
{
  "type": "test",
  "data": "hello"
}

// Test a function
> await parseJobMessage(message.body)
{ ... }

This is amazing for exploring objects and testing fixes without restarting.

Common Issues and Solutions

Issue 1: Breakpoints Show as Gray/Unverified

Problem: Source maps aren't working correctly.

Solution: Make sure your tsconfig.json has source maps enabled:

{
  "compilerOptions": {
    "sourceMap": true,
    "inlineSourceMap": false
  }
}

And restart both Wrangler and the VS Code debugger.

Issue 2: "Cannot connect to runtime process"

Problem: Wrangler isn't running with --inspect.

Solution: Make sure you started Wrangler with:

wrangler dev --remote=false --inspect

Issue 3: Debugger Disconnects After First Request

Problem: This can happen with certain Wrangler versions.

Solution: Use --persist-to to keep the Worker alive:

wrangler dev --remote=false --inspect --persist-to=.wrangler/state

Issue 4: Can't Debug External Dependencies

Problem: Breakpoints in node_modules don't work.

Solution: Remove this line from launch.json:

"skipFiles": ["<node_internals>/**"]

But be warned - you'll hit a LOT of Node.js internal breakpoints.

My Debugging Workflow

Here's how I debug a typical queue handler issue:

1. Reproduce the Issue Locally

# Terminal 1: Start Wrangler
wrangler dev --remote=false --inspect

# Terminal 2: Send problematic message
wrangler queues send my-jobs '{"id": 123, "type": "problematic"}'

2. Attach Debugger

Open VS Code
Press F5 to attach
Set breakpoints in the queue handler

3. Re-trigger

# Send the same message again
wrangler queues send my-jobs '{"id": 123, "type": "problematic"}'

Debugger hits, and I can step through to find the issue.

4. Test the Fix

Fix the code, save (Wrangler hot-reloads), trigger again:

wrangler queues send my-jobs '{"id": 123, "type": "problematic"}'

If it works, remove breakpoints and move on.

Pro Tips

Use Multiple Launch Configurations

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Attach to Wrangler (Local)",
      "type": "node",
      "request": "attach",
      "port": 9229
    },
    {
      "name": "Attach to Wrangler (Remote)",
      "type": "node",
      "request": "attach",
      "port": 9229,
      "localRoot": "${workspaceFolder}",
      "remoteRoot": "/tmp/worker"
    }
  ]
}

Switch between them based on whether you're using --remote=false or not.

Create a Debug Script

Add to package.json:

{
  "scripts": {
    "dev": "wrangler dev",
    "dev:debug": "wrangler dev --remote=false --inspect",
    "test:queue": "wrangler queues send my-jobs '{\"type\": \"test\"}'"
  }
}

Now you can just run:

npm run dev:debug

Use Debugger Statements

Sometimes I just add debugger; directly in the code:

async queue(batch, env, ctx) {
  for (const message of batch.messages) {
    if (message.body.id === 42) {
      debugger; // Automatic breakpoint when debugger is attached
    }

    await processJob(message.body);
    message.ack();
  }
}

This is faster than clicking around in VS Code when you know exactly where to break.

Debugging Production Issues Locally

Sometimes you get a failed message in production and want to replay it locally:

1. Get the Message from Your DLQ

# List messages in your dead letter queue
wrangler queues messages list my-jobs-dlq

# Copy the message body

2. Replay it Locally

# Paste the exact production message
wrangler queues send my-jobs '{"id": 123, "data": "..."}'

3. Debug With Real Data

Now you're debugging with the actual message that failed, which makes finding bugs way easier.

Performance Debugging

You can also profile your queue handlers:

export default {
  async queue(batch, env, ctx) {
    const start = performance.now();

    for (const message of batch.messages) {
      const jobStart = performance.now();

      await processJob(message.body);

      const jobTime = performance.now() - jobStart;
      console.log(`Job ${message.id} took ${jobTime}ms`);

      message.ack();
    }

    const totalTime = performance.now() - start;
    console.log(`Batch of ${batch.messages.length} took ${totalTime}ms`);
  }
};

Set a breakpoint after the loop and inspect totalTime to see if you're hitting performance issues.

Wrapping Up

Yes, you can absolutely debug queue handlers with VS Code.

In fact, you can debug all three handler types (HTTP, cron, queue) with full breakpoint support, variable inspection, and step-through debugging.

The setup is:

Run wrangler dev --remote=false --inspect
Configure VS Code's launch.json to attach on port 9229
Set breakpoints and trigger your handlers
Debug like any other Node.js app

This has completely changed how I develop Workers. I rarely use console.log debugging anymore because breakpoints are so much faster.

Questions? Drop them in the comments! What's your debugging workflow like?

Quick Reference

# Start Wrangler in debug mode
wrangler dev --remote=false --inspect

# Send test queue message
wrangler queues send my-jobs '{"test": true}'

# Trigger scheduled event
# Press 's' in Wrangler terminal

// .vscode/launch.json
{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Attach to Wrangler",
      "type": "node",
      "request": "attach",
      "port": 9229,
      "skipFiles": ["<node_internals>/**"]
    }
  ]
}

Happy debugging!

Testing Cloudflare Workers Locally: Queues, Cron, and HTTP (Part 3)

teaganga — Wed, 10 Dec 2025 13:28:27 +0000

In Part 1, I explained why Queues solve the long-running job problem. In Part 2, I showed you how to set up all three handler types.

Now let's talk about the part that tripped me up the most: how do you actually test this stuff locally?

I spent way too long trying to figure out if I needed to deploy to production just to test a queue message. Turns out, Wrangler has everything built-in—once you know how it works.

The Challenge: Three Different Handler Types

Your Worker now has three ways to get invoked:

HTTP requests → fetch() handler
Cron schedules → scheduled() handler
Queue messages → queue() handler

Each one needs to be tested differently because Cloudflare doesn't "magically fire" cron or queue events in dev mode. You have to manually trigger them.

Here's how I do it.

Step 1: Start Your Dev Server

First, get your Worker running locally:

wrangler dev

This starts:

✅ Your HTTP server (usually on localhost:8787)
✅ Your queue consumer (waiting for messages)
✅ Your scheduled handler (waiting for triggers)

Important: Wrangler creates a real local queue in memory. You don't need any external services or database. It's all built-in.

You should see something like:

⎔ Starting local server...
[wrangler:inf] Ready on http://localhost:8787

Step 2: Testing HTTP Handlers (Easy)

This is the straightforward one. Just hit your endpoints:

curl http://localhost:8787/api/status

Or open it in your browser:

http://localhost:8787/admin

Your fetch() handler runs exactly like it would in production. Nothing special needed.

Step 3: Testing Queue Handlers (The Tricky One)

Here's where it gets interesting. Your queue consumer is running, but it won't receive messages automatically. You have to send them manually.

Wrangler provides a CLI command for this:

wrangler queues send domain-jobs '{"type": "test-job", "data": "hello"}'

Replace domain-jobs with whatever your queue name is (from your wrangler.jsonc).

What happens:

The message goes into the local in-memory queue
Wrangler immediately delivers it to your queue() handler
You see the logs in your terminal

You should see output like:

[queue] Processing 1 messages
[queue] Starting job abc-123
[queue] Job complete!

Testing Batch Delivery

Want to test how your Worker handles multiple messages? Send several in quick succession:

wrangler queues send domain-jobs '{"id": 1}'
wrangler queues send domain-jobs '{"id": 2}'
wrangler queues send domain-jobs '{"id": 3}'

Depending on your max_batch_size and timing, Wrangler might deliver these as one batch:

[queue] Processing 3 messages

This lets you test your batching logic locally before deploying.

Step 4: Testing Scheduled Handlers (Cron)

Cron jobs don't fire automatically in dev mode (thank goodness—imagine getting pinged every minute while coding).

You have two ways to trigger them:

Option A: Press a Key

While wrangler dev is running, press the s key in your terminal.

This sends a scheduled event to your Worker. You'll see:

Trigger schedule event (s to trigger)
[scheduled] Running scheduled job...

Option B: HTTP Endpoint

Wrangler exposes a special endpoint:

curl "http://localhost:8787/__scheduled?cron=*+*+*+*+*"

This manually fires your scheduled() handler.

Pro tip: I add a test-only endpoint in development:

export default {
  async fetch(request, env, ctx) {
    const url = new URL(request.url);

    // Only in development
    if (url.pathname === '/__test-cron' && env.ENVIRONMENT === 'dev') {
      const event = { scheduledTime: Date.now(), cron: '* * * * *' };
      await this.scheduled(event, env, ctx);
      return new Response('Cron simulated');
    }

    // ... rest of your handlers
  },

  async scheduled(event, env, ctx) {
    console.log('[scheduled] Running at', new Date(event.scheduledTime));
    // Your job logic here
  }
};

Then I can just hit http://localhost:8787/__test-cron in my browser during development.

The Complete Local Testing Workflow

Here's my typical dev loop:

Terminal 1: Run the Worker

wrangler dev

Leave this running. Watch the logs.

Terminal 2: Send Test Commands

# Test HTTP
curl http://localhost:8787/api/health

# Test queue
wrangler queues send my-jobs '{"test": true}'

# Test multiple messages
for i in {1..5}; do
  wrangler queues send my-jobs "{\"id\": $i}"
done

Terminal 1: Press Keys to Trigger Events

Press s to fire a scheduled event
Press c to clear the console
Press x to exit

This gives me full control over when things execute, which is perfect for debugging.

Understanding the Local Queue

When I first started, I wondered: "Is this a real queue, or just a mock?"

It's real. Here's what you get locally:

Feature	Local Queue	Production Queue
Batch delivery	✅ Yes	✅ Yes
`message.ack()`	✅ Yes	✅ Yes
`message.retry()`	✅ Yes	✅ Yes
Automatic retries	✅ Yes	✅ Yes
Dead letter queue	❌ No	✅ Yes
Persistence	❌ No (in-memory)	✅ Yes (durable)
Delays/scheduling	⚠️ Simplified	✅ Full featured

The key difference: Local queues are in-memory only. When you stop Wrangler, the queue disappears.

But for development, this is perfect. You get full queue semantics without needing any infrastructure.

Queue Configuration Deep Dive

Let me show you the correct wrangler.jsonc format, because I got this wrong the first time:

{
  "name": "my-worker",
  "main": "src/index.ts",

  "queues": {
    // Producer: lets you SEND messages
    "producers": [
      {
        "queue": "background-jobs",
        "binding": "JOB_QUEUE"  // Used in env.JOB_QUEUE.send()
      }
    ],

    // Consumer: lets you RECEIVE messages
    "consumers": [
      {
        "queue": "background-jobs",  // Must match producer queue name
        "max_batch_size": 10,        // Max messages per batch
        "max_batch_timeout": 30,     // Max seconds to wait for full batch
        "max_retries": 10,           // Retry failed messages up to 10x
        "dead_letter_queue": "background-jobs-dlq"  // Where failed messages go
      }
    ]
  }
}

Key points:

producers need a binding (that's how you reference it in code)
consumers do NOT have a binding (you just implement the handler)
The queue name connects producers to consumers
You can have multiple producers sending to the same queue
You can have multiple consumers processing the same queue (in different Workers)

Dead Letter Queue Setup

If you configure a dead_letter_queue, you need to also consume it:

{
  "queues": {
    "producers": [
      { "queue": "main-jobs", "binding": "MAIN_QUEUE" }
    ],
    "consumers": [
      {
        "queue": "main-jobs",
        "max_retries": 3,
        "dead_letter_queue": "failed-jobs"
      },
      {
        "queue": "failed-jobs",  // Consume the DLQ
        "max_batch_size": 1      // Process failures carefully
      }
    ]
  }
}

Then handle DLQ messages differently:

export default {
  async queue(batch, env, ctx) {
    for (const message of batch.messages) {
      // Check if this is from the DLQ
      if (message.queue === 'failed-jobs') {
        await logFailureForManualReview(message);
        message.ack();  // Don't retry again
      } else {
        // Normal processing
        await processJob(message.body);
        message.ack();
      }
    }
  }
};

Debugging Tips I Wish I Knew Earlier

1. Use Structured Logging

Don't just console.log('queue handler'). Include context:

async queue(batch, env, ctx) {
  console.log(`[queue] Received ${batch.messages.length} messages`);

  for (const message of batch.messages) {
    console.log(`[queue] Processing message ${message.id}`, {
      attempt: message.attempts,
      timestamp: message.timestamp,
      body: message.body
    });

    try {
      await processJob(message.body);
      message.ack();
      console.log(`[queue] ✓ Message ${message.id} complete`);
    } catch (error) {
      console.error(`[queue] ✗ Message ${message.id} failed:`, error);
      message.retry();
    }
  }
}

This makes it so much easier to see what's happening when you have multiple messages in flight.

2. Test Retry Logic Explicitly

Force a failure to see if retries work:

# Send a message that will fail
wrangler queues send my-jobs '{"shouldFail": true}'

async queue(batch, env, ctx) {
  for (const message of batch.messages) {
    if (message.body.shouldFail) {
      console.log(`[queue] Simulating failure (attempt ${message.attempts})`);
      message.retry();
      continue;
    }

    await processJob(message.body);
    message.ack();
  }
}

Watch your logs to see the retry attempts increment.

3. Simulate Production Conditions

Test with realistic batch sizes:

# Send 10 messages quickly
for i in {1..10}; do
  wrangler queues send my-jobs "{\"id\": $i}" &
done
wait

This helps you catch race conditions or batching issues before deploying.

Testing Scheduled Events Realistically

Here's a pattern I use to test different cron schedules:

async scheduled(event, env, ctx) {
  const hour = new Date(event.scheduledTime).getUTCHours();

  // Different behavior based on time
  if (hour % 6 === 0) {
    console.log('[scheduled] Running full refresh');
    await env.JOB_QUEUE.send({ type: 'full-refresh' });
  } else {
    console.log('[scheduled] Running incremental update');
    await env.JOB_QUEUE.send({ type: 'incremental' });
  }
}

Then test different times:

# Simulate 6am UTC
curl "http://localhost:8787/__scheduled?scheduledTime=2024-01-01T06:00:00Z"

# Simulate 3pm UTC  
curl "http://localhost:8787/__scheduled?scheduledTime=2024-01-01T15:00:00Z"

This lets me verify the logic works correctly at different hours without waiting for cron to actually fire.

Common Gotchas I Ran Into

Gotcha 1: Queue Messages Aren't Persisted Locally

If you send messages and then restart wrangler dev, they're gone. The local queue is in-memory only.

Solution: Use a script to set up test data:

#!/bin/bash
# setup-test-queue.sh

echo "Sending test messages..."
wrangler queues send my-jobs '{"id": 1, "type": "test"}'
wrangler queues send my-jobs '{"id": 2, "type": "test"}'
wrangler queues send my-jobs '{"id": 3, "type": "test"}'
echo "Done!"

Run this after starting dev mode.

Gotcha 2: Bindings Don't Auto-Update

If you change your wrangler.jsonc bindings, you need to restart wrangler dev.

Just saving the file isn't enough. Stop and restart the dev server.

Gotcha 3: Environment Variables

Make sure you have your env vars set locally:

# .dev.vars file
DATABASE_URL=http://localhost:5432
API_KEY=test-key-123

Wrangler loads these automatically in dev mode.

My Complete Testing Checklist

Before deploying, I test:

[ ] HTTP endpoints respond correctly
[ ] Queue messages get processed
[ ] Batch processing handles multiple messages
[ ] Failed messages retry correctly
[ ] Scheduled events trigger the right jobs
[ ] All three handlers can access environment bindings
[ ] Error handling works as expected
[ ] Logs are clear and informative

This usually takes 10-15 minutes and catches 95% of issues before they hit production.

What About Integration Tests?

For unit tests, you can mock the queue:

// tests/queue.test.ts
import { expect, test } from 'vitest';

test('processes messages correctly', async () => {
  const mockEnv = {
    JOB_QUEUE: {
      send: vi.fn()
    }
  };

  const batch = {
    messages: [
      {
        id: 'test-1',
        body: { type: 'test' },
        ack: vi.fn(),
        retry: vi.fn()
      }
    ]
  };

  await worker.queue(batch, mockEnv, {});

  expect(batch.messages[0].ack).toHaveBeenCalled();
});

But honestly? I prefer testing with real Wrangler because it catches configuration issues that mocks don't.

Wrapping Up

Testing Workers locally is easier than I expected once I understood the tools:

wrangler dev gives you a real local queue
wrangler queues send lets you trigger queue messages
Press s to trigger scheduled events
Everything runs in-memory, nothing to configure

The local dev experience is actually really good. I rarely need to deploy to staging anymore just to test something.

Next time: I'll show you how to set up monitoring and alerts so you know when things break in production. Because they will. 😅

Questions? Hit me in the comments! What's your local testing workflow like?

Adding Queue and Cron Handlers to Your Cloudflare Worker (Part 2)

teaganga — Wed, 10 Dec 2025 13:21:20 +0000

In Part 1, I explained why Queues are the right solution for long-running background jobs. Now let me show you exactly how to set it up.

This is the copy-paste-ready guide I wish I had when I started.

What We're Building

By the end of this post, your Worker will support all three invocation types:

HTTP (fetch) - your API and UI
Cron (scheduled) - automatic periodic jobs
Queue (queue) - on-demand background processing

All in one deployment, using Cloudflare's official Worker runtime.

Let's go step by step.

Step 1: Add Queue Configuration

First, open your wrangler.toml (or wrangler.jsonc) and add a queue binding:

# wrangler.toml

name = "my-worker"
main = "src/index.ts"

[[queues.producers]]
queue = "background-jobs"
binding = "JOB_QUEUE"

[[queues.consumers]]
queue = "background-jobs"
max_batch_size = 10
max_batch_timeout = 30

What this does:

producers - lets your Worker send messages to the queue
consumers - lets your Worker receive messages from the queue
binding - the name you'll use in your code (like env.JOB_QUEUE)

Important: The queue name (background-jobs) connects producers and consumers. Use the same name for both.

Now deploy:

wrangler deploy

Cloudflare will automatically create the queue if it doesn't exist yet. No manual setup needed!

Step 2: Add Cron Schedule

While you're in wrangler.toml, add a cron trigger:

# wrangler.toml (continued)

[triggers]
crons = ["0 */6 * * *"]  # Every 6 hours

This uses standard cron syntax:

*/10 * * * * - every 10 minutes
0 2 * * * - daily at 2am UTC
0 */6 * * * - every 6 hours

You can add multiple schedules:

[triggers]
crons = [
  "0 2 * * *",      # Daily refresh
  "*/30 * * * *"    # Health check every 30 min
]

Step 3: Add the Handler Functions

Now the fun part. Your Worker needs to export an object with all three handlers:

// src/index.ts

export default {
  // 1️⃣ HTTP Handler
  async fetch(request, env, ctx) {
    const url = new URL(request.url);

    if (url.pathname === '/api/trigger-job') {
      // Enqueue a background job
      await env.JOB_QUEUE.send({
        type: 'heavy-processing',
        timestamp: Date.now(),
        requestedBy: 'admin'
      });

      return new Response('Job queued successfully!', { status: 202 });
    }

    return new Response('Hello World!');
  },

  // 2️⃣ Cron Handler
  async scheduled(event, env, ctx) {
    console.log('[cron] Running scheduled job');

    // Option A: Do the work directly
    await doPeriodicMaintenance(env);

    // Option B: Enqueue work for the queue handler
    await env.JOB_QUEUE.send({
      type: 'scheduled-job',
      scheduledTime: event.scheduledTime
    });

    console.log('[cron] Job complete');
  },

  // 3️⃣ Queue Handler
  async queue(batch, env, ctx) {
    console.log(`[queue] Processing ${batch.messages.length} messages`);

    for (const message of batch.messages) {
      try {
        const { type, timestamp } = message.body;

        console.log(`[queue] Starting job ${message.id}`);
        await processHeavyJob(env, message.body);

        // Mark as successfully processed
        message.ack();

      } catch (error) {
        console.error(`[queue] Job failed:`, error);

        // Return to queue for retry
        message.retry();
      }
    }
  }
};

Key points:

Each handler gets env (bindings) and ctx (execution context)
message.ack() tells Cloudflare "this message is done"
message.retry() puts it back in the queue for another attempt
You can enqueue from any handler (HTTP, cron, or even queue)

Step 4: Implement Your Job Logic

Here's a clean pattern I use to keep job logic separate:

// src/jobs/processor.ts

export async function processHeavyJob(env, payload) {
  console.log('Starting heavy job...', payload);

  // This can run for minutes with unlimited CPU time!
  await fetchExternalAPIs();
  await processLargeDataset();
  await writeResultsToStorage(env);

  console.log('Job complete!');
}

Then import it in your main Worker:

// src/index.ts
import { processHeavyJob } from './jobs/processor';

export default {
  async queue(batch, env, ctx) {
    for (const message of batch.messages) {
      await processHeavyJob(env, message.body);
      message.ack();
    }
  }
};

This keeps your handlers clean and your job logic testable.

Step 5: Trigger It From Your Admin UI

Now when an admin clicks "Run Job" in your UI:

// Inside your fetch handler

if (url.pathname === '/admin/run-job' && request.method === 'POST') {
  // Validate admin auth first!

  await env.JOB_QUEUE.send({
    type: 'admin-triggered',
    userId: 'admin-123',
    priority: 'high'
  });

  return new Response(JSON.stringify({
    success: true,
    message: 'Job queued'
  }), {
    status: 202,
    headers: { 'Content-Type': 'application/json' }
  });
}

The request returns instantly (under 1ms typically), and the job runs in the background with no time limits.

Understanding What You Just Built

You now have three ways to trigger work:

Trigger	Handler	Use Case	CPU Limit
HTTP Request	`fetch()`	User actions, API calls	10-50ms*
Cron Schedule	`scheduled()`	Periodic maintenance	30s
Queue Message	`queue()`	Heavy background jobs	Unlimited ⚡

*50ms on paid plans, 30s on Business+

The magic: Queue handlers have unlimited CPU time. You can process for minutes without hitting limits.

Common Patterns I Use

Pattern 1: Immediate + Scheduled

Use cron for regular updates, but let admins trigger on-demand:

export default {
  async fetch(request, env, ctx) {
    if (request.url.endsWith('/refresh-now')) {
      await env.JOB_QUEUE.send({ source: 'manual' });
      return new Response('Queued');
    }
  },

  async scheduled(event, env, ctx) {
    // Same job, runs automatically every 6 hours
    await env.JOB_QUEUE.send({ source: 'cron' });
  },

  async queue(batch, env, ctx) {
    // Processes both manual and automatic triggers
    for (const msg of batch.messages) {
      await doTheWork(env, msg.body);
      msg.ack();
    }
  }
};

Pattern 2: Progressive Work

Break huge jobs into chunks:

async queue(batch, env, ctx) {
  for (const message of batch.messages) {
    const { items, cursor } = message.body;

    // Process this batch
    await processBatch(items);

    // If more work remains, enqueue next chunk
    if (cursor) {
      await env.JOB_QUEUE.send({
        items: await fetchNextBatch(cursor),
        cursor: nextCursor
      });
    }

    message.ack();
  }
}

This lets you process unlimited amounts of data without hitting timeouts.

Pattern 3: Dead Letter Queue

Track failed jobs:

async queue(batch, env, ctx) {
  for (const message of batch.messages) {
    try {
      await processJob(message.body);
      message.ack();

    } catch (error) {
      if (message.attempts >= 3) {
        // Save to storage for manual review
        await env.FAILED_JOBS.put(
          message.id,
          JSON.stringify({ error, body: message.body })
        );
        message.ack(); // Don't retry again
      } else {
        message.retry(); // Try again
      }
    }
  }
}

Should You Keep Everything in One Worker?

You can put all three handlers in one Worker. They don't compete for resources at runtime—each invocation is isolated.

But I usually split them once my job logic gets heavy:

Worker 1: API & UI

Handles fetch() only
Stays small and fast
Just enqueues messages

Worker 2: Job Runner

Handles queue() and scheduled()
Can import heavy dependencies
Focuses on background work

You configure this by creating two separate wrangler.toml files (or two directories), and pointing the queue consumer to the job worker.

I'll cover this architecture in Part 3 if there's interest!

Testing Your Handlers Locally

Cloudflare's dev server supports all three handlers:

wrangler dev

To test queues locally:

# Terminal 1: Run your worker
wrangler dev

# Terminal 2: Send a test message
wrangler queues producer send background-jobs '{"test": true}'

To test cron locally:

Cron doesn't run in dev mode, but you can simulate it:

// Add a test endpoint
if (url.pathname === '/__test-cron') {
  await this.scheduled({ scheduledTime: Date.now() }, env, ctx);
  return new Response('Cron simulated');
}

Wrapping Up

You now have a Worker that can:

✅ Serve HTTP traffic quickly
✅ Run scheduled maintenance jobs
✅ Process long-running background work on-demand

The complete code is less than 100 lines, and it gives you the full power of Cloudflare's infrastructure.

Next steps:

Add monitoring (I use Sentry)
Set up alerts for failed jobs
Consider splitting into multiple Workers as you scale

What would you like to see in Part 3? Two-Worker architecture? Error handling patterns? Let me know in the comments!

Quick Reference

// Full minimal example
export default {
  async fetch(request, env, ctx) {
    await env.JOB_QUEUE.send({ type: 'work' });
    return new Response('Queued!');
  },

  async scheduled(event, env, ctx) {
    await env.JOB_QUEUE.send({ type: 'cron' });
  },

  async queue(batch, env, ctx) {
    for (const msg of batch.messages) {
      await doWork(msg.body);
      msg.ack();
    }
  }
};

# wrangler.toml
[[queues.producers]]
queue = "my-jobs"
binding = "JOB_QUEUE"

[[queues.consumers]]
queue = "my-jobs"

[triggers]
crons = ["0 */6 * * *"]

Triggering Long Jobs in Cloudflare Workers

teaganga — Wed, 10 Dec 2025 13:14:22 +0000

I recently hit a wall with Cloudflare Workers that I'm sure many of you have encountered: how do you trigger a long-running background job on demand?

It seems simple enough—just call a function from your API, right? But Workers aren't quite that straightforward, and I spent way too long trying to work around limitations that, it turns out, Cloudflare already solved for me.

Let me walk you through what I learned.

The Problem: My Job Was Too Long for HTTP

I had a Worker that handled my admin UI. One of the features was a button that kicked off a heavy background process—think scraping, data processing, batch operations, that kind of thing.

My first implementation was naive:

export default {
  async fetch(request, env, ctx) {
    if (request.url.endsWith('/admin/run-job')) {
      await runHeavyJob(); // 😬
      return new Response('Job complete!');
    }
  }
}

This worked fine in development. But in production? Timeouts. Everywhere.

Here's why that didn't work:

HTTP Requests Have Strict Limits

Plan	CPU Time	Wall Time
Free	10ms	30s
Workers Paid	50ms	30s
Business+	30s	30s

My job needed more than 30 seconds of wall time, and I was burning through CPU time like crazy. Even on the paid plan, I kept hitting limits.

"No problem," I thought, "I'll just use ctx.waitUntil() to let it finish after the response!"

export default {
  async fetch(request, env, ctx) {
    if (request.url.endsWith('/admin/run-job')) {
      ctx.waitUntil(runHeavyJob()); // Still doesn't work! 😭
      return new Response('Job started!');
    }
  }
}

Turns out, waitUntil() doesn't extend the timeout—it just lets you do cleanup work after sending the response. The isolate still shuts down at the same time limit.

Why I Couldn't Just Use `scheduled()`

My next idea was: "Wait, I have a cron job that runs this successfully every night. Why not just... trigger that?"

export default {
  async fetch(request, env, ctx) {
    if (request.url.endsWith('/admin/run-job')) {
      // Can I just... call scheduled() somehow? 🤔
      await this.scheduled(); // Nope!
      return new Response('Done!');
    }
  },

  async scheduled(event, env, ctx) {
    await runHeavyJob(); // This works great!
  }
}

This doesn't work. You can't call scheduled() from your code. Cloudflare's cron system is the only thing that can invoke it.

I tried a bunch of hacky workarounds:

Calling the Cloudflare API to trigger a cron (requires external auth, not instant)
Setting up webhooks to external services (defeats the purpose of Workers)
Storing a flag in KV and polling it every minute (works, but... gross)

All of these felt wrong.

The Lightbulb Moment: Queues Are Made For This

Then I discovered Cloudflare Queues, and everything clicked.

Queues give you a third type of invocation handler:

export default {
  async fetch(request, env, ctx) { ... },
  async scheduled(event, env, ctx) { ... },
  async queue(batch, env, ctx) { ... }, // 👈 This one!
}

And here's the key difference:

Execution Limits by Handler Type

Handler	CPU Time	Best For
`fetch()`	10-50ms (most plans)	Quick APIs, UI
`scheduled()`	30s	Periodic jobs
`queue()`	Unlimited ⚡	Heavy processing

Queue handlers have no CPU time limit. Only wall time limits, which are measured in minutes, not seconds.

How I Actually Solved It

Here's my final architecture:

Worker 1: Admin UI (Producer)

export default {
  async fetch(request, env, ctx) {
    if (request.url.endsWith('/admin/run-job')) {
      // Enqueue a message
      await env.MY_QUEUE.send({
        type: 'heavy-job',
        triggeredBy: 'admin',
        timestamp: Date.now()
      });

      return new Response('Job queued!');
    }
  }
}

Worker 2: Job Runner (Consumer)

export default {
  async queue(batch, env, ctx) {
    for (const message of batch.messages) {
      const { type, triggeredBy } = message.body;

      if (type === 'heavy-job') {
        await runHeavyJob(); // Runs with unlimited CPU time! 🎉
        message.ack();
      }
    }
  }
}

This works beautifully because:

The UI Worker stays fast (just enqueues and returns)
The job Worker runs with unlimited CPU time
Queues handle retries automatically if something fails
I can scale the workers independently
Execution is nearly instant (no polling delay)

Important: Handlers Don't Compete for Resources

I initially thought combining fetch() and queue() in the same Worker would cause problems. Like, maybe a running queue job would slow down HTTP requests?

Nope. Each handler invocation runs in its own isolated execution context. They don't share CPU or memory at runtime.

What they DO share is:

The code bundle (larger bundles = slower cold starts)
The deployment (a bug in one handler affects the whole Worker)

So you CAN put all three handlers in one Worker:

export default {
  async fetch(request, env, ctx) {
    await env.MY_QUEUE.send({ type: 'job' });
    return new Response('Queued!');
  },

  async scheduled(event, env, ctx) {
    await env.MY_QUEUE.send({ type: 'cron-job' });
  },

  async queue(batch, env, ctx) {
    await runHeavyJob(); // This won't slow down fetch()
  }
}

But I prefer separating them because:

Smaller UI bundle = faster cold starts for users
I can deploy job changes without touching the UI
Cleaner separation of concerns

Other Options I Considered

Cron Polling

Set a flag in KV, then check it every minute with scheduled():

export default {
  async fetch(request, env, ctx) {
    await env.KV.put('pending-job', 'true');
    return new Response('Job will run soon');
  },

  async scheduled(event, env, ctx) {
    const pending = await env.KV.get('pending-job');
    if (pending) {
      await runHeavyJob();
      await env.KV.delete('pending-job');
    }
  }
}

This works, but it's not instant. You're at the mercy of your cron interval (minimum 1 minute).

Durable Object Alarms

Durable Objects can set alarms that fire almost immediately:

export class JobRunner {
  async fetch(request) {
    await this.storage.setAlarm(Date.now() + 100); // 100ms
    return new Response('Alarm set');
  }

  async alarm() {
    await runHeavyJob(); // Runs in the DO context
  }
}

This is actually pretty elegant, but requires setting up Durable Objects, which feels heavyweight for this use case.

My Recommendation

For on-demand long-running jobs: use Queues.

They're purpose-built for exactly this scenario:

Unlimited CPU time
Built-in retry logic
Simple API
Scales automatically
Near-instant execution

Setup is minimal:

# wrangler.toml
[[queues.producers]]
queue = "my-jobs"
binding = "MY_QUEUE"

[[queues.consumers]]
queue = "my-jobs"
max_batch_size = 10
max_batch_timeout = 30

And you're off to the races.

Wrapping Up

What I learned from this:

Don't fight the platform. I wasted time trying to make fetch() do something it wasn't designed for.
Read the limits. Understanding CPU vs. wall time saved me hours of debugging.
Queues are underrated. They're not just for distributed systems—they're perfect for background jobs in monoliths too.

If you're running into timeout issues with Workers, check if Queues solve your problem. They probably do.

Getting Started With NextJs and Shadcn on Cloudflare, with Hono and D1

teaganga — Sat, 06 Dec 2025 10:17:34 +0000

This is a starting kit created with wrangler init:

╭ Create an application with Cloudflare Step 1 of 3
│
├ In which directory do you want to create your application?
│ dir ./nameless-ocean-1ab9
│
├ What would you like to start with?
│ category Framework Starter
│
├ Which development framework do you want to use?
│ framework Next.js
│
├ Continue with Next.js via `npx create-next-app@15.4.6 nameless-ocean-1ab9`
│

✔ Would you like to use TypeScript? … No / Yes
✔ Would you like to use ESLint? … No / Yes
✔ Would you like to use Tailwind CSS? … No / Yes
✔ Would you like your code inside a `src/` directory? … No / Yes
✔ Would you like to use App Router? (recommended) … No / Yes
✔ Would you like to use Turbopack for `next dev`? … No / Yes
✔ Would you like to customize the import alias (`@/*` by default)? … No / Yes
✔ What import alias would you like configured? … @/*
Creating a new Next.js app in /home/adiian/projects/aapps/starterkit/nameless-ocean-1ab9.

Using npm.

Initializing project with template: app-tw 


Installing dependencies:
- react
- react-dom
- next

Installing devDependencies:
- typescript
- @types/node
- @types/react
- @types/react-dom
- @tailwindcss/postcss
- tailwindcss
- eslint
- eslint-config-next
- @eslint/eslintrc


added 332 packages, and audited 333 packages in 59s

136 packages are looking for funding
  run `npm fund` for details

1 moderate severity vulnerability

To address all issues, run:
  npm audit fix --force

Run `npm audit` for details.
Success! Created nameless-ocean-1ab9 at /home/adiian/projects/aapps/starterkit/nameless-ocean-1ab9

A new version of `create-next-app` is available!
You can update by running: npm i -g create-next-app

├ Copying template files
│ files copied to project directory
│
╰ Application created 

╭ Configuring your application for Cloudflare Step 2 of 3
│
├ Installing wrangler A command line tool for building Cloudflare Workers
│ installed via `npm install wrangler --save-dev`
│
├ Adding the Cloudflare adapter
│ installed @opennextjs/cloudflare)}
│
├ Updating `next.config.ts`
│ updated `next.config.ts`
│
├ Adding Wrangler files to the .gitignore file
│ updated .gitignore file
│
├ Updating `package.json` scripts
│ updated `package.json`
│
├ Generating types for your application
│ generated to `./cloudflare-env.d.ts` via `npm run cf-typegen`
│
├ Installing @types/node
│ installed via npm
│
├ You're in an existing git repository. Do you want to use git for version control?
│ yes git
│
╰ Application configured 

╭ Deploy with Cloudflare Step 3 of 3
│
├ Do you want to deploy your application?
│ no deploy via `npm run deploy`
│
╰ Done 

────────────────────────────────────────────────────────────
🎉  SUCCESS  Application created successfully!

💻 Continue Developing
Change directories: cd nameless-ocean-1ab9
Start dev server: npm run dev
Deploy: npm run deploy

📖 Explore Documentation
https://developers.cloudflare.com/workers

🐛 Report an Issue
https://github.com/cloudflare/workers-sdk/issues/new/choose

💬 Join our Community
https://discord.cloudflare.com

Then install shadcn:

npx shadcn@latest init

When you run npx shadcn@latest init, here's what happens:

npx downloads the package temporarily - It fetches shadcn from npm to a cache
Runs it immediately - Executes the CLI command
Doesn't permanently install it - The package isn't added to your node_modules or package.json, but shadcn will install a bunch of other packages:

    "dependencies": {
        "@hookform/resolvers": "^5.2.2",
        ...
        "@radix-ui/react-label": "^2.1.7",
        "@radix-ui/react-slot": "^1.2.3",
        "class-variance-authority": "^0.7.1",
        "clsx": "^2.1.1",
        "lucide-react": "^0.546.0",
        ...
        "react-hook-form": "^7.65.0",
        "tailwind-merge": "^3.3.1",
        "zod": "^4.1.12"
    },
    "devDependencies": {
        ...
        "tw-animate-css": "^1.4.0",
        ...
    }

Then you:

npx shadcn@latest add button card input form label

When you ran the init and add commands shadcn will install of those packages:

Installed by `shadcn init`:

class-variance-authority - Manages component variants (size, color, etc.)
clsx - Combines CSS class names conditionally
tailwind-merge - Intelligently merges Tailwind classes (prevents conflicts)
tw-animate-css - Animation utilities for Tailwind v4 (replaces old tailwindcss-animate)

Installed by `shadcn add <component>`:

When you added `button`, `label`, `input`:

@radix-ui/react-slot - Used by Button component for composition
@radix-ui/react-label - Accessible label primitive
lucide-react - Icon library (many components use icons)

When you added `form`:

react-hook-form - Powerful form state management
@hookform/resolvers - Connects validation libraries to react-hook-form
zod - TypeScript-first schema validation

What shadcn Does Smart

shadcn only installs what you actually need:

Add a button? → Gets Radix Slot
Add a form? → Gets react-hook-form + zod
Add a select? → Gets more Radix primitives

This keeps your bundle size lean - you're not installing form libraries if you only need buttons. You don't need to manually install anything else unless you want additional components.

Microsoft Certifications Relevant to Fabric Data Engineering & Architecture

teaganga — Fri, 05 Dec 2025 11:51:52 +0000

I want to start studding for a certification for MS Azure in the Ai Field, so I create a list of certifications to see which is the best fit for me. I recently noticed a job requiring MS Fabric knowledge.

So I'm checking if I should study something more specific or something broader.

⭐ 1. DP-700 — Microsoft Fabric Data Engineer Associate

Most directly relevant to Fabric engineering.
Focus: Implementing data-engineering solutions inside Fabric.

Covers:

Lakehouses, Warehouses, KQL DBs
Data ingestion & transformation (Pipelines, Dataflows, Notebooks)
Storage design, Delta Lake
Real-time ingestion (Eventstream/Eventhouse)
Monitoring & governance in Fabric

Best for: Fabric Data Engineers / Fabric Architects

⭐ 2. DP-600 — Fabric Analytics Engineer Associate

Focuses on the semantic layer + analytics side of Fabric.

Covers:

Semantic models
Direct Lake / DirectQuery
Power BI in Fabric
Data modeling, DAX, metrics
Performance tuning for analytics

Best for: BI/Fabric Analytics Engineers, those touching modeling/reporting.

⭐ 3. DP-203 — Azure Data Engineer Associate

The classic Azure data engineering cert.

Covers:

Azure Data Lake, Synapse, Databricks
Data ingestion/ETL/ELT
SQL/NoSQL data stores
Batch + streaming
Lakehouse fundamentals (pre-Fabric world)

Useful because Fabric still relies on many Azure concepts.

Best for: Azure Data Engineers / Hybrid Fabric–Azure architects

⭐ 4. AZ-305 — Azure Solutions Architect Expert

High-level architecture and design certification.

Covers:

Designing end-to-end Azure solutions
Storage, networking, security, identity
Cost optimization & governance
Aligning designs with Microsoft Cloud Adoption Framework

Perfect match for the role’s architecture responsibilities.

Best for: Solution Architects / Lead Engineers / Consultants

➕ Helpful, but Secondary

5. PL-300 — Power BI Data Analyst

Covers:

Data modeling
DAX
Report design
Dataset relationships & performance

Useful for Fabric because Power BI is the semantic layer within Fabric.

6. AI-900 — Azure AI Fundamentals

Basics of:

Cognitive Services
ML concepts
GenAI and Azure OpenAI

Good only if the project includes AI/ML components.

7. AI-102 — Azure AI Engineer Associate

Advanced AI implementation:

NLP, Vision, Speech
Azure AI services integration
Responsible AI, deployment

Only relevant if Fabric solutions integrate AI pipelines.

Certification Comparison Table

Certification	Focus Area	Key Topics Covered	Best For	Relevance to Azure AI / Fabric
⭐ DP-700 — Microsoft Fabric Data Engineer Associate	Fabric data engineering	• Lakehouses, Warehouses, KQL DBs • Pipelines, Dataflows, Notebooks • Delta Lake, storage design • Eventstream/Eventhouse • Monitoring & governance	Fabric Data Engineers, Fabric Architects	Highest relevance for Fabric engineering
⭐ DP-600 — Fabric Analytics Engineer Associate	Semantic modeling + analytics in Fabric	• Semantic models • Direct Lake / DirectQuery • Power BI in Fabric • DAX, metrics, performance tuning	BI Engineers, Analytics Engineers	Strong for modeling/reporting inside Fabric
⭐ DP-203 — Azure Data Engineer Associate	Core Azure data engineering	• ADLS, Synapse, Databricks • ETL/ELT workflows • SQL/NoSQL stores • Batch + streaming • Pre-Fabric lakehouse fundamentals	Azure Data Engineers, Hybrid Azure–Fabric roles	Very relevant; Azure foundations still apply to Fabric
⭐ AZ-305 — Azure Solutions Architect Expert	Architecture & high-level Azure design	• End-to-end Azure solution design • Networking, security, identity • Governance & cost optimization • Microsoft CAF alignment	Solutions Architects, Lead Engineers	Very relevant if you’ll design Fabric + Azure solutions
➕ PL-300 — Power BI Data Analyst	BI modeling and reporting	• Data modeling • DAX • Report design • Performance optimization	Data Analysts, BI Engineers	Helpful because Power BI is Fabric’s semantic layer
➕ AI-900 — Azure AI Fundamentals	Intro to Azure AI	• Cognitive Services basics • ML & GenAI fundamentals	AI beginners, generalists	Useful only if touching AI components
➕ AI-102 — Azure AI Engineer Associate	Applied AI engineering	• NLP, Vision, Speech • Azure AI service integration • Responsible AI • Deployment patterns	AI Engineers	Relevant only if AI will be integrated with Fabric pipelines

For a Fabric Data Engineer / Solution Architect consultant, the ideal bundle is:

Core / Highly Recommended

DP-700 — Fabric Data Engineer
DP-203 — Azure Data Engineer
AZ-305 — Solutions Architect Expert

Nice-to-Have / Add-on

DP-600 — Fabric Analytics Engineer
PL-300 — Power BI Data Analyst
AI-900 / AI-102 (only if AI-related work is expected)

Selenium vs. Playwright vs. Cypress (2025): The Ultimate Comparison Guide

teaganga — Thu, 04 Dec 2025 15:31:11 +0000

Automated testing is no longer optional. As web applications grow more complex, development teams rely on powerful testing frameworks to ensure reliability, performance, and seamless user experiences. I had to pick a testing framework to test our web application recently, so I checked what other options are beyond Selenium and Playright, to discover Cypress which seems good for heavy front end react-like apps. So I had to pick one of the three tools dominate the modern landscape:

Selenium — the industry veteran
Playwright — the modern powerhouse
Cypress — the developer-friendly favorite

They all automate browsers—but their approaches, strengths, and ideal use cases couldn’t be more different.

This guide offers a clean, deep comparison plus practical advice on when to use each tool over the others.

🚀 Quick Comparison Table

Feature / Tool	Selenium	Playwright	Cypress
Language Support	Java, Python, C#, JS, Ruby etc.	JS/TS, Python, Java, .NET	JavaScript only
Browser Support	All browsers + mobile (Appium)	Chromium, Firefox, WebKit	Chromium, Edge, Firefox (beta)
Execution Speed	Medium–Slow	Fast	Fast
Architecture	WebDriver protocol	Modern API, no driver	Runs inside the browser
Best For	Enterprise, multi-language stacks	Modern E2E testing, low flakiness	Front-end apps, JS teams
Flakiness	Medium–High	Very low	Low
Parallel Execution	Manual setup	Built-in	Paid dashboard for easy parallelization
Mobile Automation	Full (Appium)	Limited	None
Recorder Tools	Third-party	Built-in	Built-in
Open Source	Yes	Yes	Yes (dashboard has paid tier)

🧩 Selenium: The Veteran of Web Testing

Selenium has been the backbone of browser automation for over a decade. It’s mature, stable, and extremely flexible—supporting nearly every programming language and browser.

It integrates deeply with enterprise ecosystems, which is why large organizations continue to rely on it.

👍 Why teams choose Selenium

Works with Java, Python, C#, JavaScript, and more
Supports legacy browsers and enterprise environments
Compatible with Appium for mobile automation
Huge community, plugins, and long-term ecosystem stability

👎 Where Selenium struggles

Slower execution due to WebDriver architecture
Requires more manual waits and synchronization
Higher flakiness if not tuned well

🔄 Selenium vs. Playwright — When to Choose Which

Choose Selenium over Playwright when:

You need multiple languages, not just JS/Python/Java/.NET
Your environment requires older browser support
You rely on enterprise ecosystems (TestNG, Cucumber, corporate CI setups)
You need mobile automation with Appium

Choose Playwright over Selenium when:

You want fast and reliable tests with minimal flakiness
You want auto-waiting, parallelism, and built-in debugging
Cross-browser support (including WebKit) matters
You are starting a new automation project and want the modern option

🔄 Selenium vs. Cypress — When to Choose Which

Choose Selenium over Cypress when:

You need full cross-browser or mobile coverage
You want to use languages other than JavaScript
Your application requires multi-tab or complex window scenarios
You work in large enterprises needing legacy support

Choose Cypress over Selenium when:

Your team is JavaScript-focused
You want instant feedback and a visual test runner
You’re testing front-end SPA frameworks like React/Vue/Angular
You value developer experience over flexibility

⚡ Playwright: The Modern Powerhouse

Playwright is quickly becoming the default choice for new testing projects.
Created by the original Puppeteer team at Microsoft, it delivers:

Speed
Reliability
A modern API
Powerful debugging tools

Playwright removes the WebDriver middle layer entirely, enabling stable tests with automatic waiting and excellent cross-browser support (including WebKit, which mimics Safari).

👍 Why teams love Playwright

Extremely fast, low-flake tests
Supports Chromium, Firefox, WebKit
Parallel execution out of the box
Great debugging tools (trace viewer, codegen, inspector)
Tests run consistently in CI and locally

👎 Where Playwright has limits

No full mobile automation (only WebView)
Fewer enterprise ecosystem integrations than Selenium
Requires TypeScript/Java/Python/.NET skillset

🔄 Playwright vs. Selenium — When to Choose Which

Choose Playwright over Selenium when:

You want modern, reliable, low-maintenance tests
Cross-browser support matters—but not necessarily legacy browsers
You want built-in parallel execution, tracing, and time-travel debugging
You’re starting a new automation project

Choose Selenium over Playwright when:

Your org requires Java/C#/Python-first solutions
You need legacy browser support
You run extensive mobile automation suites

🔄 Playwright vs. Cypress — When to Choose Which

Choose Playwright over Cypress when:

You need multi-tab, multi-domain, or iframe capabilities
You want full support for Chromium, Firefox, and WebKit
You need scalable CI performance
You prefer flexibility over opinionated workflows

Choose Cypress over Playwright when:

Your team loves visual debugging and time-travel UI
You’re exclusively testing JavaScript front-end apps
You want the simplest onboarding for junior developers
You value an all-in-one developer experience

🌿 Cypress: The Developer-Friendly Favorite

Cypress is adored by front-end teams.
Its biggest selling point? A fantastic developer experience.

Cypress runs inside the browser itself, offering time-travel debugging, clear error messages, and instant visual feedback. This makes it perfect for front-end-heavy applications.

👍 Why teams choose Cypress

Unmatched debugging and test visualization
Seamless JavaScript/TypeScript workflow
Deep DOM access, great for SPAs
Zero-flake auto-waiting for most interactions

👎 Cypress limitations

Limited cross-browser support
No multi-tab support
No native mobile automation
Opinionated architecture restricts flexibility

🔄 Cypress vs. Selenium — When to Choose Which

Choose Cypress over Selenium when:

You’re testing a React/Vue/Angular SPA
Your team is 100% JavaScript
You need excellent debugging and fast feedback
You want a tool that’s easy for new developers to learn

Choose Selenium over Cypress when:

You need enterprise-level browser coverage
You work in multi-language environments
You test multiple windows/tabs
You require Appium mobile testing

🔄 Cypress vs. Playwright — When to Choose Which

Choose Cypress over Playwright when:

Debugging clarity and ease matter most
You prefer a highly opinionated, developer-focused workflow
You mainly test Chromium browsers
You want fast onboarding for UI developers

Choose Playwright over Cypress when:

You need multi-domain or multi-context capability
You want Firefox + WebKit support
You need scalable, fast CI execution
You want to avoid Cypress’s architectural limitations

I decided to stay with Playright for the time being, but still keeping an eye on Cypress, so if you’re choosing today:

🏆 Best all-around choice for modern automation:

➡ Playwright

🧱 Best for enterprises and multi-language environments:

➡ Selenium

🌱 Best for front-end-focused JavaScript teams:

➡ Cypress

How to Seed Data in Drizzle (The Right Way)

teaganga — Mon, 01 Dec 2025 13:59:07 +0000

Best practices for Drizzle ORM, migrations, seed scripts, and system data

Seeding data is one of the most common tasks when building a backend—but if you're using Drizzle ORM, the right way to seed data may not be obvious at first.

Should you put seed data inside migrations?
Should you generate seed migrations automatically?
Should you write seed scripts instead?
What goes where?

This guide breaks down exactly how to seed data in Drizzle the right way, along with example SQL and TypeScript migrations.

⭐ Why Seeding Data Matters

Seeding is how you insert:

Essential system constants (roles, permissions, configuration defaults)
Initial lookup tables
Local development data
Demo or sample data

Drizzle handles schema migrations beautifully—but when it comes to seeding, there are a few rules that help you avoid headaches across environments.

1. Two Ways to Seed Data in Drizzle

Drizzle supports seeding in two primary ways:

A) Seed data in a migration (SQL or TypeScript)

→ Best for system-required data like roles, permissions, default settings.

B) Seed data using a seed script (your own script)

→ Best for environment-specific data like test users, fake orgs, or demo content.

Understanding the difference is important.

2. When You Should Seed Data in Migrations

Migrations should include static, deterministic, environment-independent data that your application must have to function.

Examples:

Default RBAC roles
Permissions
Role → permission mappings
Default feature flags
System-level configuration rows
Enum-like lookup tables

These values belong in migrations because they define the system itself.

✔️ Good migration seed examples

INSERT INTO roles (id, name) VALUES
  ('admin', 'Administrator'),
  ('editor', 'Editor')
ON CONFLICT (id) DO NOTHING;

These values never change based on environment—so they belong in migrations.

**3. When You Should Not Seed Data in Migrations**

Never put environment-specific or temporary data inside migrations.

These do NOT belong in migrations:

Test users
Demo accounts
Sample websites
Development-only data
API keys or secrets
Customer, agency, or tenant data

Migrations must remain stable, repeatable, and safe to run in production.

So anything environment-specific should go into a seed script, not a migration.

4. Seeding Data Inside Drizzle Migrations

You can seed data using:

Option 1 — SQL migration (`.sql`)

Drizzle runs plain SQL migrations out of the box.

Example: 0005_seed_roles.sql

INSERT INTO rbap_roles (id, scope, name) VALUES
  ('platform_admin', 'platform', 'Platform Admin'),
  ('partner_admin', 'partner', 'Partner Admin'),
  ('customer_admin', 'customer', 'Customer Admin')
ON CONFLICT (id) DO NOTHING;

Option 2 — TypeScript migration (`.ts`)

If you prefer Drizzle's typed database client (and sql tag):

import { sql } from "drizzle-orm";

export const up = async (db) => {
  await db.execute(sql`
    INSERT INTO rbap_roles (id, scope, name) VALUES
      ('platform_admin', 'platform', 'Platform Admin'),
      ('partner_admin', 'partner', 'Partner Admin'),
      ('customer_admin', 'customer', 'Customer Admin')
    ON CONFLICT (id) DO NOTHING;
  `);
};

export const down = async (db) => {
  await db.execute(sql`
    DELETE FROM rbap_roles 
    WHERE id IN ('platform_admin', 'partner_admin', 'customer_admin');
  `);
};

Both options work perfectly.

5. Does Drizzle Auto-Generate Seed Migrations?

❌ No.

Drizzle generates schema change migrations only.

That includes:

create table
add column
drop index
change constraint

Drizzle does not generate migrations for:

inserts
seed data
role lists
permissions
enums implemented via lookup tables

So you must write these manually (SQL or TS).

6. Creating a Seed Script for Local or Dev Data

For data you want in development but not in production, create your own simple script:

Example: seed.ts

import { db } from "./db";
import { users } from "./schema";

await db.insert(users).values({
  id: "dev-user-1",
  email: "test@example.com",
  name: "Dev Tester",
});

Run it with:

ts-node seed.ts

or add a script:

"scripts": {
  "seed": "ts-node seed.ts"
}

This keeps dev/test data separate from production migrations.

7. Best Practices for Seeding in Drizzle

Put system-level constants inside migrations: Roles, permissions, status codes, lookup tables.
Put environment-specific data inside seed scripts: Demo data, test users, dev orgs.
Never mix schema migrations with app data: Avoid creating partner agencies, customer orgs, or users inside migrations.
Use ON CONFLICT DO NOTHING for idempotency: Ensures migrations stay safe and re-runnable.
Keep migrations deterministic: Every run should produce the same final result.

Final Takeaway

Seeding in Drizzle is extremely flexible—once you follow the right boundaries.

Task	Migration	Seed Script
Create roles	✅ Yes	❌ No
Create demo users	❌ No	✅ Yes
Insert default permissions	✅ Yes	❌ No
Insert dev-only test data	❌ No	✅ Yes
Populate lookup tables	✅ Yes	❌ No

If the data defines the system, put it in a migration.
If the data defines the environment, put it in a seed script.

What Is SIEM? Understanding Its Role in the Modern Cybersecurity Ecosystem

teaganga — Thu, 27 Nov 2025 16:11:20 +0000

In today’s hyper-connected world, organizations generate an overwhelming amount of data—from user activity and network traffic to application logs and cloud telemetry. Hidden in that data are the early warning signs of cyber threats. The challenge is making sense of it all.

That’s where SIEM, or Security Information and Event Management, enters the picture.

A SIEM platform acts as the central nervous system of an organization’s security operations. It collects, correlates, and analyzes security events from across your entire IT and OT environment, helping security teams detect threats, investigate incidents, and maintain compliance.

But SIEM isn’t just a tool—it’s a strategic component of the broader cybersecurity stack.

What Exactly Is SIEM?

A SIEM system performs three fundamental functions:

1. Log Collection & Centralization

SIEM aggregates logs and events from many different sources:

firewalls
servers
applications
cloud services
identity platforms
OT devices
security tools (EDR, IDS, WAF, DLP, etc.)

Instead of analyzing each log in isolation, SIEM provides a single, unified view of everything happening across the organization.

2. Correlation & Detection

Raw logs on their own aren't enough to reveal threats. A SIEM uses built-in detection rules, machine learning, and correlation logic to:

detect abnormal behavior
identify attack patterns
connect events across systems
generate actionable alerts

This enables earlier detection of threats like lateral movement, privilege escalation, or data exfiltration.

3. Analytics, Reporting & Compliance

SIEM platforms provide:

dashboards for visibility
audit reports
long-term data retention
forensic search capabilities

This helps with compliance requirements such as ISO 27001, NIS2, SOC 2, PCI-DSS, and many more.

Where SIEM Fits in the Bigger Cybersecurity Context

To understand SIEM fully, it’s important to see where it sits in the broader ecosystem. SIEM is not an isolated product—it's the hub that connects the entire security stack.

1. SIEM as the Heart of Security Operations (SOC)

A SIEM typically sits at the center of a Security Operations Center (SOC). Analysts rely on SIEM dashboards, alerts, and logs to:

monitor the environment in real-time
identify suspicious activity
investigate incidents
escalate or respond to threats

Without a SIEM, SOC teams would be blind.

2. SIEM and SOAR: From Detection to Automated Response

SIEM identifies threats.
SOAR (Security Orchestration, Automation, and Response) takes action.

SIEM + SOAR together enable:

automated ticketing
enrichment (WHOIS, threat intel, geolocation)
containment actions (disable user, isolate host)
orchestrated response playbooks

Many modern SIEMs (e.g., Splunk, Microsoft Sentinel) now include SOAR features natively.

3. SIEM Within the Modern Detection & Response Stack

Here’s how SIEM relates to other security technologies:

EDR/XDR → provides endpoint-level telemetry (process, memory, behavior)
NDR → monitors network traffic
FIM, IDS/IPS → detect changes and intrusions
Firewalls & WAF → enforce network boundaries
IAM/IDP → handles identity and access events
Cloud Security Tools → monitor SaaS and multi-cloud environments

All of these feed into the SIEM.
SIEM becomes the aggregation and analysis layer.

4. SIEM in OT (Operational Technology) Security

In industrial environments—energy, manufacturing, transportation, utilities—SIEM plays a unique role:

collecting logs from PLCs, SCADA systems, HMIs, and OT firewalls
correlating behavior across IT and OT networks
integrating with ICS threat detection platforms
ensuring compliance with critical infrastructure standards

OT environments often operate in highly segmented networks, making SIEM one of the few windows into cross-domain visibility.

5. SIEM in a DevSecOps & API-Driven World

Modern SIEMs aren’t just log viewers; they’re programmable platforms.

They integrate with:

RESTful APIs
CI/CD pipelines
data transformations (Logstash, Fluentd, Kafka)
cloud event streams
container orchestration systems like Kubernetes

This allows security teams to automate:

ingestion pipelines
enrichment steps
alert response
data normalization
custom detection rules

In other words, SIEM is evolving into a fully integrated part of the DevSecOps toolchain.

Why SIEM Still Matters—and More Than Ever

With expanding attack surfaces and increasing regulatory pressure, SIEM has become essential for:

real-time threat detection
compliance and audit readiness
end-to-end visibility
incident response
unified monitoring across cloud, on-prem, and OT systems

As environments grow more complex and distributed, SIEM remains one of the few technologies capable of giving security teams a complete picture.

Closing Thoughts

A SIEM is much more than a log collector—it’s the analytical brain of modern security operations. It sits at the intersection of IT, OT, cloud, and identity systems, providing the context needed to detect threats before they become incidents.

In an era where digital operations are expanding faster than ever, a well-implemented SIEM isn’t just useful—it’s indispensable.

Bicep / ARM vs Terraform

teaganga — Thu, 27 Nov 2025 16:05:20 +0000

Bicep and ARM templates are Terraform alternatives, but only within the Azure ecosystem.

Bicep / ARM vs Terraform — What’s the difference?

Bicep

Azure-specific DSL for IaC.
Compiles into ARM templates.
First-class support by Microsoft.
Best choice if you're 100% Azure and want:
- Tight integration with Azure
- Fast updates when new Azure features come out
- Simple syntax compared to ARM JSON

ARM Templates

Low-level JSON IaC for Azure.
Verbose & harder to maintain.
Bicep is meant to replace writing ARM JSON manually.

Terraform

Cloud-agnostic IaC tool.
Works with Azure, AWS, GCP, VMware, Kubernetes, etc.
Uses HCL (HashiCorp Configuration Language).
Great for:
- Multi-cloud environments
- Advanced orchestration
- Rich ecosystem of providers & modules

🔍 So is Bicep an alternative to Terraform?

Yes, but only if your infrastructure is Azure-only.

If you're Azure-only → Bicep is a strong alternative, simpler and more native.
If you're multi-cloud → Terraform is the better choice.

📊 Quick Comparison

Feature	Bicep	ARM Templates	Terraform
Cloud support	Azure only	Azure only	Multi-cloud
Language	Simple DSL	JSON	HCL
Native Azure support	Excellent	Excellent	Very good (slightly slower updates)
Learning curve	Low	High	Moderate
State management	Azure handles state	Azure handles state	Terraform state backend (S3, Azure blob, etc.)
Modularity	Good	Limited	Excellent
Multi-cloud workflows	❌	❌	✅

🧭 When to choose which?

Choose Bicep if:

You work primarily in Azure.
You want clean, readable IaC.
You want the newest Azure features immediately.

Choose Terraform if:

You operate across multiple clouds.
You want very strong modules and ecosystem support.
You need complex workflows, reusable patterns, and a mature toolchain.

More about Bicep and ARM

Bicep and ARM templates are both ways to define Infrastructure as Code (IaC) for deploying Azure resources.

ARM templates = JSON-based, older, more verbose.
Bicep = Newer, simpler, domain-specific language that compiles into ARM JSON.

🧱 ARM Templates (Azure Resource Manager Templates)

ARM templates are JSON files that describe Azure resources you want to deploy.
They are:

JSON-based (structured but verbose)
Deterministic (same template = same deployment result)
Supported everywhere in Azure

Example snippet (ARM JSON):

{
  "type": "Microsoft.Storage/storageAccounts",
  "apiVersion": "2023-01-01",
  "name": "mystorage",
  "location": "eastus",
  "sku": { "name": "Standard_LRS" },
  "kind": "StorageV2"
}

Problems:

Hard to read and write
Lots of nested syntax
Painful for complex deployments

🟦 Bicep (Next-Gen IaC for Azure)

Bicep is a domain-specific language (DSL) from Microsoft made to replace ARM templates.

Key traits:

Much more concise & readable
Strong type checking & IntelliSense in VS Code
Modular & reusable
Converts to ARM JSON under the hood (so same engine, better language)

Example snippet (Bicep):

resource storage 'Microsoft.Storage/storageAccounts@2023-01-01' = {
  name: 'mystorage'
  location: 'eastus'
  sku: {
    name: 'Standard_LRS'
  }
  kind: 'StorageV2'
}

Benefits:

60–80% fewer lines than ARM
Easier learning curve
Better tooling (VS Code extension)

🔁 Relationship Between Them

Bicep → compiles to → ARM JSON
ARM engine → executes the deployment
Anything ARM can do, Bicep can do (because it uses the same backend)

You can:

Convert existing ARM templates → Bicep (bicep decompile)
Convert Bicep → ARM JSON (bicep build)

🥇 Which should you use today?

Bicep is the recommended IaC language for Azure
ARM templates still work, but Bicep is easier and more productive.

Forem: teaganga

Using Docker Compose Profiles to unit tests part of the application

How it works

Multiple Databases and Profiles

Database Configuration Strategy

Alternative Approach

Concrete Example with unit-test-db and app-db

1️⃣ docker-compose.yml

2️⃣ What DATABASE_URL Should Look Like

Test profile → connect to unit-test-db

Prod profile → connect to app-db

3️⃣ Running with Different Environment Variable Sets

✅ Option A — Use Separate .env Files (Recommended)

.env.test

.env.prod

Start test stack

Start prod stack

✅ Option B — Inline Environment Variables

Test

Prod

4️⃣ What Actually Starts

Clean Mental Model

How to Add Vitest to a Cloudflare Worker Project (TypeScript)

Starting Point: Existing Worker Project

Why Vitest?

Step 1: Install Vitest (and Only What You Need)

What this actually installs

❌ What you do not need

Step 2: Add a Vitest Config

Why environment: 'node'?

Step 3: Add Test Scripts

When to use which

Step 4: Where Should Tests Live?

Recommended structure

Why this works best

Step 5: Example Test

src/index.ts

src/index.test.ts

Step 6: Make Sure Tests Aren’t Deployed

Summary

Debugging Cloudflare Workers with VS Code: Queue Handlers Edition (Part 4)

The Setup: VS Code + Wrangler Dev + Debugger

Step 1: Run Wrangler in Debug Mode

Step 2: Configure VS Code

Step 3: Start Debugging

Step 4: Set Breakpoints and Trigger Queue Messages

Debugging All Three Handler Types

HTTP Handlers (fetch)

Scheduled Handlers (scheduled)

Queue Handlers (queue)

Advanced Debugging Techniques

1. Conditional Breakpoints

2. Logpoints

3. Watch Expressions

4. Debug Console

Common Issues and Solutions

Issue 1: Breakpoints Show as Gray/Unverified

Issue 2: "Cannot connect to runtime process"

Issue 3: Debugger Disconnects After First Request

Issue 4: Can't Debug External Dependencies

My Debugging Workflow

1. Reproduce the Issue Locally

2. Attach Debugger

3. Re-trigger

4. Test the Fix

Pro Tips

Use Multiple Launch Configurations

Create a Debug Script

Use Debugger Statements

Debugging Production Issues Locally

1. Get the Message from Your DLQ

2. Replay it Locally

3. Debug With Real Data

Performance Debugging

Wrapping Up

Quick Reference

Testing Cloudflare Workers Locally: Queues, Cron, and HTTP (Part 3)

The Challenge: Three Different Handler Types

Step 1: Start Your Dev Server

Step 2: Testing HTTP Handlers (Easy)

Concrete Example with `unit-test-db` and `app-db`

1️⃣ `docker-compose.yml`

2️⃣ What `DATABASE_URL` Should Look Like

Test profile → connect to `unit-test-db`

Prod profile → connect to `app-db`

✅ Option A — Use Separate `.env` Files (Recommended)

`.env.test`

`.env.prod`

Why `environment: 'node'`?

`src/index.ts`

`src/index.test.ts`

HTTP Handlers (`fetch`)

Scheduled Handlers (`scheduled`)

Queue Handlers (`queue`)

Why I Couldn't Just Use `scheduled()`

Installed by `shadcn init`:

Installed by `shadcn add <component>`:

When you added `button`, `label`, `input`:

When you added `form`: