Convert Figma logo to code with AI

cloudflare logoworkerd

The JavaScript / Wasm runtime that powers Cloudflare Workers

6,037
287
6,037
233
View on GitHub

Top Related Projects

nodejs's avatar

node

106,466

Node.js JavaScript runtime ✨🐢🚀✨

denoland's avatar

deno

93,919

A modern runtime for JavaScript and TypeScript.

vercel's avatar

next.js

124,777

The React Framework

nestjs's avatar

nest

66,731

A progressive Node.js framework for building efficient, scalable, and enterprise-grade server-side applications with TypeScript/JavaScript 🚀

fastify's avatar

fastify

31,844

Fast and low overhead web framework, for Node.js

expressjs's avatar

express

64,773

Fast, unopinionated, minimalist web framework for node.

Quick Overview

Cloudflare/workerd is the JavaScript/Wasm runtime that powers Cloudflare Workers. It's an open-source project that allows developers to run and test Workers scripts locally, providing a development environment that closely mimics the production Cloudflare Workers environment.

Pros

  • Enables local development and testing of Cloudflare Workers
  • Provides a runtime environment that closely matches the production environment
  • Open-source, allowing for community contributions and customizations
  • Supports both JavaScript and WebAssembly

Cons

  • May have a learning curve for developers not familiar with Cloudflare Workers
  • Limited documentation compared to more established runtimes
  • Potential differences between local and production environments may still exist
  • Primarily focused on Cloudflare Workers, limiting its use cases outside of this ecosystem

Code Examples

  1. Basic Worker script:
addEventListener('fetch', event => {
  event.respondWith(handleRequest(event.request))
})

async function handleRequest(request) {
  return new Response('Hello World!', {
    headers: { 'content-type': 'text/plain' }
  })
}

This example shows a simple Cloudflare Worker that responds with "Hello World!" to all requests.

  1. Using KV storage:
addEventListener('fetch', event => {
  event.respondWith(handleRequest(event.request))
})

async function handleRequest(request) {
  const value = await MY_KV_NAMESPACE.get('my-key')
  return new Response(value || 'Key not found', {
    headers: { 'content-type': 'text/plain' }
  })
}

This example demonstrates how to use KV storage in a Worker to retrieve a value and return it in the response.

  1. Handling different HTTP methods:
addEventListener('fetch', event => {
  event.respondWith(handleRequest(event.request))
})

async function handleRequest(request) {
  switch (request.method) {
    case 'GET':
      return new Response('This is a GET request')
    case 'POST':
      return new Response('This is a POST request')
    default:
      return new Response('Method not allowed', { status: 405 })
  }
}

This example shows how to handle different HTTP methods in a Worker script.

Getting Started

To get started with cloudflare/workerd:

  1. Clone the repository:

    git clone https://github.com/cloudflare/workerd.git

  2. Build the project (requires Bazel):

    bazel build //src/workerd:workerd

  3. Run a Worker script locally:

    ./bazel-bin/src/workerd/workerd serve your-config.capnp

Note: You'll need to create a configuration file (your-config.capnp) that defines your Worker and its bindings. Refer to the project's documentation for more details on configuration.

Competitor Comparisons

nodejs logo

node

106,466

Node.js JavaScript runtime ✨🐢🚀✨

Pros of Node.js

  • Extensive ecosystem with a vast number of packages available through npm
  • Well-established and mature platform with a large community and extensive documentation
  • Supports a wide range of use cases, from server-side applications to desktop apps

Cons of Node.js

  • Single-threaded nature can lead to performance bottlenecks for CPU-intensive tasks
  • Callback-based asynchronous programming can lead to "callback hell" if not managed properly
  • Larger runtime size compared to more specialized runtimes

Code Comparison

Node.js:

const http = require('http');

const server = http.createServer((req, res) => {
  res.writeHead(200, { 'Content-Type': 'text/plain' });
  res.end('Hello World\n');
});

server.listen(8080);

workerd:

