@cloudflare/wrangler - npm Package Versions

Configurable binary host URL - noherczeg, pull/1018

Previously, binaries installed by Wrangler were all assumed to come from npm. If you work in a controlled environment and can only install binaries from a specific endpoint (instead of npm), you can now specify that endpoint using the WRANGLER_BINARY_HOST environment variable.

Eliminate downtime when redeploying Workers Sites - ashleymichal, issue/783, pull/1115

When Workers Sites were first introduced, redeploying a site could lead to a few seconds of downtime if the Worker upload fails. Specifically, if a new Workers Sites upload failed, it was possible that the old, now-unused files in Workers KV would be deleted anyways, meaning that the preexisting Workers Site would suddenly have missing resources. This fix waits to delete now-unused files until after a new Workers Sites script is published.

Add npm badge to README - tomByrer, [pull/1121]

Add badge to README that points to npm page for Wrangler.

Unify attention-grabbing messages - [EverlastingBugstopper], [pull/1128]

Use more actionable, easy-to-read information printouts throughout Wrangler.

Error messaging for internet required to talk to Cloudflare API - EverlastingBugstopper, issue/1093 pull/1114

With the release of wrangler dev in 1.8.0, it was not clear to users that internet is required since the feature communicates with Cloudflare's API. With this error message, users without internet connection are shown actionable next steps - check internet connection and lastly check if Cloudflare's API is down.

Fix live reload for wrangler dev - EverlastingBugstopper, issue/1082 pull/1117

wrangler dev re-builds and re-uploads your script to the Cloudflare API when it detects a file change. The Cloudflare API returns a new token which allows wrangler dev to route subsequent requests to the new script. Previously, wrangler dev would re-build, re-upload, and receive the new token, but it wouldn't use it for a couple of minutes due to some faulty threading logic. (darn mutexes!) After this change, wrangler dev will block incoming requests when it is switching the token, thus fixing the issue.

Remove unneeded carriage return in wrangler secret put - gabbifish, issue/1109 pull/1112

Previously, interactive input from wrangler secret put added a carriage return to the secret key/value pairs on Windows. This no longer happens and input is parsed properly before uploading.

wrangler dev - [EverlastingBugstopper], issue/845 pull/883

wrangler dev is a local proxy server to Cloudflare's preview service, allowing you to automatically re-build and preview your application on localhost. This feature is in alpha and we're looking for feedback and bug reports: check out this issue!

wrangler dev works very similarly to wrangler preview, but instead of opening your browser to preview your Worker, it will start a server on localhost that will execute your Worker on incoming HTTP requests:

$ wrangler dev

You should be able to send HTTP requests to localhost:8787, along with any headers or other request data, and your Worker should execute as expected. Additionally, you'll see console.log messages and exceptions appearing in your terminal (!!!).

For more information on wrangler dev's options, such as passing a custom host, ip, or port, run wrangler dev in your terminal for the available flags and options.

Multi-route support - [ashleymichal], issue/866 pull/916

Wrangler now allows developers to publish their Workers projects to multiple routes on a Cloudflare zone.

To deploy your Workers project to multiple routes, you can migrate from the route key to routes:

name = "worker"
type = "javascript"
account_id = "youraccountid"
# change this line
# route = "example.com/foo/*"
# to this line
routes = ["example.com/foo/*", "example.com/bar/*"]
zone_id = "yourzoneid"

wrangler secret commands - [ashleymichal], [bradyjoslin], issue/907 issue/909 issue/912 pull/1045

Wrangler now allows developers to use secrets in their Workers codebase. Secrets are secure values that can be accessed as constants, similar to text variables, inside of your Workers code.

To set a secret, you can use wrangler secret put MY_SECRET_NAME. The interactive prompt will ask for the secret text you'd like to add to your project:

$ wrangler secret put MY_SECRET_NAME
Enter the secret text you'd like assigned to the variable MY_SECRET_NAME on the script named my-project

Importantly, secrets are constrained to an environment, and do not carry over between different deployed Workers (e.g. my-worker and my-worker-production). This allows you to use different API keys, URLs, and other common "environment variable"-style values in your different environments. Specifying an environment can be done using the --env (or -e, for short):

$ wrangler secret put MY_SECRET_NAME --env production
Enter the secret text you'd like assigned to the variable MY_SECRET_NAME on the script named my-project-production

The wrangler secret subcommand also allows developers to list and delete secrets for your Workers projects:

$ wrangler secret delete MY_SECRET_NAME
Are you sure you want to permanently delete the variable MY_SECRET_NAME on the script named my-project [y/n] y
🌀  Deleting the secret MY_SECRET_NAME on script my-project.
✨  You've deleted the secret MY_SECRET_NAME.

