worker-express

Cloudflare Workers 向けの最小 Express 風ルーティングライブラリです。内部実装は TypeScript で管理し、配布物は ESM (dist/index.js) と型定義 (dist/index.d.ts) を同梱します。

インストール

npm i worker-express

最小サンプル

import express from 'worker-express';

const app = express();

app.get('/', (req, res) => {
  res.send('Hello World!');
});

export default app;

TypeScript 利用時も同じ import で型補完が有効になります。

サポート範囲

• 実行環境: Cloudflare Workers
• 開発 / 検証環境: Node.js LTS の最新 2 系統（現時点では 20, 22）
• 配布形式: ESM (dist/index.js) + 型定義 (dist/index.d.ts)
• 想定用途: Workers の fetch ハンドラとして export default app する最小構成

できること

• Cloudflare Workers で Express 風の最小ルーティングを組めます。
• app.use() によるミドルウェア実行ができます。
• path params と req.query を扱えます。
• JSON / text / urlencoded / multipart form の本文を扱えます。
• multipart form のファイルを req.files から配列で扱えます。
• res.status(), res.set(), res.send(), res.json(), res.end() を使えます。
• next(err) による最小の 500 応答へフォールバックできます。
• ルート一致後に未送信のまま next() で終わる fallthrough は 404 を返します。

既知の制約

• express.Router() や app.route() には未対応です。
• cookie / CORS helper や static 配信は未対応です。
• Node.js の HTTP サーバー実装としての Express 互換実行は対象外です。

Express との差分

• Express 互換を志向しますが、完全互換ではありません。
• 実行対象は Cloudflare Workers に限定し、Node.js の http.Server は扱いません。
• ルーティング API は MVP の最小セットに絞っており、express.Router() と app.route() は未対応です。
• method 不一致時にコアが 405 Method Not Allowed を自動では返しません。
• next(err) は最小の 500 応答へフォールバックし、Express の詳細なエラーハンドリング機構は未実装です。
• multipart form は Express 本体ではなく周辺ミドルウェアが担う領域ですが、本ライブラリでは Workers 向けの標準便利機能としてテキスト項目を req.body、ファイルを req.files に分離します。
• send/json/end の実行後は headersSent が true になり、status/set による後続変更は反映されません。
• res.json() は content-type 未設定時のみ application/json; charset=utf-8 を補完し、事前設定済みならその値を維持します。
• res.end() は低レベル API として暗黙の本文変換・content-type 補完を行いません。

安定性と互換性

• 0.x 系の間は MVP として改善を優先するため、API や挙動に breaking change が入る可能性があります。
• 互換性影響のある変更は、README・CHANGELOG・GitHub Releases で明示します。
• 今後の予定や breaking change 候補は ROADMAP.md で管理します。

対応API（MVP）

• express()
• app.use(middleware)
• app.get/post/put/patch/delete(path, ...handlers)
• req.method, req.url, req.path, req.query, req.params, req.headers, req.body, req.files
• res.status(code), res.set(name, value), res.send(body), res.json(data), res.end(body?)
• next(err) による 500 応答

Cloudflare Workers での実行

wrangler.toml 例:

name = "worker-express-example"
main = "src/index.ts"
compatibility_date = "2025-01-01"

src/index.ts で export default app すれば fetch ハンドラとして動作します。

開発方法

npm install
npm run lint
npm test

Workers 実行に近い確認は Miniflare を使った npm run test:integration で行えます。手動確認は Wrangler を使い、npm run dev:hello で examples/hello-world を起動します。

詳細ドキュメント

詳細な使い方は docs/USAGE.md を参照してください。npm 配布物にも同梱しています。

サポートと案内

• バグ報告や機能提案は GitHub Issues を利用してください。
• 使い方の相談や未確定な仕様の相談は GitHub Discussions を利用してください。
• 今後の対応予定は ROADMAP.md を参照してください。

ライセンス

MIT License