export default {
  async fetch(request) {
    return new Response('Hello World\n', {
      headers: { 'Content-Type': 'text/plain' },
    });
  },
};

The Node.js example shows a traditional HTTP server setup, while the workerd example demonstrates a more streamlined approach for serverless environments. workerd's code is more concise and focused on handling individual requests, reflecting its design for edge computing scenarios.

denoland logo

deno

93,919

A modern runtime for JavaScript and TypeScript.

Pros of Deno

  • Broader ecosystem support with a large standard library and third-party modules
  • Built-in TypeScript support without additional configuration
  • More versatile, supporting both server-side and client-side JavaScript

Cons of Deno

  • Slower startup time compared to workerd
  • Less optimized for edge computing and serverless environments
  • Larger runtime size, which can impact deployment speed and resource usage

Code Comparison

Deno:

import { serve } from "https://deno.land/std/http/server.ts";

serve((req) => new Response("Hello World!"), { port: 8000 });

workerd:

export default {
  async fetch(request, env, ctx) {
    return new Response("Hello World!");
  }
};

The code comparison shows that Deno uses a more traditional server setup with imports and a serve function, while workerd is designed specifically for serverless environments with a simpler export structure. workerd's approach is more aligned with edge computing patterns, emphasizing minimal boilerplate and quick execution.

vercel logo

next.js

124,777

The React Framework

Pros of Next.js

  • Rich ecosystem with extensive documentation and community support
  • Built-in optimizations for performance and SEO
  • Seamless integration with Vercel's deployment platform

Cons of Next.js

  • Steeper learning curve for developers new to React or server-side rendering
  • Can be overkill for simple static websites or small applications
  • Potential vendor lock-in with Vercel's platform

Code Comparison

Next.js (React-based routing):

import Link from 'next/link'

export default function Home() {
  return (
    <Link href="/about">
      <a>About Us</a>
    </Link>
  )
}

workerd (Service Worker-like API):

addEventListener('fetch', event => {
  event.respondWith(handleRequest(event.request))
})

async function handleRequest(request) {
  return new Response('Hello World!')
}

The code snippets highlight the different approaches: Next.js focuses on React-based components and routing, while workerd uses a more low-level, Service Worker-like API for handling requests. Next.js provides a higher-level abstraction for building web applications, whereas workerd offers more granular control over request handling, making it suitable for edge computing scenarios.

nestjs logo

nest

66,731

A progressive Node.js framework for building efficient, scalable, and enterprise-grade server-side applications with TypeScript/JavaScript 🚀

Pros of Nest

  • Comprehensive framework with built-in support for dependency injection, modules, and decorators
  • Strong TypeScript integration and extensive documentation
  • Large and active community with numerous third-party packages

Cons of Nest

  • Steeper learning curve due to its opinionated structure and concepts
  • Potentially heavier and slower compared to more lightweight alternatives
  • May be overkill for simple applications or microservices

Code Comparison

Nest:

@Controller('cats')
export class CatsController {
  @Get()
  findAll(): string {
    return 'This action returns all cats';
  }
}

workerd:

export default {
  async fetch(request) {
    return new Response('Hello World!');
  },
};

Key Differences

  • Nest is a full-featured Node.js framework, while workerd is focused on serverless edge computing
  • Nest provides a structured approach to building scalable applications, whereas workerd offers a more lightweight and flexible environment
  • Nest has a broader scope and can be used for various types of applications, while workerd is specifically designed for Cloudflare Workers

Use Cases

  • Choose Nest for complex, enterprise-level applications or when you need a robust, opinionated framework
  • Opt for workerd when building serverless edge functions or when you require lightweight, fast execution in a Cloudflare Workers environment
fastify logo

fastify

31,844

Fast and low overhead web framework, for Node.js

Pros of Fastify

  • Highly performant and low overhead web framework for Node.js
  • Extensive plugin ecosystem and active community support
  • Built-in TypeScript support and excellent documentation

Cons of Fastify

  • Limited to Node.js environment, not as versatile as Workerd
  • Requires more setup and configuration compared to Workerd's serverless approach

