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

Additional Documentation

General documentation surrounding workers development and using wrangler can be found here. This documentation will be highly valuable to you when developing with wrangler.

🎙️ Commands

• 👯 generate

  Scaffold a project, including boilerplate for a Rust library and a Cloudflare Worker. You can pass a name and template to this command optionally.

  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 options:

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

• 🔧 config

  Configure your global Cloudflare user. This is an interactive command that will prompt you for your email and API key:

  wrangler config
  Enter email:
  [e-mail]
  Enter api key:
  ...
  

  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.

  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 <your-worker>.<your-subdomain>.workers.dev.

Publishing to workers.dev

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:

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

Publishing to your own domain

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
workers_dev	false	workers_dev = false
route	The route you would like to publish to	route = "example.com/my-worker/*"
zone_id	Your Cloudflare zone ID, this can be found in the Cloudflare dashboard	zone_id = "b6558acaf2b4cad1f2b51c5236a6b972"

Publishing the same code to multiple places

If you would like to be able to publish your code to multiple places, please see the documentation for environments.

• 🔬 preview

  Preview 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:

  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

  wrangler preview
  

  or

  wrangler preview get
  

  POST requests can be sent with

  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.

• 🗂️ kv

  Interact with your Cloudflare Workers KV store. Check out the docs.

🔩 Configuration

There are two types of configuration that wrangler uses: global user and per project.

• Global User

  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.

• Using environment variables

  You can also configure your global user with environment variables. This is the preferred method for using Wrangler in CI:

  # e.g.
  CF_API_KEY=superlongapikey CF_EMAIL=[e-mail] wrangler publish --release
  # where
  # $CF_API_KEY -> your Cloudflare API key
  # $CF_EMAIL -> your Cloudflare account email
  

• Per Project

  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/hello

    This 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 script
    • id: the namespace_id assigned to your KV Namespace upon creation.

    For example:

    kv-namespaces = [
        { binding = "FOO", id = "0f2ac74b498b48028cb68387c421e279" },
        { binding = "BAR", id = "068c101e168d03c65bddf4ba75150fb0" }
    ]
    

    Note: Creating your KV Namespaces should be handled using Wrangler's KV Commands.

  Environments

  Environments

  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.

Additional Installation Instructions

Wrangler can be installed both through npm and through Rust's package manager, Cargo.

Using npm

1. If 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.

2. Install Wrangler by running:

   npm i @cloudflare/wrangler -g
   

Using cargo

1. Install cargo:

   Rustup, a tool for installing Rust, will also install Cargo. On Linux and macOS systems, rustup can be installed as follows:

   curl https://sh.rustup.rs -sSf | sh
   

   Additional installation methods are available here.

2. Install wrangler:

   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.

   cargo install wrangler --features vendored-openssl
   

Manual Install

1. Download the binary tarball for your platform from our releases page. You don't need to download wranglerjs, wrangler will install that for you.

2. Unpack the tarball and place the binary wrangler somewhere on your PATH, preferably /usr/local/bin for linux/macOS or Program Files for windows.

Changelog

🐛 1.3.1

