workers

README

workers-go

• workers-go is a Go module to run an HTTP server written in Go on Cloudflare Workers. Its root package is 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-go

Migrating from github.com/syumai/workers

This module was published as github.com/syumai/workers up to v0.34.0 and was renamed to github.com/syumai/workers-go in v0.35.0 (#173). The old path still works: it is now a thin forwarding module that re-exports this module's API and follows its releases for a transition period, but it is marked deprecated. To switch, rewrite the import paths and tidy:

# Linux
find . \( -name '*.go' -o -name go.mod \) -exec sed -i 's|github.com/syumai/workers\([/" ]\)|github.com/syumai/workers-go\1|g' {} +
# macOS
find . \( -name '*.go' -o -name go.mod \) -exec sed -i '' 's|github.com/syumai/workers\([/" ]\)|github.com/syumai/workers-go\1|g' {} +
go mod tidy

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

• You can easily create and deploy a project from Deploy to Cloudflare button.

• If you want to create a project manually, please follow the guide below.

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-go/_templates/cloudflare/worker-go

After creating the project, follow the steps below to initialize it.

Initialize the project

1. Navigate to your new project directory:

cd my-app

1. Initialize Go modules:

go mod init
go mod tidy

1. Start the development server:

npm start

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

If you want a smaller Wasm binary, you can use the TinyGo template instead.

The TinyGo template requires TinyGo 0.42.0 or later. TinyGo 0.41.x cannot build net/http for Wasm (see tinygo-org/tinygo#5350).

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.

Documentation

Index

• func Done() <-chan struct{}
• func Ready()
• func Serve(handler http.Handler)
• func ServeNonBlock(handler http.Handler)

Functions

func Done

func Done() <-chan struct{}

Done returns a channel which is closed when the handler is done.

func Ready

func Ready()

Ready must be called after all setups of the Go side's handlers are done.

func Serve

func Serve(handler http.Handler)

Serve serves http.Handler on a JS runtime. if the given handler is nil, http.DefaultServeMux will be used.

func ServeNonBlock

func ServeNonBlock(handler http.Handler)

ServeNonBlock sets the http.Handler to be served but does not signal readiness or block indefinitely. The non-blocking form is meant to be used in conjunction with Ready and WaitForCompletion.