Skip to content
Visit Workers on GitHub
Set theme to dark (⇧+D)


Out of the box, Wrangler allows you to develop modern ES6 applications with support for modules. This is because of the 🧙‍♂️ magic of webpack. This document describes how Wrangler uses webpack to build your Workers, and how you can bring your own configuration.

Sensible defaults

This is the default webpack configuration that Wrangler uses to build your worker:

module.exports = {  target: "webworker",  entry: "./index.js" // inferred from "main" in package.json}

Our default configuration sets target to webworker. From the webpack docs:

Because JavaScript can be written for both server and browser, webpack offers multiple deployment targets that you can set in your webpack configuration.

Cloudflare Workers are built to match the Service Worker API, so we set our target to webworker.

The entry field is taken directly from the main field in your package.json. Learn more about the entry property on the webpack site.

Bring your own configuration

You can tell Wrangler to use a custom webpack configuration file by setting webpack_config in your wrangler.toml. You’ll want to make sure that target is always webworker.


webpack.config.jsmodule.exports = {  target: "webworker",  entry: "./index.js",  mode: "production"}
wrangler.tomltype = "webpack"name = "my-worker"account_id = "12345678901234567890"workers_dev = truewebpack_config = "webpack.config.js"

Example with multiple environments

wrangler.tomltype = "webpack"name = "my-worker-dev"account_id = "12345678901234567890"workers_dev = truewebpack_config = "webpack.development.js"
[env.staging]name = "my-worker-staging"webpack_config = "webpack.staging.js"
[env.production]name = "my-worker-production"webpack_config = "webpack.production.js"
webpack.development.jsmodule.exports = {  target: "webworker",  devtool: "cheap-module-source-map", // avoid "eval": Workers environment doesn’t allow it  entry: "./index.js",  mode: "development"}
webpack.production.jsmodule.exports = {  target: "webworker",  entry: "./index.js",  mode: "production"}

Using with Workers Sites

Wrangler commands are run from the project root, so ensure your entry and context are set appropriately. For a project with structure:

.├── public│   ├── 404.html│   └── index.html├── workers-site│   ├── index.js│   ├── package-lock.json│   ├── package.json│   └── webpack.config.js└── wrangler.toml

webpack.config.js should look like this:

webpack.config.jsmodule.exports = {  context: __dirname,  target: "webworker",  entry: "./index.js",  mode: "production"}

Shimming globals

Sometimes you want to bring your own implementation of an existing global API. You can do this by shimming a third party module in its place as a webpack plugin.

For example, to replace the runtime global URL class with the npm package url-polyfill — or your choice of third party package — npm i the package to install it locally and add it to your worker’s package.json, then add a plugin entry to your webpack config.

Example with webpack plugin

webpack.config.jsconst webpack = require("webpack")
module.exports = {  target: "webworker",  entry: "./index.js",  mode: "production",  plugins: [    new webpack.ProvidePlugin({      URL: "url-polyfill",    }),  ],}

Backwards compatibility

If you are using a version of Wrangler before 1.6.0, worker projects will simply use any webpack.config.js that is in the root of your project. This is not always obvious, so we plan to require that you specify webpack_config in your wrangler.toml if you would like to use it. If you’re seeing this warning and would like to use your webpack.config.js, simply add webpack_config = "webpack.config.js" to your wrangler.toml.

If you are using Workers Sites and want to specify your own webpack configuration, you will always need to specify this. By default, Wrangler will not assume the webpack.config.js at the root of your project is meant to be used for building your Worker.