@bino0216/nitro-cloudflare-dev 0.2.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) Pooya Parsa <pooya@pi0.io>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,60 @@
+# Cloudflare Platform for Nitro and Nuxt
+
+This proof of concept module enables access to the Cloudflare runtime platform in the development server of [Nitro](https://nitro.unjs.io) and [Nuxt](https://nuxt.com) using the [new `getPlatformProxy` API](https://github.com/cloudflare/workers-sdk/pull/5002) exposed by [wrangler](https://developers.cloudflare.com/workers/wrangler/) and [miniflare](https://miniflare.dev/)
+
+> [!NOTE]
+> Nitro plans to introduce a new method to allow native dev presets, meaning you can natively run [miniflare](https://miniflare.dev/) as your development server without this module or a proxy in the future!
+
+## Usage
+
+First, install `nitro-cloudflare-dev` and `wrangler` packages as a dev dependency: ([unjs/nypm](https://nypm.unjs.io) will automatically detect your package manager!)
+
+```sh
+npx nypm@latest add -D wrangler nitro-cloudflare-dev
+```
+
+For **Nuxt** update `nuxt.config.ts`:
+
+```js
+export default defineNuxtConfig({
+  modules: ["nitro-cloudflare-dev"],
+});
+```
+
+For **Nitro** update `nitro.config.ts`:
+
+```js
+import nitroCloudflareBindings from "nitro-cloudflare-dev";
+
+export default defineNitroConfig({
+  modules: [nitroCloudflareBindings],
+});
+```
+
+## Configuration and persistence
+
+This module automatically finds the closest [`wrangler.toml`](https://developers.cloudflare.com/workers/wrangler/configuration/) file for configuration.
+
+Data is persisted `.wrangler/state/v3` directory. On first use of the module, it will be automatically added to the `.gitignore` file.
+
+You can configure additional options using `cloudflareDev: { }` in `nitro.config` or `nitro: { cloudflareDev: {} }` in `nuxt.config`.
+
+### Available options
+
+- `persistDir`: Sets the persist dir (default `.wrangler/state/v3`).
+- `configPath`: Sets a custom path for `wrangler.toml` file.
+- `silent`: Hide initial banner.
+- `environment`: Sets specific environment (useful for multi-environment configurations)
+
+## Development
+
+- Clone this repository
+- Install the latest LTS version of [Node.js](https://nodejs.org/en/)
+- Enable [Corepack](https://github.com/nodejs/corepack) using `corepack enable`
+- Install dependencies using `pnpm install`
+- Build in stub mode using `pnpm build --stub`
+- Run Nitro playground using `pnpm dev:nitro` or Nuxt playground using `pnpm dev:nuxt`
+
+## License
+
+[MIT](./LICENSE)

package/dist/index.d.mts

@@ -0,0 +1,41 @@
+import { PlatformProxy } from 'wrangler';
+
+declare module "h3" {
+    interface H3EventContext {
+        cf: PlatformProxy["cf"];
+        cloudflare: {
+            request: Request & {
+                cf: PlatformProxy["cf"];
+            };
+            env: PlatformProxy["env"];
+            context: PlatformProxy["ctx"];
+        };
+    }
+}
+
+interface RemoteBinding {
+    type: "r2" | "kv" | "d1";
+    name: string;
+    bucketName?: string;
+    databaseId?: string;
+    namespaceId?: string;
+}
+interface CloudflareDevOptions {
+    configPath?: string;
+    environment?: string;
+    persistDir?: string;
+    silent?: boolean;
+    remote?: {
+        accountId?: string;
+        apiToken?: string;
+    };
+}
+declare module "nitropack" {
+    interface NitroOptions {
+        cloudflareDev?: CloudflareDevOptions;
+    }
+}
+declare function nitroCloudflareDev(arg1: unknown, arg2: unknown): void;
+
+export { nitroCloudflareDev as default };
+export type { CloudflareDevOptions, RemoteBinding };

package/dist/index.d.ts

@@ -0,0 +1,41 @@
+import { PlatformProxy } from 'wrangler';
+
+declare module "h3" {
+    interface H3EventContext {
+        cf: PlatformProxy["cf"];
+        cloudflare: {
+            request: Request & {
+                cf: PlatformProxy["cf"];
+            };
+            env: PlatformProxy["env"];
+            context: PlatformProxy["ctx"];
+        };
+    }
+}
+
+interface RemoteBinding {
+    type: "r2" | "kv" | "d1";
+    name: string;
+    bucketName?: string;
+    databaseId?: string;
+    namespaceId?: string;
+}
+interface CloudflareDevOptions {
+    configPath?: string;
+    environment?: string;
+    persistDir?: string;
+    silent?: boolean;
+    remote?: {
+        accountId?: string;
+        apiToken?: string;
+    };
+}
+declare module "nitropack" {
+    interface NitroOptions {
+        cloudflareDev?: CloudflareDevOptions;
+    }
+}
+declare function nitroCloudflareDev(arg1: unknown, arg2: unknown): void;
+
+export { nitroCloudflareDev as default };
+export type { CloudflareDevOptions, RemoteBinding };

package/dist/index.mjs

@@ -0,0 +1,202 @@
+import { resolve, relative } from 'node:path';
+import { promises } from 'node:fs';
+import { fileURLToPath } from 'mlly';
+import { consola } from 'consola';
+import { colorize } from 'consola/utils';
+import { findFile } from 'pkg-types';
+
+function parseTomlBindings(content, key) {
+  const results = [];
+  const inlineMatch = content.match(new RegExp(`${key}\\s*=\\s*\\[([\\s\\S]*?)\\](?=\\n[a-z_]|\\n*$)`, "i"));
+  if (inlineMatch) {
+    const arrayContent = inlineMatch[1];
+    const objectMatches = arrayContent.match(/\{[^}]+\}/g);
+    if (objectMatches) {
+      for (const obj of objectMatches) {
+        const item = {};
+        const pairs = obj.match(/(\w+)\s*=\s*(?:"([^"]+)"|'([^']+)'|(\w+))/g);
+        if (pairs) {
+          for (const pair of pairs) {
+            const match = pair.match(/(\w+)\s*=\s*(?:"([^"]+)"|'([^']+)'|(\w+))/);
+            if (match) {
+              const k = match[1];
+              const v = match[2] || match[3] || match[4];
+              item[k] = v === "true" ? true : v === "false" ? false : v;
+            }
+          }
+        }
+        results.push(item);
+      }
+    }
+  }
+  const blockRegex = new RegExp(`\\[\\[${key}\\]\\]([\\s\\S]*?)(?=\\[\\[|$)`, "g");
+  let blockMatch;
+  while ((blockMatch = blockRegex.exec(content)) !== null) {
+    const block = blockMatch[1];
+    const item = {};
+    const lines = block.split("\n");
+    for (const line of lines) {
+      const match = line.match(/^(\w+)\s*=\s*(?:"([^"]+)"|'([^']+)'|(\w+))/);
+      if (match) {
+        const k = match[1];
+        const v = match[2] || match[3] || match[4];
+        item[k] = v === "true" ? true : v === "false" ? false : v;
+      }
+    }
+    if (Object.keys(item).length > 0) {
+      results.push(item);
+    }
+  }
+  return results;
+}
+async function parseWranglerConfig(configPath) {
+  const remoteBindings = [];
+  const content = await promises.readFile(configPath, "utf8");
+  if (configPath.endsWith(".toml")) {
+    const r2Bindings = parseTomlBindings(content, "r2_buckets");
+    for (const item of r2Bindings) {
+      if (item.remote === true && typeof item.binding === "string") {
+        remoteBindings.push({
+          type: "r2",
+          name: item.binding,
+          bucketName: typeof item.bucket_name === "string" ? item.bucket_name : void 0
+        });
+      }
+    }
+    const kvBindings = parseTomlBindings(content, "kv_namespaces");
+    for (const item of kvBindings) {
+      if (item.remote === true && typeof item.binding === "string") {
+        remoteBindings.push({
+          type: "kv",
+          name: item.binding,
+          namespaceId: typeof item.id === "string" ? item.id : void 0
+        });
+      }
+    }
+    const d1Bindings = parseTomlBindings(content, "d1_databases");
+    for (const item of d1Bindings) {
+      if (item.remote === true && typeof item.binding === "string") {
+        remoteBindings.push({
+          type: "d1",
+          name: item.binding,
+          databaseId: typeof item.database_id === "string" ? item.database_id : void 0
+        });
+      }
+    }
+  } else {
+    const jsonContent = content.replace(/\/\*[\s\S]*?\*\/|\/\/.*/g, "");
+    const config = JSON.parse(jsonContent);
+    if (config.r2_buckets) {
+      for (const bucket of config.r2_buckets) {
+        if (bucket.remote === true) {
+          remoteBindings.push({
+            type: "r2",
+            name: bucket.binding,
+            bucketName: bucket.bucket_name
+          });
+        }
+      }
+    }
+    if (config.kv_namespaces) {
+      for (const kv of config.kv_namespaces) {
+        if (kv.remote === true) {
+          remoteBindings.push({
+            type: "kv",
+            name: kv.binding,
+            namespaceId: kv.id
+          });
+        }
+      }
+    }
+    if (config.d1_databases) {
+      for (const d1 of config.d1_databases) {
+        if (d1.remote === true) {
+          remoteBindings.push({
+            type: "d1",
+            name: d1.binding,
+            databaseId: d1.database_id
+          });
+        }
+      }
+    }
+  }
+  return remoteBindings;
+}
+async function nitroModule(nitro) {
+  if (!nitro.options.dev) {
+    return;
+  }
+  let configPath = nitro.options.cloudflareDev?.configPath;
+  if (!configPath) {
+    configPath = await findFile(
+      ["wrangler.json", "wrangler.jsonc", "wrangler.toml"],
+      {
+        startingFrom: nitro.options.srcDir
+      }
+    ).catch(() => void 0);
+  }
+  let remoteBindings = [];
+  if (configPath) {
+    remoteBindings = await parseWranglerConfig(configPath).catch(() => []);
+  }
+  const persistDir = resolve(
+    nitro.options.rootDir,
+    nitro.options.cloudflareDev?.persistDir || ".wrangler/state/v3"
+  );
+  const gitIgnorePath = await findFile(".gitignore", {
+    startingFrom: nitro.options.rootDir
+  }).catch(() => void 0);
+  let addedToGitIgnore = false;
+  if (gitIgnorePath && persistDir === ".wrangler/state/v3") {
+    const gitIgnore = await promises.readFile(gitIgnorePath, "utf8");
+    if (!gitIgnore.includes(".wrangler/state/v3")) {
+      await promises.writeFile(gitIgnorePath, gitIgnore + "\n.wrangler/state/v3\n").catch(() => {
+      });
+      addedToGitIgnore = true;
+    }
+  }
+  if (!nitro.options.cloudflareDev?.silent) {
+    const remoteInfo = remoteBindings.length > 0 ? `
+Remote bindings: ${remoteBindings.map((b) => `${b.name} (${b.type})`).join(", ")}` : "";
+    consola.box(
+      [
+        "\u{1F525} Cloudflare context bindings enabled for dev server",
+        "",
+        `Config path: \`${configPath ? relative(".", configPath) : colorize("yellow", "cannot find `wrangler.json`, `wrangler.jsonc`, or `wrangler.toml`")}\``,
+        `Persist dir: \`${relative(".", persistDir)}\` ${addedToGitIgnore ? colorize("green", "(added to `.gitignore`)") : ""}`,
+        remoteInfo
+      ].join("\n")
+    );
+  }
+  nitro.options.runtimeConfig.wrangler = {
+    ...nitro.options.runtimeConfig.wrangler,
+    configPath,
+    persistDir,
+    environment: nitro.options.cloudflareDev?.environment,
+    remoteBindings,
+    remoteCredentials: {
+      accountId: nitro.options.cloudflareDev?.remote?.accountId || process.env.CF_ACCOUNT_ID,
+      apiToken: nitro.options.cloudflareDev?.remote?.apiToken || process.env.CF_API_TOKEN
+    }
+  };
+  nitro.options.externals.inline = nitro.options.externals.inline || [];
+  nitro.options.externals.inline.push(
+    fileURLToPath(new URL("runtime/", import.meta.url))
+  );
+  nitro.options.plugins = nitro.options.plugins || [];
+  nitro.options.plugins.push(
+    fileURLToPath(new URL("runtime/plugin.dev", import.meta.url))
+  );
+}
+function nitroCloudflareDev(arg1, arg2) {
+  if (arg2?.options?.nitro) {
+    arg2.hooks.hookOnce("nitro:config", (nitroConfig) => {
+      nitroConfig.modules = nitroConfig.modules || [];
+      nitroConfig.modules.push(nitroModule);
+    });
+  } else {
+    nitroModule(arg1);
+  }
+}
+
+export { nitroCloudflareDev as default };

package/dist/runtime/plugin.dev.d.ts

@@ -0,0 +1,3 @@
+import type { NitroAppPlugin } from "nitropack";
+declare const _default: NitroAppPlugin;
+export default _default;

package/dist/runtime/plugin.dev.mjs

@@ -0,0 +1,111 @@
+import { useRuntimeConfig, getRequestURL } from "#imports";
+const _proxy = _getPlatformProxy().catch((error) => {
+  console.error("Failed to initialize wrangler bindings proxy", error);
+  return _createStubProxy();
+}).then((proxy) => {
+  globalThis.__env__ = proxy.env;
+  return proxy;
+});
+globalThis.__env__ = _proxy.then((proxy) => proxy.env);
+export default (function(nitroApp) {
+  nitroApp.hooks.hook("request", async (event) => {
+    const proxy = await _proxy;
+    event.context.cf = proxy.cf;
+    event.context.waitUntil = proxy.ctx.waitUntil.bind(proxy.ctx);
+    const request = new Request(getRequestURL(event));
+    request.cf = proxy.cf;
+    event.context.cloudflare = {
+      ...event.context.cloudflare,
+      request,
+      env: proxy.env,
+      context: proxy.ctx
+    };
+    event.node.req.__unenv__ = {
+      ...event.node.req.__unenv__,
+      waitUntil: event.context.waitUntil
+    };
+  });
+  nitroApp.hooks._hooks.request.unshift(nitroApp.hooks._hooks.request.pop());
+  nitroApp.hooks.hook("close", () => {
+    return _proxy?.then((proxy) => proxy.dispose);
+  });
+});
+async function _getPlatformProxy() {
+  const runtimeConfig = useRuntimeConfig();
+  const { remoteBindings, remoteCredentials } = runtimeConfig.wrangler;
+  const _pkg = "wrangler";
+  const { getPlatformProxy } = await import(_pkg).catch(() => {
+    throw new Error(
+      "Package `wrangler` not found, please install it with: `npx nypm@latest add -D wrangler`"
+    );
+  });
+  const proxyOptions = {
+    configPath: runtimeConfig.wrangler.configPath,
+    persist: { path: runtimeConfig.wrangler.persistDir }
+  };
+  if (runtimeConfig.wrangler.environment) {
+    proxyOptions.environment = runtimeConfig.wrangler.environment;
+  }
+  const proxy = await getPlatformProxy(proxyOptions);
+  if (remoteBindings.length > 0 && remoteCredentials.accountId && remoteCredentials.apiToken) {
+    const { getBindings } = await import("openwrangler");
+    const openBindings = getBindings({
+      accountId: remoteCredentials.accountId,
+      apiToken: remoteCredentials.apiToken
+    });
+    for (const binding of remoteBindings) {
+      switch (binding.type) {
+        case "r2": {
+          proxy.env[binding.name] = openBindings.r2;
+          break;
+        }
+        case "kv": {
+          proxy.env[binding.name] = openBindings.kv;
+          break;
+        }
+        case "d1": {
+          proxy.env[binding.name] = openBindings.d1;
+          break;
+        }
+      }
+    }
+  }
+  return proxy;
+}
+function _createStubProxy() {
+  return {
+    env: {},
+    cf: {},
+    ctx: {
+      waitUntil() {
+      },
+      passThroughOnException() {
+      },
+      props: {}
+    },
+    caches: {
+      open() {
+        const result = Promise.resolve(new _CacheStub());
+        return result;
+      },
+      get default() {
+        return new _CacheStub();
+      }
+    },
+    dispose: () => Promise.resolve()
+  };
+}
+class _CacheStub {
+  delete() {
+    const result = Promise.resolve(false);
+    return result;
+  }
+  match() {
+    const result = Promise.resolve(void 0);
+    return result;
+  }
+  put() {
+    const result = Promise.resolve();
+    return result;
+  }
+}

package/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "@bino0216/nitro-cloudflare-dev",
+  "private": false,
+  "version": "0.2.2",
+  "description": "POC module to enable access to the Cloudflare runtime bindings in development server of Nitro and Nuxt",
+  "repository": "pi0/nitro-cloudflare-dev",
+  "license": "MIT",
+  "sideEffects": false,
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.mjs"
+    },
+    "./dist/runtime/*": {
+      "types": "./dist/runtime/*.d.ts",
+      "default": "./dist/runtime/*.mjs"
+    }
+  },
+  "main": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "resolutions": {
+    "@binochoi/nitro-cloudflare-dev": "workspace:*"
+  },
+  "dependencies": {
+    "consola": "^3.4.0",
+    "mlly": "^1.7.4",
+    "pkg-types": "^2.1.0",
+    "openwrangler": "0.0.1"
+  },
+  "devDependencies": {
+    "@cloudflare/workers-types": "^4.20250303.0",
+    "@types/node": "^22.13.9",
+    "changelogen": "^0.6.1",
+    "eslint": "^9.21.0",
+    "eslint-config-unjs": "^0.4.2",
+    "h3": "^1.15.1",
+    "jiti": "^2.4.2",
+    "miniflare": "^3.20250224.0",
+    "nitropack": "^2.11.2",
+    "nuxt": "^3.15.4",
+    "prettier": "^3.5.3",
+    "typescript": "^5.8.2",
+    "unbuild": "^3.5.0",
+    "wrangler": "^3.113.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "unbuild",
+    "dev:nitro": "pnpm run -C examples/nitro dev",
+    "dev:nuxt": "pnpm run -C examples/nuxt dev",
+    "lint": "eslint --cache . && prettier -c src",
+    "lint:fix": "eslint --cache . --fix && prettier -c src -w",
+    "release": "pnpm test && pnpm build && changelogen --release && npm publish && git push --follow-tags",
+    "test": "pnpm lint && pnpm test:types",
+    "test:types": "tsc --noEmit --skipLibCheck"
+  }
+}