$ wrangler secret list
[{"name":"API_KEY","type":"secret_text"},{"name":"MY_OTHER_SECRET","type":"secret_text"}]

Plain text binding support - [EverlastingBugstopper] - issue/993 pull/1014

In addition to secrets, Wrangler now also supports setting "plain text" bindings – values that will be available as constants in your Workers code, but aren't encrypted. This can be done by passing values in wrangler.toml under the vars key:

name = "worker"
type = "javascript"
account_id = "your-account-id"
workers_dev = true
vars = { ENV = "staging" }
[env.prod]
vars = { ENV = "production" }

Return accounts and account IDs when running wrangler whoami - [ashleygwilliams], issue/630 pull/983

We've made big improvements to wrangler whoami, and now return a list of Cloudflare accounts and account IDs for your authenticated user. If you are unauthenticated, or something is wrong with your API key or token, we'll also return an error with this command to help you understand how to fix your authentication issues!

Configure sourcemap file - [xtuc], issue/681 pull/1063

webpack (by default) emits a sourcemap that maps to a main.js file, which doesn't match the Workers runtime's configured filename, worker.js. This causes exception reporting tools to be unable to process a Workers sourcemap file – we've updated our Webpack config to output the file worker.js and have fixed this issue.

Upload "draft" worker if secret is created before initial worker script has been uploaded - [gabbifish], issue/913 pull/1087

If your script hasn't yet been deployed to the Workers platform, creating and deleting secrets will also create a "draft" Worker – allowing you to still manage secret bindings before you deploy the first version of your script.

Correctly tar release binaries - [EverlastingBugstopper], issue/1055 pull/1062

This PR updates the way that release binaries are generated during Wrangler's release workflow.

Change NPM binary permissions - [xtuc], pull/1058

This PR removes an unnecessary executable permission from npm/binary.js.

Improvements to GitHub Actions build process - [EverlastingBugstopper], pull/1037

This PR adds a number of improvements to wrangler's GitHub Actions workflows, including caching, release management, and more granular trigger conditions.

Add GitHub Actions badge to README - [EverlastingBugstopper], pull/1030

This PR adds a GitHub Actions badge to our README, indicating whether the repo's builds are currently passing:

Test Rust with GitHub Actions - [EverlastingBugstopper], pull/1028

This PR adds a GitHub Actions workflow for running wrangler's test suite on a number of platforms and Rust versions.

Add release checklist - [EverlastingBugstopper], pull/1021

This PR adds a release checklist, documenting the steps that we use to release new versions of Wrangler. That checklist includes writing this CHANGELOG - very meta!!!

Update dependencies - [EverlastingBugstopper], pull/1000

This PR updates some project dependencies as a result of running cargo update.

Run CI on pull requests, not pushes - [EverlastingBugstopper], pull/1090

This PR changes the GitHub Actions workflow "event trigger" to fire on pull_request, not push. This will allow wrangler's GitHub Actions workflows to run on PRs sent from forks!

Zip .tar files in CI - [EverlastingBugstopper], pull/1069 pull/1080

These PRs fix some issues in the GitHub Actions release workflow that were causing release artifacts to be incorrectly generated.

Fixes clippy warnings - [EverlastingBugstopper], pull/1071

This PR fixes some linting issues surfaced by clippy throughout the project.

Extract upload and deploy to lib modules - [ashleymichal], pull/1075

This PR refactors some of the underlying code used inside of wrangler publish, to create two higher-level upload and deploy modules. This work has already been used to support "draft workers" in #1087, and to reduce duplication of code between wrangler preview, wrangler dev, and wrangler publish.

Do not factor in .gitignore into workers sites upload directory traversal - gabbifish, issue/958 pull/981

This change ensures that the wrangler include/exclude logic for Workers Sites bucket directory traversal does NOT take into account .gitignore, since best practice for static site generators is to put your build directory into your .gitignore.

Update cloudflare-rs, reqwest, http, uuid - ashleymichal, issue/301 pull/1009

These dependency updates may look like routine maintenance, but this reqwest version actually makes support for corporate proxies possible!

Add progress bar during Site upload - gabbifish, issue/906 pull/956

Larger static asset uploads in Wrangler now show a progress bar based on the bulk uploads being made.

Allow custom webpack config for Workers Sites projects - ashleymichal, issue/905 pull/957

Previously we blocked users from declaring webpack_config in their wrangler.toml, as it can be relatively confusing due to the nested nature of the workers-site directory. We removed that block, and added a friendly help message when webpack build fails and the user has a custom webpack_config declared.

