Migrate an Express.js API to Cloudflare Workers
Command Palette
Search for a command to run...
Comments
Join the discussionNo comments yet. Be the first to comment.
Search for a command to run...
No comments yet. Be the first to comment.
Originally published at my personal website
Migrating from Express.js to Cloudflare Workers represents a fundamental shift from server-based computing to edge computing. This document provides an in-depth analysis of the migration process, architectural considerations, technical challenges, and strategic decision-making frameworks to ensure a successful transition.
Performance and reach: This makes your API accessible in more than 300 locations worldwide.
Latency: Your app experiences zero cold starts. Workers spin up in under 5ms on average.
Cost efficiency: You get to pay for only requests and not idle server time
Automatic scaling: Handle traffic spikes with zero configuration
Express.js applications run on centralized servers with the following characteristics:
Runtime Environment: Node.js provides a full operating system environment with access to file systems, network sockets, and long-running processes. Applications maintain state in memory across requests, enabling session management, connection pooling, and background job processing.
Request Lifecycle: When a request arrives, it traverses through a middleware stack where each function can modify the request, perform operations, and pass control to the next middleware. The server maintains context throughout this chain, enabling complex request-processing patterns.
Resource Management: Servers allocate dedicated resources, including memory, CPU, and network connections. Database connections are typically pooled and reused across requests. The application lifecycle includes startup, runtime, and graceful shutdown phases.
Workers operate on a fundamentally different model:
Distributed Execution: Code runs in over 300 data centres globally. Each request is routed to the nearest location to minimise latency. There's no single server; instead, your code exists as a distributed system automatically.
Isolate-based Runtime: Instead of spinning up containers or VMs, Workers use V8 isolates—lightweight execution contexts that start in under 5ms. Each request gets its own isolated environment, which is destroyed after completion.
Stateless by Default: Workers don't maintain state between requests. Every invocation starts fresh. This requires rethinking session management, caching strategies, and data persistence patterns.
Before we get started, the following requirements are essential to follow along:
An existing Express.js application
Node.js and npm installed
A Cloudflare account
Wrangler CLI - install via npm install -g wrangler on your local machine
There are several techniques you can use to migrate your Express.js application to Cloudflare Workers. In this article, we will be using the following technique:
const express = require('express');
const app = express();
app.use(express.json());
app.get('/api/health', (req, res) => {
res.json({ status: 'healthy' });
});
app.post('/api/users', (req, res) => {
const { name, email } = req.body;
res.status(201).json({ id: 123, name, email });
});
app.get('/api/users/:id', (req, res) => {
res.json({ id: req.params.id, name: 'Jane Doe' });
});
Hono is a lightweight framework for building web applications. It is a great choice for migrating your Express.js application to Cloudflare Workers because it is built on top of Cloudflare Workers and is a great way to get started. It is an Express-like framework designed for edge environments and provides familiar routing patterns with minimal refactoring.
To get started with Hono on Workers, you can create a new Worker project using the following command:
wrangler init my-worker
This will create a new Worker project with a default wrangler.toml file and a index.ts file.
You can then start the Worker locally using the following command:
wrangler dev
This will start the Worker locally on port 8787. You can then access the Worker at http://localhost:8787.
To deploy the Worker to Cloudflare, you can use the following command:
wrangler deploy
This will deploy the Worker to Cloudflare and you can then access the Worker at https://your-worker-name.cloudflare.workers.dev.
You can then access the Worker at https://your-worker-name.cloudflare.workers.dev.
To get the Worker's URL, you can use the following command:
wrangler url
This will return the Worker's URL.
You can then use the Worker's URL in your application to access the Worker.
hono packageInstall Hono using the following command:
npm install hono
You can also use the hono package to create a Worker. This is a great way to get started with Hono on Workers.
import { Hono } from 'hono';
const app = new Hono();
app.get('/api/health', (c) => {
return c.json({ status: 'healthy' });
});
app.post('/api/users', async (c) => {
const { name, email } = await c.req.json();
return c.json({ id: 123, name, email }, 201);
});
app.get('/api/users/:id', (c) => {
const id = c.req.param('id');
return c.json({ id, name: 'Jane Doe' });
});
export default app;
Hono remains a great choice for migrating your Express.js application to Cloudflare Workers because it mimics the Express.js API and syntax while running on the mordern infrastructure of Cloudflare Workers.
One common question is how middleware will be handled after migrating from Express.js to Hono. It is importnant to note that they both implement similar middleware patterns.
app.use((req, res, next) => {
console.log(`${req.method} ${req.path}`);
next();
});
app.use((c) => {
console.log(`${c.req.method} ${c.req.path}`);
return c.next();
});
As you can see, the middleware patterns are similar. The main difference is that Hono middleware is async and returns a Promise. This is because Hono middleware is executed in a different context than Express.js middleware. There are other libraries that can be used to replace several functionalities found in ExpressJS in Hono, for example:
cors -> hono/cors
compression -> hono/compress
jwt -> hono/jwt
logging -> hono/logger
Rate Limiting -> https://github.com/rhinobase/hono-rate-limiter
In express.js, environment variables are loaded using different libraries, for example: dotenv, config, env-cmd, nconf, etc. In Hono, a utilty method called env is provided to load environment variables across multiple runtimes and services.
In Workers for example, environment variables can be managed through the worker configuration file saved in format of a toml or jsonc file, for example: wrangler.toml or wrangler.jsonc.
In wrangler.toml, you can define environment variables for your Worker like this:
[vars]
...
API_KEY=...
API_URL=...
APP_ENV=production
...
Or in wrangler.jsonc, you can define environment variables for your Worker like this:
{
"vars": {
"API_KEY": "...",
"API_URL": "...",
"APP_ENV": "production",
... // other environment variables
}
}
You can then access the environment variables in your Worker using the env method:
import { Hono } from 'hono';
const app = new Hono<{ Bindings: Env }>();
app.get('/api/health', (c) => {
return c.json({ status: 'healthy', vars: c.env.APP_ENV });
});
... // other routes
export default app;
You can find more information about working with environment variables in Hono, working with environment variables in Workers and managing secrets in Workers.
In summary, we were able to successfully migrate an Express.js application to Cloudflare Workers using Hono. We were able to use the same middleware patterns, environment variables and routing patterns as we used in Express.js. We were also able to use the same API and syntax as we used in Express.js. This is good strategy at developing modern applications that are fast, scalable and efficient, with the added benefit of running on the edge of the internet.