Skip to main content
Before contributing code to workerd, please read these guidelines carefully to understand the project’s development process and standards.

​
Questions and discussions

If you want to ask a question or have an open-ended conversation, use the “discussions” tab rather than filing an issue. This keeps the issues list focused on action items.

​
Before you code

​
Discuss your change

This repository is the canonical source code for the core of Cloudflare Workers. The Workers team actively does their development in this repository. Any changes landed in the main branch automatically become available on the Cloudflare Workers Platform typically within a week or two. Cloudflare Workers has a strong commitment to backwards-compatibility. Once a feature is in use on Cloudflare’s platform, it generally cannot be taken away. The Workers team will be required to maintain the feature forever.
The project does not use semver and cannot just bump a major version number to introduce breaking changes.
As a result, the team is cautious about what is added. Typically, inside Cloudflare, a new feature will be discussed by product managers and described in design docs long before any code is written. For non-trivial changes, always post an issue or discussion before you write code. If you have a very specific proposal for which you’re seeking approval, file an issue with the label “feature proposal”. If your ideas are more open-ended, they may make sense as a discussion instead. The team can then discuss whether to accept the feature and, if so, give you some hints on how to implement it.
The project sets an extremely high bar for new APIs that are not defined by standards. If you are proposing adding a new non-standard API, it is very likely the team will decline.
Conversely, if you are proposing adding support for an API that is defined by standards, it is an easier decision to accept. For trivial changes, it is OK to go directly to filing a PR, with the understanding that the PR issue itself will serve as the place to discuss the change idea.

​
Development environment

​
Building the project

This codebase includes many unit tests. To run them: 
bazel test //src/...
You may find it convenient to have Bazel automatically re-run every time you change a file using watchexec: 
watchexec --restart --watch src bazel test //src/...

​
Using Just commands

The project provides convenient Just commands for development: 
just build    # Build the project
just test     # Run tests
just format   # Format code

​
Visual Studio Code

See the VSCode guide for instructions on how to set up Visual Studio Code for development.

​
Understanding the codebase

workerd is based on KJ, the C++ toolkit library underlying Cap’n Proto. Before writing code, review:

​
Key technologies

V8

JavaScript engine powering the runtime

Cap'n Proto

Serialization/RPC framework and KJ base library

KJ Library

C++ toolkit providing containers, async I/O, and promises

Bazel

Primary build system

​
Code review culture

The Cloudflare Workers project has a culture of careful code review. If code is hard to review, it may take much longer to land, or may be declined entirely for this reason alone. The same standards apply within the team.

​
Next steps

Code style

Learn about the project’s code style guidelines

Testing

Understand the testing requirements and practices

Documentation

Guidelines for writing and updating documentation

Architecture

Explore the architecture of the workerd runtime

Build docs developers (and LLMs) love

Get started for freeTalk to us