🌜
🌞
@cloudflare/wrangler

@cloudflare/wrangler

v1.19.12

Command-line interface for all things Cloudflare Workers

npm install @cloudflare/wrangler

README

🀠 wrangler

Banner

crates.io   npm   GitHub Actions - Test Status   GitHub Actions - Linter Status  

wrangler is a CLI tool designed for folks who are interested in using Cloudflare Workers.

Wrangler Demo

Installation

You have many options to install wrangler!

Install with npm

We strongly recommend you install npm with a Node version manager like nvm, which puts the global node_modules in your home directory to eliminate permissions issues with npm install -g. Distribution-packaged npm installs often use /usr/lib/node_modules (which is root) for globally installed npm packages, and running npm install -g as root prevents wrangler from installing properly.

Once you've installed nvm and configured your system to use the nvm managed node install, run:

npm i @cloudflare/wrangler -g

If you are running an ARM based system (eg Raspberry Pi, Pinebook) you'll need to use the cargo installation method listed below to build wrangler from source.

Specify binary location

In case you need wrangler's npm installer to place the binary in a non-default location (such as when using wrangler in CI), you can use the following configuration options to specify an install location:

  • Environment variable: WRANGLER_INSTALL_PATH
  • NPM configuration: wrangler_install_path

Specify binary site URL

In case you need to store/mirror binaries on premise you will need to specify where wrangler should search for them by providing any of the following:

  • Environment variable: WRANGLER_BINARY_HOST
  • NPM configuration: wrangler_binary_host

Install with cargo

cargo install wrangler

If you don't have cargo or npm installed, you will need to follow these additional instructions.

Install on Windows

perl is an external dependency of crate openssl-sys. If installing wrangler with cargo, you will need to have perl installed. We've tested with Strawberry Perl. If you instead install perl via scoop, you may need to also run scoop install openssl in order to get the necessary openssl dlls. Installing wrangler with npm instead of cargo is another option if you don't want to install perl.

Updating

For information regarding updating Wrangler, click here.

Getting Started

Once you have installed Wrangler, spinning up and deploying your first Worker is easy!

$ wrangler generate my-worker
$ cd my-worker
# update your wrangler.toml with your Cloudflare Account ID
$ wrangler config
$ wrangler publish

πŸŽ™οΈ Top Level Commands

πŸ‘― generate

Scaffold a project, including boilerplate code for a Rust library and a Cloudflare Worker.

wrangler generate <name> <template> --type=["webpack", "javascript", "rust"]

All of the arguments and flags to this command are optional:

πŸ“₯ init

Creates a skeleton wrangler.toml in an existing directory. This can be used as an alternative to generate if you prefer to clone a repository yourself.

wrangler init <name> --type=["webpack", "javascript", "rust"]

All of the arguments and flags to this command are optional:

  • name: defaults to the name of your working directory
  • type: defaults to "webpack".

πŸ¦€βš™οΈ build

Build your project. This command looks at your wrangler.toml file and runs the build steps associated with the "type" declared there.

Additionally, you can configure different environments.

πŸ”“ login

Authorize Wrangler with your Cloudflare login. This will prompt you with a Cloudflare account login page and a permissions consent page. This command is the alternative to wrangler config and it uses OAuth tokens.

wrangler login --scopes-list --scopes <scopes>

All of the arguments and flags to this command are optional:

  • scopes-list: list all the available OAuth scopes with descriptions.
  • scopes: allows to choose your set of OAuth scopes.

Read more about this command in Wrangler Login Documentation.

πŸ”§ config

Authenticate Wrangler with a Cloudflare API Token. This is an interactive command that will prompt you for your API token:

wrangler config
Enter API token:
superlongapitoken

You can also provide your email and global API key (this is not recommended for security reasons):

wrangler config --api-key
Enter email:
[email protected]
Enter global API key:
superlongapikey

You can also use environment variables to configure these values.

☁️ πŸ†™ publish

Publish your Worker to Cloudflare. Several keys in your wrangler.toml determine whether you are publishing to a workers.dev subdomain or your own registered domain, proxied through Cloudflare.

