goflare

GoFlare

GoFlare is a self-contained Go tool (library + CLI) for deploying Go WASM projects to Cloudflare Workers and static assets. No Node.js, no Wrangler. Pure Go, direct Cloudflare API. Deploy runs in GitHub Actions — secrets never touch the developer's machine.

When to use

• Cloudflare Worker with Static Assets (recommended) — static site + Go edge function deployed in a single Cloudflare Worker.
• Standalone Cloudflare Workers in Go (WASM).
• Static Cloudflare Sites (Go WASM frontends).

See BUILD_WORKER_ASSETS.md.

Project layout

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 tinywasm/cloudflare/edge or cloudflare/workers
└── .build/                    # generated by goflare
    ├── edge.js                # JS glue bundle
    └── edge.wasm              # compiled edge/main.go

.env

PROJECT_NAME=my-app
# DOMAIN=example.com             # optional custom domain

CLOUDFLARE_API_TOKEN and CLOUDFLARE_ACCOUNT_ID are secrets — they live in GitHub Secrets, never in .env.

CLI

Install the CLI:

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

• goflare auth --check: Validate CLOUDFLARE_API_TOKEN from environment.
• goflare build: Build edge function into .build/ and static site assets into web/public/.
• goflare deploy: Single path deployment to Cloudflare Workers with assets. ⚠️ Designed for CI/CD environments.
• goflare size: Desglosa el tamaño del wasm del edge por paquete y lista imports prohibidos.
• goflare tinygo: Instala TinyGo si falta e imprime su directorio bin y su versión.

GitHub Setup

Deployment is designed to run in CI with a single action line:

- uses: actions/checkout@v4
- uses: tinywasm/goflare@v1
  with:
    worker: mi-worker
    domain: mi-worker.ejemplo.cl
    d1-binding: DB
  env:
    CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
    CLOUDFLARE_ACCOUNT_ID: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
    D1_DATABASE_ID: ${{ secrets.D1_DATABASE_ID }}

For more details see CI_GITHUB_ACTIONS.md and CI_D1_SECRETS.md.

Edge function entrypoint

edge/main.go (runtime lives in tinywasm/cloudflare):

//go:build wasm

package main

import (
    "github.com/tinywasm/cloudflare/edge"
    "github.com/your-project/routes"
)

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

The edge runtime (edge, workers, d1, r2, log, cloudflare.Env) is now github.com/tinywasm/cloudflare — goflare only bundles it via cloudflare/assets. Legacy github.com/tinywasm/goflare/edge is still accepted by mode.go during migration.

Migrations from Outside a Worker

goflare.NewD1Migrator runs DDL migrations against a D1 database from CI — outside a Worker, where cloudflare/d1.NewEdge doesn't exist. See docs/D1.md.

⚠️ Critical: NO heavy stdlib in wasm code

Files with //go:build wasm (everything under edge/, routes/, modules/, tinywasm/cloudflare) 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%. goflare warns at 256 KiB raw and aborts build at 900 KiB raw to preserve fast cold-start instantiation. 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/ $(go env GOPATH)/pkg/mod/github.com/tinywasm/cloudflare* must return empty — edge runtime lives in tinywasm/cloudflare.

Library usage

cfg := &goflare.Config{
    ProjectName: "myapp",
    AccountID:   "acc-id",
}
g := goflare.New(cfg)
g.Build()
g.Deploy()

Config reference

Testing

Edge code talks to js.Global(), not to Cloudflare — so it is tested in a browser against a fake context.env, with no deploy and no wrangler. See docs/TESTING.md for the three tiers and the rule for choosing one.

gotest    # never `go test` — dual WASM/stdlib, browser-driven

Requirements

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