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 Open external link before continuing.

​​ 1. Create a new project

C3 (create-cloudflare-cli) is a command-line tool designed to help you setup and deploy Workers to Cloudflare as fast as possible. To get started, open a terminal window and run with npm:

$ npm create cloudflare

or yarn:

$ yarn create cloudflare

This will prompt you to install the create-cloudflare Open external link package, and lead you through a setup wizard.

Once your project has been configured and scaffolded, you will be asked if you would like to deploy the project to Cloudflare. If you choose not to deploy, you can navigate to the newly created project folder to begin development. Otherwise, you’ll be asked to authenticate (if not logged in already), and your project will be deployed.

​​ 2. Develop with Wrangler CLI

The Workers command-line interface, Wrangler, allows you to create, test, and deploy your Workers projects. Templates installed via C3 will have it installed in the project by default.

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

You will now be able to go to http://localhost:8787 Open external link 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.

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

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

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

3. Parameters: request, env, context

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

4. 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, run C3 again for more examples or refer to Workers Examples in our documentation.

​​ 4. Deploy your project

If you did not deploy previously via C3, you can 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.

Deploy to workers.dev
$ 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.

​​ Next steps

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