Additionally, you can configure different environments.

You can also use environment variables to handle authentication when you publish a Worker.

# e.g.
CF_API_TOKEN=superlongtoken wrangler publish
# where
# $CF_API_TOKEN -> your Cloudflare API token

CF_API_KEY=superlongapikey [email protected] wrangler publish
# where
# $CF_API_KEY -> your Cloudflare API key
# $CF_EMAIL -> your Cloudflare account email

πŸ—‚ kv

Interact with your Workers KV store. This is actually a whole suite of subcommands. Read more about in Wrangler KV Documentation.

πŸ‘‚ dev

wrangler dev works very similarly to wrangler preview except that 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. From there you can use cURL, Postman, your browser, or any other HTTP client to test the behavior of your worker before publishing it.

You should run wrangler dev from your worker directory, and if your worker makes any requests to a backend, you should specify the host with --host example.com.

From here you should be able to send HTTP requests to localhost:8787 along with any headers and paths, and your worker should execute as expected. Additionally, you should see console.log messages and exceptions appearing in your terminal.

πŸ‘‚ Listening on http://localhost:8787
[2020-02-18 19:37:08] GET example.com/ HTTP/1.1 200 OK

All of the arguments and flags to this command are optional:

  • env: environment to build
  • host: domain to test behind your worker. defaults to example.com
  • ip: ip to listen on. defaults to localhost
  • port: port to listen on. defaults to 8787

Additional Documentation

All information regarding wrangler or Cloudflare Workers is located in the Cloudflare Workers Developer Docs. This includes:

  • Using wrangler commands
  • Wrangler configuration
  • General documentation surrounding Workers development
  • All wrangler features such as Workers Sites and KV

✨Workers Sites

To learn about deploying static assets using wrangler, see the Workers Sites Quickstart.

Release Notes

1.19.12
Published on April 21, 2022

1.19.12

1.19.11
Published on March 22, 2022

