💪 1.10.2

• Fixes

  • Fixes bug preventing wrangler publish from deleting over 10000 keys - ashleymichal, issue/1398 pull/1400

    In 1.10.0 we removed the limit on bulk KV PUT and DELETE operations by batching the values but missed batched deletes for Workers Sites. Now with some refactoring all batched operations use the same logic and have the same behavior.

⏳ 1.10.1

• Fixes

  • reinstate longer timeout on bulk uploads for sites - ashleymichal, pull/1391

    In 1.10.0 we introduced a bug that reduced the timeout for bulk uploads back to the standard 30 seconds. This fixes that and restores the five minute bulk upload/delete timeout.

  • Increase default timeout to one minute - EverlastingBugstopper, pull/1392

    For folks with slower connections we're increasing the timeout for API requests.

♻️ 1.10.0

• Features

  • wrangler dev now requires that you specify "preview" versions of KV namespaces - EverlastingBugstopper, ashleymichal, issue/1032 pull/1357 pull/1359 pull/1360

    In order to prevent you from accidentally stomping on production data in Workers KV, we're introducing the concept of explicit preview namespaces. When running wrangler dev, if you're using Workers KV, you'll need to specify a specific KV Namespace to use when previewing the Worker.

    Specifically, this change:

    • Adds a preview_id field to items in kv_namespaces in wrangler.toml that must be provided in order to preview a worker that has kv namespaces.
    • also adds --preview to kv commands in order to interact with them instead of production namespaces.

    If you define a KV Namespace in your wrangler.toml but don't specify a preview_id, and then try to run wrangler dev, you'll see the following:

    $ wrangler preview
    💁  JavaScript project found. Skipping unnecessary build!
    Error: In order to preview a worker with KV namespaces, you must designate a preview_id for each KV namespace you'd like to preview.

    More details can be found in the documentation.

  • wrangler subdomain allows you to rename your existing workers.dev subdomain - nprogers, issue/1279 pull/1353

    Workers recently introduced the ability to rename your workers.dev subdomain in the Workers dashboard. This change allows you to do the same thing from wrangler.

  • Return more detailed error when preview uploads fail - jahands, issue/1330 pull/1356

    When running wrangler dev or wrangler preview, if the upload failed for validation or other reasons, we displayed pretty obtuse errors. Now we pass along more informative error details.

  • Check for wrangler updates every 24 hours and message if you should update - EverlastingBugstopper, jspspike, issue/397 pull/1190 pull/1331

    wrangler will now let you know if there's an update available, and will only bug you once every 24 hours.

  • Improve some error messages with human-readable suggestions - jspspike, issue/1157 pull/1329

    Previously, you would see not-super-helpful error messages if your API Token was expired or missing some permissions, didn't have Workers Unlimited enabled and tried to upload to KV, or tried to create a namespace that already existed. But we strive for helpful, informative error messages!

    Now, you'll see the following error messages as appropriate:

    10026 => "You will need to enable Workers Unlimited for your account before you can use this feature.",
    10014 => "Namespace already exists, try using a different namespace.",
    10037 => "Edit your API Token to have correct permissions, or use the 'Edit Cloudflare Workers' API Token template.",
    

• Fixes

  • wrangler dev pretty-prints JSON messages from console.log() - jspspike, issue/1249 pull/1371

    Previously, when running wrangler dev, you could console.log(JSON.stringify(some_object)), but the output was hard to read: newlines weren't appropriately parsed and whitespace was a bit of a mess.

    This change pretty-prints JSON received from the Inspector, so JSON output is much easier to read in wrangler dev.

  • Don't install wasm-pack when publishing a type:webpack project - EverlastingBugstopper, issue/745 pull/1344

    We shouldn't install wasm-pack if your project doesn't need it. We thought we fixed this in 1.7.0, but we didn't. This time it's fixed for real, we swear.

  • Pin wasm-pack and cargo-generate to specific versions instead of always downloading the latest version - jspspike, issue/1240 pull/1358

    Previously, every time wasm-pack or cargo-generate was needed, Wrangler would download and install the latest version. Now, we pin those dependencies to a specific version in every release of Wrangler. If you have either of these tools installed locally, Wrangler will use them if you have a more recent version.

  • Support batched KV PUT and DELETE operations to improve Workers Site publish performance - jspspike, issue/1191 pull/1339

    Previously, you couldn't use Workers Sites if you wanted to upload more than 10,000 static files, and it took a lot of time to upload close to that many files. This change instead batches upload and delete calls, allowing us to increase the limit and improve performance for everyone.

