goflare

GoFlare

GoFlare is a self-contained Go tool (library + CLI) for deploying Go WASM projects to Cloudflare Workers and Pages. No Node.js, no Wrangler, no GitHub Actions. Pure Go, direct Cloudflare API.

When to use

• Cloudflare Pages Functions in Go (recommended) — static site + Go edge function deployed via CF Git Integration
• Standalone Cloudflare Workers in Go (WASM)
• Static Cloudflare Pages (Go WASM frontends)

The project mode is inferred from edge/main.go imports — no MODE variable in .env. See BUILD_PAGES_FUNCTIONS.md.

Project layout — Pages Functions (recommended)

my-project/
├── .env                       # credentials — gitignored (NEVER tokens)
├── .env.example
├── routes/
│   └── routes.go              # build-agnostic — func Register(r router.Router)
├── modules/
│   └── contact/
│       ├── model.go           # build-agnostic — model + Validate()
│       └── handler.go         # build-agnostic — func Handle(ctx router.Context)
├── web/
│   ├── client.go              # //go:build wasm — frontend (browser)
│   ├── server.go              # //go:build !wasm — local dev server
│   └── public/                # static assets — committed; produced by tinywasm framework
│       ├── index.html
│       ├── client.wasm
│       ├── script.js
│       └── style.css
├── edge/
│   └── main.go                # //go:build wasm — entrypoint, imports goflare/pages
└── functions/                 # generated by goflare — COMMITTED
    ├── [[path]].mjs           # catch-all glue (exports onRequest)
    └── edge.wasm              # compiled edge/main.go

Project layout — Workers (legacy)

my-project/
├── .env
├── edge/
│   └── main.go                # imports goflare/workers (workers.Handle)
└── .build/                    # gitignored worker artifacts
    ├── edge.js
    └── edge.wasm

.env

PROJECT_NAME=my-app
CLOUDFLARE_ACCOUNT_ID=your-account-id
PUBLIC_DIR=web/public            # optional, default: web/public
FUNCTIONS_DIR=functions          # optional, default: functions
# ENTRY=edge                     # optional, auto-detected if edge/main.go exists
# DOMAIN=example.com             # optional, custom domain for Pages

NEVER put CLOUDFLARE_API_TOKEN in .env. The token lives in the OS keyring via goflare auth.

CLI

Install the CLI:

go install github.com/tinywasm/goflare/cmd/goflare@latest

• goflare init [--mode=pages-functions|workers|pages]: Setup project, scaffold edge/main.go, write .env.
• goflare auth: Save Cloudflare API token to the OS keyring.
• goflare build: Infer mode from edge/main.go imports and produce artifacts.
• goflare deploy: Direct Upload v2. ⚠️ Status not fully verified — primary deploy flow is git push via CF Git Integration.

Edge function — Pages Functions (recommended)

edge/main.go:

//go:build wasm

package main

import (
    "github.com/tinywasm/goflare/pages"   // ← this import sets MODE=pages-functions
    "github.com/your-project/routes"
)

func main() {
    r := pages.NewRouter()
    routes.Register(r)
    pages.Serve(r)
}

Handlers live in modules/<feature>/handler.go and use the router.Context interface:

package contact

import (
    "github.com/tinywasm/goflare/cloudflare"
    "github.com/tinywasm/goflare/router"
)

func Handle(ctx router.Context) {
    ctx.SetHeader("Content-Type", "application/json")
    ctx.WriteStatus(200)
    ctx.Write([]byte(`{"ok":true}`))
    _ = cloudflare.Env("RESEND_API_KEY") // read secret from context.env
}

routes/routes.go wires URLs to handlers (build-agnostic — reused by edge/main.go and web/server.go):

package routes

import (
    "github.com/tinywasm/goflare/router"
    "github.com/your-project/modules/contact"
)

func Register(r router.Router) {
    r.Post("/api/contacto", contact.Handle)
}

Edge function — Workers (legacy)

edge/main.go:

//go:build wasm

package main

import "github.com/tinywasm/goflare/workers"

func main() { workers.Handle(handler) }

func handler(w *workers.Response, r *workers.Request) {
    w.Header()["Content-Type"] = "application/json"
    w.WriteHeader(200)
    w.Write([]byte(`{"ok":true}`))
}

D1 Database (Cloudflare D1)

Connect to a Cloudflare D1 SQLite database from within a Worker or Pages Function edge handler using github.com/tinywasm/goflare/d1. See docs/D1.md for full documentation.

db, err := d1.New("DB") // "DB" is the binding name in wrangler.toml
if err != nil { ... }
defer db.Close()
db.CreateTable(&MyModel{})
db.Create(&MyModel{...})

⚠️ Critical: NO heavy stdlib in wasm code

Files with //go:build wasm (everything under edge/, routes/, modules/, workers/, pages/pages.go, cloudflare/env_wasm.go) NEVER import fmt, strings, errors, encoding/*, net/http, log, io/ioutil. Use tinywasm/fmt, tinywasm/json, tinywasm/strings, tinywasm/fetch instead.

Stdlib inflates the wasm binary ~80% and exceeds Cloudflare Free's 1 MiB limit. TinyGo also does not fully support net/http in js/wasm.

Verification: grep -rE '^\s*"(fmt|strings|errors|encoding|net/http|log|io/ioutil)"' edge/ routes/ modules/ workers/ pages/pages.go cloudflare/env_wasm.go must return empty.

The dev local can use stdlib freely in web/server.go and pages/devserver/ — those don't run on the edge.

Frontend WASM

Minimal working web/client.go:

//go:build wasm

package main

import (
    "github.com/tinywasm/dom"
    "github.com/tinywasm/form"
)

type MyForm struct {
    Name string `input:"required"`
}

func main() {
    data := &MyForm{}
    f, _ := form.New("app", data)
    dom.Render("app", f)
    select {}
}

Note: compiled to web/public/client.wasm.

Shared models (modules/)

Shared models live in modules/ and can be imported by both frontend and edge.

package contact

// ormc:formonly
type ContactForm struct {
    Nombre  string `input:"required,min=2"`
    Email   string `input:"email,required"`
    Mensaje string `input:"textarea,required,min=10"`
}

Library usage

cfg := &goflare.Config{
    ProjectName: "myapp",
    AccountID:   "acc-id",
    PublicDir:   "web/public",
}
g := goflare.New(cfg)
g.Build()
store := goflare.NewKeyringStore()
g.Deploy(store)

Config reference

At least one of Entry or PublicDir must be set. There is no MODE key — the mode is inferred from edge/main.go imports.

Build output

After goflare build:

Compiler modes

• S: Small (TinyGo production, minified)
• M: Medium (TinyGo debug)
• L: Large (Go standard compiler)

Requirements

• Go 1.25.2+
• TinyGo — installed automatically by goflare build via tinywasm/tinygo

goflare calls tinygo.EnsureInstalled() before each Worker build. If TinyGo is already in PATH at the correct version, nothing happens. If it is missing or outdated, it is downloaded and installed to the local cache automatically.

To manage TinyGo independently:

import "github.com/tinywasm/tinygo"

tinygo.EnsureInstalled()
env := tinygo.GetEnv()

Reference project

See goflare-demo for a complete example.