rsbuild-plugin-cloudflare 0.0.0 → 0.0.1

package/LICENSE

@@ -0,0 +1,25 @@
+Copyright (c) 2020 Cloudflare, Inc. <wrangler@cloudflare.com>
+
+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

@@ -1,3 +1,229 @@
-# rsbuild-plugin-cloudflare
+# `rsbuild-plugin-cloudflare`
 
-This is a placeholder release. The plugin isn't published yet.
+An experimental [Rsbuild](https://rsbuild.rs) plugin for Cloudflare Workers. It
+runs your Workers in workerd during `rsbuild dev` and `rsbuild preview`, and
+builds them, with your client assets, during `rsbuild build` into a Cloudflare
+Build Output that you can deploy with `cf deploy --prebuilt`.
+
+It's built on the internals of
+[`@cloudflare/vite-plugin`](https://developers.cloudflare.com/workers/vite-plugin/),
+and accepts the same options.
+
+> **Using TanStack Start?** Follow the [TanStack Start guide](#tanstack-start):
+> the framework's server environment has to be set as the Worker's, or every
+> request fails.
+
+## Usage
+
+```ts
+// rsbuild.config.ts
+import { cloudflare } from "rsbuild-plugin-cloudflare";
+import { defineConfig } from "@rsbuild/core";
+
+export default defineConfig({
+	plugins: [cloudflare()],
+});
+```
+
+The Worker is configured in `cloudflare.config.ts`, as for the Vite plugin.
+
+### Options
+
+The options are those of the Vite plugin's `cloudflare()` (e.g. `config`,
+`auxiliaryWorkers`, `persistState`, `inspectorPort`, `remoteBindings`), apart
+from `tunnel`, and with `rsbuildEnvironment` in place of `viteEnvironment`
+(see [Worker environments](#worker-environments)), plus:
+
+- `envDir`: the directory to load `.env` and `.dev.vars` files from, or `false`
+  to skip them. Defaults to the project root.
+- `envMode`: the mode used to load `cloudflare.config.ts`, `.env.[mode]` and
+  `.dev.vars.[mode]`. Defaults to Rsbuild's mode.
+
+### Worker environments
+
+Each Worker is built by an
+[Rsbuild environment](https://rsbuild.rs/config/environments). The entry
+Worker's is named `cloudflare`, unless `rsbuildEnvironment.name` is set.
+Auxiliary Workers' are named as in the Vite plugin, unless their own
+`rsbuildEnvironment.name` is set. `rsbuildEnvironment` replaces the Vite
+plugin's `viteEnvironment`, without `childEnvironments`.
+
+To change how a Worker is built, configure its environment in Rsbuild's
+`environments` config. The plugin merges its settings in, and yours take
+precedence, apart from `source.entry`, `output.target` and `output.module`,
+which the plugin always sets so that the Worker runs in workerd, and
+`output.distPath.root`, which it sets to the Worker's Build Output location, as
+the Vite plugin does.
+
+```ts
+export default defineConfig({
+	plugins: [cloudflare()],
+	environments: {
+		cloudflare: { output: { minify: true } },
+	},
+});
+```
+
+### Frameworks
+
+As with the Vite plugin, put `cloudflare()` before the framework's plugins, and
+set `rsbuildEnvironment.name` to the framework's server environment. The plugin
+builds that environment for workerd, whatever target the framework sets.
+
+In dev, the Worker environment's `loadBundle()` returns a module whose `fetch`
+sends requests to the Worker in workerd, so frameworks that serve their server
+bundle through `loadBundle()`, such as
+[TanStack Start](https://tanstack.com/start), run it in workerd.
+
+#### TanStack Start
+
+To run a [TanStack Start](https://tanstack.com/start) app that's built with
+Rsbuild (e.g. one created from TanStack's Rsbuild template) on Workers:
+
+1. Install the plugin, and [`cf`](https://www.npmjs.com/package/cf) for
+   `cf/config` and `cf deploy`:
+
+   ```sh
+   pnpm add -D rsbuild-plugin-cloudflare cf
+   ```
+
+2. Configure the Worker in `cloudflare.config.ts`, with TanStack Start's server
+   entry as its entrypoint. TanStack Start uses Node.js APIs, such as
+   `AsyncLocalStorage`. From compatibility date `2026-08-04`,
+   [Node.js compatibility](https://developers.cloudflare.com/workers/runtime-apis/nodejs/)
+   is on by default; with an earlier date, add the `nodejs_compat` flag.
+
+   ```ts
+   // cloudflare.config.ts
+   import { defineConfig } from "cf/config";
+
+   export default defineConfig({
+   	worker: {
+   		name: "my-tanstack-start-app",
+   		entrypoint: "@tanstack/react-start/server-entry",
+   		compatibilityDate: "2026-10-19",
+   	},
+   });
+   ```
+
+3. Add `cloudflare()` before `tanstackStart()`, with `rsbuildEnvironment.name`
+   set to TanStack Start's server environment, `ssr`. This is required: without
+   it, the plugin builds the entrypoint in its own `cloudflare` environment,
+   without TanStack Start's build setup, and every request fails (e.g. with
+   `tsrStartManifest is not a function`).
+
+   ```ts
+   // rsbuild.config.ts
+   import { defineConfig } from "@rsbuild/core";
+   import { pluginReact } from "@rsbuild/plugin-react";
+   import { tanstackStart } from "@tanstack/react-start/plugin/rsbuild";
+   import { cloudflare } from "rsbuild-plugin-cloudflare";
+
+   export default defineConfig({
+   	plugins: [
+   		pluginReact(),
+   		cloudflare({ rsbuildEnvironment: { name: "ssr" } }),
+   		tanstackStart(),
+   	],
+   });
+   ```
+
+4. Replace the template's scripts. Its `start` script runs the server in
+   Node.js, so it doesn't apply; `rsbuild preview` runs the build in workerd.
+
+   ```json
+   {
+   	"scripts": {
+   		"dev": "rsbuild dev",
+   		"build": "rsbuild build",
+   		"preview": "rsbuild preview",
+   		"deploy": "rsbuild build && cf deploy --prebuilt"
+   	}
+   }
+   ```
+
+5. Add `.cloudflare` to `.gitignore`. It holds the bindings' local state, the
+   Build Output, and the Worker's types, which are generated to
+   `.cloudflare/types`: add that to `tsconfig.json`'s `include` to use them.
+
+Server functions and server routes can then use the Worker's bindings:
+
+```ts
+import { createServerFn } from "@tanstack/react-start";
+import { env } from "cloudflare:workers";
+
+const getGreeting = createServerFn().handler(() => env.GREETING);
+```
+
+See [`packages/e2e/fixtures/tanstack-start`](https://github.com/james-elicx/rsbuild-plugin-cloudflare/tree/main/packages/e2e/fixtures/tanstack-start) for
+a complete app.
+
+## Differences from the Vite plugin
+
+The plugin replaces Vite's module runner with Rsbuild's bundles, so behaviour
+that depends on how Vite works internally isn't available:
+
+- Workers are rebuilt and reloaded when their code changes; there's no in-Worker
+  HMR (`import.meta.hot`).
+- Uncaught errors in the entry Worker aren't returned to the dev server with
+  the `MF-Experimental-Error-Stack` header, as the Vite plugin's module runner
+  does, so there's no error overlay or source-mapped stack: the browser gets a
+  plain-text `500` response.
+- Child environments, the hot channel, `bundledDev`, middleware mode, custom
+  `buildApp`s and Vite plugins (e.g. for virtual modules) don't apply.
+- Prerendering isn't supported, as Rsbuild has no equivalent of `buildApp`. The
+  prerender Worker is still built and written to the Build Output.
+- Containers aren't supported yet: in dev and preview, a warning is logged and
+  Container-backed Durable Objects fail; in a build, a warning is logged and no
+  Container images or Container output are written.
+- `tunnel` and the Vite CLI shortcuts aren't supported.
+- The Local Explorer hint that the Vite plugin prints for AI agents isn't
+  printed.
+
+Other differences:
+
+- Rsbuild serves `/` and `*.html` itself, so the plugin intercepts page
+  navigations (`GET` and `HEAD` requests for `.html` paths or paths without an
+  extension, apart from Rsbuild's HMR path and paths starting with `/__` or
+  `/rsbuild-`) and sends them to the Workers. These requests reach the Workers
+  before Rsbuild's `server.proxy`.
+- In dev, Rsbuild also serves the Worker environments' output (e.g.
+  `/index.js` and `/index.js.map`), as it serves the assets of every
+  `web-worker` environment.
+- When workerd restarts, the Vite plugin restarts the dev server; the Rsbuild
+  bundles don't depend on workerd's state, so the plugin doesn't.
+- Setting `output.externals` (other than Node.js built-ins) for a Worker's
+  environment logs a warning, where the Vite plugin rejects `resolve.external`,
+  as Rsbuild also applies top-level externals to every environment.
+- Config changes (e.g. to `cloudflare.config.ts` or `.dev.vars`) restart
+  Rsbuild's dev server, which closes the old server first: a broken config
+  leaves no server running, whereas the Vite plugin keeps the old one. Miniflare
+  is recreated rather than updated.
+- The Rsbuild CLI loads `.env`, `.env.local`, `.env.[mode]` and
+  `.env.[mode].local` into `process.env`, using its own env mode and directory
+  rather than `envMode` and `envDir`. `process.env` takes precedence over the
+  plugin's `.env` files, so these values override the Worker's `.env` values. A
+  `.dev.vars` file is used on its own, so it isn't affected.
+- The top-level `output.minify` setting for JavaScript, and the top-level
+  `resolve.extensions`, `resolve.conditionNames` and `resolve.mainFields`, don't
+  apply to Workers: the plugin sets these for the Worker environments, and
+  Rsbuild uses an environment's settings over the top-level ones. Set them in
+  `environments.<name>` instead. The top-level `output.sourceMap`, and the
+  `output.minify` setting for CSS, do apply.
+- Without `source.entry` or client environments, a client is built from
+  Rsbuild's default entry (`src/index.*`) only when `index.html` exists at the
+  project root, where Vite builds one whenever `index.html` exists. The default
+  entry mustn't be a Worker's entrypoint, but an entrypoint that's an alias or a
+  bare specifier isn't recognised as it. Rsbuild doesn't use that `index.html`
+  as the page's template unless `html.template` is set to it. Without a client,
+  as in the Vite plugin, the client output has only the public assets (and the
+  assets that the entry Worker imports), and `assetsOnly` requires public assets
+  or a prerender Worker.
+- `devOnly` and `assetsOnly` functions are called when the config is resolved,
+  to choose the Worker environments to build, rather than lazily at build time.
+- Additional modules (e.g. `.wasm` and `.txt` imports) are emitted at the root
+  of the Worker's output directory, with hashed names, rather than in `assets/`.
+- SWC lowers `using` declarations in the Worker build, which Vite keeps.
+- No "Debug" URL is printed, but `/__debug` works.
+- Miniflare's message about updating the compatibility date mentions
+  `@cloudflare/vite-plugin`.

package/dist/chunk-53YJWLG7-_ps118Xl.mjs

@@ -0,0 +1,43 @@
+import { createRequire } from "node:module";
+
+//#region ../../workers-sdk/packages/workers-utils/dist/chunk-53YJWLG7.mjs
+const require$1 = createRequire(import.meta.url || (typeof __filename === "string" ? __filename : "/"));
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __name = (target, value) => __defProp(target, "name", {
+	value,
+	configurable: true
+});
+var __require = /* @__PURE__ */ ((x) => typeof require$1 !== "undefined" ? require$1 : typeof Proxy !== "undefined" ? new Proxy(x, { get: (a, b) => (typeof require$1 !== "undefined" ? require$1 : a)[b] }) : x)(function(x) {
+	if (typeof require$1 !== "undefined") return require$1.apply(this, arguments);
+	throw Error("Dynamic require of \"" + x + "\" is not supported");
+});
+var __commonJS = (cb, mod) => function __require2() {
+	return mod || (0, cb[__getOwnPropNames(cb)[0]])((mod = { exports: {} }).exports, mod), mod.exports;
+};
+var __export = (target, all) => {
+	for (var name in all) __defProp(target, name, {
+		get: all[name],
+		enumerable: true
+	});
+};
+var __copyProps = (to, from, except, desc) => {
+	if (from && typeof from === "object" || typeof from === "function") {
+		for (let key of __getOwnPropNames(from)) if (!__hasOwnProp.call(to, key) && key !== except) __defProp(to, key, {
+			get: () => from[key],
+			enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
+		});
+	}
+	return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", {
+	value: mod,
+	enumerable: true
+}) : target, mod));
+
+//#endregion
+export { __toESM as a, __require as i, __export as n, __name as r, __commonJS as t };

package/dist/index.d.mts

@@ -0,0 +1,123 @@
+import { InputWorkerConfig, ParsedInputWorkerConfig } from "@cloudflare/config";
+import { RsbuildPlugin } from "@rsbuild/core";
+
+//#region ../../workers-sdk/packages/vite-plugin-cloudflare/src/plugin-config.d.ts
+
+type PersistState = boolean | {
+  path: string;
+};
+type TunnelConfig = {
+  autoStart?: boolean;
+  name?: string;
+  /** Email addresses or domain patterns allowed to authenticate to a Quick Tunnel. */
+  allowedMail?: string[];
+};
+interface BaseWorkerOptions {
+  viteEnvironment?: {
+    name?: string;
+    childEnvironments?: string[];
+  };
+}
+/**
+ * Whether this Worker is only used during development and should not be built for production.
+ * Can be a boolean or a function that returns a boolean. The function is evaluated lazily
+ * at build time, allowing frameworks to provide the value after initialization.
+ */
+type DevOnly = boolean | (() => boolean);
+interface EntryWorkerOptions extends BaseWorkerOptions {
+  config?: EntryWorkerConfigCustomizer;
+  /**
+   * Whether the entry Worker should be omitted from the production build.
+   * Can be a boolean or a function that returns a boolean. The function is
+   * evaluated lazily at build time, allowing frameworks to provide the value
+   * after initialization.
+   *
+   * When set, an assets-only Build Output config is emitted. This enables using
+   * server-side code in development but producing a fully static app for
+   * deployment.
+   */
+  assetsOnly?: DevOnly;
+}
+interface AuxiliaryWorkerOptions extends BaseWorkerOptions {
+  /** Configure an auxiliary Worker. */
+  config: WorkerConfigProvider;
+  devOnly?: DevOnly;
+}
+interface PrerenderWorkerOptions extends BaseWorkerOptions {
+  config: WorkerConfigProvider;
+}
+interface TypeGenerationOptions {
+  /**
+   * Whether to auto-generate `.cloudflare/types/index.d.ts`. Defaults to
+   * `true`.
+   */
+  generate?: boolean;
+  /**
+   * Whether to include the Worker's runtime types (generated from the
+   * project's compatibility date and flags) in the generated
+   * `.cloudflare/types/index.d.ts`. Defaults to `true`.
+   */
+  includeRuntime?: boolean;
+}
+interface Experimental {
+  /** Experimental support for handling the _headers and _redirects files during Vite dev mode. */
+  headersAndRedirectsDevModeSupport?: boolean;
+}
+type EntryWorkerConfigCustomizer = Partial<ParsedInputWorkerConfig> | ((config: ParsedInputWorkerConfig) => Partial<ParsedInputWorkerConfig> | void);
+type WorkerConfigProvider = InputWorkerConfig | ((options: {
+  entryWorkerConfig: ParsedInputWorkerConfig;
+}) => InputWorkerConfig);
+interface PluginConfig$1 extends EntryWorkerOptions {
+  auxiliaryWorkers?: AuxiliaryWorkerOptions[];
+  /** Configuration for a dedicated prerender Worker. */
+  prerenderWorker?: PrerenderWorkerOptions;
+  persistState?: PersistState;
+  inspectorPort?: number | false;
+  remoteBindings?: boolean;
+  tunnel?: boolean | TunnelConfig;
+  /**
+   * Options for generating Worker types from `cloudflare.config.ts`. Type
+   * generation is skipped when the file does not exist.
+   */
+  types?: TypeGenerationOptions;
+  experimental?: Experimental;
+}
+//#endregion
+//#region src/index.d.ts
+/** Options for the Rsbuild environment that builds a Worker. */
+interface RsbuildEnvironmentOptions {
+  /**
+   * The Rsbuild environment that builds the Worker, in place of the Vite
+   * plugin's `viteEnvironment`. `name` is its key in Rsbuild's
+   * `environments` config.
+   */
+  rsbuildEnvironment?: {
+    name?: string;
+  };
+}
+/** A Worker's options in the Vite plugin, with `rsbuildEnvironment` in place of `viteEnvironment`. */
+type RsbuildWorkerOptions<T> = Omit<T, "viteEnvironment"> & RsbuildEnvironmentOptions;
+/**
+ * The same options as the Vite plugin's `cloudflare()`, apart from the tunnel,
+ * with `rsbuildEnvironment` in place of `viteEnvironment`.
+ */
+interface PluginConfig extends RsbuildWorkerOptions<Omit<PluginConfig$1, "tunnel" | "auxiliaryWorkers" | "prerenderWorker">> {
+  auxiliaryWorkers?: Array<RsbuildWorkerOptions<NonNullable<PluginConfig$1["auxiliaryWorkers"]>[number]>>;
+  prerenderWorker?: RsbuildWorkerOptions<NonNullable<PluginConfig$1["prerenderWorker"]>>;
+  /** The directory to load `.env` and `.dev.vars` files from, or `false` to skip them. Defaults to the project root. */
+  envDir?: string | false;
+  /** The mode used to load `cloudflare.config.ts`, `.env.[mode]` and `.dev.vars.[mode]`. Defaults to Rsbuild's mode. */
+  envMode?: string;
+}
+/**
+ * Rsbuild plugin that builds the Workers defined in `cloudflare.config.ts` and
+ * the plugin options with rspack and runs them in workerd (via Miniflare)
+ * during `rsbuild dev`. `rsbuild build` writes the Build Output Specification
+ * to `.cloudflare/output`, which `rsbuild preview` runs in workerd.
+ *
+ * @param options Plugin options.
+ * @returns An Rsbuild plugin.
+ */
+declare function cloudflare(options?: PluginConfig): RsbuildPlugin;
+//#endregion
+export { PluginConfig, cloudflare };