Reformat config api-key output - bradyjoslin, issue/889 pull/910

We care a lot about our error output. Now the output from wrangler config is consistent between calls with and without the --api-key flag.

Improve error message for wrangler init --site when wrangler.toml already exists - ashleygwilliams, issue/648 pull/931

wrangler init generally expects that you don't already have a wrangler.toml present; however it is common that users want to add static site functionality to their existing wrangler project and will try using wrangler init to do so. Rather than simply complaining that the toml already exists, now we add the workers-site directory to the project, and print out the suggested configuration to add to wrangler.toml. Much nicer!

Add a helpful error message on authentication error - EverlastingBugstopper, issue/492 pull/932

Previously, when wrangler publish ran into authentication errors, the API result would just print to the screen. Now, it prints a helpful hint to users to re-run wrangler config to fix the error.

Provide helpful error when user accidentally puts kv-namespace config under [site] - gabbifish, issue/798 pull/937

TOML formatting can be tricky, specifically tables, so it is common for users unfamiliar with the format to accidentally nest attributes inside tables without intending it. In this case, if a user adds a kv-namespaces entry to the bottom of a toml with [site] configuration already declared, it is parsed as a part of the [site] table, rather than as a top-level key. The error output from this is not super helpful, as it just says "unknown field kv-namespaces" which isn't precisely correct.

This PR detects when this error occurs and provides a help suggestion to put kv-namespaces ABOVE the [site] table entry to fix the problem.

Don't install wasm-pack for webpack type projects - EverlastingBugstopper, issue/745 pull/849

You may have noticed that Wrangler installs wasm-pack for your webpack projects, which may seem strange since it's the tool we use to build Rust projects. The reason for this is because you can also build Rust using wasm-pack and webpack in tandem if you use the wasm-pack-plugin. This plugin recently added support for handling the installation of wasm-pack which means Wrangler no longer needs to handle those installs.

Make Azure use latest rustc - EverlastingBugstopper, issue/887 pull/893

Updates our CI to update the rust toolchain to the latest stable version after installation.

Fix nightly builds - EverlastingBugstopper, pull/895, pull/898

Now we confirm Wrangler builds against nightly Rust releases!

Fix compiler warnings on windows - uma0317, issue/800 pull/919

We build Wrangler for Mac OSX, Linux, and Windows, and each of these environments has slightly different needs at compile time. In this case, community contributor uma0317 added configuration that eliminated unused imports for Windows at compile time.

Remove deprecated kv-namespace config check - ashleymichal, pull/929

Back in 1.1.0, we introduced more robust support for adding KV namespaces to your project. It was a breaking change for users who were still using our first pass at configuration for this in their toml, so we added a friendly error message telling them how to update their wrangler.toml. At this point, all of our users have safely transitioned onto the new syntax, and so we removed the warning; any lingering use of the old syntax will be met with a parse error instead.

Use binary-install for npm - EverlastingBugstopper, pull/862

This extracts a lot of the logic in Wrangler's installer to an external package, binary-install, which we will also use for installing wasm-pack on webpack project builds. Switching to this package also has the added benefit of cleaning up the downloaded binary on npm uninstall -g @cloudflare/wrangler.

BREAKING CHANGE: Require the webpack_config field in wrangler.toml to build with a custom configuration - EverlastingBugstopper, issue/296 pull/847

Wrangler will no longer use a webpack.config.js at the root of your project to build your worker. If you would like to continue using a custom build configuration, you will need to specify the webpack_config field in your wrangler.toml like so:

name = "my-worker"
workers_dev = true
account_id = "01234567890987654321234567890"
webpack_config = "webpack.config.js"

API Token Support - gabbifish/ashleymichal, issue/354 pull/471/pull/879

Wrangler can now be configured with API Tokens!

Don't worry, current configurations with an email address and a Global API Key will continue to work, but we highly recommend that you switch to API Tokens as they are a much more secure authentication method.

If you want to use API tokens, create an API token from the "Edit Cloudflare Workers" API token template here, and copy/paste it in the wrangler config prompt. Alternatively, you can set the CF_API_TOKEN environment variable.

Add the ability to preview without opening the browser - EverlastingBugstopper, issue/256 pull/816

wrangler preview can now be called with a --headless flag that will not open the browser.

Check for valid credentials when running wrangler config - gabbifish, issue/439 pull/842

Before this version of Wrangler, wrangler config would allow any input string to be passed for your user details. Now, Wrangler validates that the credentials will work with Cloudflare's API.

