1. Migrate webpack projects

This guide describes the steps to migrate a webpack project from Wrangler v1 to Wrangler v2. After completing this guide, update your Wrangler version.

Previous versions of Wrangler offered rudimentary support for webpack ↗ with the type and webpack_config keys in wrangler.toml. Starting with Wrangler v2, Wrangler no longer supports the type and webpack_config keys, but you can still use webpack with your Workers.

As a developer using webpack with Workers, you may be in one of four categories:

1. I use [build] to run webpack (or another bundler) external to wrangler..

2. I use type = webpack, but do not provide my own configuration and let Wrangler take care of it..

3. I use type = webpack and webpack_config = <path/to/webpack.config.js> to handle JSX, TypeScript, WebAssembly, HTML files, and other non-standard filetypes..

4. I use type = webpack and webpack_config = <path/to/webpack.config.js> to perform code-transforms and/or other code-modifying functionality..

If you do not see yourself represented, file an issue ↗ and we can assist you with your specific situation and improve this guide for future readers.

I use [build] to run webpack (or another bundler) external to Wrangler.

Wrangler v2 supports the [build] key, so your Workers will continue to build using your own setup.

I use type = webpack, but do not provide my own configuration and let Wrangler take care of it.

Wrangler will continue to take care of it. Remove type = webpack from your wrangler.toml file.

I use type = webpack and webpack_config = <path/to/webpack.config.js> to handle JSX, TypeScript, WebAssembly, HTML files, and other non-standard filetypes.

As of Wrangler v2, Wrangler has built-in support for this use case. Refer to Bundling for more details.

The Workers runtime handles JSX and TypeScript. You can import any modules you need into your code and the Workers runtime includes them in the built Worker automatically.

You should remove the type and webpack_config keys from your wrangler.toml file.

I use type = webpack and webpack_config = <path/to/webpack.config.js> to perform code-transforms and/or other code-modifying functionality.

Wrangler v2 drops support for project types, including type = webpack and configuration via the webpack_config key. If your webpack configuration performs operations beyond adding loaders (for example, for TypeScript) you will need to maintain your custom webpack configuration. In the long term, you should migrate to an external [build] process. In the short term, it is still possible to reproduce Wrangler v1's build steps in newer versions of Wrangler by following the instructions below.

1. Add wranglerjs-compat-webpack-plugin ↗ as a devDependency.

wrangler-js ↗, shipped as a separate library from Wrangler v1 ↗, is a Node script that configures and executes webpack 4 ↗ for you. When you set type = webpack, Wrangler v1 would execute this script for you. We have ported the functionality over to a new package, wranglerjs-compat-webpack-plugin ↗, which you can use as a webpack plugin ↗.

To do that, you will need to add it as a dependency:

npm install --save-dev webpack@^4.46.0 webpack-cli wranglerjs-compat-webpack-plugin
# or
yarn add --dev webpack@4.46.0 webpack-cli wranglerjs-compat-webpack-plugin

You should see this reflected in your package.json file:

{
  "name": "my-worker",
  "version": "x.y.z",
  // ...
  "devDependencies": {
    // ...
    "wranglerjs-compat-webpack-plugin": "^x.y.z",
    "webpack": "^4.46.0",
    "webpack-cli": "^x.y.z"
  }
}

2. Add wranglerjs-compat-webpack-plugin to webpack.config.js.

Modify your webpack.config.js file to include the plugin you just installed.

const {
  WranglerJsCompatWebpackPlugin,
} = require("wranglerjs-compat-webpack-plugin");

module.exports = {
  // ...
  plugins: [new WranglerJsCompatWebpackPlugin()],
};

3. Add a build script your package.json.

{
  "name": "my-worker",
  "version": "2.0.0",
  // ...
  "scripts": {
    "build": "webpack" // <-- Add this line!
    // ...
  }
}

4. Remove unsupported entries from your wrangler.toml.

Remove the type and webpack_config keys from your wrangler.toml file, as they are not supported anymore.

wrangler.toml

# Remove these!
type = "webpack"
webpack_config = "webpack.config.js"

wrangler.json

{
  "type": "webpack",
  "webpack_config": "webpack.config.js"
}

5. Tell Wrangler how to bundle your Worker.

Wrangler no longer has any knowledge of how to build your Worker. You will need to tell it how to call webpack and where to look for webpack's output. This translates into two fields:

wrangler.toml

main = "./worker/script.js" # by default, or whatever file webpack outputs
[build]
command = "npm run build" # or "yarn build"
# ...

wrangler.json

{
  "main": "./worker/script.js",
  "build": {
    "command": "npm run build"
  }
}

6. Test your project.

Try running npx wrangler deploy to test that your configuration works as expected.

Was this helpful?

What did you like?

Accurate

Easy to understand

Solved my problem

Helped me decide to use the product

Other

What went wrong?

Hard to understand

Incorrect information

Missing the information

Other

Thank you for helping improve Cloudflare's documentation!