cloudflare / wrangler-legacy

🤠 Home to Wrangler v1 (deprecated)

🤠 wrangler

🛑 This repository is for Wrangler version 1, which is deprecated and no longer updated. This repository is now archived.

New versions of Wrangler are maintained in the Workers SDK repository.

---

Legacy Documentation

       

wrangler is a CLI tool designed for folks who are interested in using Cloudflare Workers.

Installation

You have many options to install wrangler!

For the latest version, see https://github.com/cloudflare/workers-sdk

Install with npm

We strongly recommend you install npm with a Node version manager like nvm, which puts the global node_modules in your home directory to eliminate permissions issues with npm install -g. Distribution-packaged npm installs often use /usr/lib/node_modules (which is root) for globally installed npm packages, and running npm install -g as root prevents wrangler from installing properly.

Once you've installed nvm and configured your system to use the nvm managed node install, run:

npm i @cloudflare/wrangler -g

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

Specify binary location

In case you need wrangler's npm installer to place the binary in a non-default location (such as when using wrangler in CI), you can use the following configuration options to specify an install location:

• Environment variable: WRANGLER_INSTALL_PATH
• NPM configuration: wrangler_install_path

Specify binary site URL

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

Install with cargo

cargo install wrangler

If you don't have cargo or npm installed, you will need to follow these additional instructions.

Install on Windows

perl is an external dependency of crate openssl-sys. If installing wrangler with cargo, you will need to have perl installed. We've tested with Strawberry Perl. If you instead install perl via scoop, you may need to also run scoop install openssl in order to get the necessary openssl dlls. Installing wrangler with npm instead of cargo is another option if you don't want to install perl.

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 javascript based on the "worker-template"

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

🔓 login

Authorize Wrangler with your Cloudflare login. This will prompt you with a Cloudflare account login page and a permissions consent page. This command is the alternative to wrangler config and it uses OAuth tokens.

wrangler login --scopes-list --scopes <scopes>

All of the arguments and flags to this command are optional:

• scopes-list: list all the available OAuth scopes with descriptions.
• scopes: allows to choose your set of OAuth scopes.

Read more about this command in Wrangler Login Documentation.

🔧 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:
superlongapitoken

You can also provide your email and global API key (this is not recommended for security reasons):

wrangler config --api-key
Enter email:
[email protected]
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 [email protected] 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.

wrangler-legacy's Issues

Handle API errors in script_status

When an API error is returned, https://github.com/cloudflare/wrangler/blob/921c626bb0a0a611ac7d6fb01fe0296d79f3bcca/src/user/account.rs#L27 doesn't handle it properly.

For example here's the API response: {"success":false,"errors":[{"code":10000,"message":"Authentication error"}]}, I would suggest adding into account the success field.

add banner img to readme

POST query with body message

Hello,

Thanks for the awesome library! I'm working with the demo example in Rust and have a question about sending POST requests with a body message.

In worker.js, I'm returning the request object as a JSON string:

async function handleRequest(request) {
    return new Response(JSON.stringify(request), {status: 200})
}

But calling it on the command line doesn't seem to pass the body along:

root@f396da212a3a:/src/demo# wrangler preview post "hello world"
🌀 Compiling your project to WebAssembly...
[INFO]: Checking for the Wasm target...
[INFO]: Compiling to Wasm...
    Finished release [optimized] target(s) in 2.08s
[INFO]: Installing wasm-bindgen...
[INFO]: Optional fields missing from Cargo.toml: 'description', 'repository', and 'license'. These are not necessary, but recommended
[INFO]: :-) Done in 2.36s
[INFO]: :-) Your wasm pkg is ready to publish at ./pkg.
👷‍♀️ POST https://00000000000000000000000000000000.cloudflareworkers.com
👷‍♀️ Your worker responded with: {"fetcher":{},"redirect":"manual","headers":{},"url":"https://example.com/","method":"POST","bodyUsed":false,"body":{"locked":false}}

Is this the right way to do it?

In case it helps, I'm using wrangler 0.1.0:

root@f396da212a3a:/src/demo# wrangler --version
👷‍♀️🧡☁️ ✨ wrangler 0.1.0

Allow to deploy to a route from

wrangler publish pushed up the script to the edge, but actually getting it running on the edge still required signing in and using the UI.

It would be great to be able to specify a route to deploy to, i.e:
wrangler route example.com/hello
or have a default route that the script gets deployed to. i.e. wrangler publish would just push to random-string.example.com.

Alternatively, you could have a route configured as a part of wrangler config

Generate command always prints rustwasm copy