Add a warning when publishing a Workers Site to a route without a trailing asterisk - EverlastingBugstopper, issue/814 pull/839

When publishing a Workers Site to your own domain, it's important that the Worker code runs on every path on your domain. This isn't particularly clear, so now when attempting to publish a Workers Site to a route without a trailing asterisk, Wrangler will print a warning message.

Better error message for publishing to a duplicate route - pradovic, issue/519 pull/813

When publishing to a route that is associated with another worker, Wrangler now prints a more actionable error message.

Better error message when webpack fails - ashleymichal, issue/428 pull/837

Wrangler now recommends running npm install as a possible remedy for failed webpack builds.

Properly handle errors when running Wrangler as a global npm package - jaredmcdonald, issue/848 pull/857

Clean up temporary build files - EverlastingBugstopper, pull/853

When building a script, Wrangler creates a temporary file. Old versions of Wrangler were quite messy about it, but now it cleans up after itself.

Fix the help text for wrangler generate - EverlastingBugstopper, pull/830

The default value for a template is now a complete and valid URL instead of a sample project name.

Remove --version on subcommands - EverlastingBugstopper, issue/791 pull/829

Each subcommand in Wrangler used to take a --version argument which would print the name of the subcommand. For instance, wrangler publish --version would print wrangler-publish. This wasn't super helpful, so we've removed that functionality.

Fix a broken link in the README - victoriabernard92, pull/838

Create fixtures programmatically - EverlastingBugstopper, pull/854

Wrangler's test suite relied on a large number of fixtures that it read in from the file system. Now, it writes the test fixtures itself and does not rely on reading fixtures from the file system.

Clean up Workers Sites logic - ashleymichal, issue/622 issue/643 pull/851

Call cloudflare-rs from https.rs - gabbifish, pull/841

We've refactored some of our API client code in order to make way for some future improvements.

Audit code comments - EverlastingBugstopper, pull/846

Update the author of the npm package - EverlastingBugstopper, pull/836

The author of the npm package is now wrangler@cloudflare.com

Remove unused code warnings when running tests - pradovic, issue/818 pull/832

Due to the way the Rust compiler works, some of our test code appeared to be unused, even though it wasn't really. After making a couple of modules public, there are no more warnings.

Use the same binding name for Rust and webpack wasm modules - ashleymichal, pull/822

Move the code for each subcommand to its own directory - EverlastingBugstopper, pull/831

Refactor upload forms - ashleymichal, pull/826

We've separated some tangled logic regarding the form Wrangler POSTs to the Cloudflare v4 API.

Pull npm version from package.json - EverlastingBugstopper, issue/812 pull/817

Wrangler's npm installer version now only needs updating in the package.json instead of both the package.json and the source code.

Move Wrangler docs from READMEs to the Cloudflare Workers documentation site - victoriabernard92, pull/823

Wrangler has outgrown the README as primary documentation paradigm, and we've moved its documentation to the Cloudflare Workers documentation site.

Update the demo gif in the README - EverlastingBugstopper, issue/843 pull/868

The demo gif at the top of the README now accurately reflects the behavior of the latest Wrangler release.

Deprecate wrangler publish --release - [EverlastingBugstopper], issue/538 pull/751

wrangler publish --release is now simply an alias of wrangler publish. This is related to the introduction of environments made in 1.3.1 and is intended to reduce confusion surrounding deploy targets. Previously, wrangler publish --release would deploy to a route on your own domain, and wrangler publish would deploy to your workers.dev subdomain. This was a confusing API, and we now require individual environments to have either workers_dev = true or both a route and zone_id in each section of wrangler.toml. This makes it very clear where your Workers code is being deployed. If you're not using wrangler publish --release but you added workers_dev = false to the top level of your wrangler.toml because Wrangler warned you to - you can now safely remove it! If you are using wrangler publish --release, know that it is functionally the same as wrangler publish. If you want to deploy to workers.dev and also a route on your own domain, you will need to set up multiple environments.

Deprecate private field in wrangler.toml - stevenfranks, issue/782 pull/782

In a related note, the private field no longer functions in wrangler.toml. The original intent behind this field was to allow "publishing" without "activating". Unfortunately this led to a lot of undefined behavior if the value was switched from true to false in between a wrangler publish command and a wrangler publish --release command and vice versa. With the removal of wrangler publish --release, we are also removing the private field. If your wrangler.toml files contain a value for private, you can remove it!

Include/exclude static assets in a Workers Sites project - gabbifish, issue/716 pull/760

Your wrangler.toml has two new optional fields: include and exclude. These fields give you more granular control over what files are uploaded to Workers KV. This behavior mirrors Cargo's include/exclude functionality. Further documentation for this feature is available here.

