Cloudflare Docs
Workers
Cloudflare Docs
Workers
Search icon (depiction of a magnifying glass)
GitHub icon
Visit Workers on GitHub
Set theme to dark (⇧+D)

Get started guide

This guide will instruct you through setting up a Cloudflare account to deploying your first Worker. This guide assumes that you already have a Cloudflare account. If you do not have a Cloudflare account, sign up before continuing.

​​ 1. Install Wrangler (Workers CLI)

Installing wrangler, the Workers command-line interface (CLI), allows you to init, dev, and publish your Workers projects.

To install wrangler, ensure you have npm installed, preferably using a Node version manager like Volta or nvm. Using a version manager helps avoid permission issues and allows you to easily change Node.js versions. Then run:

$ npm install -g wrangler

or install with yarn:

$ yarn global add wrangler

​​ 2. Authenticate Wrangler

To authenticate Wrangler, run wrangler login:

$ wrangler login

You will be directed to a web page asking you to log in to the Cloudflare dashboard. After you have logged in, you will be asked if Wrangler can make changes to your Cloudflare account. Scroll down and select Allow to continue.

​​ 3. Start a new project

With Wrangler installed, you are ready to create your Worker project.

Run wrangler init followed by your project name:

$ wrangler init <YOUR_WORKER>

In your terminal, you will be asked:

  1. Would you like to use git to manage this Worker? (y/n) Indicate y.
  2. Would you like to use TypeScript? (y/n) Indicate n to continue with JavaScript for this guide.
  3. No package.json found. Would you like to create one? (y/n) Indicate y.
  4. Would you like to create a Worker at <YOUR_WORKER>\src\index.js? Indicate y.

You can also use one of Cloudflare’s templates to start a new project.

After you have created your new Worker, cd into your new project directory:

$ cd <YOUR_WORKER>

In your project directory, wrangler init has generated the following files:

  1. wrangler.toml: Your Wrangler configuration file.
  2. index.js (in /src): A minimal Hello World Worker written in JavaScript module syntax.
  3. package.json: A minimal Node dependencies configuration file. Only generated if indicated in wrangler init command.
  4. tsconfig.json: TypeScript configuration that includes Workers types. Only generated if indicated in wrangler init command.

​​ 4. Run your development server

After you have created your first Worker, run the wrangler dev command to start a local server for developing your Worker. This will allow you to test your Worker in development.

$ wrangler dev

​​ 5. Write code

With your new project generated, you can begin to write your code.

After running the wrangler init command to generate your Worker, the index.js file will be populated with the code below:

export default {
  async fetch(request) {
    return new Response("Hello World!");
  },

};

This code block consists of four parts:

  1. The export statement: export default

export default is JavaScript syntax required for defining JavaScript modules. export default lets the Workers runtime know that this is a Worker object as opposed to another Cloudflare product. Refer to MDN documentation for more information on default exports.

  1. The event handler: async fetch(request)

The event handler indicates what events the Worker should listen to, such as fetch or scheduled.

  1. Parameters: request, env, context

The event handler will always get three parameters passed into it: request, env and context. If you would like to interact with these parameters, you will have to accept the parameters as variables by indicating them in your code. You can choose which parameters to use. They must always be written in order (request, env, context). In this example, request is indicated and your Worker can now interact with the Request object.

  1. The Response object: return new Response("Hello World!");

The Workers runtime expects fetch events to return a Response object. In this example, you will return a new Response with the string "Hello World!".

To review code changes in real time, rewrite the "Hello World!" string to "Hello Worker!" and, with wrangler dev running, save your changes.

To experiment with more premade Workers, refer to Workers Examples.

​​ 6. Publish your project

With your project configured, you can now publish your Worker. You can publish your Worker to a custom domain, or, if not configured, the Worker will publish to a *.workers.dev subdomain by default. To set up a *.workers.dev subdomain, go to the Cloudflare dashboard > Workers > Your subdomain > Change.

Publish to workers.dev
$ wrangler publish

You can preview your Worker at <YOUR_WORKER>.<YOUR_SUBDOMAIN>.workers.dev.

​​ Next steps

To do more with Workers, explore the Tutorials and Examples.