Cloudflare Workers Webpack Boilerplate [RFC]


You’ll find the latest stable release, and all future releases, here:

Thank you everybody for your suggestions, help, insights and encouragement! :clap::tada::raised_hands:


Hi there, CF community!

This is a request for comments and feedback on a freshly-released Cloudflare Workers Webpack Boilerplate on Github: GitHub - detroitenglish/cloudflare-worker-webpack-boilerplate: Placeholder repo for external link preservation

What It Is

The goal is to provide a simple template for building, bundling and deploying Cloudflare Workers using Webpack - especially for devs unfamiliar with the black-magic of webpack.config.js :skull:

Facebook’s React team demonstrated pretty clearly that providing developers with a solid boilerplate to hack away with is a fantastic tool for building a community around new tech. In short, this project is intended to be that exact tool for Cloudflare Workers.

The Stuff It Does

Quoting the repository’s README…

What you configure:

  • Your Cloudflare credentials
  • Your site name (FQDN), or zone-ID
  • (Optional) One or more route matching patterns for your Worker

What you get:

  • Transparent, optimized and ready-to-rock Webpack configuration file
  • Babel configuration ensuring development-setup build compatibility for Node 6 and up
  • Babel-assured compatibility for Worker’s JavaScript in the latest CF-Worker (i.e. Chrome) runtime
  • Dynamic polyfilling, applied only when needed (which is anyways very unlikely!)
  • Baked-in management of route matching patterns, if and when routes are provided
  • Minification of deployed Worker scripts to help keep them under the 1MB limit
  • A ready-to-deploy example Worker in worker.js, which includes the use of require() and comments to help make sense of it all


You’re the experts on (…and inventors of!) everything Cloudflare Workers, so I’m asking for your comments, suggestions and criticisms in the hope that we can offer a rock-solid starting point for developers.

Your thoughts are all I’m hoping for… but if you’re feeling saucy, try installing the boilerplate, deploying workers, and generally doing whatever you can to break stuff.

Have insights or ideas? Please, write your thoughts in the comments of this thread! :bowing_man:

(Creating an issue on Github is also both welcome and awesome)

Mandatory Action-Packed Gif

For some context, here’s the boilerplate Worker’s build and deployment inaction:

:clap: All input will be mucho appreciated; nonetheless, thanks for reading! :bowing_man:


27 Aug 2018:

  • Change configuration requirement with new auto-lookup of site FQDN
  • New .gif image to show 0.0.1-beta.5 output style

29 Aug 2018:

  • Final update; v1.0.2 stable released - link added up top :arrow_up:

23 May 2019:

  • v2.2.0 released: supports metadata.json files for defining Worker Vault secrets, and now Namespace resource bindings for the hot new :fire: Workers KV :fire:


This is amazing! Figuring out how to package code into a worker, and how to use a router, is one of the hardest components to getting started with Workers, and you’ve created a great example of how to do it. Thank you!

1 Like

Thank you, @zack - very nice to have the approval of a Cloudflare overlord team member!

I should add that I just do this for fun, so if you and your Cloudflarian colleagues ever want to take the wheel on this, just let me know! :+1:

1 Like

Updated the project docs with a small feature roadmap:

  • Replace zone-id requirement with automatic zone-lookup of FQDN Added in 0.0.1-beta.5
  • Support single-shot deployment to multiple zones
  • Add argument parsing (or actual binary?) for deployment via pure CLI

By no means written in stone - thoughts?

This is awesome, thank you :slight_smile:
I already did some of it myself, but will probably migrate very soon.

One thing I‘m always confused about is people talking about the 1MB limit. My limit is 2MB for some reason?

1 Like

@cat24max I can’t really find anything in the docs about worker script size limits… I do know the v4 API returned a 400 for being over 1MB when I tried deploying my password strength estimation Worker unminified. I just assumed that limit was the same for everyone…

I’m only developing/testing with a site on the free plan, though. Are you on Business or Enterprise? I also joined the CF-Workers beta testing program - maybe that somehow affects my limit?

If a Cloudflare team member could please clarify worker script upload size limitations, I’ll gladly update the Boilerplate and CF-Worker Webpack plugin.

1 Like

@detroitenglish have you looked into the bundle? I see a lot of polyfill for older browsers. One is bringing in a replacement for addEventListener.

Currently, my goal is to not install any additional packages via npm. Just using webpack to merge into a single bundle and deploy. I have my bundle down from ~750kb (unminified) to 39.4kb.

People might also be interested in deploying across multiple orgs (which I recognize you probably don’t have access to on your plan type). If I come across a useful code snippet for that i’ll see if I can share it.

@webchad Have you pulled the latest version (0.0.1-beta.6)?

Can you please try changing the debug flag in .babelrc to true, and running npm run build?

Should look something like this:

Most importantly, Babel should output the following (regarding polyfills):

Based on your code and targets, none were added.

Should definitely not be polyfilling addEventListener when targeting the latest Chrome version in .browserslistrc

@cs-cf Didn’t think of that… I just tried deploying to another organization I manage and yeah, it 403’d with

[code 10015]: workers.api.error.not_entitled

GETting /client/v4/zones shows I have #worker:read and #worker:edit permissions for the zone, but I guess they’ll have to somehow authorize me to enable any kind of payed features for them?

Would also love to support the Enterprise Worker features, but that plan’s a bit heavy for the total 398 requests my worker script handled last week :sweat_smile:

1 Like

I know my script is definitely over 1MB, I sometimes get the 2MB warning while editing.
I‘m on the free plan.

@cat24max Definitely still throwing above 1MB for me:

[code 10027]: workers.api.error.script_too_large (1062KB)

Are you editing in the CF dashboard or uploading via /workers/script API?

Currently only over the dashboard.

@cs-cf @zack I create a GH-pages link workaround that redirects visitors to the main repo, but when shared on e.g. Twitter, shows the Cloudflare Logo in link preview cards (…instead of that ugly mug in my GitHub avatar :see_no_evil:)

It’s the official downloadable logo but I thought its best to ask if this is kosher, or at least find out who to ask.

Example below - thank you, gentlemen!


Link used:

I can’t imagine we’d have an issue, but on the off chance someone does contact you point them to this thread and tel them to yell at me first. :smiley:

1 Like

You’d risk a stern talking-to just for my sake??! :laughing:

In your defense, plan B was to steal this icon off CF dash


I was married for 14 years, I can tune out a ‘stern talking to’ like a pro. :slight_smile:

1 Like

The two things that removed a lot of the extra stuff was:

  • webpack.config.js – node: false, – this was the big one. It pointed out the one error I was seeing when using Node’s crypto, something was overriding the addEventListener
  • The web.dom.iterable exclude in .babelrc.js

Thanks a ton for this project!

1 Like

Glad you find it useful, and thanks for the support!

Webpack shims Node APIs and global objects pretty aggressively by default, and unfortunately there’s no ‘shim-as-needed’ code evaluation like Babel’s useBuiltIns: 'usage'.

The downside is that disabling shimming changes default Webpack behavior - any devs expecting e.g. Buffer to ‘just work’ are in for a nasty surprise.

So as of v1.0.4, worker scripts are run through eslint-loader, which will throw if Node builtins aren’t manually shimmed and cause the build to fail.

(And as much as I’d love to impose my hatred of semicolons on everyone, only no-undef is enforced)