Workers Overview
Serverless compute at the edge with Cloudflare Workers
Workers
OmniBase Workers provide serverless compute on Cloudflare Workers using the Hono web framework. Build globally distributed APIs, background jobs, and scheduled tasks that run at the edge.
What Are Workers?
Workers are lightweight, serverless functions that run on Cloudflare's global network across 300+ cities. They execute close to your users for ultra-low latency and can handle millions of requests per second.
Key Benefits
- Global Distribution — Deploy once, run everywhere on Cloudflare's edge
- Zero Cold Starts — Instant execution with no warmup time
- Unlimited Scale — Automatically scales to handle traffic spikes
- Low Latency — Sub-10ms response times globally
- Built on Standards — Uses Web APIs (Request/Response) with full TypeScript support
Features
Edge Functions
HTTP APIs that run globally at the edge with sub-10ms latency
Cron Jobs
Scheduled tasks for automated workflows and background processing
Queues
Background job processing with guaranteed delivery and automatic retries
Quick Start
# Initialize OmniBase (creates omnibase/workers/)
omnibase init
# Navigate to workers directory
cd omnibase/workers
# Install dependencies
bun install
# Start local development
bun dev
# Deploy to OmniBase
omnibase cloud workers deployYour worker will be deployed globally on Cloudflare's edge network via OmniBase.
Architecture
OmniBase Workers are built with:
- Hono — Fast, lightweight web framework (Express-like API)
- Cloudflare Workers — Edge runtime with V8 isolates
- Wrangler — CLI for development and deployment
- TypeScript — Full type safety and autocomplete
import { Hono } from "hono";
import { cors } from "hono/cors";
const app = new Hono();
app.use("/*", cors());
app.get("/api/hello", (c) => {
return c.json({
message: "Hello from the edge!",
location: c.req.header("cf-ray"),
});
});
export default {
fetch: app.fetch,
};Project Structure
omnibase/workers/
├── src/
│ └── index.ts # Main entry point
├── package.json # Dependencies (Hono, etc.)
├── wrangler.toml # Cloudflare Workers config
├── tsconfig.json # TypeScript config
└── .env # Local environment variablesUse Cases
API Endpoints
Build REST APIs that respond in milliseconds globally:
app.get("/api/users/:id", async (c) => {
const userId = c.req.param("id");
const user = await fetchUser(userId);
return c.json(user);
});Webhooks
Handle incoming webhooks from Stripe, GitHub, etc.:
app.post("/webhooks/stripe", async (c) => {
const event = await c.req.json();
await processStripeEvent(event);
return c.json({ received: true });
});Content Proxying
Cache and optimize content at the edge:
app.get("/images/:id", async (c) => {
const id = c.req.param("id");
const response = await fetch(`https://storage.example.com/${id}`);
return new Response(response.body, {
headers: {
"Cache-Control": "public, max-age=31536000",
},
});
});Edge Redirects
Handle redirects at the edge without hitting your origin:
app.get("/old-path", (c) => {
return c.redirect("/new-path", 301);
});Environment Variables
Environment variables are managed through OmniBase environment files in omnibase/environments/.
Configure Variables
Add your variables to the appropriate environment file:
# omnibase/environments/.env.production
OMNIBASE_API_URL=https://api.yourdomain.com
DATABASE_URL=postgresql://...
API_KEY=your-secret-key# omnibase/environments/.env.staging
OMNIBASE_API_URL=https://staging-api.yourdomain.com
DATABASE_URL=postgresql://...
API_KEY=your-staging-keyAccess in Workers
Access environment variables via c.env in your worker code:
app.get("/api/data", async (c) => {
const apiUrl = c.env.OMNIBASE_API_URL;
const apiKey = c.env.API_KEY;
return c.json({ connected: true });
});When you deploy with omnibase cloud workers deploy --env production, the CLI automatically injects variables from omnibase/environments/.env.production into your worker.
Deployment
Local Development
Run locally with hot reload:
cd omnibase/workers
bun devAccess at http://localhost:8787
Deploy to OmniBase
Deploy your workers to OmniBase Cloud:
omnibase cloud workers deployFor specific environments:
omnibase cloud workers deploy --env production
omnibase cloud workers deploy --env staging
omnibase cloud workers deploy --env devYour worker will be deployed globally on Cloudflare's edge network and accessible at your project's worker URL.
Best Practices
Keep Workers Lightweight
Workers are designed for fast execution. Avoid heavy processing:
// ✅ Good: Quick response with offloading
app.post("/api/process", async (c) => {
const data = await c.req.json();
// Queue heavy processing
await c.env.QUEUE.send({ data });
return c.json({ queued: true });
});
// ❌ Bad: Heavy processing blocks worker
app.post("/api/process", async (c) => {
const data = await c.req.json();
await heavyProcessing(data); // Takes 5+ seconds
return c.json({ done: true });
});Use TypeScript
Get full type safety and autocomplete:
type EnvVars = {
DATABASE_URL: string;
API_KEY: string;
};
const app = new Hono<{ Bindings: EnvVars }>();
app.get("/", (c) => {
// c.env is now fully typed
const dbUrl = c.env.DATABASE_URL;
return c.json({ connected: true });
});Cache Responses
Leverage Cloudflare's cache for static responses:
app.get("/api/data", async (c) => {
const cached = await caches.default.match(c.req.url);
if (cached) return cached;
const data = await fetchData();
const response = c.json(data);
c.executionCtx.waitUntil(
caches.default.put(c.req.url, response.clone())
);
return response;
});