Add documentation for webpack behavior

README.md

@@ -50,7 +50,7 @@ General documentation surrounding workers development and using `wrangler` can b
 
   - `name`: defaults to `worker`
   - `template`: defaults to the [`https://github.com/cloudflare/worker-template`](https://github.com/cloudflare/worker-template)
-  - `type`: defaults to "webpack"
+  - `type`: defaults to ["webpack"](https://github.com/cloudflare/wrangler/blob/master/docs/content/webpack.md)
 
 - ### 📥 `init`
 
@@ -63,7 +63,7 @@ General documentation surrounding workers development and using `wrangler` can b
   All of the arguments and flags to this command are options:
 
   - `name`: defaults to the name of your working directory
-  - `type`: defaults to "webpack"
+  - `type`: defaults to ["webpack"](https://github.com/cloudflare/wrangler/blob/master/docs/content/webpack.md).
 
 - ### 🦀⚙️ `build`
 
@@ -168,6 +168,7 @@ If you would like to be able to publish your code to multiple places, please see
   Additionally, you can preview different environments. This is useful if you have different builds for different environments (like staging vs. production), but typically isn't needed. For more information see the [environments documentation](https://github.com/cloudflare/wrangler/blob/master/docs/content/environments.md).
 
 - ### 🗂️ `kv`
+
   Interact with your Cloudflare Workers KV store. [Check out the docs.](./docs/content/kv_commands.md)
 
 ## 🔩 Configuration
@@ -210,7 +211,7 @@ There are two types of configuration that `wrangler` uses: global user and per p
         - `rust`: This project contains a Rust crate that uses `wasm-bindgen`. It will be built with `wasm-pack`.
         - `webpack`: This project contains any number of JavaScript files or Rust/C/C++ files that compile to
             WebAssembly. Rust files will be built with `wasm-pack`.
-            This project type uses webpack and webpack plugins in the background to build your worker.
+            This project type uses webpack and webpack plugins in the background to build your worker. You can read more about this type [here](https://github.com/cloudflare/wrangler/blob/master/docs/content/webpack.md).
     - `zone_id`: This is the ID of the "zone" or domain you want to run your script on. This is optional if you are using a [workers.dev](https://workers.dev) subdomain and is only required when `workers_dev` is false, or excluded from an [environment](https://github.com/cloudflare/wrangler/blob/master/docs/content/environments.md) configuration.
     - `account_id`: This is the ID of the account associated with your zone. You might have more than one account, so make sure to use the ID of the account associated with the `zone_id` you provide, if you provide one.
     - `route`: This is the route you'd like to use your worker on. You need to include the hostname. Examples:
@@ -220,7 +221,7 @@ There are two types of configuration that `wrangler` uses: global user and per p
 
         This key is optional if you are using a [workers.dev](https://workers.dev) subdomain and is only required when `workers_dev` is false, or excluded from an [environment](https://github.com/cloudflare/wrangler/blob/master/docs/content/environments.md). 
 
-    - `webpack_config`: This is the path to the webpack configuration file for your worker. This is optional and defaults to `webpack.config.js`
+    - `webpack_config`: This is the path to a custom webpack configuration file for your worker. You must specify this field to use a custom webpack configuration, otherwise Wrangler will use a default configuration for you. You can read more [here](https://github.com/cloudflare/wrangler/blob/master/docs/content/webpack.md).
     - `workers_dev`: This is a boolean flag that specifies if your worker will be deployed to your [workers.dev](https://workers.dev) subdomain. For more information, please read the [environments documentation](https://github.com/cloudflare/wrangler/blob/master/docs/content/environments.md).
     - `kv-namespaces`: These specify any [Workers KV](https://workers.cloudflare.com/docs/reference/storage/) Namespaces you want to access from
         inside your Worker. Each namespace you include should have an entry in your `wrangler.toml` that includes:

docs/content/webpack.md

@@ -0,0 +1,98 @@
+# 🦄 Webpack
+
+Out of the box, Wrangler allows you to develop modern ES6 applications with support for modules. This is because of the 🧙‍♂️ magic of [webpack](https://webpack.js.org/). This document describes how Wrangler uses webpack to build your Workers, and how you can bring your own configuration.
+
+**IMPORTANT: In order for Wrangler to use webpack to bundle your worker scripts, you must set `type = "webpack"` in your `wrangler.toml`, no other types will build your script with webpack.**
+
+If you're here because you're seeing warnings about specifying `webpack_config`, click [here](#backwards-compatibility)
+
+## Sensible Defaults
+
+This is the default webpack configuration that Wrangler uses to build your worker:
+
+```js
+module.exports = {
+  "target": "webworker",
+  "entry": "./index.js" // inferred from "main" in package.json
+};
+```
+
+Our default configuration sets `target` to `webworker`. From the [webpack docs](https://webpack.js.org/concepts/targets/):
+
+> 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](https://developer.mozilla.org/en-US/docs/Web/API/Service_Worker_API), so we set our `target` to `webworker`.
+
+The `entry` field is taken directly from the `main` field in your `package.json`. To read more about the webpack `entry` property, click [here](https://webpack.js.org/concepts/entry-points/).
+
+## 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`.
+
+### Example
+
+`webpack.config.js`
+
+```js
+module.exports = {
+  "target": "webworker",
+  "entry": "./index.js",
+  "mode": "production"
+}
+```
+
+`wrangler.toml`
+
+```toml
+type = "webpack"
+name = "my-worker"
+account_id = "12345678901234567890"
+workers_dev = true
+webpack_config = "webpack.config.js"
+```
+
+### Example with multiple environments
+
+`wrangler.toml`
+
+```toml
+type = "webpack"
+name = "my-worker-dev"
+account_id = "12345678901234567890"
+workers_dev = true
+webpack_config = "webpack.development.js"
+
+[env.staging]
+name = "my-worker-staging"
+webpack_config = "webpack.production.js"
+
+[env.production]
+name = "my-worker-production"
+webpack_config = "webpack.production.js"
+```
+
+`webpack.development.js`
+
+```js
+module.exports = {
+  "target": "webworker",
+  "entry": "./index.js",
+  "mode": "development"
+}
+```
+
+`webpack.production.js`
+
+```js
+module.exports = {
+  "target": "webworker",
+  "entry": "./index.js",
+  "mode": "production"
+}
+```
+
+## 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.