https://github.com/cloudflare/wrangler/blob/9d4f33137a787ac5eb8887d291d50cdc9705df92/src/commands/generate.rs#L23

The generate command will always print Generating a new rustwasm worker project even if the passed template is unrelated to rustwasm.

Maybe just Generating a new Wrangler project would be more appropriate here?

fix the mistakes in readme

• installation should have "doesn't work right now" caveat
• no -- in the publish command ya dingus

Webpack: introducing JS deps

I realized that the PR might not the best way to track this discussion.

@steveklabnik you commented in #75 (comment), could you please elaborate? Are you aware of any precedence?

I agree that our JavaScript dependecy should be transparent for our users, apart from requiring nodejs.

It would be simpler for the user to not handle a node_modules/package.json setup in their project, especially if they are not used to JS.

How should we support wasm-pack?

Currently, wrangler directly depends on wasm-pack to ship Rust code.

However, with the introducion of Webpack, we can support wasm-pack using the existing wasm-pack-plugin. This allows the support of npm dependecies and more.

Removing wasm-pack also simplifies our internals; what do you think?

fix travis

creds are wrong and so is the repo name, probably etoomany name changes.

cleanup output, print finish statements

parameterize template

add instructions to readme about how to update wrangler

default name should auto increment

default name is "worker". if you try to use the default more than once it should be worker-1, worker-2, etc

'loudflare' is not recognized as an internal or external command

Copy/paste is being a bit wonky right now, but the TL;DR is that the call to cargo-generate when you run wrangler generate is not properly quoted. This means if there's a space in the path, things break, and it won't properly generate.

I'll try to get a more proper report later.

per project config file

• zone id xxxxx
• account id xxxxx
• routes { route: script, route: script }
• resources, [wasm, kv, ...]

0.1.1

changelog!

preview command, post to cloudflareworkers.com

logging

log + env_logger probs

[DISREGARD]`wrangler build` fails on compilation of `rustc-serialize`

Hello,

On a Mac running 10.14.2, I get the following when I run wrangler build in the folder generated by wrangler generate without changing anything:

Says it fails on the rustc-serialize function. I'll try to compile this module separately, and I'll file an issue on that dependency if the compilation issues are universal.

use enum for commands

CI

add crates.io badge

get rid of TODO

capture and use stdout

Moving wrangler-js into this repo

Source is https://github.com/xtuc/wrangler-js

Wrangler Workers preview OOM error

I attempted to follow the Wrangler tutorial and started by generating the demo project; I did not modify anything in the project.
I ran wrangler preview and hit a OOM: wasm memory issue.
It's very reproducible and others have confirmed they hit it as well.

wrangler's configuration format

We talked with @ashleygwilliams about a non-Rust nor JS centric configuration format.

I don't think we reached consensus on a format. I propose using yaml (and toml for backward compatiblity).

designing the publish command

there are a few considerations in designing the publish command that largely center around overwriting preexisting scripts and routes:

• publishing a script is always a put and always overwrites
• publishing a route is a post, and will fail if a route already exists with the same pattern
• there is no guarantee that a route with an id has the same pattern as it previously had

i have stopped work on route in #65 by allowing a single publish. if the route is changed in the wrangler.toml, multiple publishes will work, but attempts to publish to a route that has a pattern that has already been published will currently throw an error.

what is the behavior we want to see here? what API do we need to do to improve this situation?

tests

🙏

`Wrangler.toml` not appearing on `wrangler generate`

When I run wrangler generate the folder it creates does not contain a wrangler.toml file anywhere. I don't know if this is a bug or the file was deprecated and the docs were not updated. Either way I'd be happy to help with this issue.

This is on a Mac running 10.14.2, in case that's relevant

Default wildcard route for Apps