• Maintenance

  • Add Code of Conduct - EverlastingBugstopper, pull/1346

    We actually didn't have one before, so now we do!

  • Deprecate undocumented KV bucket attribute - ashleymichal, issue/1136 pull/1355

    The bucket attribute was not originally intended to be released into the wild. We announced deprecation in March, and are now removing it as an available configuration property.

  • Refactor to separate KV commands, implementation of said commands, and site-specific logic - ashleymichal, pull/1332

    This refactor makes the logic for interacting with KV more re-usable and maintainable.

  • Add SECURITY.md with responsible reporting guidelines - EverlastingBugstopper, pull/1345

🐼 1.9.2

• Fixes

  • Fix piping secret values to wrangler secret put <VAR_NAME> - dmcgowan, issue/1322 pull/1316

    In 1.9.1, we introduced a bug where piping values to wrangler secret put no longer worked. In 1.9.2, that bug is squashed, and the command works as expected.

🐎 1.9.1

• Features

  • Accept --verbose for every command - bradyjoslin, issue/975 pull/1110

    Not every command outputs additional information when you pass --verbose, but none of them will fail to run if you pass --verbose after this change.

  • wrangler dev checks if the specified port is available - EverlastingBugstopper, issue/1122 pull/1272

    When starting up wrangler dev, it now checks to see if the requested port is already in use and returns a helpful error message if that's the case.

• Fixes

  • Don't reinstall vendored binaries on every build - EverlastingBugstopper, issue/768 pull/1003

    You may have noticed some very verbose and over-eager installation output when running Wrangler. Every webpack type build would install wranglerjs and wasm-pack. This was... super annoying and not a great experience, especially when running wrangler preview --watch or wrangler dev. Each time you'd change a file, Wrangler would reinstall those external dependencies. This doesn't happen anymore! Wrangler will still download and install these external dependencies, but only if you have an outdated version.

  • Remove redundant builds - EverlastingBugstopper, issue/1219 pull/1269

    When running wrangler preview --watch or wrangler dev on a webpack type project, Wrangler will provide a new build artifact and upload it via the Cloudflare API. Before, we'd start a long-running webpack --watch command, in addition to running webpack on every change. We were running two builds on every change! This was not great and has been removed. This, combined with the above fix removing redundant installations, should greatly improve your dev iteration cycles.

  • wrangler dev will reconnect to the devtools WebSocket after being disconnected - EverlastingBugstopper, issue/1241 pull/1276

    wrangler dev initiates a WebSocket connection via the Cloudflare API in order to stream console.log messages to your terminal. Over time, it's very likely that the WebSocket would be disconnected. When this happened, Wrangler would panic, requiring developers to restart the process. Now, if wrangler dev gets disconnected, it will issue a reconnect request, allowing developers to run wrangler dev as long as they are connected to the Internet.

• Maintenance

  • Adds Developing Wrangler section to CONTRIBUTING.md - EverlastingBugstopper, issue/270 pull/1288

    We love external contributors, and what better way to help get folks kickstarted than to add some documentation on developing Wrangler? Check out CONTRIBUTING.md if you're interested in helping out.

  • Remove --release from wrangler publish --help - EverlastingBugstopper, pull/1289

    We deprecated wrangler publish --release a long time ago in favor of environments, but it's still an accepted argument to preserve backwards compatibility. Now, it no longer shows up in wrangler publish --help as an accepted argument, even though it's still an alias of wrangler publish.

  • Updates license file to wrangler@cloudflare.com - EverlastingBugstopper, pull/1290

    The copyright in our MIT license was outdated and pointed to the email address of @ashleygwilliams (who no longer works at Cloudflare 😢). Now it points to wrangler@cloudflare.com :)

  • Add Dependabot to Wrangler - ispivey, pull/1294

    Wrangler now uses Dependabot to automatically update dependencies. We had already been doing this on a sort of ad-hoc basis, but this should make it much easier to stay on top of updates!

  • Remove unused code warnings - ashleymichal, pull/1304

    For our integration tests we create fixtures containing sample Workers projects. When we ran cargo test, cargo would say that the code used to create said fixtures were unused (which was not true). This PR moves the fixture code to a place where cargo says "This is a Fine Place for This Code."

  • Handle clippy warnings - ashleymichal EverlastingBugstopper, pull/1305 pull/1306

    cargo clippy is a helpful little tool that helps you write more idiomatic Rust. Over time, we've developed an immunity to the warnings produced by this tool, and we took a stab at cleaning some of them up.

🦚 1.9.0