1.19.11

  • Fixes

    • revert sites expiry stuff - caass, [pull/222**

      After discussion with @threepointone and @petebacondarwin we've decided simply to revert back to the old behavior for workers-sites where we delete old assets, rather than marking them for expiration. See #2224 for our reasoning for this change.

1.19.10
Published on March 21, 2022

1.19.10

  • Fixes

    • hotfix for expiring unused sites assets - caass, [pull/222**
1.19.9
Published on March 18, 2022
1.19.8
Published on February 8, 2022
  • Features

    • r2 bindings and subcommands - taylorlee, [pull146]**

      Added r2 sub-commands to create/delete/list r2 bucket

1.19.7
Published on January 4, 2022

v1.19.7

  • Fixes

    • Check for updates in the foreground, not the background - jyn514, [pull/21]**

      This avoids creating a new OpenSSL context while the main thread exits the process.

    • fix cli help typo - saikatdas0790, [ll/2160]**

    • Improve heuristic for --openssl-legacy-provider (#2155) - eagleflo, [pull/72]**

      Improve the heuristic for detecting whether we need --openssl-legacy-provider added in #2116 by also checking whether the Node.js was actually built against OpenSSL 3 and has that option available.

    • Revert "Don't look for background updates unless Wrangler finished successfully" - jyn514, [pull/21]**

1.19.6
Published on December 16, 2021

v1.19.6

  • Features

  • Fixes

    • Don't look for background updates unless Wrangler finished successfully - jyn514, [pull/21]**

      This works around a segfault due to OpenSSL's exit handlers not being thread-safe.

      See https://github.com/cloudflare/wrangler/issues/1464#issuecomment-988245785 for an explanation and alternatives.

    • fix: incomplete binary with npm installation - 12f23eddde, [pul2149]**

      Closes #2148. This PR modifies binary-install.js (reference) to make sure the file stream is complete before the program finishes. I'm not a ... truncated

    • Get https websockets working - jyn514, [pull/21]**

      It turns out websocket upgrades with HTTP/2 require an HTTP extension, which Cloudflare doesn't currently support: https://datatracker.ietf.org/doc/html/rfc8441

      To avoid this, enable HTTP/1 for the remote client.

      This required an upd ... truncated

    • Get the audit CI job passing - jyn514, [pull/21]**

      Note that I didn't say "fix the vulnerabilities" - this just ignores the chrono and time vulnerabilities because they're both very hard to fix and not very common in practice.

      This uncovered a tokio vulnerability, which I've fixed by ... truncated

    • Proxy websocket connections when using authenticated (realish) preview - jyn514, [pull/21]**

      Previously, Wrangler would return a "101 Switching Protocols" response and then immediately close the TCP connection. This changes it to instead continue proxying the connection to the remote worker.

      This is simpler than `wrangler dev ... truncated

  • Maintenance

    • Update Rust toolchain to 1.57 - taylorlee, [pull145]**

      I originally updated my toolchain to 1.56.1 on a local branch, since afaict rust-analyzer wasn't able to work with derived StructOpt proc-macros in 1.54. Since 1.57 was released today, I figured I'd update it all the way in this pr.

      foll ... truncated

1.19.5
Published on November 10, 2021

v1.19.5

  • Features

    • add __STATIC_CONTENT_MANIFEST as a text module for modules workers - g45t345rt, [pull126]**

      The __STATIC_CONTENT_MANIFEST is not accessible when using modules workers [sites]

      This pr makes it possible to import the content of manifest as text.

      It is also in favor of storing the manifest in vars https://github.com/cloudf ... truncated

  • Maintenance

    • Bump os-version to 0.2.0 - a1ien, [pull/212**

      In 0.2 os-version use new stable version of plist In plist 1.2.2(which is not published yet) remove chrono dependency and use time 0.3 which fix part of #2117

    • Fix missing fmt argument in error message - dtolnay, [pull/28]**

      • The first commit fills in a missing argument to {} in config.rs. Without this, the error message would literally be 'Your token has status "{}"' with curly braces in it instead of the token status.

      • The second commit closes an incon ... truncated

    • Fix some migration errors - xortive, [pull/27]**

      • Don't include migrations in Target for preview/dev uploads
    • Fixes wrangler.toml being incorrectly inserted into existing directory - Scotsoo, [pull110]**

      Fixes #2051 by passing new_name rather than name to config_path path

    • Remove serde-hjson transitive dependency - a1ien, [pull/212**

      serde-hjson crate is not maintained anymore With removing this dependency we also remove duplicate of old serde Also in new version of config crate hjson also removed

    • Remove unneeded heartbeat logic with sketchy time addition - [nataliescottdavidn], pull/2129**

    • Remove unused eventual dependency - a1ien, [pull/211**

      This also fix part of #2117

    • Update hash comment to changed XxHash64 usage - dcousens, [pull/24]**

      As introduced in https://github.com/cloudflare/wrangler/pull/1221

    • use --openssl-legacy-provider flag when running node 17 - caass, [pull/211**

      Closes #2108

      Node 17 uses openssl 3 by default, which is not compatible with webpack 4. This change adds a check to see if the user is running node 17, and if they are, we add the appropriate flag to the call to node (https://github.com/no ... truncated

1.19.4
Published on October 19, 2021
  • Features

    • Force flag for kv commands to avoid user confirmation prompt - andersquist, [pu/2100]**

      Make it possible to override any user confirmation prompt when performing KV bulk deletes.

  • Fixes

    • Allow running wrangler dev without an account_id - jyn514, [pull/20]**

      Previously, running it with no account_id and no config in ~/.wrangler would give an error

    • Don't delete unused assets for sites - threepointone, [ll/2096]**

      We have a consistency issue when after uploading a new site, it takes a while for the worker to propagate, so incoming requests will try to fetch older assets, and 404.

    • Allow host to be passed while authenticated - jspspike, [pull/91]**

      This also adds an --unauthenticated flag to dev and fixes bad error message

    • Fix wrangler dev session expiration - Electroid, [pull071]**

      This PR fixes the issue described in #2068. API errors related to syntax or preview token return the same bad_request status code, and the changes should address these two particular cases.

    • Move TOML table fields come later than other fields - antiphoton, [pul2085]**

      Reorder manifest fields so that table fields (durable_objects, kv_namespaces, site) come later than string fields. The reason table fields need to come later is the same as #2037.

    • Only warn about compatibility dates on publish - Electroid, [pull080]**

      Changes the compatibility date warning to only occur when using wrangler publish. We do not want this warning to be sent when using other commands like wrangler tail, etc.

1.19.3
Published on September 16, 2021
  • Features

    • Generate compatibility_date in wrangler init and warn if it's missing - kentonv, [pull/20]**

      We'd like everyone to specify a compatibility_date in their wrangler.toml going forward. This change both adds the date automatically to newly-generated wrangler.toml files, and warns when parsing old ones that are missing it.

      See ... truncated

    • Implement wrangler dev --inspect - [jyn514], [pull/2016]

      Helps with #946.

      How do I use this?

      1. wrangler dev --inspect, which should have output similar to this:
      πŸ’  watching "./"
      πŸ‘‚  Listening on http://127.0.0.1:8787
      [2021-07-28 13:38:20] GET worker.jnelson.workers.dev/ HTTP/
      ... truncated
      
      [jyn514]: https://github.com/jyn514
      [pull/2016]: https://github.com/cloudflare/wrangler/pull/2016
      
    • OAuth integration for Wrangler login - ocsfrank, [pull/48]**

      Still in staging, but it should be ready for review.

      Please also ignore the cargo.toml, I will update it once the service goes to prod. The CI test are failing because of oauth2 library.

    • Tagged Durable Objects Migrations - xortive, [pull/12]**

      fixes #1950

      This PR adds support for tagged migrations to wrangler. Migration tags are a way to ensure that you are applying the correct migration to a given script that contains a DO.

      They are also used for allowing multiple migrati ... truncated

  • Fixes

    • Allow showing a backtrace for errors returned from main - [jyn514], [pull/2059]

      Example usage:

      $ RUST_BACKTRACE=1 wrangler dev --inspect
      Error: missing field `prewarm` at line 1 column 627
      
      Stack backtrace:
         0: <core::result::Result<T,F> as core::ops::try_trait::FromResidual<core::result::Result<core::con
      ... truncated
      
      [jyn514]: https://github.com/jyn514
      [pull/2059]: https://github.com/cloudflare/wrangler/pull/2059
      
    • Fix wrangler dev session expiration - ocsfrank, [pull/71]**

      This PR fixes the issue described in #2068. API errors related to syntax or preview token return the same bad_request status code, and the changes should address these two particular cases.

      In the future, it would be great to update th ... truncated

    • fix: remove panic when send fails, log error instead - nilslice, [pull/61]**

      Removes the panic on send failure from the last remaining place for this particular --watch error.

General

License
MIT OR Apache-2.0
Typescript Types
None found
Tree-shakeable
No

Popularity

GitHub Stargazers
3,145
Community Interest
3,040
Number of Forks
382

Maintenance

Commits
11/2110/22015
Last Commit
Open Issues
60
Closed Issues
961
Open Pull Requests
10
Closed Pull Requests
303

Versions

Versions Released
11/2110/2203
Latest Version Released
Apr 21, 2022
Current Tags
latest1.19.12
beta1.19.3-rc.1

Dependencies

Dependencies (3)
Dev Dependencies (0)

Contributors

EverlastingBugstopper
EverlastingBugstopper
Commits: 406
ashleymichal
ashleymichal
Commits: 304
ashleygwilliams
ashleygwilliams
Commits: 157
gabbifish
gabbifish
Commits: 120
xtuc
xtuc
Commits: 87
xortive
xortive
Commits: 78
jspspike
jspspike
Commits: 66
nilslice
nilslice
Commits: 37
jyn514
jyn514
Commits: 23
caass
caass
Commits: 20
ags799
ags799
Commits: 17
nataliescottdavidson
nataliescottdavidson
Commits: 15
signalnerve
signalnerve
Commits: 14
ObsidianMinor
ObsidianMinor
Commits: 13
Electroid
Electroid
Commits: 12