• Features

  • Environments - EverlastingBugstopper, issue/385

    Wrangler 1.3.1 includes supports for environments, allowing developers to deploy Workers projects to multiple places. For instance, an application can be deployed to a production URL and a staging URL, without having to juggle multiple configuration files.

    To use environments, you can now pass in [env.$env_name] properties in your wrangler.toml. Here's an example:

    type = "webpack"
    name = "my-worker-dev"
    account_id = "12345678901234567890"
    zone_id = "09876543210987654321"
    workers_dev = false
    
    [env.staging]
    name = "my-worker-staging"
    route = "staging.example.com/*"
    
    [env.production]
    name = "my-worker"
    route = "example.com/*"
    

    With multiple environments defined, wrangler build, wrangler preview, and wrangler publish now accept a --env flag to indicate what environment you'd like to use, for instance, wrangler publish --env production.

    To support developers transitioning to environments, we've written documentation for the feature, including further information about deprecations and advanced usage. Check out the documentation here!

  • KV commands - ashleymichal, gabbifish, issue/339

    Wrangler 1.3.1 includes commands for managing and updating Workers KV namespaces, keys, and values directly from the CLI.

    • wrangler kv:namespace

      wrangler kv:namespace allows developers to create, list, and delete KV namespaces, from the CLI. This allows Wrangler users to configure new namespaces without having to navigate into the Cloudflare Web UI to manage namespaces. Once a namespace has been created, Wrangler will even give you the exact configuration to copy into your wrangler.toml to begin using your new namespace in your project. Neat!

      $ wrangler kv:namespace create "MY_KV"
      🌀  Creating namespace with title "worker-MY_KV"
      ✨  Success: WorkersKvNamespace {
        id: "e29b263ab50e42ce9b637fa8370175e8",
        title: "worker-MY_KV",
      }
      ✨  Add the following to your wrangler.toml:
      kv-namespaces = [
        { binding = "MY_KV", id = "e29b263ab50e42ce9b637fa8370175e8" }
      ]
      

    • wrangler kv:key

      wrangler kv:key gives CLI users access to reading, listing, and updating KV keys inside of a namespace. For instance, given a namespace with the binding KV, you can directly set keys and values from the CLI, including passing expiration data, such as below:

      $ wrangler kv:key put --binding=KV "key" "value" --ttl=10000
      ✨  Success
      

    • wrangler kv:bulk

      wrangler kv:bulk can be used to quickly upload or remove a large number of values from Workers KV, by accepting a JSON file containing KV data. Let's define a JSON file, data.json:

      [
        {
          "key": "test_key",
          "value": "test_value",
          "expiration_ttl": 3600
        },
        {
          "key": "test_key2",
          "value": "test_value2",
          "expiration_ttl": 3600
        }
      ]
      

      By calling wrangler kv:bulk put --binding=KV data.json, I can quickly create two new keys in Workers KV - test_key and test_key2, with the corresponding values test_value and test_value2:

      $ wrangler kv:bulk put --binding=KV data.json
      ✨  Success
      

    The KV subcommands in Wrangler 1.3.1 make it super easy to comfortably query and manage your Workers KV data without ever having to leave the command-line. For more information on the available commands and their usage, see the documentation. 🤯

  • Reduce output from publish command - EverlastingBugstopper, issue/523

    This PR improves the messaging of wrangler publish.

    Before:

    ✨  Built successfully, built project size is 517 bytes.
    ✨  Successfully published your script.
    ✨  Success! Your worker was successfully published. You can view it at example.com/*
    

    After:

    $ wrangler publish
    ✨  Built successfully, built project size is 523 bytes.
    ✨  Successfully published your script to example.com/*
    

  • feat #323: Allow fn & promise from webpack config - third774, issue/323

    This PR fixes Wrangler's handling of webpack.config.js files to support functions and promises, as per the Webpack documentation.

  • Use webworker target - xtuc, issue/477

    This PR updates how Wrangler builds JavaScript projects with Webpack to conform to the webworker build target. This ensures that projects built with Wrangler are less likely to generate code that isn't supported by the Workers runtime.

• Fixes

  • Have live reload preview watch over entire rust worker directory - gabbifish, pull/535

    This change updates the live reload functionality to watch over the entire Rust worker directory, and does not look for package.json files that do not typically exist for Rust and WASM projects.

  • Fix javascript live preview for linux - gabbifish, issue/517

    This PR fixes an issue with Wrangler's live preview (wrangler preview --watch) functionality on Linux. In addition, it simplifies the console output for a live preview instance, which could get pretty noisy during development!

  • Different emojis for different commands - EverlastingBugstopper, pull/605

    KV subcommands would return the same emoji value in --help output. This PR updates the command-line output to use different emoji, making the output easier to read!

• Maintenance

  • Add keywords for npm SEO - EverlastingBugstopper, pull/583

    This PR improves the discoverability for wrangler on npm by adding keywords to the installer's package.json.

  • Clean up emoji - xortive, pull/455

    This PR removes some extraneous unicode that keeps our emoji from displaying correctly in certain terminal emulators, especially for multi-codepoint emoji.

• Documentation

  • Add documentation for init to the README - EverlastingBugstopper, pull/585

    This PR adds documentation in our README for wrangler init, which allows you to begin using an existing project with Wrangler.

  • Remove link to docs for installation because they link back to wrangler README - EverlastingBugstopper, pull/494

  • Minor formatting fix in README.md - kentonv, pull/515

    This PR fixes a small syntax issue in the Wrangler README, causing Markdown lists to render incorrectly.

  • Fix link to Cloudflare Workers preview service - dentarg, pull/472

    This PR fixes a link to the Cloudflare Workers preview service in the Wrangler README.