• Features

  • Wrangler Tail - ashleymichal, gabbifish, EverlastingBugstopper, pull/1182

    Wrangler Tail introduces a way to view console statements and exceptions live as they occur in your Worker. Simply run wrangler tail against any deployed Worker and pipe the output through jq or to a file to stream trace events per request.

  • Much faster build times for Workers Sites projects - EverlastingBugstopper, pull/1221

    When you deploy a Workers Site, Wrangler generates a unique hash for each file. It does this so that your Worker does not serve stale files from Cloudflare's edge cache to end users. Unfortunately, generating these hashes took a really really long time since we were using a cryptographically strong hash. Since we're just using this hash for cache invalidation, we decided it's not necessary to use such a complicated algorithm. We switched to using xxhash and have seen noticeable speed improvements.

  • Add --url to wrangler preview - larkin-nz, issue/351 pull/1001

    wrangler preview now has the ability to open any URL! Before, wrangler preview would always open example.com, and you would be able to change the URL in the browser only. Now, you can use wrangler preview --url https://mysite.com/my-amazing-endpoint and your preview session will get started off on the right foot.

  • Print email addresses for API token users on wrangler whoami - dhaynespls, issue/863 pull/1212

    Before, if you ran wrangler whoami as an API token user, you didn't get much info. Due to some heavy lifting by folks working on the Cloudflare API, API token users with the correct permissions can now see what email address they are authenticated with when they run wrangler whoami. Nifty!

  • wrangler generate auto increments default worker name - xprazak2, issue/58 pull/469

    When wrangler generate is run without a name for the worker, it will find a name for the worker that does not already exist in that directory.

  • Standardize colors in stdout - EverlastingBugstopper, pull/1248

    Wrangler likes to print colors where appropriate, and now there is a standard module for printing different colors that is used across the codebase.

  • Suggests wrangler init if wrangler.toml does not exist - ashleymichal, issue/827 pull/1239

    When there is no wrangler.toml in a directory you're trying to run Wrangler in, it doesn't know what to do. The way to fix this is to make a wrangler.toml, and the way to do that is to run wrangler init.

• Fixes

  • Allow kv-namespaces and kv_namespaces - EverlastingBugstopper, issue/1158 pull/1169

    Most fields defined in wrangler.toml are one word, but some of them are two! In the past, we usually use _ to separate words, but somehow we used a - for kv-namespaces. This was inconsistent and a bit confusing. Now we allow both for the sake of backwards compatibility, but in the future we'll try to stick to snake_case.

  • Typo fix in wrangler init - jplhomer, pull/1210

    A successful wrangler init execution used to output "Succesfully" instead of "Successfully", but not anymore!

  • More granular errors in wrangler dev - EverlastingBugstopper, pull/1251

    In the last release we added an error message in wrangler dev for failed uploads. Unfortunately it was a bit overeager and some information about different types of errors were lost. This behavior has been fixed!

• Maintenance

  • Unify wrangler's user agent - EverlastingBugstopper, issue/731 pull/1070

    Wrangler sure does send a lot of API requests! Before, about half of the API requests Wrangler sent would send them with the HTTP header User-Agent: wrangler. Now, all requests sent by Wrangler include that User Agent. This lets the APIs we use know that the request is coming from this tool. Yay for being good netizens!

  • Refactors and documentation of wrangler dev - EverlastingBugstopper, pull/1220

    No behavior changes with this one, just some improvements to code layout and some extra documentation comments. Check it out if you're interested!

v1.9.0-rc.1

wrangler tail testing instructions

What's changed?

Release Candidate 1 adds support for port configuration. Add flag --port to set the localhost server used to receive tail logs (by default 8080 or OS allocated port); add flag --metrics to set the localhost server used to serve tunnel metrics (by default 8081 or OS allocated port).

Installation

Installing wrangler beta

npm i @cloudflare/wrangler@beta -g

Install cloudflared

Wrangler tail uses cloudflared under the hood. If you are already using cloudflared, be sure you have installed the latest version. Otherwise, follow the getting started guide for Argo Tunnel.

Creating a project

The documentation below assumes you have some familiarity with Wrangler and are already developing Workers. If this is not the case that is OK, come back after you've read through our Quickstart and have gotten up and running with Wrangler.

What gets logged?

Currently your tail will pick up console statements and exceptions thrown in your Worker. To illustrate, here is an example of a Hello World Worker (the result of wrangler generate) with a console statement and a thrown exception added:

addEventListener('fetch', event => {
  event.respondWith(handleRequest(event.request))
})
/**
 * Respond with hello worker text
 * @param {Request} request
 */
