@astrojs/cloudflare 7.1.1 → 7.3.0

package/README.md

@@ -75,6 +75,92 @@ export default defineConfig({
 
 Note that this adapter does not support using [Cloudflare Pages Middleware](https://developers.cloudflare.com/pages/platform/functions/middleware/). Astro will bundle the [Astro middleware](https://docs.astro.build/en/guides/middleware/) into each page.
 
+### routes.strategy
+
+`routes.strategy: "auto" | "include" | "exclude"`
+
+default `"auto"`
+
+Determines how `routes.json` will be generated if no [custom `_routes.json`](#custom-_routesjson) is provided.
+
+There are three options available:
+
+- **`"auto"` (default):** Will automatically select the strategy that generates the fewest entries. This should almost always be sufficient, so choose this option unless you have a specific reason not to.
+
+- **`include`:** Pages and endpoints that are not pre-rendered are listed as `include` entries, telling Cloudflare to invoke these routes as functions. `exclude` entries are only used to resolve conflicts. Usually the best strategy when your website has mostly static pages and only a few dynamic pages or endpoints.
+
+  Example: For `src/pages/index.astro` (static), `src/pages/company.astro` (static), `src/pages/users/faq.astro` (static) and `/src/pages/users/[id].astro` (SSR) this will produce the following `_routes.json`:
+
+  ```json
+  {
+    "version": 1,
+    "include": [
+      "/_image", // Astro's image endpoint
+      "/users/*" // Dynamic route
+    ],
+    "exclude": [
+      // Static routes that needs to be exempted from the dynamic wildcard route above
+      "/users/faq/",
+      "/users/faq/index.html"
+    ]
+  }
+  ```
+
+- **`exclude`:** Pre-rendered pages are listed as `exclude` entries (telling Cloudflare to handle these routes as static assets). Usually the best strategy when your website has mostly dynamic pages or endpoints and only a few static pages.
+
+  Example: For the same pages as in the previous example this will produce the following `_routes.json`:
+
+  ```json
+  {
+    "version": 1,
+    "include": [
+      "/*" // Handle everything as function except the routes below
+    ],
+    "exclude": [
+      // All static assets
+      "/",
+      "/company/",
+      "/index.html",
+      "/users/faq/",
+      "/favicon.png",
+      "/company/index.html",
+      "/users/faq/index.html"
+    ]
+  }
+  ```
+
+### routes.include
+
+`routes.include: string[]`
+
+default `[]`
+
+If you want to use the automatic `_routes.json` generation, but want to include additional routes (e.g. when having custom functions in the `functions` folder), you can use the `routes.include` option to add additional routes to the `include` array.
+
+### routes.exclude
+
+`routes.exclude: string[]`
+
+default `[]`
+
+If you want to use the automatic `_routes.json` generation, but want to exclude additional routes, you can use the `routes.exclude` option to add additional routes to the `exclude` array.
+
+The following example automatically generates `_routes.json` while including and excluding additional routes. Note that that is only necessary if you have custom functions in the `functions` folder that are not handled by Astro.
+
+```diff
+// astro.config.mjs
+export default defineConfig({
+    adapter: cloudflare({
+        mode: 'directory',
++       routes: {
++           strategy: 'include',
++           include: ['/users/*'], // handled by custom function: functions/users/[id].js
++           exclude: ['/users/faq'], // handled by static page: pages/users/faq.astro
++       },
+    }),
+});
+```
+
 ## Enabling Preview
 
 In order for preview to work you must install `wrangler`
@@ -191,6 +277,49 @@ export default defineConfig({
 });
 ```
 
+## Wasm module imports
+
+`wasmModuleImports: boolean`
+
+default: `false`
+
+Whether or not to import `.wasm` files [directly as ES modules](https://github.com/WebAssembly/esm-integration/tree/main/proposals/esm-integration).
+
+Add `wasmModuleImports: true` to `astro.config.mjs` to enable in both the Cloudflare build and the Astro dev server.
+
+```diff
+// astro.config.mjs
+import {defineConfig} from "astro/config";
+import cloudflare from '@astrojs/cloudflare';
+
+export default defineConfig({
+    adapter: cloudflare({
++       wasmModuleImports: true
+    }),
+	  output: 'server'
+})
+```
+
+Once enabled, you can import a web assembly module in Astro with a `.wasm?module` import.
+
+The following is an example of importing a Wasm module that then responds to requests by adding the request's number parameters together.
+
+```javascript
+// pages/add/[a]/[b].js
+import mod from '../util/add.wasm?module';
+
+// instantiate ahead of time to share module
+const addModule: any = new WebAssembly.Instance(mod);
+
+export async function GET(context) {
+  const a = Number.parseInt(context.params.a);
+  const b = Number.parseInt(context.params.b);
+  return new Response(`${addModule.exports.add(a, b)}`);
+}
+```
+
+While this example is trivial, Wasm can be used to accelerate computationally intensive operations which do not involve significant I/O such as embedding an image processing library.
+
 ## Headers, Redirects and function invocation routes
 
 Cloudflare has support for adding custom [headers](https://developers.cloudflare.com/pages/platform/headers/), configuring static [redirects](https://developers.cloudflare.com/pages/platform/redirects/) and defining which routes should [invoke functions](https://developers.cloudflare.com/pages/platform/functions/routing/#function-invocation-routes). Cloudflare looks for `_headers`, `_redirects`, and `_routes.json` files in your build output directory to configure these features. This means they should be placed in your Astro project’s `public/` directory.
@@ -202,6 +331,33 @@ This will enable Cloudflare to serve files and process static redirects without
 
 See [Cloudflare's documentation](https://developers.cloudflare.com/pages/platform/functions/routing/#create-a-_routesjson-file) for more details.
 
+## Node.js compatibility
+
+Astro's Cloudflare adapter allows you to use any Node.js runtime API supported by Cloudflare:
+
+- assert
+- AsyncLocalStorage
+- Buffer
+- Diagnostics Channel
+- EventEmitter
+- path
+- process
+- Streams
+- StringDecoder
+- util
+
+To use these APIs, your page or endpoint must be server-side rendered (not pre-rendered) and must use the the `import {} from 'node:*'` import syntax.
+
+```js
+// pages/api/endpoint.js
+export const prerender = false;
+import { Buffer } from 'node:buffer';
+```
+
+Additionally, you'll need to enable the Compatibility Flag in Cloudflare. The configuration for this flag may vary based on where you deploy your Astro site.
+
+For detailed guidance, please refer to the [Cloudflare documentation](https://developers.cloudflare.com/workers/runtime-apis/nodejs).
+
 ## Troubleshooting
 
 For help, check out the `#support` channel on [Discord](https://astro.build/chat). Our friendly Support Squad members are here to help!

package/dist/index.d.ts

@@ -4,12 +4,26 @@ export type { DirectoryRuntime } from './server.directory.js';
 type Options = {
     mode?: 'directory' | 'advanced';
     functionPerRoute?: boolean;
+    /** Configure automatic `routes.json` generation */
+    routes?: {
+        /** Strategy for generating `include` and `exclude` patterns
+         * - `auto`: Will use the strategy that generates the least amount of entries.
+         * - `include`: For each page or endpoint in your application that is not prerendered, an entry in the `include` array will be generated. For each page that is prerendered and whoose path is matched by an `include` entry, an entry in the `exclude` array will be generated.
+         * - `exclude`: One `"/*"` entry in the `include` array will be generated. For each page that is prerendered, an entry in the `exclude` array will be generated.
+         * */
+        strategy?: 'auto' | 'include' | 'exclude';
+        /** Additional `include` patterns */
+        include?: string[];
+        /** Additional `exclude` patterns */
+        exclude?: string[];
+    };
     /**
      * 'off': current behaviour (wrangler is needed)
      * 'local': use a static req.cf object, and env vars defined in wrangler.toml & .dev.vars (astro dev is enough)
      * 'remote': use a dynamic real-live req.cf object, and env vars defined in wrangler.toml & .dev.vars (astro dev is enough)
      */
     runtime?: 'off' | 'local' | 'remote';
+    wasmModuleImports?: boolean;
 };
 export declare function getAdapter({ isModeDirectory, functionPerRoute, }: {
     isModeDirectory: boolean;

package/dist/index.js

@@ -6,10 +6,11 @@ import { AstroError } from "astro/errors";
 import esbuild from "esbuild";
 import * as fs from "node:fs";
 import * as os from "node:os";
-import { sep } from "node:path";
+import { basename, dirname, relative, sep } from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import glob from "tiny-glob";
 import { getEnvVars } from "./parser.js";
+import { wasmModuleLoader } from "./wasm-module-loader.js";
 class StorageFactory {
   storages = /* @__PURE__ */ new Map();
   storage(namespace) {
@@ -146,6 +147,15 @@ function createIntegration(args) {
             server: new URL(`.${SERVER_BUILD_FOLDER}`, config.outDir),
             serverEntry: "_worker.mjs",
             redirects: false
+          },
+          vite: {
+            // load .wasm files as WebAssembly modules
+            plugins: [
+              wasmModuleLoader({
+                disabled: !args?.wasmModuleImports,
+                assetsDirectory: config.build.assets
+              })
+            ]
           }
         });
       },
@@ -229,6 +239,7 @@ function createIntegration(args) {
       },
       "astro:build:done": async ({ pages, routes, dir }) => {
         const functionsUrl = new URL("functions/", _config.root);
+        const assetsUrl = new URL(_buildConfig.assets, _buildConfig.client);
         if (isModeDirectory) {
           await fs.promises.mkdir(functionsUrl, { recursive: true });
         }
@@ -237,23 +248,56 @@ function createIntegration(args) {
           const entryPaths = entryPointsURL.map((entry) => fileURLToPath(entry));
           const outputUrl = new URL("$astro", _buildConfig.server);
           const outputDir = fileURLToPath(outputUrl);
-          await esbuild.build({
-            target: "es2020",
-            platform: "browser",
-            conditions: ["workerd", "worker", "browser"],
-            entryPoints: entryPaths,
-            outdir: outputDir,
-            allowOverwrite: true,
-            format: "esm",
-            bundle: true,
-            minify: _config.vite?.build?.minify !== false,
-            banner: {
-              js: SHIM
-            },
-            logOverride: {
-              "ignored-bare-import": "silent"
-            }
-          });
+          const entryPathsGroupedByDepth = !args.wasmModuleImports ? [entryPaths] : entryPaths.reduce((sum, thisPath) => {
+            const depthFromRoot = thisPath.split(sep).length;
+            sum.set(depthFromRoot, (sum.get(depthFromRoot) || []).concat(thisPath));
+            return sum;
+          }, /* @__PURE__ */ new Map()).values();
+          for (const pathsGroup of entryPathsGroupedByDepth) {
+            const pagesDirname = relative(fileURLToPath(_buildConfig.server), pathsGroup[0]).split(
+              sep
+            )[0];
+            const absolutePagesDirname = fileURLToPath(new URL(pagesDirname, _buildConfig.server));
+            const urlWithinFunctions = new URL(
+              relative(absolutePagesDirname, pathsGroup[0]),
+              functionsUrl
+            );
+            const relativePathToAssets = relative(
+              dirname(fileURLToPath(urlWithinFunctions)),
+              fileURLToPath(assetsUrl)
+            );
+            await esbuild.build({
+              target: "es2020",
+              platform: "browser",
+              conditions: ["workerd", "worker", "browser"],
+              external: [
+                "node:assert",
+                "node:async_hooks",
+                "node:buffer",
+                "node:diagnostics_channel",
+                "node:events",
+                "node:path",
+                "node:process",
+                "node:stream",
+                "node:string_decoder",
+                "node:util"
+              ],
+              entryPoints: pathsGroup,
+              outbase: absolutePagesDirname,
+              outdir: outputDir,
+              allowOverwrite: true,
+              format: "esm",
+              bundle: true,
+              minify: _config.vite?.build?.minify !== false,
+              banner: {
+                js: SHIM
+              },
+              logOverride: {
+                "ignored-bare-import": "silent"
+              },
+              plugins: !args?.wasmModuleImports ? [] : [rewriteWasmImportPath({ relativePathToAssets })]
+            });
+          }
           const outputFiles = await glob(`**/*`, {
             cwd: outputDir,
             filesOnly: true
@@ -287,6 +331,18 @@ function createIntegration(args) {
             target: "es2020",
             platform: "browser",
             conditions: ["workerd", "worker", "browser"],
+            external: [
+              "node:assert",
+              "node:async_hooks",
+              "node:buffer",
+              "node:diagnostics_channel",
+              "node:events",
+              "node:path",
+              "node:process",
+              "node:stream",
+              "node:string_decoder",
+              "node:util"
+            ],
             entryPoints: [entryPath],
             outfile: buildPath,
             allowOverwrite: true,
@@ -298,7 +354,12 @@ function createIntegration(args) {
             },
             logOverride: {
               "ignored-bare-import": "silent"
-            }
+            },
+            plugins: !args?.wasmModuleImports ? [] : [
+              rewriteWasmImportPath({
+                relativePathToAssets: isModeDirectory ? relative(fileURLToPath(functionsUrl), fileURLToPath(assetsUrl)) : relative(fileURLToPath(_buildConfig.client), fileURLToPath(assetsUrl))
+              })
+            ]
           });
           await fs.promises.rename(buildPath, finalBuildUrl);
           if (isModeDirectory) {
@@ -320,6 +381,9 @@ function createIntegration(args) {
             }
           }
         }
+        if (!isModeDirectory) {
+          cloudflareSpecialFiles.push("_worker.js");
+        }
         const routesExists = await fs.promises.stat(new URL("./_routes.json", _config.outDir)).then((stat) => stat.isFile()).catch(() => false);
         if (!routesExists) {
           const functionEndpoints = routes.filter((route) => potentialFunctionRouteTypes.includes(route.type) && !route.prerender).map((route) => {
@@ -375,29 +439,34 @@ function createIntegration(args) {
             );
           }
           staticPathList.push(...routes.filter((r) => r.type === "redirect").map((r) => r.route));
-          let include = deduplicatePatterns(
-            functionEndpoints.map((endpoint) => endpoint.includePattern)
-          );
-          let exclude = deduplicatePatterns(
-            staticPathList.filter(
-              (file) => functionEndpoints.some((endpoint) => endpoint.regexp.test(file))
+          const strategy = args?.routes?.strategy ?? "auto";
+          const includeStrategy = strategy === "exclude" ? void 0 : {
+            include: deduplicatePatterns(
+              functionEndpoints.map((endpoint) => endpoint.includePattern).concat(args?.routes?.include ?? [])
+            ),
+            exclude: deduplicatePatterns(
+              staticPathList.filter(
+                (file) => functionEndpoints.some((endpoint) => endpoint.regexp.test(file))
+              ).concat(args?.routes?.exclude ?? [])
             )
-          );
-          if (include.length === 0) {
-            include = ["/"];
-            exclude = ["/"];
-          }
-          if (include.length + exclude.length > staticPathList.length) {
-            include = ["/*"];
-            exclude = deduplicatePatterns(staticPathList);
+          };
+          if (includeStrategy?.include.length === 0) {
+            includeStrategy.include = ["/"];
+            includeStrategy.exclude = ["/"];
           }
+          const excludeStrategy = strategy === "include" ? void 0 : {
+            include: ["/*"],
+            exclude: deduplicatePatterns(staticPathList.concat(args?.routes?.exclude ?? []))
+          };
+          const includeStrategyLength = includeStrategy ? includeStrategy.include.length + includeStrategy.exclude.length : Infinity;
+          const excludeStrategyLength = excludeStrategy ? excludeStrategy.include.length + excludeStrategy.exclude.length : Infinity;
+          const winningStrategy = includeStrategyLength <= excludeStrategyLength ? includeStrategy : excludeStrategy;
           await fs.promises.writeFile(
             new URL("./_routes.json", _config.outDir),
             JSON.stringify(
               {
                 version: 1,
-                include,
-                exclude
+                ...winningStrategy
               },
               null,
               2
@@ -423,6 +492,27 @@ function deduplicatePatterns(patterns) {
     return true;
   });
 }
+function rewriteWasmImportPath({
+  relativePathToAssets
+}) {
+  return {
+    name: "wasm-loader",
+    setup(build) {
+      build.onResolve({ filter: /.*\.wasm.mjs$/ }, (args) => {
+        const updatedPath = [
+          relativePathToAssets.replaceAll("\\", "/"),
+          basename(args.path).replace(/\.mjs$/, "")
+        ].join("/");
+        return {
+          path: updatedPath,
+          // change the reference to the changed module
+          external: true
+          // mark it as external in the bundle
+        };
+      });
+    }
+  };
+}
 export {
   createIntegration as default,
   getAdapter

package/dist/wasm-module-loader.d.ts

@@ -0,0 +1,14 @@
+import { type Plugin } from 'vite';
+/**
+ * Loads '*.wasm?module' imports as WebAssembly modules, which is the only way to load WASM in cloudflare workers.
+ * Current proposal for WASM modules: https://github.com/WebAssembly/esm-integration/tree/main/proposals/esm-integration
+ * Cloudflare worker WASM from javascript support: https://developers.cloudflare.com/workers/runtime-apis/webassembly/javascript/
+ * @param disabled - if true throws a helpful error message if wasm is encountered and wasm imports are not enabled,
+ * 								otherwise it will error obscurely in the esbuild and vite builds
+ * @param assetsDirectory - the folder name for the assets directory in the build directory. Usually '_astro'
+ * @returns Vite plugin to load WASM tagged with '?module' as a WASM modules
+ */
+export declare function wasmModuleLoader({ disabled, assetsDirectory, }: {
+    disabled: boolean;
+    assetsDirectory: string;
+}): Plugin;

package/dist/wasm-module-loader.js

@@ -0,0 +1,88 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import {} from "vite";
+function wasmModuleLoader({
+  disabled,
+  assetsDirectory
+}) {
+  const postfix = ".wasm?module";
+  let isDev = false;
+  return {
+    name: "vite:wasm-module-loader",
+    enforce: "pre",
+    configResolved(config) {
+      isDev = config.command === "serve";
+    },
+    config(_, __) {
+      return {
+        assetsInclude: ["**/*.wasm?module"],
+        build: { rollupOptions: { external: /^__WASM_ASSET__.+\.wasm\.mjs$/i } }
+      };
+    },
+    load(id, _) {
+      if (!id.endsWith(postfix)) {
+        return;
+      }
+      if (disabled) {
+        throw new Error(
+          `WASM module's cannot be loaded unless you add \`wasmModuleImports: true\` to your astro config.`
+        );
+      }
+      const filePath = id.slice(0, -1 * "?module".length);
+      const data = fs.readFileSync(filePath);
+      const base64 = data.toString("base64");
+      const base64Module = `
+const wasmModule = new WebAssembly.Module(Uint8Array.from(atob("${base64}"), c => c.charCodeAt(0)));
+export default wasmModule
+`;
+      if (isDev) {
+        return base64Module;
+      } else {
+        let hash = hashString(base64);
+        const assetName = path.basename(filePath).split(".")[0] + "." + hash + ".wasm";
+        this.emitFile({
+          type: "asset",
+          // put it explicitly in the _astro assets directory with `fileName` rather than `name` so that
+          // vite doesn't give it a random id in its name. We need to be able to easily rewrite from
+          // the .mjs loader and the actual wasm asset later in the ESbuild for the worker
+          fileName: path.join(assetsDirectory, assetName),
+          source: fs.readFileSync(filePath)
+        });
+        const chunkId = this.emitFile({
+          type: "prebuilt-chunk",
+          fileName: assetName + ".mjs",
+          code: base64Module
+        });
+        return `
+import wasmModule from "__WASM_ASSET__${chunkId}.wasm.mjs";
+export default wasmModule;
+	`;
+      }
+    },
+    // output original wasm file relative to the chunk
+    renderChunk(code, chunk, _) {
+      if (isDev)
+        return;
+      if (!/__WASM_ASSET__/g.test(code))
+        return;
+      const final = code.replaceAll(/__WASM_ASSET__([a-z\d]+).wasm.mjs/g, (s, assetId) => {
+        const fileName = this.getFileName(assetId);
+        const relativePath = path.relative(path.dirname(chunk.fileName), fileName).replaceAll("\\", "/");
+        return `./${relativePath}`;
+      });
+      return { code: final };
+    }
+  };
+}
+function hashString(str) {
+  let hash = 0;
+  for (let i = 0; i < str.length; i++) {
+    const char = str.charCodeAt(i);
+    hash = (hash << 5) - hash + char;
+    hash &= hash;
+  }
+  return new Uint32Array([hash])[0].toString(36);
+}
+export {
+  wasmModuleLoader
+};

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@astrojs/cloudflare",
   "description": "Deploy your site to Cloudflare Workers/Pages",
-  "version": "7.1.1",
+  "version": "7.3.0",
   "type": "module",
   "types": "./dist/index.d.ts",
   "author": "withastro",
@@ -41,19 +41,19 @@
     "esbuild": "^0.19.2",
     "find-up": "^6.3.0",
     "tiny-glob": "^0.2.9",
+    "vite": "^4.4.9",
     "@astrojs/underscore-redirects": "0.3.0"
   },
   "peerDependencies": {
-    "astro": "^3.1.1"
+    "astro": "^3.1.3"
   },
   "devDependencies": {
     "@types/iarna__toml": "^2.0.2",
     "chai": "^4.3.7",
     "cheerio": "1.0.0-rc.12",
-    "kill-port": "^2.0.1",
     "mocha": "^10.2.0",
     "wrangler": "^3.5.1",
-    "astro": "3.1.1",
+    "astro": "3.1.3",
     "astro-scripts": "0.0.14"
   },
   "scripts": {