add Wrangler 'find_additional_modules' documentation

Author: petebacondarwin

src/content/docs/workers/wrangler/bundling.mdx

@@ -3,24 +3,28 @@ pcx_content_type: configuration
 title: Bundling
 head: []
 description: Review Wrangler's default bundling.
-
 ---
 
 By default, Wrangler bundles your Worker code using [`esbuild`](https://esbuild.github.io/). This means that Wrangler has built-in support for importing modules from [npm](https://www.npmjs.com/) defined in your `package.json`. To review the exact code that Wrangler will upload to Cloudflare, run `npx wrangler deploy --dry-run --outdir dist`, which will show your Worker code after Wrangler's bundling.
 
 :::note
 
-We recommend using Wrangler's inbuilt bundling, but we understand there are cases where you will need more flexibility. We have built an escape hatch in the form of [Custom Builds](/workers/wrangler/custom-builds/), which lets you run your own build before Wrangler's built-in one. 
+Wrangler's inbuilt bundling usually provides the best experience, but we understand there are cases where you will need more flexibility.
+You can provide `rules` and set `find_additional_modules` in your configuration to control which files are included in the deployed Worker but not bundled into the entry-point file.
+Furthermore, we have an escape hatch in the form of [Custom Builds](/workers/wrangler/custom-builds/), which lets you run your own build before Wrangler's built-in one.
 :::
 
-## Files which will not be bundled
+## Including non-JavaScript modules
 
-Bundling your Worker code takes multiple modules and bundles them into one. Sometimes, you might have modules that should not be inlined directly into the bundle. For example, instead of bundling a Wasm file into your JavaScript Worker, you would want to upload the Wasm file as a separate module that can be imported at runtime. Wrangler supports this for the following file types:
+Bundling your Worker code takes multiple modules and bundles them into one file.
+Sometimes, you might have modules that cannot be inlined directly into the bundle.
+For example, instead of bundling a Wasm file into your JavaScript Worker, you would want to upload the Wasm file as a separate module that can be imported at runtime.
+Wrangler supports this for the following file types:
 
-* `.txt`
-* `.html`
-* `.bin`
-* `.wasm` and `.wasm?module`
+- `.txt`
+- `.html`
+- `.bin`
+- `.wasm` and `.wasm?module`
 
 Refer to [Bundling configuration](/workers/wrangler/configuration/#bundling) to customize these file types.
 
@@ -37,17 +41,30 @@ import wasm from "./example.wasm"; // Where `example.wasm` is a file in your loc
 const instance = await WebAssembly.instantiate(wasm); // Instantiate Wasm modules in global scope, not within the fetch() handler
 
 export default {
-  fetch(request) {
-    const result = instance.exports.exported_func();
-  },
+	fetch(request) {
+		const result = instance.exports.exported_func();
+	},
 };
 ```
 
 :::caution
 
-Cloudflare Workers does not support `WebAssembly.instantiateStreaming()`. 
+Cloudflare Workers does not support `WebAssembly.instantiateStreaming()`.
 :::
 
+## Find additional modules
+
+By setting `find_additional_modules` to `true` in your configuration file, Wrangler will traverse the file tree below `base_dir`.
+Any files that match the `rules` you define will also be included as unbundled, external modules in the deployed Worker.
+
+This approach is useful for supporting lazy loading of large or dynamically imported JavaScript files:
+
+- Normally a large lazy imported file (e.g. `await import("./large-dep.mjs")`) would be bundled directly into your entrypoint, making lazy loading less effective.
+  If matching rule is added to `rules`, then this file would only be loaded and executed at runtime when it is actually imported.
+- Previously, variable based dynamic imports (e.g. ``await import(`./lang/${language}.mjs`)``) would always fail at runtime, as Wrangler would have no way of knowing which modules to include in the upload.
+  Providing a rule that matches all these files (e.g. ` { type = "EsModule", globs = ["./land/**/*.mjs"], fallthrough = true }), will ensure this module is available at runtime.
+- "Partial bundling" is supported when `find_additional_modules` is `true`, and a source file matches one of the configured `rules`, since Wrangler will then treat it as "external" and not try to bundle it into the entry-point file.
+
 ## Conditional exports
 
 Wrangler respects the [conditional `exports` field](https://nodejs.org/api/packages.html#conditional-exports) in `package.json`. This allows developers to implement isomorphic libraries that have different implementations depending on the JavaScript runtime they are running in. When bundling, Wrangler will try to load the [`workerd` key](https://runtime-keys.proposal.wintercg.org/#workerd). Refer to the Wrangler repository for [an example isomorphic package](https://github.com/cloudflare/workers-sdk/tree/main/fixtures/isomorphic-random-example).
@@ -56,7 +73,7 @@ Wrangler respects the [conditional `exports` field](https://nodejs.org/api/packa
 
 :::caution
 
-Disabling bundling is not recommended in most scenarios. Use this option only when deploying code pre-processed by other tooling. 
+Disabling bundling is not recommended in most scenarios. Use this option only when deploying code pre-processed by other tooling.
 :::
 
 If your build tooling already produces build artifacts suitable for direct deployment to Cloudflare, you can opt out of bundling by using the `--no-bundle` command line flag: `npx wrangler deploy --no-bundle`. If you opt out of bundling, Wrangler will not process your code and some features introduced by Wrangler bundling (for example minification, and polyfills injection) will not be available.

src/content/docs/workers/wrangler/configuration.mdx

@@ -132,22 +132,33 @@ At a minimum, the `name`, `main` and `compatibility_date` keys are required to d
 
   - Skip internal build steps and directly deploy your Worker script. You must have a plain JavaScript Worker with no dependencies.
 
-- `minify` <Type text="boolean" /> <MetaInfo text="optional" />
+- `find_additional_modules` <Type text="boolean" /> <MetaInfo text="optional" />
 
-  - Minify the Worker script before uploading.
+  - If true then Wrangler will traverse the file tree below `base_dir`.
+    Any files that match `rules` will be included in the deployed Worker.
+    Defaults to true if `no_bundle` is true, otherwise false.
+    Can only be used with Module format workers (not Service Worker format).
 
-- `node_compat` <Type text="boolean" /> <MetaInfo text="optional" />
+- `base_dir` <Type text="string" /> <MetaInfo text="optional" />
 
-  - Deprecated — Instead, [enable the `nodejs_compat_v2` compatibility flag](/workers/runtime-apis/nodejs/#enable-nodejs-with-workers), which enables both built-in Node.js APIs, and adds polyfills as necessary.
-    Setting `node_compat = true` will add polyfills for Node.js built-in modules and globals to your Worker's code, when bundled with Wrangler.
-    This is powered by `@esbuild-plugins/node-globals-polyfill` which in itself is powered by [rollup-plugin-node-polyfills](https://github.com/ionic-team/rollup-plugin-node-polyfills/).
+  - The directory in which module "rules" should be evaluated when including additional files (via `find_additional_modules`) into a Worker deployment. Defaults to the directory containing the `main` entry point of the Worker if not specified.
 
 - `preserve_file_names` <Type text="boolean" /> <MetaInfo text="optional" />
 
   - Determines whether Wrangler will preserve the file names of additional modules bundled with the Worker.
     The default is to prepend filenames with a content hash.
     For example, `34de60b44167af5c5a709e62a4e20c4f18c9e3b6-favicon.ico`.
 
+- `minify` <Type text="boolean" /> <MetaInfo text="optional" />
+
+  - Minify the Worker script before uploading.
+
+- `node_compat` <Type text="boolean" /> <MetaInfo text="optional" />
+
+  - Deprecated — Instead, [enable the `nodejs_compat_v2` compatibility flag](/workers/runtime-apis/nodejs/#enable-nodejs-with-workers), which enables both built-in Node.js APIs, and adds polyfills as necessary.
+    Setting `node_compat = true` will add polyfills for Node.js built-in modules and globals to your Worker's code, when bundled with Wrangler.
+    This is powered by `@esbuild-plugins/node-globals-polyfill` which in itself is powered by [rollup-plugin-node-polyfills](https://github.com/ionic-team/rollup-plugin-node-polyfills/).
+
 - `logpush` <Type text="boolean" /> <MetaInfo text="optional" />
 
   - Enables Workers Trace Events Logpush for a Worker. Any scripts with this property will automatically get picked up by the Workers Logpush job configured for your account. Defaults to `false`.
@@ -942,7 +953,13 @@ assets = { directory = "./public", binding = "ASSETS", html_handling = "force-tr
 
 ## Bundling
 
-You can bundle modules into your Worker using the `rules` key, making these modules available to be imported when your Worker is invoked. The `rules` key will be an array of the below object.
+Wrangler can operate in two modes: the default bundling mode and `--no-bundle` mode.
+In bundling mode, Wrangler will traverse all the imports of your code and generate a single JavaScript "entry-point" file.
+Imported source code is "inlined/bundled" into this entry-point file.
+
+It is also possible to include additional modules into your Worker, which are uploaded alongside the entry-point.
+You specify which additional modules should be included into your Worker using the `rules` key, making these modules available to be imported when your Worker is invoked.
+The `rules` key will be an array of the below object.
 
 - `type` <Type text="string" /> <MetaInfo text="required" />
 
@@ -978,6 +995,15 @@ export default {
 };
 ```
 
+### Find additional modules
+
+Normally Wrangler will only include additional modules that are statically imported in your source code as in the example above.
+By setting `find_additional_modules` to `true` in your configuration file, Wrangler will traverse the file tree below `base_dir`.
+Any files that match `rules` will also be included as unbundled, external modules in the deployed Worker.
+`base_dir` defaults to the directory containing your `main` entrypoint.
+
+See https://developers.cloudflare.com/workers/wrangler/bundling/ for more details and examples.
+
 ## Local development settings
 
 You can configure various aspects of local development, such as the local protocol or port.