async function handleRequest(request) {
  console.log('hello tail!') // all console messages will be forwarded to your tail
  throw new Error('oh dang')
  return new Response('Hello worker!', {
    headers: { 'content-type': 'text/plain' },
  })
}

Deploy your worker

Wrangler tail is designed to consume logs emitted by a published worker instance in production; this isn't a development tool like wrangler dev or wrangler preview. If you wish to "test" tails, we recommend publishing a new [env] and tailing that. See more on using environments in Wrangler here.

Run wrangler tail

Once your Worker has been published, you can run wrangler tail (or wrangler tail --env foo if you are tailing a Worker specified in your wrangler.toml with [env.foo]). We recommend piping the output through a JSON parser such as jq as shown in the example command below, but this isn't strictly necessary.

The command can take up to a minute to establish the tail, but once it is ready you should get a stderr message saying so:

$ wrangler tail | jq
Setting up log streaming from Worker script "tail-worker" to Wrangler. This may take a few seconds…
Now prepared to stream logs.

Log Output and TraceItems

NOTE: the logging output schema is subject to change substantially before wrangler tail is fully released.

For each request received by a tailed Worker, a log will be sent to Wrangler and printed to stdout on a newline. Below is an example of a request to our example worker logged and piped through jq:

{
  "scriptName": "example",
  "outcome": "exception",
  "event": {
    "request": {
      "url": "https://example.com/some/requested/url",
      "method": "GET",
      "headers": {
        "CF-Ray": "57d55f210d7b95f3",
        "X-Custom-Header-Name": "my-header-value"
      },
      "cf": {
        "colo": "SJC"
      }
    },
  },
  "exceptions": [
    {
      "name": "Error",
      "message": "oh dang",
      "timestamp": 1587058642005
    }
  ],
  "logs": [
    {
      "message": "[\"hello tail!\"]",
      "level": "log",
      "timestamp": 1587058642005
    }
  ]
}

Note that if you are using a browser to hit your worker, you may end up with at least two entries; one of these is a request made automatically by your browser to fetch the favicon.ico for the domain. If you are serving assets with something like Workers Sites, you will see a request for each asset referenced in your index.html.

Each line represents a TraceItem, which has the following attributes:

scriptName

scriptName is just the name of your uploaded Worker Script. Note: work to populate this field is ongoing, so you may see null

outcome

outcome is a string describing the outcome of the worker invocation, one of:

• ok: The worker invocation succeeded.
• exception: An unhandled exception was thrown. This can happen for many reasons, including:
  • An uncaught JavaScript exception
  • A 'fetch' handler that does not result in a Response
  • An internal error
• exceededCpu: The Worker invocation exceeded either its CPU or memory limits.
• scriptNotFound: an internal error indicating a misconfigured pipeline or a difficulty retrieving the script.
• canceled: The worker invocation was canceled before it completed, commonly because the client disconnected before a response could be sent.

Note that outcome is not the same as HTTP status. A Worker can have an ok outcome when it successfully sends a 4xx or 5xx error. Likewise, a worker can have a non-ok outcome even after successfully sending a 200 response — for example, when an asynchronous task registered via waitUntil() later exceeds CPU or memory limits.

event

event is a FetchEventInfo object that contains information about the Worker's triggering fetchEvent. This object currently contains a single field, request, that holds a TraceRequest object, which contains properties that selectively mirror properties on FetchEvent's event.request. These properties include:

• cf: a JavaScript Object containing the data from FetchEvent.request.cf
• method: a string containing the data from FetchEvent.request.method
• headers: an object containing header keys and values. Headers are down-cased, and duplicate header values are comma-concatenated under the appropriate key. Note that this is not a standard Headers object but a read only struct!
• url: a string containing FetchEvent.request.url

Redaction

The headers and url properties of the TraceRequest object are subject to redaction rules. This makes it harder to accidentally record sensitive information like user credentials or API tokens. The redactions use heuristic rules, so they are subject to false positives and negatives.

• Header redaction: The header value will be the string REDACTED when the (case-insensitive) header name is "Cookie"/"Set-Cookie" or contains a substring "auth", "key", "secret", or "token".
• URL redaction: For each greedily matched substring of ID characters (a-z, A-Z, 0-9, '+', '-', '_') in the URL, if it meets the following criteria for a hex or base-64 ID, the substring will be replaced with the string REDACTED:
  • Hex ID: Contains 32 or more hex digits, and contains only hex digits and separators ('+', '-', '_')
  • Base-64 ID: Contains 21 or more characters, and contains at least two uppercase, two lowercase, and two digits.

