CLI
Set up and deploy your first Worker with Wrangler, the Cloudflare Developer Platform CLI.
This guide will instruct you through setting up and deploying your first Worker.
- Sign up for a Cloudflare account ↗.
- Install
Node.js
↗.
Node.js version manager
Use a Node version manager like Volta ↗ or nvm ↗ to avoid permission issues and change Node.js versions. Wrangler, discussed later in this guide, requires a Node version of 16.17.0
or later.
Open a terminal window and run C3 to create your Worker project. C3 (create-cloudflare-cli
) ↗ is a command-line tool designed to help you set up and deploy new applications to Cloudflare.
For setup, select the following options:
- For What would you like to start with?, choose
Hello World example
. - For Which template would you like to use?, choose
Hello World Worker
. - For Which language do you want to use?, choose
JavaScript
. - For Do you want to use git for version control?, choose
Yes
. - For Do you want to deploy your application?, choose
No
(we will be making some changes before deploying).
Now, you have a new project set up. Move into that project folder.
What files did C3 create?
In your project directory, C3 will have generated the following:
wrangler.toml
: Your Wrangler configuration file.index.js
(in/src
): A minimal'Hello World!'
Worker written in ES module syntax.package.json
: A minimal Node dependencies configuration file.package-lock.json
: Refer tonpm
documentation onpackage-lock.json
↗.node_modules
: Refer tonpm
documentationnode_modules
↗.
What if I already have a project in a git repository?
In addition to creating new projects from C3 templates, C3 also supports creating new projects from Git repositories. To create a new project from a Git repository, open your terminal and run:
<SOURCE>
may be any of the following:
user/repo
(GitHub)[email protected]:user/repo
https://github.com/user/repo
user/repo/some-template
(subdirectories)user/repo#canary
(branches)user/repo#1234abcd
(commit hash)bitbucket:user/repo
(Bitbucket)gitlab:user/repo
(GitLab)
At a minimum, template folders must contain the following:
package.json
wrangler.toml
src/
containing a worker script referenced fromwrangler.toml
C3 installs Wrangler, the Workers command-line interface, in Workers projects by default. Wrangler lets you to create, test, and deploy your Workers projects.
After you have created your first Worker, run the wrangler dev
command in the project directory to start a local server for developing your Worker. This will allow you to preview your Worker locally during development.
If you have never used Wrangler before, it will open your web browser so you can login to your Cloudflare account.
Go to http://localhost:8787 ↗ to view your Worker.
Browser issues?
If you have issues with this step or you do not have access to a browser interface, refer to the wrangler login
documentation.
With your new project generated and running, you can begin to write and edit your code.
Find the src/index.js
file. index.js
will be populated with the code below:
Code explanation
This code block consists of a few different parts.
export default
is JavaScript syntax required for defining JavaScript modules ↗. Your Worker has to have a default export of an object, with properties corresponding to the events your Worker should handle.
This fetch()
handler will be called when your Worker receives an HTTP request. You can define additional event handlers in the exported object to respond to different types of events. For example, add a scheduled()
handler to respond to Worker invocations via a Cron Trigger.
Additionally, the fetch
handler will always be passed three parameters: request
, env
and context
.
The Workers runtime expects fetch
handlers to return a Response
object or a Promise which resolves with a Response
object. In this example, you will return a new Response
with the string "Hello World!"
.
Replace the content in your current index.js
file with the content below, which changes the text output.
Then, save the file and reload the page. Your Worker’s output will have changed to the new text.
No visible changes?
If the output for your Worker does not change, make sure that:
- You saved the changes to
index.js
. - You have
wrangler dev
running. - You reloaded your browser.
Deploy your Worker via Wrangler to a *.workers.dev
subdomain or a Custom Domain.
If you have not configured any subdomain or domain, Wrangler will prompt you during the publish process to set one up.
Preview your Worker at <YOUR_WORKER>.<YOUR_SUBDOMAIN>.workers.dev
.
Seeing 523 errors?
If you see 523
errors when pushing your *.workers.dev
subdomain for the first time, wait a minute or so and the errors will resolve themselves.
To do more:
- Visit the Cloudlfare dashboard ↗ for simpler editing.
- Review our Examples and Tutorials for inspiration.
- Set up bindings to allow your Worker to interact with other resources and unlock new functionality.
- Learn how to test and debug your Workers.
- Read about Workers limits and pricing.