npm i @cloudflare/wrangler@1.8.0-rc.0 -gThe documentation below assumes you have some familiarity with Wrangler and are already developing Workers. If this is not the case that is OK, come back after you've read through our Quickstart and have gotten up and running with Wrangler.
These features are all unstable and are not beholden to the same backwards compatibility guarantees as normal Wrangler releases.
Proceed with Caution!
Thanks for trying these features out! We're really excited, there's some really cool stuff in here :)
There are three main features in this release candidate which each have their own individual testing instructions:
$ wrangler dev --help
👂 Start a local server for developing your worker
USAGE:
wrangler dev [OPTIONS]
FLAGS:
--help Prints help information
OPTIONS:
-e, --env <env> environment to build
-h, --host <host> domain to test behind your worker. defaults to example.com
-i, --ip <ip> ip to listsen on. defaults to localhost
-p, --port <port> port to listen on. defaults to 8787wrangler 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. If either of these things don't happen, or you think the output is incorrect, please file an issue!
You should be able to use cURL, Postman, and any other HTTP client you'd like with this.
wrangler dev should work with Workers Sites as well! If your site has some sort of configuration for the base url, you'll want to change them to point to localhost:8787 instead of the usual. Then you can just run wrangler dev with the same configuration options outlined above.
If you'd like to provide feedback on wrangler dev, you can comment on this issue or file a new one! Just make sure to prefix your issue title with [dev].
If you'd like for wrangler dev to listen on something other than localhost, you can pass something like --ip 127.0.0.1. This may be useful if you want to test with Docker.
You can also pass --port 8000 if you are already using port 8787 for something else.
If you would like to try something that hasn't been tested yet, you could try to put a worker in front of something you're running on localhost.
Let's say you have a react app that you're developing locally and it's running on localhost:4000 and you want to also develop a worker at the same time (maybe play around with the new HTMLRewriter API a bit). Unfortunately, you cannot call $ wrangler dev --host localhost:4000 because Cloudflare's preview service needs the back end to be a public URL.
What you can do instead is spin up a TryCloudflare endpoint and pass that url to the --host argument of wrangler dev and then develop them in tandem.
This is a completely unpaved path that has not been tested at all so your mileage may vary. If you get it to work, we'd love to hear about it!
To add a secret to your project, from project root run wrangler secret put <SECRET_NAME>, then type in your secret when prompted.
Now, modify your script to access the secret and return it in the response:
addEventListener('fetch', event => {
event.respondWith(handleRequest(event.request))
})
/**
* Respond with secret text
* @param {Request} request
*/
async function handleRequest(request) {
return new Response(`this was super secret! ${SECRET_NAME}`, {
headers: { 'content-type': 'text/plain' },
})
}Run wrangler preview and you should see the browser pop up with the Cloudflare Workers preview and your response.
Note: secrets require authentication for use; if you see an error saying that wrangler fell back to unauthenticated preview, try adding your account_id to your wrangler.toml, or re-run wrangler config
If you already have a project using KV to store secrets, it's easy to migrate to using secrets.
Let's use an example of a Worker that calls a third party API using an API token. It might look something like this if you are using KV to store the token:
example script:
async function handleRequest(request) {
// With secrets, we can remove this line...
let API_TOKEN = await KV_SECRETS.get("API_TOKEN")
let init = {
headers: {
'content-type': 'application/json;charset=UTF-8',
// ...and use our API_TOKEN variable directly here
'authorization': `Bearer ${API_TOKEN}`,
},
}
const response = await fetch('https://example.com/api/resource', init)
const result = await response.json()
return new Response(result, { headers: { 'content-type': 'application/json;charset=UTF-8' } })
}
addEventListener('fetch', event => {
return event.respondWith(handleRequest(event.request))
})example wrangler.toml:
name = "worker"
type = "javascript"
account_id = "youraccountid"
# remove this line
kv-namespaces = [{ id = "kvnamespaceid", binding = "KV_SECRETS" }]From the command line, run wrangler secret put API_TOKEN. You will be prompted to provide your secret here. You can also pipe a secret to the command in the case of CI:
$ echo "secretapitokenshhdontpeek" | wrangler secret put API_TOKENSecrets are scoped to each script, so if you are developing across multiple environments in Wrangler, you'll want to set secrets individually on each environment. Like other Wrangler commands, secret commands accept an --env flag specifying the named environment in your wrangler.toml.
for example, given this wrangler.toml:
name = "worker"
type = "javascript"
account_id = "youraccountid"
[env.prod]if you want to make the API_TOKEN secret for your prod env, you would run
$ wrangler secret put API_TOKEN --env prodIn addition to Secrets, you can also add simple text globals to your Worker. These can be handy when you want to use the same script file, but flip based on "environment". Let's try a simple one where we use a global "ENV" to tell our Worker whether it is in "production" or "staging".
addEventListener('fetch', event => {
event.respondWith(handleRequest(event.request))
})
/**
* Respond with hello worker text
* @param {Request} request
*/
async function handleRequest(request) {
return new Response(`this worker is running in ${ENV}`, {
headers: { 'content-type': 'text/plain' },
})
}
In your wrangler.toml, add the following:
name = "worker"
type = "javascript"
account_id = "your-account-id"
workers_dev = true
config = { ENV = "staging" }
[env.prod]
config = { ENV = "production" }Now, if you run wrangler preview, you should get back the response this worker is running in staging. If you then run wrangler preview --env prod, you should get back the response this worker is running in production. ✨
Inheritance works for config vars very nicely; if i wanted to include a hostname in the above but wanted it to be the same between workers, you can add it to the top level and it will be inherited by all of the environments:
name = "worker"
type = "javascript"
account_id = "your-account-id"
workers_dev = true
config = { ENV = "staging", hostname = "https://example.com" }
[env.prod]
config = { ENV = "production" }Both worker and worker-prod will have access to the variable hostname with value https://example.com.
We love bug reports!!! But we also love any feedback on terminal messaging, including success messages, error messages, etc. Please feel free to file an issue with any feedback or bug reports.
If you are deploying Workers to a zone on Cloudflare (as opposed to deploying to a subdomain on workers.dev), you can now specify multiple routes in your wrangler.toml file! Just change your route key to routes and turn the value into an array:
name = "worker"
type = "javascript"
account_id = "youraccountid"
# change this line
# route = "example.com/foo/*"
# to this line
routes = ["example.com/foo/*", "example.com/bar/*"]
zone_id = "yourzoneid"*Note: the route key is still supported for backward compatibility and simplicity; many Workers projects only need a single root level route. For everyone else, we created a new key.
There are a few potential results of deploying to a route, and each route is deployed individually (we don't currently have a bulk upload endpoint for routes). Wrangler will tell you if:
- your route was created successfully
- your route already existed
- the route you specified is already pointing to a different Worker
- there was an error deploying to a route (includes the returned API error)
Once you have published, at minimum visit the zoned dashboard on Cloudflare to confirm that your routes table has been updated.
To list the routes associated with a zone, run wrangler route list
To delete a route from a zone, run wrangler route delete <route-id> (route ids are included in the output of wrangler route list).
These should respond appropriately to an --env flag, so if you have a wrangler.toml with
name = "my-worker"
[env.prod]
routes = ["example.com/other-path"]Running wrangler route list --env prod will return the routes for the worker named my-worker-prod
We are of course interested in bug reports!!! We also love any feedback on terminal messaging, including success messages, error messages, etc. Please feel free to file an issue with any feedback or bug reports.
Just like the route key, routes is incompatible with workers_dev. It also requires a zone_id value to deploy. Finally, you can only specify route or routes, not both.
Here are a couple of "evil" tomls:
name = "worker"
type = "javascript"
account_id = "youraccountid"
routes = ["example.com/foo/*", "example.com/bar/*"]
zone_id = "" # zone_id is required to deploy to routesname = "worker"
type = "javascript"
account_id = "youraccountid"
workers_dev = true # you must specify either routes or a workers_dev deploy, not both
routes = ["example.com/foo/*", "example.com/bar/*"]
zone_id = "yourzoneid"name = "worker"
type = "javascript"
account_id = "youraccountid"
route = "example.com/*" # you must specify either route or routes, not both
routes = ["example.com/foo/*", "example.com/bar/*"]
zone_id = "yourzoneid"While your zone_id can be specified once at the top level and used across all environments, neither the route key nor the routes key should inherit; if you specify a zoned deploy in an environment, you must specify either route or routes.
bad:
name = "worker"
type = "javascript"
account_id = "youraccountid"
routes = ["example.com/foo/*", "example.com/bar/*"]
zone_id = "yourzoneid"
[env.foo]
# you need to include a `route | routes` entry heregood:
name = "worker"
type = "javascript"
account_id = "youraccountid"
routes = ["example.com/foo/*", "example.com/bar/*"]
zone_id = "yourzoneid"
[env.foo]
routes = ["foo.example.com/foo/*", "foo.example.com/bar/*"]This version does not support the concept of "null" workers.
i don't quite understand this; i assume you mean if your worker has an origin?