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

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

Changelog

😈 1.8.1

• Features

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

• Fixes

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