wrangler is a CLI tool designed for folks who are interested in using Cloudflare Workers.
You have many options to install wrangler!
We strongly recommend you install npm with a Node version manager like nvm, which will allow wrangler to install configuration data in a global node_modules directory in your user's home directory, without requiring that you run as root.
Once you've installed nvm, run:
npm i @cloudflare/wrangler -gIf 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.
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
cargo install wranglerIf you don't have cargo or npm installed, you will need to follow these additional instructions.
perl is an external dependency of crate openssl-sys. If installing with cargo, you will need to have it installed. Installing with npm is another option if you don't want to install perl.
For information regarding updating Wrangler, click here.
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 publishScaffold 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 toworkertemplate: defaults to thehttps://github.com/cloudflare/worker-templatetype: defaults to "webpack"
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 directorytype: defaults to "webpack".
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.
Authenticate Wrangler with your Cloudflare login. This will prompt you with a Cloudflare account login page and is the alternative to wrangler 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:
superlongapitokenYou can also provide your email and global API key (this is not recommended for security reasons):
wrangler config --api-key
Enter email:
testuser@example.com
Enter global API key:
superlongapikeyYou can also use environment variables to configure these values.
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=testuser@example.com wrangler publish
# where
# $CF_API_KEY -> your Cloudflare API key
# $CF_EMAIL -> your Cloudflare account emailInteract with your Workers KV store. This is actually a whole suite of subcommands. Read more about in Wrangler KV Documentation.
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 OKAll of the arguments and flags to this command are optional:
env: environment to buildhost: domain to test behind your worker. defaults to example.comip: ip to listen on. defaults to localhostport: port to listen on. defaults to 8787
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
To learn about deploying static assets using wrangler, see the Workers Sites Quickstart.