Code Comparison

Fastify:

const fastify = require('fastify')()

fastify.get('/', async (request, reply) => {
  return { hello: 'world' }
})

fastify.listen({ port: 3000 })

Workerd:

export default {
  async fetch(request) {
    return new Response('Hello World!', {
      headers: { 'content-type': 'text/plain' },
    })
  },
}

Key Differences

  • Fastify is a traditional web framework, while Workerd is designed for serverless environments
  • Workerd offers built-in edge computing capabilities, whereas Fastify requires additional setup for similar functionality
  • Fastify provides more flexibility in terms of server configuration and middleware, while Workerd focuses on simplicity and ease of deployment

Use Cases

  • Choose Fastify for building complex, high-performance Node.js applications with extensive customization needs
  • Opt for Workerd when developing serverless applications or requiring edge computing capabilities with minimal setup
expressjs logo

express

64,773

Fast, unopinionated, minimalist web framework for node.

Pros of Express

  • Mature and widely adopted ecosystem with extensive middleware and plugins
  • Flexible and unopinionated, allowing developers to structure applications as they see fit
  • Excellent documentation and large community support

Cons of Express

  • Not optimized for serverless or edge computing environments
  • Requires more setup and configuration for modern web applications
  • Performance can be slower compared to more specialized frameworks

Code Comparison

Express:

const express = require('express');
const app = express();

app.get('/', (req, res) => {
  res.send('Hello World!');
});

workerd:

export default {
  async fetch(request) {
    return new Response('Hello World!');
  }
};

Key Differences

  • Express is designed for traditional Node.js environments, while workerd is built for edge computing
  • workerd offers better performance and scalability for serverless deployments
  • Express provides more flexibility and a larger ecosystem of middleware and plugins
  • workerd has a simpler API and is more focused on modern web standards

Use Cases

  • Choose Express for traditional web applications or when extensive customization is required
  • Opt for workerd when building edge-native applications or requiring high-performance serverless deployments

Convert Figma logo designs to code with AI

Visual Copilot

Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.

Try Visual Copilot

README

👷 workerd, Cloudflare's JavaScript/Wasm Runtime

Banner

workerd (pronounced: "worker-dee") is a JavaScript / Wasm server runtime based on the same code that powers Cloudflare Workers.

You might use it:

  • As an application server, to self-host applications designed for Cloudflare Workers.
  • As a development tool, to develop and test such code locally.
  • As a programmable HTTP proxy (forward or reverse), to efficiently intercept, modify, and route network requests.

Introduction

Design Principles

  • Server-first: Designed for servers, not CLIs nor GUIs.

  • Standard-based: Built-in APIs are based on web platform standards, such as fetch().

  • Nanoservices: Split your application into components that are decoupled and independently-deployable like microservices, but with performance of a local function call. When one nanoservice calls another, the callee runs in the same thread and process.

  • Homogeneous deployment: Instead of deploying different microservices to different machines in your cluster, deploy all your nanoservices to every machine in the cluster, making load balancing much easier.

  • Capability bindings: workerd configuration uses capabilities instead of global namespaces to connect nanoservices to each other and external resources. The result is code that is more composable -- and immune to SSRF attacks.

  • Always backwards compatible: Updating workerd to a newer version will never break your JavaScript code. workerd's version number is simply a date, corresponding to the maximum "compatibility date" supported by that version. You can always configure your worker to a past date, and workerd will emulate the API as it existed on that date.

Read the blog post to learn more about these principles.

WARNING: This is a beta. Work in progress

Although most of workerd's code has been used in Cloudflare Workers for years, the workerd configuration format and top-level server code is brand new. We don't yet have much experience running this in production. As such, there will be rough edges, maybe even a few ridiculous bugs. Deploy to production at your own risk (but please tell us what goes wrong!).

The config format may change in backwards-incompatible ways before workerd leaves beta, but should remain stable after that.