it would be nice to have a "sane default" of /* for "app" type scripts. need to take into consideration:

• zones that already have routes configured: most naive would be check route list and refrain from setting the wildcard if any exist

it would also be valid to simply have a default line in the configuration file.

Zoneless support

As suggested by @xtuc , I'm opening an issues to start the conversation around supporting zone-less Workers in Wrangler.

What are your thoughts in this direction?

travis keeps failing

use child_process to spawn commands

add windows tests to CI

refactor all cloudflare API calls to use cloudflare-rs

as we implemented KV support in Wrangler, we adopted the cloudflare-rs crate (https://github.com/cloudflare/cloudflare-rs) as our official cloudflare api client for use with those endpoints. We should make an effort to move all of our cloudflare api calls into that crate, which would give us uniformity in api request and response handling, as well as a more robust pattern for writing unit tests (the crate comes with an example mock api client).

should likely convert this into a project to track work both in wrangler and in cloudflare-rs.

as per #57 (comment)

only overwrite on force... for now

install binaries

parameterize project name

README, fix it

projects with a - in the name fail with file not found because of rust name inflection

s/-/_

Force overriding the route in multi-script mode

Wrangler should just override the script by default. Using a tool that deploys generated code, i'm not going to change the code in the UI.

Webpack: configuration in folders

Based on https://github.com/cloudflare/wrangler/wiki/Draft-Webpack-design; following #69.

We have (virtually or not) a Webpack configuration at the root of the workspace, which defines the entrypoint.

If we want the user to configure Webpack locally in each folder and we merge all the configurations in-memory. Since the workspace is considered as a single Webpack tree, the merged configuration will apply to everything.

Here are a few ideas:

1. Let the user merge it in the folder Webpack configuration; this doesn't fix the issue.

2. Each loaders has a test property where we can add the folder path, so only files in that folder will be affected with these rules; doesn't work with plugins.

3. Hook into Webpack and try to insolate the compiler ourselves; is that even feasable?
   3.1. build each folder as a seperate DLL/project and link them in the root.

Webpack: stabilize wasm finalizer

The transformation in Webpack to the Wasm binary has some edge cases, sometime triggered by emscripten binaries.

We should work on webpack/webpack#7565.

RFC: leverage Webpack as backend

Problem

Currently wrangler is coupled to wasm-pack, which makes it unpracticable for non-rust projects (especially JavaScript projects).

Proposal

Use Webpack as a backend to build any projects that use a Webpack configuration.

For prototyping, I made wranger-js and came up with a few demos https://github.com/xtuc/wrangler-js-demo to give you a better idea.

Note that we don't want to have multiple tools but rather add that support in wrangler to have a single tool.

Context about Webpack

With the integration of WebAssembly in Webpack, any loader can emit a wasm binary in Webpack that will be bundled along the JavaScript project.

That integration already implements the ECMAScript module integration, which make working with Wasm module easier in JavaScript.

Allows npm dependecies

Webpack is a bundler, npm dependecies are supported.

Optimize JavaScript

Webpack runs, in production mode, a JavaScript minifier. Also we could add Wasm optimization.

Auto generate the Worker's metadata.json

Webpack constructs the module graph of the project, we can look at it to find any wasm modules and generate the corresponding metadata.json.

switch API on plan

document openssl fix

I attempted the tutorial here but ran into a problem with openssl:
I installed cargo
$ curl https://sh.rustup.rs -sSf \| sh
and configured my shell with:
$ source $HOME/.cargo/env
I then succesfully installed wrangler with
$ cargo install wrangler
and tried to generate a "Hello, World" project with:
$ wrangler generate demo
However, that throws an error:

dyld: Library not loaded: /usr/local/opt/[email protected]/lib/libssl.1.1.dylib
Referenced from: /Users/userspace/Library/Caches/.wrangler/cargo-generate-2665b6ba17ab8008/cargo-generate
Reason: image not found
Error: ErrorMessage { msg: "failed to execute /Users/userspace/Library/Caches/.wrangler/cargo-generate-2665b6ba17ab8008/cargo-generate generate --git https://github.com/cloudflare/rustwasm-worker-template --name demo: exited with signal: 6" }

So I instead tried
$ cargo install cargo-generate
which led to a similar error:

It looks like you're compiling on macOS, where the system contains a version of
OpenSSL 0.9.8. This crate no longer supports OpenSSL 0.9.8.

As a consumer of this crate, you can fix this error by using Homebrew to
install the openssl package, or as a maintainer you can use the openssl-sys
0.7 crate for support with OpenSSL 0.9.8.

Unfortunately though the compile cannot continue, so aborting.

', /Users/username/.cargo/registry/src/github.com-1ecc6299db9ec823/openssl-sys-0.9.43/build/find_normal.rs:150:5
note: Run with RUST_BACKTRACE=1 environment variable to display a backtrace.

warning: build failed, waiting for other jobs to finish...
error: failed to compile cargo-generate v0.2.2, intermediate artifacts can be found at /var/folders/j7/_vypfcb179g8wbw84pkrrkx00000gn/T/cargo-installdX02Cv

emoji fallback

not all terminal support emoji. there is a library to wrap this:
https://github.com/rustwasm/wasm-pack/blob/master/src/emoji.rs
create a file like this for wrangler and then replace instances of emoji with constants from that file

use wasm-pack as an example. the implementation should basically be Exactly the Same

cache binaries

put wasm behind a flag, default to js only worker

not actually sure we want this for 0.1.0