Cloudflare を使い倒す Alchemy 編

この記事は ひとりCloudflareを使い倒す Advent Calendar 2025 の23日目です

こんにちは。@toreis です。
Workers を書くとこう思いませんか？「あーあ、Bindings 書くのめんどくせ〜〜〜」って。

そこで Alchemy です。

リソース管理なら Terraform もありますが、Terraform はどちらかというと DNS とか WAF を設定するものなので、Workers の Bindings 管理には向いていません。

そこで Alchemy です。(2回目)

タコスの人に教えてもらいました。

教えてもらったらやるしかないです。

ということで、この記事では Alchemy ってなんやねんをもとに、仕組みを理解していきたいかと思います。

Alchemy ってなんやねん

Alchemy is an embeddable, TypeScript-native Infrastructure-as-Code (IaC) library for modeling Resources that are Created, Updated and Deleted automatically.

Unlike similar tools like Pulumi, Terraform, and CloudFormation, Alchemy is implemented in pure ESM-native TypeScript code.

Resources are simple memoized async functions that can run in any JavaScript runtime, including the browser, serverless functions and durable workflows.

TypeScript で書ける IaC、リソースも自動で作ったり消したりしてくれるらしいです。

Cloudflare の Workers と Bindings の組み合わせ管理に特化したライブラリで、他にもフロントエンドフレームワークをくっつけても動くところがポイントです。

使い方はかなり簡単です。

コマンドをちょいちょい打って、alchemy.run.ts で Workers に乗せる Bindings を指定すると、wrangler.jsonc を書かなくても Bindings がくっついて動きます。

また、Nuxt や SvelteKit などのフレームワークが超簡単に Workers に載せられて動きます。

ここでは、何も考えずに Nuxt をデプロイしてみましょうか。

まずは pnpm dlx alchemy create hello-alchemy-nuxt --template=nuxt でプロジェクトを作ります。

出来上がったらば pnpm i でパッケージを入れます。

そして、pnpm alchemy dev で実行してみると

あら wrangler がないよって怒られてしまいました。
デフォルトで入れといてくれよって気持ちで pnpm i -D wrangler を使って追加します。

もう一度実行しましたらば、

動きましたね。アクセスできました。

気になるのは Using cloudflare-dev emulation in development mode. と書いてあるところです。

およそ Nuxt のサーバーである (要調査) Nitro が出しているものですね。

nuxt.config.ts を見ると、nitro に preset が渡っていて、cloudflare オプションにも alchemy がデフォルトで持っているコンフィグが渡っていますね。

nuxt.config.ts

import alchemy from "alchemy/cloudflare/nuxt";
import { defineNuxtConfig } from "nuxt/config";

// https://nuxt.com/docs/api/configuration/nuxt-config
export default defineNuxtConfig({
  devtools: { enabled: true },
  nitro: {
    preset: "cloudflare_module",
    cloudflare: alchemy(),
  },
  modules: ["nitro-cloudflare-dev"],
});

だからローカル検証の段階で Cloudflare の環境で動いてるよ、って感じなんですかね。

動くことはわかりましたので、デプロイしてティアダウンするまでやってみます。

まずは pnpm alchemy deploy でデプロイしてみます。

なんかお茶飲んでたらデプロイ出来てました。

最後、ティアダウン (インスタンス破棄) をして終わりです。

お茶飲むでもなく、コップに入れたくらいでティアダウン終わってました。

さて、なんで wrangler 入れてないのに動くんでしょうか

とはいえ入れましたが、これはおよそ Nuxt のためですね。

実際に、pnpm dlx alchemy create hello-alchemy で、typescript-worker をセットアップして実行すると、package.json には Wrangler はありませんが、動きます。

答えは src/ の中に。次のレポジトリを読んで、何がどうなっているか見ていきたいかと思います。

alchemy.run.ts は以下のようになっており、Worker 1 つを設定していますが、これはどうなっているんでしょうか。

まず Worker を呼び出したときの関数が src/cloudflare/worker.ts に実装されています。

_Worker を呼んでおり、これは大体 300 行くらいのコードで書かれています。

例えば、新しく Workers をアップロードしなければならないとき (create) で、既存の Worker を使わない (adopt オプションなし) であれば、まずは 1047 行目から始まります。
(857 行目はスキップ)

で、Worker を乗せる処理は 1050 行目から動いています。

あら、WorkerExists を使っていますね…
変数に使っている api についても見ていきます。

まず、api の実装は 988 行目にあります。

createCloudflareApi を使っていますね。
これは src/cloudflare/api.ts の 62 行目から定義しています。

この中で返している CloudflareApi は、この下 142 行目に定義されています。

ですが、一番おもしろいのはコンストラクタです。

どうやって動いているかわかってきてしまった気がします。

さて、戻って workerExists ですが、

api.get で直接 API を呼んでいますね。

このエンドポイントを叩いて、200 でダウンロードできれば存在している、の判定みたいです。

で、この結果存在していなければ putWorker を呼びます。

putWorker は結構下にいます。

まずは Worker をアップロードするための準備をしています。

で、エンドポイントを持ってきて PUT する指示も入っていますね。

これはエンドポイントが正式に存在します。

で、結果抽出する関数を挟んで api.fetch が呼ばれていますね。

返される extractCloudflareResult については、src/cloudflare/api-response.ts に定義されています。

動いていれば、result のデータを返す、そうでなければ相応のエラーを吐く、って感じですね。

Workers については理解しました。

なんかパターンが割れてきましたが、R2Bucket を見てみましょう。

bucket もとい、_R2Bucket が怪しいです。他の get や list 関数でも、bucket.name と参照しているためです。

_R2Bucket についても同じファイルに定義されています。

bucket 作成においては、ここで定義されています。

createBucket て。そのままの命名でいいですね。
そんな createBucket は以下の通りに実装されています。

叩いてますね。API。(倒置法)

ということで、API を叩いているから wrangler がいらない が答えでした。

おわりに

面白いライブラリに出会いました。ありがとうタコスの人。

Wrangler を叩くことなく、API のラッパーとして動いているのもいいですね。
フレームワークがナチュラルに使えるのも良いですね。

モノレポ構成も面白いです。

総じて、おもしろライブラリでございました。
ほな。