exceptions

exceptions is populated with an array of TraceExceptions. Note that a single worker invocation might result in multiple unhandled exceptions, since a worker can register multiple asynchronous tasks.

TraceException

Records an unhandled exception that occurred during the Worker invocation. Made up of the following properties:

• timestamp: a Number indicating milliseconds since time origin
• message: a string, typically the error description (e.g. "'x' is not a function")
• name: a string, typically the error type (e.g. "Error", "TypeError", etc.)

logs

logs is populated with an array of TraceLogs. These reflect calls to console methods in your worker.

TraceLog

Records information sent to console functions. Made up of the following properties:

• timestamp: a Number indicating milliseconds since time origin
• level: a string indicating the console function that was called, one of:
  • debug
  • info
  • log
  • warn
  • error
• message: a JSON-encoded string of the array of parameters passed to the console function.

Limitations

How many tails can I run at once?

Scripts are limited to three concurrent tails at any given time.

How long can I tail?

Each tail is automatically closed after a period of 24 hours.

If I lose my connection do I lose my tail?

Wrangler sends a heartbeat every ~60s. If no heartbeat is received for 10 minutes, the tail is removed.

Traffic limits

In order to avoid DOSing your local machine, tails are currently rate limited and will be denied/closed if the Worker they are tailing is receiving more than 6000 requests over the previous 10 min period.

Expected questions

how do logs work with async code?

You'll want to use event.waitUntil() for async operations that may return after your worker sends a response.

Feedback

Love it? Hate it? Wish it was better? Tell us! If you'd like to provide feedback on wrangler tail, you can comment on this issue or file a new one! Just make sure to prefix your issue title with [tail].

🗞v1.9.0-rc.0

This beta release is now out of date. If you previously installed this release, you should reinstall with npm i -g @cloudflare/wrangler@beta and see what's changed in the latest release.

🎭 1.8.4

• Fixes

  • Don't remove user configuration on npm installs - EverlastingBugstopper, issue/1180 pull/1181

    Wrangler started removing user's authentication configuration files on reinstallation from npm - this is no good and is fixed in this release.

  • Allow multiline files to be piped to wrangler secret put - EverlastingBugstopper, issue/1132 pull/1171

    Previously, if you tried to pipe a multiline file to wrangler secret put, the secret would only upload the first line of the file. This... was not helpful - cat hello_world.txt | wrangler secret put should behave as expected with this release.

• Maintenance

  • Bump GitHub Actions checkout version - imbsky, pull/1170

    GitHub Actions are pretty nifty, and we've started using them as our CI provider in Wrangler. Actions allow you to specify a step that "uses" a template, and one of the most used templates is the template that checks out relevant code. GitHub just released v2 of that template, and our CI now uses it!

🍟 1.8.3

• Features

  • Improvements to the Workers Sites asset manifest - EverlastingBugstopper, issue/897 pull/1145

    Workers Sites uses the concept of an asset manifest to invalidate Cloudflare's cache when new files are published. Every time you publish your Workers Site, Wrangler will re-create a mapping of file names with a hash to the contents of the file. This release includes a few steps that improve this experience:

    • Manifest sizes are smaller by a magnitude of ~6.4. This should help some folks who were previously running into size issues when uploading a Workers Site.

    • Any time an asset manifest is created, you will see the files that are being hashed in real time with a fancy loading spinner - no more waiting without any information!

    • Asset manifest creation is now faster due to a refactor.

  • Clarify mutual exclusivity of zoneless v. zoned deploys - EverlastingBugstopper, issue/1152 pull/1154

    When publishing a Worker, you must specify either workers_dev = true or both a zone_id and route/routes. Previously, if your wrangler.toml violated this requirement, it would error with the following message:

    $ wrangler publish
    Error: you must set workers_dev = true OR provide a zone_id and route/routes.

    It's technically correct, but we can make it even more clear what the issue is. The new error message looks like:

    $ wrangler publish
    Error: you must set EITHER workers_dev = true OR provide a zone_id and route/routes.

• Fixes

  • Fixes wrangler config information message - EverlastingBugstopper, pull/1164

    In Wrangler 1.8.2, we updated the formatting of some of Wrangler's informational messages. Unfortunately when this was introduced, it came with a bug in wrangler config that made the message read out in the wrong order. This is fixed in this release!

• Maintenance

  • Remove unused badges from README - EverlastingBugstopper, pull/1166

    We no longer use Azure Pipelines as our CI provider, nor do we run non-test builds in CI so we removed those badges from the README.