Improve bundling page #12980
Closed
Improve bundling page #12980
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?s=60&v=4){kind=small}
Deploying with
|
| Latest commit: |
1a89e79
|
| Status: | ✅ Deploy successful! |
| Preview URL: | https://9c832ff9.cloudflare-docs-7ou.pages.dev |
| Branch Preview URL: | https://penalosa-bundling.cloudflare-docs-7ou.pages.dev |
Contributor
|
Files with changes (up to 15)
|
8 tasks
Collaborator
|
closes #9351 |
kodster28
approved these changes
Apr 23, 2024
Collaborator
kodster28
left a comment
kodster28
left a comment
There was a problem hiding this comment.
Added some comments & suggestions, but approved from a content perspective.
| # 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. | ||
| By default, Wrangler bundles your Worker code using [`esbuild`](https://esbuild.github.io/) before uploading your Worker to Cloudflare. 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—this command will not deploy your Worker. By default, Wrangler will look at your `wrangler.toml` file and read the `main` field. This will be passed to ESBuild as the [entrypoint](https://esbuild.github.io/api/#entry-points) to your build. You can override this by passing a positional `script` argument to `wrangler dev` or `wrangler deploy`, which overrides the `main` value in your `wrangler.toml` file. |
Collaborator
There was a problem hiding this comment.
Suggested change
| By default, Wrangler bundles your Worker code using [`esbuild`](https://esbuild.github.io/) before uploading your Worker to Cloudflare. 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—this command will not deploy your Worker. By default, Wrangler will look at your `wrangler.toml` file and read the `main` field. This will be passed to ESBuild as the [entrypoint](https://esbuild.github.io/api/#entry-points) to your build. You can override this by passing a positional `script` argument to `wrangler dev` or `wrangler deploy`, which overrides the `main` value in your `wrangler.toml` file. | |
| By default, Wrangler bundles your Worker code using [`esbuild`](https://esbuild.github.io/) before uploading your Worker to Cloudflare. 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. This command will not deploy your Worker. By default, Wrangler will look at your `wrangler.toml` file and read the `main` field. This will be passed to ESBuild as the [entrypoint](https://esbuild.github.io/api/#entry-points) to your build. You can override this by passing a positional `script` argument to `wrangler dev` or `wrangler deploy`, which overrides the `main` value in your `wrangler.toml` file. |
| {{<Aside type="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. | ||
| {{</Aside>}} | ||
| Content on this page is relevant to all Wrangler users. If you'r authoring a library that you'd like to work with Wrangler, make sure to review [Notes for Library Authors](/workers/wrangler/bundling/#notes-for-library-authors). |
Collaborator
There was a problem hiding this comment.
Suggested change
| Content on this page is relevant to all Wrangler users. If you'r authoring a library that you'd like to work with Wrangler, make sure to review [Notes for Library Authors](/workers/wrangler/bundling/#notes-for-library-authors). | |
| {{<Aside type="note">}} | |
| Content on this page is relevant to all Wrangler users. If you are authoring a library that you'd like to work with Wrangler, make sure to review [Notes for Library Authors](/workers/wrangler/bundling/#notes-for-library-authors). | |
| {{</Aside>}} |
| ## Bundling TypeScript & 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: | ||
| When authoring a Worker with Wrangler, you're able to use multiple source modules (i.e. multiple TypeScript files in your source directory). You're also able to import from `npm` packages which you've installed. When Wrangler runs ESBuild, ESBuild will bundle all of these JavaScript and TypeScript modules into a single JavaScript file, which is what will be uploaded to the Cloudflare network as your Worker. You can see the exact bundled JavaScript file that's run by the Workers runtime by opening the Quick Editor on your uploaded Worker, which will display the bundled file. |
Collaborator
There was a problem hiding this comment.
Suggested change
| When authoring a Worker with Wrangler, you're able to use multiple source modules (i.e. multiple TypeScript files in your source directory). You're also able to import from `npm` packages which you've installed. When Wrangler runs ESBuild, ESBuild will bundle all of these JavaScript and TypeScript modules into a single JavaScript file, which is what will be uploaded to the Cloudflare network as your Worker. You can see the exact bundled JavaScript file that's run by the Workers runtime by opening the Quick Editor on your uploaded Worker, which will display the bundled file. | |
| When authoring a Worker with Wrangler, you can use multiple source modules (meaning multiple TypeScript files in your source directory). You are also able to import from previously installed `npm` packages. When Wrangler runs ESBuild, ESBuild will bundle all of these JavaScript and TypeScript modules into a single JavaScript file, which is what will be uploaded to the Cloudflare network as your Worker. You can see the exact bundled JavaScript file that's run by the Workers runtime by opening the Quick Editor on your uploaded Worker, which will display the bundled file. |
| 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: | ||
| When authoring a Worker with Wrangler, you're able to use multiple source modules (i.e. multiple TypeScript files in your source directory). You're also able to import from `npm` packages which you've installed. When Wrangler runs ESBuild, ESBuild will bundle all of these JavaScript and TypeScript modules into a single JavaScript file, which is what will be uploaded to the Cloudflare network as your Worker. You can see the exact bundled JavaScript file that's run by the Workers runtime by opening the Quick Editor on your uploaded Worker, which will display the bundled file. | ||
|
|
||
| > Why does Wrangler bundle? The Workers runtime supports uploading multiple JS modules, but Wrangler bundles your code by default to support TypeScript and to reduce the size of your Worker by leveraging e.g. tree-shaking |
Collaborator
There was a problem hiding this comment.
Suggested change
| > Why does Wrangler bundle? The Workers runtime supports uploading multiple JS modules, but Wrangler bundles your code by default to support TypeScript and to reduce the size of your Worker by leveraging e.g. tree-shaking | |
| > Why does Wrangler bundle? The Workers runtime supports uploading multiple JS modules, but Wrangler bundles your code by default to support TypeScript and to reduce the size of your Worker by leveraging tree-shaking |
|
|
||
| ## Support for non-JavaScript module types | ||
|
|
||
| Often you'll have modules in your app that aren't JavaScript or TypeScript. WASM is most common here, but this could also include text or HTML files that you want to import from your Worker code. Since these modules aren't JS or TS, these can't be bundled into your Worker's JS with ESBuild, and so Wrangler has specific logic for handling them. Wrangler supports this for the following file types: |
Collaborator
There was a problem hiding this comment.
Suggested change
| Often you'll have modules in your app that aren't JavaScript or TypeScript. WASM is most common here, but this could also include text or HTML files that you want to import from your Worker code. Since these modules aren't JS or TS, these can't be bundled into your Worker's JS with ESBuild, and so Wrangler has specific logic for handling them. Wrangler supports this for the following file types: | |
| Often you have modules in your app that are not JavaScript or TypeScript. WASM is most common here, but this could also include text or HTML files that you want to import from your Worker code. Since these modules are not JS or TS, these cannot be bundled into your Worker's JS with ESBuild, and so Wrangler has specific logic for handling them. Wrangler supports this for the following file types: |
| ] | ||
| ``` | ||
|
|
||
| In most projects, adding a single rule will be sufficient. However, for advanced usecases where you're mixing ES modules and Common JS modules, you'll need to use multiple rule definitions. For instance, the following set of rules will match all `.mjs` files as ES modules, all `.cjs` files as Common JS modules, and the `nested/say-hello.js` file as Common JS. |
Collaborator
There was a problem hiding this comment.
Suggested change
| In most projects, adding a single rule will be sufficient. However, for advanced usecases where you're mixing ES modules and Common JS modules, you'll need to use multiple rule definitions. For instance, the following set of rules will match all `.mjs` files as ES modules, all `.cjs` files as Common JS modules, and the `nested/say-hello.js` file as Common JS. | |
| In most projects, adding a single rule will be sufficient. However, for advanced usecases where you are mixing ES modules and Common JS modules, use multiple rule definitions. For instance, the following set of rules will match all `.mjs` files as ES modules, all `.cjs` files as Common JS modules, and the `nested/say-hello.js` file as Common JS. |
| ### Conditional exports | ||
|
|
||
| Wrangler respects the [conditional `exports` field](https://nodejs.org/api/packages.html#conditional-exports) | ||
|
|
Collaborator
There was a problem hiding this comment.
Fix the spacing here :)
|
|
||
| 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). If you're building a library that supports the Workers runtime, we recommend adding the `workerd` `exports` field to indicate the correct configuration of your package for Wrangler to load. |
Collaborator
There was a problem hiding this comment.
Suggested change
| 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). If you're building a library that supports the Workers runtime, we recommend adding the `workerd` `exports` field to indicate the correct configuration of your package for Wrangler to load. | |
| 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). If you are building a library that supports the Workers runtime, we recommend adding the `workerd` `exports` field to indicate the correct configuration of your package for Wrangler to load. |
|
|
||
| ### Feature detection | ||
|
|
||
| If you're writing a library that needs to know whether or not it's running in the Workers runtime, make sure you use the user agent for feature detection (i.e. `navigator.userAgent === "Cloudflare-Workers`). For example, you could write this `randomBytes()` function that will work in both Node.js and Workers: |
Collaborator
There was a problem hiding this comment.
Suggested change
| If you're writing a library that needs to know whether or not it's running in the Workers runtime, make sure you use the user agent for feature detection (i.e. `navigator.userAgent === "Cloudflare-Workers`). For example, you could write this `randomBytes()` function that will work in both Node.js and Workers: | |
| If you are writing a library that needs to know whether or not it's running in the Workers runtime, use the user agent for feature detection (i.e. `navigator.userAgent === "Cloudflare-Workers`). For example, you could write this `randomBytes()` function that will work in both Node.js and Workers: |
| Wrangler will upload _two_ modules to the Cloudflare platform; one containing your bundled JS code (with the above import statement intact), and one containing the file `example.html`. When your Worker is run by the Workers runtime, the runtime will recognise that the import matches a module that was uploaded alongside your worker, and will load the contents and make it available to your JS code. In this case (since the file is a text file), importing the module will result in a `string` (i.e. the `data` variable will contain the string contents of `example.com`) but that's not always the case. For imports from a `*.bin` file, the Workers runtime will provide the value to your Worker as a `ArrayBuffer`, and for imports from a `.wasm` or `.wasm?module` file the Workers runtime will provide the value as an `ArrayBuffer` representing the binary WASM code. To turn a WASM import into callable code, you need to use the [`WebAssembly.instantiate()` API](https://developer.mozilla.org/en-US/docs/WebAssembly/JavaScript_interface/instantiate_static). For example: | ||
|
|
||
| ```js | ||
| ``` |
Collaborator
There was a problem hiding this comment.
Should this have specific syntax highlighting?
Collaborator
|
👋Hi there, we’re going to close this PR due to inactivity and web framework migration |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
4 participants
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
No description provided.