A more robust wrangler generate - [EverlastingBugstopper], issue/315 pull/759

wrangler generate is now much smarter about wrangler.toml files. Previously, wrangler generate would simply create the same configuration for every project, and it would ignore any wrangler.toml that was committed to the template. This means much less guesswork when using wrangler generate with existing Workers projects.

Add the ability to check if you've already registered a workers.dev subdomain - gusvargas, issue/701 pull/747

You can now run wrangler subdomain without any arguments to see if you have registered a workers.dev subdomain.

$ wrangler subdomain
💁  foo.workers.dev

Add --verbose flag to wrangler publish and wrangler preview - gabbifish, issue/657 pull/790

You can now run wrangler publish --verbose and wrangler preview --verbose on a Workers Sites project to view all of the files that are being uploaded to Workers KV.

$ wrangler publish --verbose
🌀  Using namespace for Workers Site "__example-workers_sites_assets"
💁  Preparing to upload updated files...
🌀  Preparing ./public/favicon.ico
🌀  Preparing ./public/index.html
🌀  Preparing ./public/404.html
🌀  Preparing ./public/img/404-wrangler-ferris.gif
🌀  Preparing ./public/img/200-wrangler-ferris.gif
✨  Success
✨  Built successfully, built project size is 11 KiB.
✨  Successfully published your script to https://test.example.workers.dev

Disallow node_modules as a bucket for Workers Sites - gabbifish, issue/723 pull/792

node_modules is no longer allowed to be a bucket for Workers Sites. It is notoriously very large and if it were specified as a bucket it would probably be a very expensive mistake.

Allow installs to utilize Wrangler binaries via a caching proxy instead of GitHub directly - gabbifish, [pull/797]

To avoid dependency on one external service, GitHub, we enabled a cache proxy (using Workers!) for installations of Wrangler.

Provide a better error message when using an unverified email address - [ashleygwilliams], issue/320 pull/795

The Cloudflare API refuses to play nice with unverified email addresses (we don't like spam!), and now when this happens, Wrangler gives an actionable error message.

Fix Rust live preview - gabbifish, issue/618 pull/699

If you use Wrangler to develop Rust Workers, you may have noticed that live preview (wrangler preview --watch) was not working with your project. Not to worry though, we cracked down on this bug with an (oxidized) iron fist! Wrangler now has cross-platform support for live previewing Rust Workers.

Minimize timeout errors for bulk uploads - gabbifish, issue/746 pull/757

Sometimes Wrangler would make API calls to Workers KV that would timeout if there were too many files. We've increased the amount of time Wrangler will wait around for the API operations to complete.

Print readable error message when external commands fail - [EverlastingBugstopper], pull/799

Wrangler depends on a few external applications, and sometimes the calls to them fail! When this happens, Wrangler would tell you the command it tried to run, but it included a bunch of quotes. This change removes those quotes so the command is easily readable and can be copy/pasted.

Disallow wrangler generate --site with a template argument - [EverlastingBugstopper], issue/776 pull/789

In Wrangler 1.4.0, we introduced Workers Sites, which included the ability to run wrangler generate --site which would use our site template behind the scenes. Confusingly, you could also pass a template to this command: wrangler generate my-site https://github.com/example/worker-site --site, which would not behave as expected. This specific usage will now correctly output an error.

Begin refactoring test suite - [ashleymichal], pull/787

We're constantly shipping features in Wrangler, and with more features comes a larger codebase. As a codebase expands, it goes through some growing pains. This release includes some improvements to the internal organization of Wrangler's codebase, and is intended to make our lives and our contributors' lives easier moving forward.

• Moved all "fixture" helper functions to "utils" module to share between build/preview tests

• Removed "metadata_wasm.json" from simple_rust fixture

• Extracted all module declarations in main.rs to lib.rs to allow tests to import with use wrangler::foo

• Split target/mod.rs into one file per struct

• Cleaned up KV Namespace mod system

• Use log::info! instead of info! in main.rs

Refactor GlobalUser to be passed as a reference consistently - gabbifish, pull/749

Remove internal link from CONTRIBUTING.md - adaptive, pull/784

Fix some Clippy warnings - [EverlastingBugstopper], pull/793

Clean up leftover directories created by tests - [ashleymichal], pull/785

Refactor subdomain module - [EverlastingBugstopper], issue/758 pull/764

Fix README markdown misrender - dottorblaster, pull/763

Remove duplicate Environments subheader from README - bradyjoslin, pull/766

Change Crate author to the Workers Developer Experience team - [ashleygwilliams], pull/752