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. 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
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 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:
- 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.
- 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.
- Parameters:
request
,env
,context
The fetch
event handler will always get three parameters passed into it: request
, env
and context
.
- 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:
The import statement
const { unstable_dev } = require("wrangler");
, this initializes theunstable_dev
API so it can be used in the test suite. Theunstable_dev
function accepts two parameters -await unstable_dev(script, options)
.The
beforeAll()
function for initializingunstable_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.The
afterAll()
function, which callsawait worker.stop()
for stopping the dev server after it runs the test suite.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.