Get started guide

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

​​ Get started in the dashboard

To create your first Worker using the Cloudflare dashboard:

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

​​ Prerequisites

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

​​ 1. Create a new Worker project

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 Open external link 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" Worker 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 Open external link .
5. node_modules: Refer to npm documentation node_modules Open external link .

​​ Create a new Worker Project from an external source

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:

$ npm create cloudflare@latest -- --template <SOURCE>

<SOURCE> may be any of the following:

• user/repo (GitHub)
• git@github.com:user/repo
• https://github.com/user/repo Open external link
• 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 from wrangler.toml

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

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

3. Parameters: request, env, context

The fetch handler will always be passed three parameters: request, env and context.

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

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!".

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.

​​ Related resources

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 Reference.
• Learn how to set up different Workers features in Configuration.
• Set up a database to use within your Workers project in Databases.
• Learn about Workers limits, betas and pricing in Platform.
• Set up Wrangler to programmatically create, test, and deploy your Worker projects.