@distilled.cloud/cloudflare-rolldown-plugin 0.3.0 → 0.4.1-beta.1

package/src/plugins/additional-modules.ts

@@ -1,8 +1,16 @@
+import MagicString from "magic-string";
 import path from "node:path";
-import { RolldownMagicString, type Plugin } from "rolldown";
+import type {
+  Plugin,
+  PluginContext,
+  RenderedChunk,
+  RolldownMagicString,
+  SourceMap,
+} from "rolldown";
+import { createPlugin } from "../factory.js";
 import { sanitizePath } from "../utils.js";
 
-const MODULE_RULES = [
+export const MODULE_RULES = [
   { type: "CompiledWasm", pattern: /\.wasm(\?module)?$/ },
   { type: "Data", pattern: /\.bin$/ },
   { type: "Text", pattern: /\.(txt|html|sql)$/ },
@@ -12,71 +20,97 @@ const MODULE_REFERENCE_PATTERN = `__CLOUDFLARE_MODULE__(${MODULE_RULES.map((rule
 const MODULE_REFERENCE_REGEX = new RegExp(MODULE_REFERENCE_PATTERN);
 const MODULE_REFERENCE_GLOBAL_REGEX = new RegExp(MODULE_REFERENCE_PATTERN, "g");
 
-export function makeAdditionalModulesPlugin(): Plugin {
+export const additionalModulesPlugin = createPlugin("additional-modules", () => {
   const additionalModulePaths = new Set<string>();
-
   return {
-    name: "rolldown-plugin-cloudflare:additional-modules",
-    // TODO: these are Vite options, not Rolldown
-    // enforce: "pre",
-    // applyToEnvironment(environment) {
-    //   return environment.name === "development";
-    // },
-    // hotUpdate(options) {
-    //   if (additionalModulePaths.has(options.file)) {
-    //     void options.server.restart();
-    //     return [];
-    //   }
-    // },
-    resolveId: {
-      filter: { id: MODULE_RULES.map((rule) => rule.pattern) },
-      async handler(source, importer, options) {
-        const resolved = await this.resolve(source, importer, options);
-        if (!resolved) {
-          return;
+    vite: {
+      enforce: "pre",
+      hotUpdate(options) {
+        if (additionalModulePaths.has(options.file)) {
+          void options.server.restart();
+          return [];
         }
+      },
+    },
+    shared: {
+      resolveId: {
+        filter: { id: MODULE_RULES.map((rule) => rule.pattern) },
+        async handler(source, importer, options) {
+          const resolved = await this.resolve(source, importer, options);
+          if (!resolved) {
+            return;
+          }
 
-        const rule = MODULE_RULES.find((rule) => rule.pattern.test(resolved.id));
-        if (!rule) {
-          return resolved;
-        }
+          const rule = MODULE_RULES.find((rule) => rule.pattern.test(resolved.id));
+          if (!rule) {
+            return resolved;
+          }
 
-        const filePath = sanitizePath(resolved.id);
-        additionalModulePaths.add(filePath);
+          const filePath = sanitizePath(resolved.id);
+          additionalModulePaths.add(filePath);
 
-        return {
-          external: true,
-          id: moduleReferenceId(rule.type, filePath),
-        };
+          return {
+            id: moduleReferenceId(rule.type, filePath),
+            external: true,
+          };
+        },
       },
-    },
-    renderChunk: {
-      filter: { code: { include: MODULE_REFERENCE_REGEX } },
-      async handler(code, chunk) {
-        const matches = code.matchAll(MODULE_REFERENCE_GLOBAL_REGEX);
-        let magicString: RolldownMagicString | undefined;
-        for (const match of matches) {
-          magicString ??= new RolldownMagicString(code);
-          const [full, , id] = match;
-          const source = await this.fs.readFile(id);
-          const referenceId = this.emitFile({
-            type: "asset",
-            name: path.basename(id),
-            source,
-          });
-          const fileName = this.getFileName(referenceId);
-          const relativePath = path.relative(path.dirname(chunk.fileName), fileName);
-          const importPath = relativePath.startsWith(".") ? relativePath : `./${relativePath}`;
-          magicString.update(match.index, match.index + full.length, importPath);
-        }
-        if (magicString) {
-          return magicString;
-        }
+      renderChunk: {
+        filter: { code: { include: MODULE_REFERENCE_REGEX } },
+        handler: withMagicString(async function (code, chunk, magicString) {
+          const matches = code.matchAll(MODULE_REFERENCE_GLOBAL_REGEX);
+          for (const match of matches) {
+            const [full, , id] = match;
+            const source = await this.fs.readFile(id);
+            const referenceId = this.emitFile({
+              type: "asset",
+              name: path.basename(id),
+              source,
+            });
+            const fileName = this.getFileName(referenceId);
+            const relativePath = path.relative(path.dirname(chunk.fileName), fileName);
+            const importPath = relativePath.startsWith(".") ? relativePath : `./${relativePath}`;
+            magicString.update(match.index, match.index + full.length, importPath);
+          }
+        }),
       },
     },
   };
-}
+});
 
 function moduleReferenceId(type: "CompiledWasm" | "Data" | "Text", id: string) {
   return `__CLOUDFLARE_MODULE__${type}__${id}__CLOUDFLARE_MODULE__` as const;
 }
+
+type PluginHandler<T extends keyof Plugin> = Plugin[T] extends infer T
+  ? T extends (...args: any) => any
+    ? T
+    : never
+  : never;
+
+/**
+ * Returns a `renderChunk` handler that transforms the chunk using a magic string.
+ * Uses Rolldown's native magic string if available, or the `magic-string` library otherwise.
+ */
+function withMagicString(
+  renderChunk: (
+    this: PluginContext,
+    code: string,
+    chunk: RenderedChunk,
+    magicString: MagicString | RolldownMagicString,
+  ) => Promise<void>,
+): PluginHandler<"renderChunk"> {
+  return async function (code, chunk, outputOptions, meta) {
+    const magicString = meta.magicString ?? new MagicString(code);
+    await renderChunk.call(this, code, chunk, magicString);
+    if ("isRolldownMagicString" in magicString && magicString.isRolldownMagicString) {
+      return magicString;
+    }
+    return {
+      code: magicString.toString(),
+      map: outputOptions.sourcemap
+        ? (magicString.generateMap({ hires: "boundary" }) as SourceMap)
+        : null,
+    };
+  };
+}

package/src/plugins/cloudflare-externals.ts

@@ -1,6 +1,6 @@
-import type { Plugin } from "rolldown";
+import { createPlugin } from "../factory.js";
 
-const CLOUDFLARE_BUILTIN_MODULES = [
+const CLOUDFLARE_BUILT_IN_MODULES = [
   "cloudflare:email",
   "cloudflare:node",
   "cloudflare:sockets",
@@ -8,19 +8,40 @@ const CLOUDFLARE_BUILTIN_MODULES = [
   "cloudflare:workflows",
 ];
 
-export const cloudflareExternalsPlugin: Plugin = {
-  name: "rolldown-plugin-cloudflare:cloudflare-externals",
-  resolveId: {
-    filter: { id: /^cloudflare:/ },
-    handler(id) {
-      if (!CLOUDFLARE_BUILTIN_MODULES.includes(id)) {
-        return;
-      }
+export const cloudflareExternalsPlugin = createPlugin("cloudflare-externals", () => {
+  return {
+    rolldown: {
+      resolveId: {
+        filter: { id: /^cloudflare:/ },
+        handler(id) {
+          if (!CLOUDFLARE_BUILT_IN_MODULES.includes(id)) {
+            return;
+          }
 
-      return {
-        id,
-        external: true,
-      };
+          return {
+            id,
+            external: true,
+          };
+        },
+      },
     },
-  },
-};
+    vite: {
+      enforce: "pre",
+      configEnvironment(name) {
+        if (name === "client") {
+          // Some frameworks allow users to mix client and server code in the same file and then extract the server code.
+          // As the dependency optimization may happen before the server code is extracted, we should exclude Cloudflare built-ins from client optimization.
+          return { optimizeDeps: { exclude: CLOUDFLARE_BUILT_IN_MODULES } };
+        }
+        return {
+          resolve: {
+            builtins: CLOUDFLARE_BUILT_IN_MODULES,
+          },
+          optimizeDeps: {
+            exclude: CLOUDFLARE_BUILT_IN_MODULES,
+          },
+        };
+      },
+    },
+  };
+});

package/src/plugins/index.ts

@@ -0,0 +1,6 @@
+export * from "./additional-modules.js";
+export * from "./cloudflare-externals.js";
+export * from "./nodejs-compat.js";
+export * from "./options.js";
+export * from "./virtual-modules.js";
+export * from "./wasm-init.js";

package/src/plugins/nodejs-compat.ts

@@ -2,174 +2,240 @@ import { getCloudflarePreset, nonPrefixedNodeModules } from "@cloudflare/unenv-p
 import assert from "node:assert";
 import { createRequire } from "node:module";
 import path from "node:path";
-import type { Plugin } from "rolldown";
 import { esmExternalRequirePlugin } from "rolldown/plugins";
 import { defineEnv } from "unenv";
-import type { CloudflarePluginOptions } from "../plugin.js";
+import { createPlugin } from "../factory.js";
 import { hasNodejsAls, hasNodejsCompat } from "../utils.js";
 
+const ASYNC_HOOKS_REGEXP = /^(node:)?async_hooks$/;
 const NODE_BUILTIN_MODULES_REGEXP = new RegExp(`^(${nonPrefixedNodeModules.join("|")}|node:.+)$`);
-const VIRTUAL_MODULE_ID_REGEXP = /^virtual:nodejs-global-inject\/.+$/;
 
-export function makeNodejsCompatPlugin(options: CloudflarePluginOptions): Plugin | Array<Plugin> {
-  if (hasNodejsCompat(options.compatibilityFlags)) {
-    return makeUnenvPlugin(options);
-  }
-  if (hasNodejsAls(options.compatibilityFlags)) {
-    return makeNodeJsAlsPlugin();
-  }
-  return makeNodeJsImportWarningPlugin();
-}
-
-function makeUnenvPlugin(options: CloudflarePluginOptions): Array<Plugin> {
-  const { alias, inject, external, polyfill } = defineEnv({
-    presets: [
-      getCloudflarePreset({
-        compatibilityDate: options.compatibilityDate,
-        compatibilityFlags: options.compatibilityFlags,
-      }),
-    ],
-  }).env;
-
-  const injectVirtualModules = makeInjectVirtualModules(inject);
-  const require = createRequire(import.meta.url);
-
-  return [
-    esmExternalRequirePlugin({
-      external: [...external],
-      skipDuplicateCheck: true,
-    }),
-    {
-      name: "rolldown-plugin-cloudflare:nodejs-compat:injects",
+export const nodejsAlsPlugin = createPlugin("nodejs-als", (options) => {
+  if (!hasNodejsAls(options.compatibilityFlags)) return;
+  return {
+    rolldown: {
       resolveId: {
-        filter: { id: VIRTUAL_MODULE_ID_REGEXP },
+        filter: { id: ASYNC_HOOKS_REGEXP },
         handler(id) {
-          if (injectVirtualModules.has(id)) {
-            return { id };
-          }
-        },
-      },
-      load: {
-        filter: { id: VIRTUAL_MODULE_ID_REGEXP },
-        handler(id) {
-          return injectVirtualModules.get(id);
+          return { id, external: true };
         },
       },
     },
-    {
-      name: "rolldown-plugin-cloudflare:nodejs-compat:unenv-preset-imports",
-      resolveId: {
-        filter: { id: /^@cloudflare\/unenv-preset\// },
-        async handler(id, importer, options) {
-          const resolved = await this.resolve(id, importer, options);
-          if (resolved) return resolved;
-          return { id: require.resolve(id) };
-        },
+    vite: {
+      enforce: "pre",
+      configEnvironment(name) {
+        if (name === "client") return;
+        return {
+          resolve: {
+            builtins: ["async_hooks", "node:async_hooks"],
+          },
+          optimizeDeps: {
+            exclude: ["async_hooks", "node:async_hooks"],
+          },
+        };
       },
     },
-    {
-      name: "rolldown-plugin-cloudflare:nodejs-compat",
-      resolveId: {
-        filter: { id: NODE_BUILTIN_MODULES_REGEXP },
-        handler(source, importer, options) {
-          const aliased = alias[source];
-          if (!aliased) {
-            return;
-          }
-          if (external.includes(aliased)) {
-            return {
-              id: aliased,
-              external: true,
-            };
-          }
-          return this.resolve(aliased, importer, options);
+  };
+});
+
+export interface UnenvApi {
+  polyfill: ReadonlyArray<string>;
+  inject: { [injectedName: string]: string };
+}
+
+export const nodejsUnenvPlugin = createPlugin<"nodejs-unenv", UnenvApi>(
+  "nodejs-unenv",
+  (options) => {
+    if (!hasNodejsCompat(options.compatibilityFlags)) return;
+    const { alias, inject, external, polyfill } = defineEnv({
+      presets: [
+        getCloudflarePreset({
+          compatibilityDate: options.compatibilityDate,
+          compatibilityFlags: options.compatibilityFlags,
+        }),
+      ],
+    }).env;
+    const entries = new Set(Object.values(alias));
+    for (const globalInject of Object.values(inject)) {
+      if (typeof globalInject === "string") {
+        entries.add(globalInject);
+      } else {
+        entries.add(globalInject[0]);
+      }
+    }
+    polyfill.forEach((module) => entries.add(module));
+    external.forEach((module) => entries.delete(module));
+    const require = createRequire(import.meta.url);
+    const resolve = (id: string) => {
+      if (alias[id] && !external.includes(alias[id])) {
+        return require.resolve(alias[id]);
+      }
+      if (entries.has(id)) {
+        return require.resolve(id);
+      }
+    };
+    const RESOLVE_ID_FILTER = {
+      id: [NODE_BUILTIN_MODULES_REGEXP, /^unenv\//, /^@cloudflare\/unenv-preset\//],
+    };
+    return {
+      shared: {
+        api: {
+          polyfill,
+          inject: Object.fromEntries(
+            Object.entries(inject).map(([injectedName, moduleSpecifier]) => {
+              assert(
+                typeof moduleSpecifier === "string",
+                `expected moduleSpecifier to be a string`,
+              );
+              return [injectedName, moduleSpecifier];
+            }),
+          ),
         },
       },
-      transform(code, id) {
-        const info = this.getModuleInfo(id);
-        if (!info?.isEntry) {
-          return;
-        }
-        return [
-          ...polyfill.map((module) => `import "${module}";`),
-          ...Array.from(injectVirtualModules.keys()).map((module) => `import "${module}";`),
-          code,
-        ].join("\n");
+      rolldown: {
+        async options(options) {
+          options.plugins = [
+            esmExternalRequirePlugin({
+              external: [...external],
+              skipDuplicateCheck: true,
+            }),
+            options.plugins,
+          ];
+          return options;
+        },
+        resolveId: {
+          filter: RESOLVE_ID_FILTER,
+          handler(source, importer, options) {
+            const resolved = resolve(source);
+            if (!resolved) return;
+            return this.resolve(resolved, importer, options);
+          },
+        },
       },
-    } satisfies Plugin,
-  ];
-}
-
-function makeNodeJsAlsPlugin(): Plugin {
-  return {
-    name: "rolldown-plugin-cloudflare:nodejs-als",
-    resolveId: {
-      filter: { id: /^(node:)?async_hooks$/ },
-      handler(id) {
-        return { id, external: true };
+      vite: {
+        enforce: "pre",
+        async configEnvironment(name) {
+          if (name === "client") return;
+          return {
+            resolve: {
+              builtins: [...external],
+            },
+            ...(this.meta.rolldownVersion
+              ? {
+                  build: {
+                    rolldownOptions: {
+                      plugins: [
+                        esmExternalRequirePlugin({
+                          external: [...external],
+                          skipDuplicateCheck: true,
+                        }),
+                      ],
+                    },
+                  },
+                }
+              : {}),
+            optimizeDeps: {
+              exclude: [
+                ...nonPrefixedNodeModules,
+                ...nonPrefixedNodeModules.map((module) => `node:${module}`),
+                // New Node.js built-in modules are only published with the `node:` prefix.
+                ...["node:sea", "node:sqlite", "node:test", "node:test/reporters"],
+              ],
+            },
+          };
+        },
+        async configureServer(server) {
+          await Promise.all(
+            Object.values(server.environments).flatMap(async (environment) => {
+              const depsOptimizer = environment.depsOptimizer;
+              if (!depsOptimizer) return;
+              await depsOptimizer.init();
+              return Array.from(entries).map((entry) => {
+                const resolved = resolve(entry);
+                if (!resolved) return;
+                const registration = depsOptimizer.registerMissingImport(entry, resolved);
+                return registration?.processing;
+              });
+            }),
+          );
+        },
+        resolveId: {
+          filter: RESOLVE_ID_FILTER,
+          handler(source, importer, options) {
+            const resolved = resolve(source);
+            if (!resolved) return;
+            if (this.environment.mode === "dev" && this.environment.depsOptimizer) {
+              // We are in dev mode (rather than build).
+              // So let's pre-bundle this polyfill entry-point using the dependency optimizer.
+              const { id } = this.environment.depsOptimizer.registerMissingImport(source, resolved);
+              // We use the unresolved path to the polyfill and let the dependency optimizer's
+              // resolver find the resolved path to the bundled version.
+              return this.resolve(id, importer, options);
+            }
+            return this.resolve(resolved, importer, options);
+          },
+        },
       },
-    },
-  };
-}
+    };
+  },
+);
 
-function makeNodeJsImportWarningPlugin(): Plugin {
+export const nodejsImportWarningPlugin = createPlugin("nodejs-import-warning", (options) => {
+  if (hasNodejsCompat(options.compatibilityFlags)) return;
   const imports = new Map<string, Set<string>>();
   let root = process.cwd();
   return {
-    name: "rolldown-plugin-cloudflare:nodejs-import-warnings",
-    options(options) {
-      if (options.cwd) {
-        root = options.cwd;
-      }
-    },
-    resolveId: {
-      filter: { id: NODE_BUILTIN_MODULES_REGEXP },
-      async handler(id, importer) {
-        if (importer) {
-          if (!imports.has(id)) {
-            imports.set(id, new Set());
-          }
-          imports.get(id)?.add(importer);
+    rolldown: {
+      options(options) {
+        if (options.cwd) {
+          root = options.cwd;
         }
-        return { id, external: true };
       },
     },
-    buildStart() {
-      imports.clear();
+    vite: {
+      enforce: "pre",
+      configResolved(config) {
+        root = config.root;
+      },
     },
-    buildEnd() {
-      if (imports.size > 0) {
-        let message =
-          `Unexpected Node.js imports. ` +
-          `Do you need to enable the "nodejs_compat" compatibility flag? ` +
-          "Refer to https://developers.cloudflare.com/workers/runtime-apis/nodejs/ for more details.\n";
+    shared: {
+      buildStart() {
+        imports.clear();
+      },
+      resolveId: {
+        filter: { id: NODE_BUILTIN_MODULES_REGEXP },
+        async handler(id, importer) {
+          if (hasNodejsAls(options.compatibilityFlags) && ASYNC_HOOKS_REGEXP.test(id)) return;
+          if (importer) {
+            if (!imports.has(id)) {
+              imports.set(id, new Set());
+            }
+            imports.get(id)?.add(importer);
+          }
+          return { id, external: true };
+        },
+      },
+      buildEnd() {
+        const filteredImports: Array<{ id: string; importer: string }> = [];
         for (const [id, importers] of imports.entries()) {
           for (const importer of importers) {
-            message += ` - "${id}" imported from "${path.relative(root, importer)}"\n`;
+            if (this.getModuleInfo(importer)) {
+              filteredImports.push({ id, importer });
+            }
           }
         }
-        this.warn(message);
-      }
+        if (filteredImports.length > 0) {
+          const message = [
+            "Unexpected Node.js imports. ",
+            'Do you need to enable the "nodejs_compat" compatibility flag? ',
+            "Refer to https://developers.cloudflare.com/workers/runtime-apis/nodejs/ for more details.\n",
+            ...filteredImports.map(
+              ({ id, importer }) => ` - "${id}" imported from "${path.relative(root, importer)}"\n`,
+            ),
+          ].join("");
+          this.warn(message);
+        }
+      },
     },
   };
-}
-
-function makeInjectVirtualModules(
-  inject: Readonly<Record<string, string | ReadonlyArray<string>>>,
-) {
-  const virtualModules = new Map<string, string>();
-  for (const [injectedName, moduleSpecifier] of Object.entries(inject)) {
-    // The type from unenv is string | string[], but the Cloudflare preset only uses string.
-    // This indicates a default export that we set on globalThis.
-    assert(typeof moduleSpecifier === "string", `expected moduleSpecifier to be a string`);
-    virtualModules.set(
-      injectVirtualModuleId(injectedName),
-      `import virtualModule from "${moduleSpecifier}"; globalThis.${injectedName} = virtualModule;`,
-    );
-  }
-  return virtualModules;
-}
-
-function injectVirtualModuleId(module: string) {
-  return `virtual:nodejs-global-inject/${module}` as const;
-}
+});