wrangler is a CLI tool designed for folks who are interested in using Cloudflare Workers.
You have many options to install wrangler!
npmbash
npm i @cloudflare/wrangler -g
cargobash
cargo install wrangler
If you don't have cargo or npm installed, you will need to follow these additional instructions.
For information regarding updating Wrangler, click here.
General documentation surrounding workers development and using wrangler can be found here. This documentation will be highly valuable to you when developing with wrangler.
generateScaffold a project, including boilerplate for a Rust library and a Cloudflare Worker. You can pass a name and template to this command optionally.
bash
wrangler generate <name> <template> --type=["webpack", "javascript", "rust"]
All of the arguments and flags to this command are optional:
name: defaults to workertemplate: defaults to the https://github.com/cloudflare/worker-templatetype: defaults to "webpack"initCreates 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.
bash
wrangler init <name> --type=["webpack", "javascript", "rust"]
All of the arguments and flags to this command are options:
name: defaults to the name of your working directorytype: defaults to "webpack"buildBuild your project. This command looks at your wrangler.toml file and runs the build steps associated
with the "type" declared there.
Additionally, you can build different environments. This is useful if you have different builds for different environments, but typically isn't needed. For more information see the environments documentation.
configConfigure your global Cloudflare user. This is an interactive command that will prompt you for your email and API key:
bash
wrangler config
Enter email:
testuser@example.com
Enter api key:
...
You can also use environment variables to configure these values.
publishPublish 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.
bash
wrangler publish
To use this command, the following fields are required in your wrangler.toml.
| Key | Value | Example |
| ---------- | ------------------------------------------------------------------------- | ------------------------------------------------- |
| name | the name of your worker | name = "your-worker" |
| type | build type (webpack, rust, or javascript) | type = "webpack" |
| account_id | your Cloudflare account ID, this can be found in the Cloudflare dashboard | account_id = "a655bacaf2b4cad0e2b51c5236a6b974" |
From here, you have two options, you can choose to publish to your own domain or you can choose to publish to \
If you want to publish to workers.dev, you will first need to have a workers.dev subdomain registered. You can register a subdomain by executing:
bash
wrangler subdomain <name>
After you have registered a subdomain, add workers_dev to your wrangler.toml.
| Key | Value | Example |
| --------------- | ----- | ------------------------ |
| workers_dev | true | workers_dev = true |
If you would like to publish to your own domain, you will need to specify these three fields in your wrangler.toml.
| Key | Value | Example |
| --------------- | ---------------------------------------------------------------------- | ---------------------------------------------- |
| workersdev | false | workers_dev = false |
| route | The route you would like to publish to | route = "example.com/my-worker/*" |
| zoneid | Your Cloudflare zone ID, this can be found in the Cloudflare dashboard | zone_id = "b6558acaf2b4cad1f2b51c5236a6b972" |
If you would like to be able to publish your code to multiple places, please see the documentation for environments.
previewPreview your project using the Cloudflare Workers preview service.
By default, wrangler preview will only bundle your project a single time. To enable live preview,
where Wrangler will continually update the preview service with the newest version of your project,
pass the --watch flag:
bash
wrangler preview --watch
You can optionally pass get or post and a body to this command. This will send a request to your
worker on the preview service and return the response in your terminal. For example:
GET requests can be sent with
bash
wrangler preview
or
bash
wrangler preview get
POST requests can be sent with
bash
wrangler preview post hello=hello
Additionally, you can preview different environments. This is useful if you have different builds for different environments (like staging vs. production), but typically isn't needed. For more information see the environments documentation.
kvInteract with your Cloudflare Workers KV store. Check out the docs.
There are two types of configuration that wrangler uses: global user and per project.
In Cloudflare's system, you have a User that can have multiple Accounts and Zones. As a result, your User
is configured globally on your machine. Your Account(s) and Zone(s) will be configured per project, but
will use your User credentials to authenticate all API calls. This config file is created in a .wrangler
directory in your computer's home directory.
To set up wrangler to work with your Cloudflare user, use the following commands:
config: a command that prompts you to enter your email and api key.whoami: run this command to confirm that your configuration is appropriately set up.
When successful, this command will print out your user information, including the type of plan you
are currently on.You can also configure your global user with environment variables. This is the preferred method for using Wrangler in CI:
```bash
CFAPIKEY=superlongapikey CF_EMAIL=testuser@example.com wrangler publish --release
```
Your project will need to have several things configured before you can publish your worker. These values are stored in a wrangler.toml file that wrangler generate will make for you. You will need to manually edit this file to add these values before you can publish.
name: This is the name of your project. It will be the name of your script.type: This key tells wrangler build how to build your project. There are currently three options (webpack, javascript, and rust), but we expect there to be more as the community grows.
javascript: This project contains a single JavaScript file, defined in package.json's main key.rust: This project contains a Rust crate that uses wasm-bindgen. It will be built with wasm-pack.webpack: This project contains any number of JavaScript files or Rust/C/C++ files that compile to
WebAssembly. Rust files will be built with wasm-pack.
This project type uses webpack and webpack plugins in the background to build your worker.zone_id: This is the ID of the "zone" or domain you want to run your script on. This is optional if you are using a workers.dev subdomain and is only required when workers_dev is false, or excluded from an environment configuration.account_id: This is the ID of the account associated with your zone. You might have more than one account, so make sure to use the ID of the account associated with the zone_id you provide, if you provide one.route: This is the route you'd like to use your worker on. You need to include the hostname. Examples:
*example.com/*http://example.com/helloThis key is optional if you are using a workers.dev subdomain and is only required when workers_dev is false, or excluded from an environment.
webpack_config: This is the path to the webpack configuration file for your worker. This is optional and defaults to webpack.config.js
workers_dev: This is a boolean flag that specifies if your worker will be deployed to your workers.dev subdomain. For more information, please read the environments documentation.kv-namespaces: These specify any Workers KV Namespaces you want to access from
inside your Worker. Each namespace you include should have an entry in your wrangler.toml that includes:
binding: the name you want to bind to in your scriptid: the namespace_id assigned to your KV Namespace upon creation.For example:
toml
kv-namespaces = [
{ binding = "FOO", id = "0f2ac74b498b48028cb68387c421e279" },
{ binding = "BAR", id = "068c101e168d03c65bddf4ba75150fb0" }
]
Note: Creating your KV Namespaces should be handled using Wrangler's KV Commands.
Additionally, you can configure Wrangler to publish to multiple environments. This means that your same codebase can be deployed to multiple places on your workers.dev subdomain, across multiple accounts, zones, and routes. Read more here.
Wrangler can be installed both through npm and through Rust's package manager, Cargo.
npmIf you don't already have npm on your machine, install it using npm's recommended method, a node.js version manager.
If you have already installed npm with a package manager, it is possible you will run into an EACCES error while installing wrangler. This is related to how many system packagers install npm. You can either uninstall npm and reinstall using the npm recommended install method (a version manager), or use one of our other install methods.
Install Wrangler by running:
bash
npm i @cloudflare/wrangler -g
cargoInstall cargo:
Rustup, a tool for installing Rust, will also install Cargo. On Linux and macOS systems, rustup can be installed as follows:
bash
curl https://sh.rustup.rs -sSf | sh
Additional installation methods are available here.
Install wrangler:
bash
cargo install wrangler
Installing wrangler on linux requires some OpenSSL-related packages to be installed. If you don't want to deal with this, you can use vendored OpenSSL.
bash
cargo install wrangler --features vendored-openssl
Download the binary tarball for your platform from our releases page. You don't need to download wranglerjs, wrangler will install that for you.
Unpack the tarball and place the binary wrangler somewhere on your PATH, preferably /usr/local/bin for linux/macOS or Program Files for windows.