README.md

workers

• workers is a package to run an HTTP server written in Go on Cloudflare Workers.
• This package can easily serve http.Handler on Cloudflare Workers.
• Caution: This is an experimental project.

Features

• serve http.Handler
• R2
  • Head
  • Get
  • Put
  • Delete
  • List
  • Options for R2 methods
• KV
  • Get
  • List
  • Put
  • Delete
  • Options for KV methods
• Cache API
• Durable Objects
  • Calling stubs
• D1 (alpha)
• Environment variables
• FetchEvent
• Cron Triggers
• TCP Sockets
• Queues
  • Producer
  • Consumer

Installation

go get github.com/syumai/workers

Usage

implement your http.Handler and give it to workers.Serve().

func main() {
	var handler http.HandlerFunc = func (w http.ResponseWriter, req *http.Request) { ... }
	workers.Serve(handler)
}

or just call http.Handle and http.HandleFunc, then invoke workers.Serve() with nil.

func main() {
	http.HandleFunc("/hello", func (w http.ResponseWriter, req *http.Request) { ... })
	workers.Serve(nil) // if nil is given, http.DefaultServeMux is used.
}

For concrete examples, see _examples directory.

Quick Start

Requirements

• Node.js (and npm)
• Go 1.24.0 or later

Create a new Worker project

Run the following command:

npm create cloudflare@latest -- --template github.com/syumai/workers/_templates/cloudflare/worker-go

Initialize the project

1. Navigate to your new project directory:

cd my-app

2. Initialize Go modules:

go mod init
go mod tidy

3. Start the development server:

npm start

4. Verify the worker is running:

curl http://localhost:8787/hello

You will see "Hello!" as the response.

If you want a more detailed description, please refer to the README.md file in the generated directory.

FAQ

How do I deploy a worker implemented in this package?

To deploy a Worker, the following steps are required.

• Create a worker project using wrangler.
• Build a Wasm binary.
• Upload a Wasm binary with a JavaScript code to load and instantiate Wasm (for entry point).

The worker-go template contains all the required files, so I recommend using this template.

But Go (not TinyGo) with many dependencies may exceed the size limit of the Worker (3MB for free plan, 10MB for paid plan). In that case, you can use the TinyGo template instead.

Where can I have discussions about contributions, or ask questions about how to use the library?

You can do both through GitHub Issues. If you want to have a more casual conversation, please use the Discord server.