Cloudflare Docs
Workers
Cloudflare Docs
Workers
GitHub icon
Visit Workers on GitHub
Set theme to dark (⇧+D)
  1. Products
  2. Workers
  3. Get started
  4. Guide

Get started guide

This guide will instruct you through setting up and deploying your first Worker.

​​ Get started in the dashboard

By following the Get started guide, you will create a Worker using the command line. To create your first Worker using the Cloudflare dashboard:

  1. Log in to the Cloudflare dashboard and select your account.
  2. Select Workers & Pages > Create application.
  3. Select Create Worker > Deploy.

​​ Prerequisites

  1. Sign up for a Cloudflare account.
  2. Install npm.
  3. Install Node.js.

​​ 1. Create a new Worker project

C3 (create-cloudflare-cli) is a command-line tool designed to help you setup and deploy Workers to Cloudflare as fast as possible.

Open a terminal window and run C3 to create your Worker project:


$ npm create cloudflare@latest


$ yarn create cloudflare

This will prompt you to install the create-cloudflare package, and lead you through setup.

For this guide, set up a basic Worker:

  1. Name your new Worker directory by specifying where you want to create your application.
  2. Select "Hello World" script as the type of application you want to create.
  3. Answer yes or no to using TypeScript.

You will be asked if you would like to deploy the project to Cloudflare.

  • If you choose to deploy, you will be asked to authenticate (if not logged in already), and your project will be deployed to the Cloudflare global network.
  • If you choose not to deploy, go to the newly created project directory to begin writing code. Deploy your project by following the instructions in step 4.

In your project directory, C3 has generated the following:

  1. wrangler.toml: Your Wrangler configuration file.
  2. index.js (in /src): A minimal 'Hello World!' Worker written in ES module syntax.
  3. package.json: A minimal Node dependencies configuration file.
  4. package-lock.json: Refer to npm documentation on package-lock.json.
  5. node_modules: Refer to npm documentation node_modules.

​​ 2. Develop with Wrangler CLI

The Workers command-line interface, Wrangler, allows you to create, test, and deploy your Workers projects. C3 will install Wrangler in projects by default.

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 test your Worker locally during development.


$ npx wrangler dev

You will now be able to go to http://localhost:8787 to see your Worker running. Any changes you make to your code will trigger a rebuild, and reloading the page will show you the up-to-date output of your Worker.

​​ 3. Write code

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:


export default {
	async fetch(request, env, ctx) {
		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. Your Worker has to have a default export of an object, with properties corresponding to the events your Worker should handle.

  1. The event handler: async fetch(request)

This event handler will be called when your Worker receives a fetch event. You can define additional event handlers in the exported object to respond to different types of events. For example, add an async scheduled(event) {} function definition to respond to scheduled events.

  1. Parameters: request, env, context

The fetch event handler will always get three parameters passed into it: request, env and context.

  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 Workers code, refer to Workers Examples.

​​ 4. Deploy your project

If you did not deploy your Worker during step 1, deploy your Worker via Wrangler, to a *.workers.dev subdomain, or a Custom Domain, if you have one configured. If you have not configured any subdomain or domain, Wrangler will prompt you during the publish process to set one up.


$ npx wrangler deploy

Preview your Worker at <YOUR_WORKER>.<YOUR_SUBDOMAIN>.workers.dev.

​​ 5. Write tests

We recommend writing tests against your Worker. One way to do this is with the unstable_dev API in Wrangler. unstable_dev is used for writing integration and end-to-end tests.

An example of using unstable_dev in a unit test looks like this:


const { unstable_dev } = require("wrangler");



describe("Worker", () => {
  let worker;


  beforeAll(async () => {
    worker = await unstable_dev("src/index.js", {
      experimental: { disableExperimentalWarning: true },
    });
  });


  afterAll(async () => {
    await worker.stop();
  });


  it("should return Hello World", async () => {
    const resp = await worker.fetch();
    if (resp) {
      const text = await resp.text();
      expect(text).toMatchInlineSnapshot(`"Hello World!"`);
    }
  });

});

The code block consists of 4 parts:

  1. The import statement const { unstable_dev } = require("wrangler");, this initializes the unstable_dev API so it can be used in the test suite. The unstable_dev function accepts two parameters - await unstable_dev(script, options).

  2. The beforeAll() function for initializing unstable_dev(), this helps minimize the overhead required to start the dev server for each individual test, running the dev server for each test will take a longer time to resolve which can end up slowing down the tests.

  3. The afterAll() function, which calls await worker.stop() for stopping the dev server after it runs the test suite.

  4. The await worker.fetch() function, for checking the response received corresponds with what you were expecting.

To do more:

  • Review Tutorials to build projects on Workers.
  • Explore Examples to experiment with copy and paste Worker code.
  • Understand how Workers works in Learning.
  • Learn how to set up different Workers features in Configuration.
  • Learn about Workers limits, betas and pricing in Platform.
  • Set up Wrangler to programmatically create, test, and deploy your Worker projects.