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(http.Handler)

Functions

func Done

func Done() <-chan struct{}

func Ready

func Ready()

func Serve

func Serve(handler http.Handler)

Server serves http.Handler as a normal HTTP server. if the given handler is nil, http.DefaultServeMux will be used. As a port number, PORT environment variable or default value (9900) is used. This function is implemented for non-JS environments for debugging purposes.

func ServeNonBlock

func ServeNonBlock(http.Handler)