@cloudflare/wrangler

🤠 wrangler

 

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

Installation

You have many options to install wrangler!

Install with npm

npm i @cloudflare/wrangler -g

Install with cargo

cargo install wrangler

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

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:

• name: defaults to worker
• template: defaults to the https://github.com/cloudflare/worker-template
• type: defaults to "webpack"

📥 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.

🔧 config

Configure your global Cloudflare user. 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:
[e-mail]
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 CF_EMAIL=[e-mail] 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.

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.

Changelog

💬 1.7.0

• Features

  • 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.

• Fixes

  • 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.

• Maintenance

  • 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.