A few caveats:

  • General error logging is awkward. Traditionally we have separated error logs into "application errors" (e.g. a Worker threw an exception from JavaScript) and "internal errors" (bugs in the implementation which the Workers team should address). We then sent these errors to completely different places. In the workerd world, the server admin wants to see both of these, so logging has become entirely different and, at the moment, is a bit ugly. For now, it may help to run workerd with the --verbose flag, which causes application errors to be written to standard error in the same way that internal errors are (but may also produce more noise). We'll be working on making this better out-of-the-box.
  • Binary packages are only available via npm, not as distro packages. This works well for testing with Miniflare, but is awkward for a production server that doesn't actually use Node at all.
  • Multi-threading is not implemented. workerd runs in a single-threaded event loop. For now, to utilize multiple cores, we suggest running multiple instances of workerd and balancing load across them. We will likely add some built-in functionality for this in the near future.
  • Performance tuning has not been done yet, and there is low-hanging fruit here. workerd performs decently as-is, but not spectacularly. Experiments suggest we can roughly double performance on a "hello world" load test with some tuning of compiler optimization flags and memory allocators.
  • Durable Objects currently always run on the same machine that requested them, using local disk storage. This is sufficient for testing and small services that fit on a single machine. In scalable production, though, you would presumably want Durable Objects to be distributed across many machines, always choosing the same machine for the same object.
  • Parameterized workers are not implemented yet. This is a new feature specified in the config schema, which doesn't have any precedent on Cloudflare.
  • Tests for most APIs are conspicuously missing. This is because the testing harness we have used for the past five years is deeply tied to the internal version of the codebase. Ideally, we need to translate those tests into the new workerd test format and move them to this repo; this is an ongoing effort. For the time being, we will be counting on the internal tests to catch bugs. We understand this is not ideal for external contributors trying to test their changes.
  • Documentation is growing quickly but is definitely still a work in progress.

WARNING: workerd is not a hardened sandbox

workerd tries to isolate each Worker so that it can only access the resources it is configured to access. However, workerd on its own does not contain suitable defense-in-depth against the possibility of implementation bugs. When using workerd to run possibly-malicious code, you must run it inside an appropriate secure sandbox, such as a virtual machine. The Cloudflare Workers hosting service in particular uses many additional layers of defense-in-depth.

With that said, if you discover a bug that allows malicious code to break out of workerd, please submit it to Cloudflare's bug bounty program for a reward.

Getting Started

Supported Platforms

In theory, workerd should work on any POSIX system that is supported by V8 and Windows.

In practice, workerd is tested on:

  • Linux and macOS (x86-64 and arm64 architectures)
  • Windows (x86-64 architecture)

On other platforms, you may have to do tinkering to make things work.

Building workerd

To build workerd, you need:

  • Bazel
    • If you use Bazelisk (recommended), it will automatically download and use the right version of Bazel for building workerd.
  • On Linux:

    • We use the clang/LLVM toolchain to build workerd and support version 16 and higher. Earlier versions of clang may still work, but are not officially supported.

    • Clang 16+ (e.g. package clang-16 on Debian Bookworm). If clang is installed as clang-<version> please create a symlink to it in your PATH named clang, or use --action_env=CC=clang-<version> on bazel command lines to specify the compiler name.

    • libc++ 16+ (e.g. packages libc++-16-dev and libc++abi-16-dev)

    • LLD 16+ (e.g. package lld-16).

    • python3, python3-distutils, and tcl8.6

  • On macOS:
    • Xcode 15 installation (available on macOS 13 and higher). Full Xcode is required, the Xcode command line tools alone are not sufficient for building.
    • Homebrew installed tcl-tk package (provides Tcl 8.6)
  • On Windows:
    • Install App Installer from the Microsoft Store for the winget package manager and then run install-deps.bat from an administrator prompt to install bazel, LLVM, and other dependencies required to build workerd on Windows.
    • Add startup --output_user_root=C:/tmp to the .bazelrc file in your user directory.
    • When developing at the command-line, run bazel-env.bat in your shell first to select tools and Windows SDK versions before running bazel.

