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

Using npm

npm i @cloudflare/wrangler -g

Using cargo

cargo install 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"

• 🦀⚙️ build

  Build your project. This command looks at your wrangler.toml file and runs the build steps associated with the "type" declared there.

• 🔧 config

  Configure your global Cloudflare user. You will need to pass your email and API key:

  wrangler config <email> <api_key>
  

• ☁️ 🆙 publish

  Publish your Worker to Cloudflare. This uses several keys in your wrangler.toml depending on whether you are publishing to a workers.dev subdomain or your own domain, registered with Cloudflare.

  wrangler publish
  

  By default, publish will make your worker available at <project-name>.<subdomain>.workers.dev. To disable publishing to your workers.dev subdomain, set private = true in your wrangler.toml. This setting prevents the publish command from making your worker publicly available. To explicitly enable deployment to <project-name>.<subdomain>.workers.dev, you can set private = false.

  To use this command, you'll need to have the following keys in your wrangler.toml:

  • name
  • type
  • account_id

  You'll also need to have a workers.dev subdomain registered. You can register a subdomain by using:

  wrangler subdomain <name>
  

  A --release can be optionally passed to publish your worker to a domain you have registered with Cloudflare. To use --release your wrangler.toml must include:

  • name
  • type
  • account_id
  • zone_id
  • route

• 🔬 preview

  Preview your project using the cloudflareworkers.com API.

  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:

  wrangler preview post hello=hello
  wrangler preview get // this is the default
  

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

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

  • private: This is a boolean. If set to true, when using wrangler publish, it will push your script but not make it publically available. This does not affect publishing in --release mode to a registered domain. Those pushes are always public. If this is not in your wrangler.toml it is assumed your project is public.

  • type: This key tells wrangler build how to build your project. There are currently 3 options, 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 reuqired for publish --release.

  • 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 for publish --release.

  • webpack_config: This is the path to the webpack configuration file for your worker. This is optional and defaults to webpack.config.js

  • [[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. e.g. (per namespace):

    [[kv-namespaces]]
    binding = "FOO"
    id = "0f2ac74b498b48028cb68387c421e279"
    

    Note: Creating your KV Namespaces should be handled either via the api or via your Cloudflare dashboard.

⚓ Installation

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.

Updating wrangler:

To get the latest version of Wrangler, using Cargo, run:

cargo install wrangler --force

To get the latest version of Wrangler, using NPM, run:

npm install @cloudflare/wrangler

⚡ Quick Start

1. Generate a new project:

   wrangler generate
   

2. Move into the new project directory:

   cd worker
   

3. Build your project:

   wrangler build
   

4. Preview your project:

   wrangler preview
   

5. (optional) Configure with your Cloudflare account:

   wrangler config <email> <api_key>
   

   Configuring your account is required to use the publish step, which will push your Worker live to the Cloudflare edge. If you don't configure, you can still use wrangler to generate, build, and preview a Worker.

   Optionally, create a workers.dev subdomain:

   wrangler subdomain <name>
   

6. Check your configuration:

   wrangler whoami
   

7. Publish your project:

   To publish to a workers.dev subdomain:

   wrangler publish
   

   To publish to a domain you have registered with Cloudflare, add a route and a zone_id to your wrangler.toml. Then run:

   wrangler publish --release
   

Changelog

🏄‍♀️ 1.1.1

• Features

  • Install current version, not latest - ashleygwilliams, issue/418

    Previously the NPM installer for wrangler would always pull the most recent release from GitHub releases, and the installer did not increase version numbers when Wrangler did. Many users found this confusing. Now the installer will increment versions along with Wrangler releases, and point at specific versions rather than the most recent one at the time of installation.

  • Improve JSON errors debuggability - xtuc, pull/394

    This PR improves JSON error output in wrangler. Specifically:

    • If a package.json file fails to decode, wrangler now emits a clearer error:

      $ wrangler build
      ⬇️  Installing wranglerjs...
      ⬇️  Installing wasm-pack...
      thread 'main' panicked at 'could not parse "./package.json": Error("expected `,` or `}`", line: 4, column: 3)', src/libcore/result.rs:999:5
      

    • If the wranglerjs backend returns invalid JSON, it now preserves the output file for further investigation. Note that the console doesn't print the output file location by default, and you will need to pass RUST_LOG=info while running wrangler build, and search for the --output-file=FILE argument passed to wranglerjs:

      $ RUST_LOG=info wrangler build
      ⬇️ Installing wasm-pack...
      [2019-08-09T19:28:48Z INFO  wrangler::commands::build::wranglerjs] Running "/Users/kristian/.nvm/versions/node/v12.1.0/bin/node" "/Users/kristian/src/workers/wrangler/wranglerjs" "--output-file=/var/folders/5x/yzqyqst11n518yl8xl7yv1f80000gp/T/.wranglerjs_output5eREv" # ...
      

    • If the preview service returns invalid JSON, it now emits a clearer error, and the full output can be seen by using RUST_LOG=info.

      Previously:

      $ wrangler preview
      ⬇️ Installing wasm-pack...
      ⬇️ Installing wranglerjs...
      ✨   Built successfully.
      Error: Error("expected value", line: 2, column: 1)
      

      Now:

      $ wrangler preview
      ⬇️ Installing wranglerjs...
      ⬇️ Installing wasm-pack...
      ✨   Built successfully, built project size is 1 MiB. ⚠️  Your built project has grown past the 1MiB size limit and may fail to deploy. ⚠️  ✨
      Error: https://cloudflareworkers.com/script: Server Error: 502 Bad Gateway
      

• Fixes

  • Fix wrangler config for systems with non-unix EOL - xortive, issue/389

    wrangler config was not properly truncating whitespace from the end of user input, resulting in a panic when trying to use wrangler publish, because wrangler would try to create an HTTP header with invalid characters. Now, wrangler will properly truncate extra whitespace (including \r) from the end of the input into wrangler config.

• Maintenance

  • Migrate straggler emojis to terminal::emoji - EverlastingBugstopper, pull/382

    This PR updates the last remaining instances where wrangler was using hard-coded emojis for messages, rather than using terminal::emoji. In addition, there are two instances where this PR changes the usage of the ⛔ emoji to ⚠️.

  • Move test fixtures to their own directory - EverlastingBugstopper, pull/383

    This PR aggregates fixtures used in integration tests into a fixtures directory to make it easier to find/use them.

  • Update issue templates to fit GitHub's data model - EverlastingBugstopper, pull/387

    Our previous issue templates were not picked up by GitHub's user interface. This PR updates the templates to fit the accepted data model, and adds some style tweaks to make the templates easier to use.

  • Move Emoji formatting/messaging into new functions - ashleymichal, pull/391

    This PR makes improvements to the internal messaging logic of Wrangler, allowing us to be more flexible in how we display information to users.

• Documentation

  • Update README to include config, env var changes - ashleymichal, pull/379

    In 1.1.0 we changed the config command to be interactive. This PR updates the README to reflect that change.

  • Add section to readme about Vendored OpenSSL - xortive, pull/407

    Wrangler has some external OpenSSL dependencies when installing on Linux -- this PR documents those dependencies, and how to install Wrangler using a vendored OpenSSL feature flag:

    cargo install wrangler --features vendored-openssl