You may then build workerd at the command-line with:

bazel build //src/workerd/server:workerd

You can also build from within Visual Studio Code using the instructions in docs/vscode.md.

The compiled binary will be located at bazel-bin/src/workerd/server/workerd.

If you run a Bazel build before you've installed some dependencies (like clang or libc++), and then you install the dependencies, you must resync locally cached toolchains, or clean Bazel's cache, otherwise you might get strange errors:

bazel sync --configure

If that fails, you can try:

bazel clean --expunge

The cache will now be cleaned and you can try building again.

If you have a fairly recent clang packages installed you can build a more performant release version of workerd:

bazel build --config=thin-lto //src/workerd/server:workerd

Configuring workerd

workerd is configured using a config file written in Cap'n Proto text format.

A simple "Hello World!" config file might look like:

using Workerd = import "/workerd/workerd.capnp";

const config :Workerd.Config = (
  services = [
    (name = "main", worker = .mainWorker),
  ],

  sockets = [
    # Serve HTTP on port 8080.
    ( name = "http",
      address = "*:8080",
      http = (),
      service = "main"
    ),
  ]
);

const mainWorker :Workerd.Worker = (
  serviceWorkerScript = embed "hello.js",
  compatibilityDate = "2023-02-28",
  # Learn more about compatibility dates at:
  # https://developers.cloudflare.com/workers/platform/compatibility-dates/
);

Where hello.js contains:

addEventListener("fetch", event => {
  event.respondWith(new Response("Hello World"));
});

Complete reference documentation is provided by the comments in workerd.capnp.

There is also a library of sample config files.

(TODO: Provide a more extended tutorial.)

Running workerd

To serve your config, do:

workerd serve my-config.capnp

For more details about command-line usage, use workerd --help.

Prebuilt binaries are distributed via npm. Run npx workerd ... to use these. If you're running a prebuilt binary, you'll need to make sure your system has the right dependencies installed:

  • On Linux:
    • glibc 2.31 or higher (already included on e.g. Ubuntu 20.04, Debian Bullseye)
  • On macOS:
    • macOS 13.5 or higher
    • The Xcode command line tools, which can be installed with xcode-select --install
  • x86_64 CPU with at least SSE4.2 and CLMUL ISA extensions, or arm64 CPU with CRC extension (enabled by default under armv8.1-a). These extensions are supported by all recent x86 and arm64 CPUs.

Local Worker development with wrangler

You can use Wrangler (v3.0 or greater) to develop Cloudflare Workers locally, using workerd. Run:

wrangler dev

Serving in production

workerd is designed to be unopinionated about how it runs.

One good way to manage workerd in production is using systemd. Particularly useful is systemd's ability to open privileged sockets on workerd's behalf while running the service itself under an unprivileged user account. To help with this, workerd supports inheriting sockets from the parent process using the --socket-fd flag.

Here's an example system service file, assuming your config defines two sockets named http and https:

# /etc/systemd/system/workerd.service
[Unit]
Description=workerd runtime
After=local-fs.target remote-fs.target network-online.target
Requires=local-fs.target remote-fs.target workerd.socket
Wants=network-online.target

[Service]
Type=exec
ExecStart=/usr/bin/workerd serve /etc/workerd/config.capnp --socket-fd http=3 --socket-fd https=4
Sockets=workerd.socket

# If workerd crashes, restart it.
Restart=always

# Run under an unprivileged user account.
User=nobody
Group=nogroup

# Hardening measure: Do not allow workerd to run suid-root programs.
NoNewPrivileges=true

[Install]
WantedBy=multi-user.target

And corresponding sockets file:

# /etc/systemd/system/workerd.socket
[Unit]
Description=sockets for workerd
PartOf=workerd.service

[Socket]
ListenStream=0.0.0.0:80
ListenStream=0.0.0.0:443

[Install]
WantedBy=sockets.target

(TODO: Fully explain how to get systemd to recognize these files and start the service.)