goflare

README

GoFlare

GoFlare is a lightweight and flexible handler designed to help you build and deploy Go-based WebAssembly (WASM) and JavaScript bundles for Cloudflare Workers, Pages, or Functions.

It’s not a full framework — GoFlare is meant to fit into your existing toolchain. You can use it as a standalone build step or attach it to any build or deploy workflow you already have.

---

🚀 Features

• Go → WASM/JS conversion made simple
• Compatible with Cloudflare’s edge platforms (Workers, Pages, and Functions)
• Integrates easily with CI/CD pipelines or other Go tools
• Minimal dependencies and lightweight footprint
• Provides a unified handler interface to hook into other builders or deployment systems

---

🧩 Example Usage

Basic Usage

import "github.com/tinywasm/goflare"

func main() {
	// Create a new Goflare instance with default configuration
	g := goflare.New(nil)
	
	// Generate Cloudflare Pages files
	err := g.GeneratePagesFiles()
	if err != nil {
		panic(err)
	}
}

Custom Configuration

config := &goflare.Config{
	AppRootDir:              ".",
	RelativeInputDirectory:  "web",
	RelativeOutputDirectory: "deploy/cloudflare",
	MainInputFile:           "main.worker.go",
	OutputWasmFileName:      "worker.wasm",
	Logger:                  func(msg ...any) { fmt.Println(msg...) },
}

g := goflare.New(config)

Using with DevTUI (HandlerExecution Interface)

GoFlare provides handlers that implement the HandlerExecution interface for integration with interactive TUI applications:

import (
	"github.com/tinywasm/goflare"
	"github.com/tinywasm/devtui"
)

func main() {
	g := goflare.New(nil)
	
	// Create execution handlers
	buildPagesHandler := g.NewBuildPagesHandler()
	buildWorkersHandler := g.NewBuildWorkersHandler()
	fastModeHandler := g.NewSetCompilerModeHandler("f")  // Fast/Go
	debugModeHandler := g.NewSetCompilerModeHandler("b") // Debug/TinyGo
	prodModeHandler := g.NewSetCompilerModeHandler("m")  // Production/TinyGo
	
	// Register handlers with DevTUI
	tui := devtui.New()
	tui.AddField(buildPagesHandler)
	tui.AddField(buildWorkersHandler)
	tui.AddField(fastModeHandler)
	tui.AddField(debugModeHandler)
	tui.AddField(prodModeHandler)
	
	// Run the TUI
	if err := tui.Run(); err != nil {
		panic(err)
	}
}

Available Handlers

• NewBuildPagesHandler() - Builds Cloudflare Pages files (_worker.js + WASM)
• NewBuildWorkersHandler() - Builds Cloudflare Workers files
• NewSetCompilerModeHandler(mode) - Changes compiler mode:
  • "f" - Fast mode (Go compiler)
  • "b" - Debug mode (TinyGo with debug symbols)
  • "m" - Production mode (TinyGo optimized)

All handlers implement the HandlerExecution interface:

type HandlerExecution interface {
    Name() string                       // Identifier for logging
    Label() string                      // Button label
    Execute(progress func(msgs ...any)) // Execute operation with progress callback
}

---

Contributing

Documentation

Index

• type Config
  • func DefaultConfig() *Config
• type Goflare
  • func New(c *Config) *Goflare
  • func (h *Goflare) Change(newValue string, progress func(msgs ...any))
  • func (g *Goflare) GeneratePagesFiles() error
  • func (g *Goflare) GenerateWorkerFiles() error
  • func (h *Goflare) Label() string
  • func (g *Goflare) Logger(messages ...any)
  • func (h *Goflare) MainInputFileRelativePath() string
  • func (h *Goflare) Name() string
  • func (h *Goflare) NewFileEvent(fileName, extension, filePath, event string) error
  • func (g *Goflare) SetCompilerMode(newValue string)
  • func (g *Goflare) SetLog(f func(message ...any))
  • func (h *Goflare) Shortcuts() []map[string]string
  • func (h *Goflare) SupportedExtensions() []string
  • func (h *Goflare) UnobservedFiles() []string
  • func (h *Goflare) Value() string

Types

type Config

type Config struct {
	AppRootDir                string        // default: "."
	RelativeInputDirectory    func() string // input relative directory for source code server app.go to deploy app.wasm (relative) default: "web"
	RelativeOutputDirectory   func() string // output relative directory for worker.js and app.wasm file (relative) default: "deploy/cloudflare"
	MainInputFile             string        // eg: "main.go"
	CompilingArguments        func() []string
	OutputWasmFileName        string // WASM file name (default: "worker.wasm")
	BuildPageFunctionShortcut string // build assets wasm,js, json files to pages functions (default: "f")
	BuildWorkerShortcut       string // build assets wasm,js, json files to workers (default: "w")
}

func DefaultConfig

func DefaultConfig() *Config

DefaultConfig returns a Config with all default values set AppRootDir=".", RelativeInputDirectory="web", RelativeOutputDirectory="deploy/cloudflare", MainInputFile="main.worker.go", OutputWasmFileName="worker.wasm"

type Goflare

type Goflare struct {
	// contains filtered or unexported fields
}

func New

func New(c *Config) *Goflare

New creates a new Goflare instance with the provided configuration Timeout is set to 40 seconds maximum as TinyGo compilation can be slow Default values: AppRootDir=".", RelativeOutputDirectory="deploy/cloudflare", MainInputFile="main.worker.go", OutputWasmFileName="app.wasm"

func (*Goflare) Change

func (h *Goflare) Change(newValue string, progress func(msgs ...any))

func (*Goflare) GeneratePagesFiles

func (g *Goflare) GeneratePagesFiles() error

GeneratePagesFiles generates all necessary files for Cloudflare Pages Functions using Advanced Mode generates the _worker.js file for Pages (Advanced Mode) https://developers.cloudflare.com/pages/functions/advanced-mode/ This creates a single combined file with wasm_exec.js and runtime.mjs inline

func (*Goflare) GenerateWorkerFiles

func (g *Goflare) GenerateWorkerFiles() error

func (*Goflare) Label

func (h *Goflare) Label() string

func (*Goflare) Logger

func (g *Goflare) Logger(messages ...any)

func (*Goflare) MainInputFileRelativePath

func (h *Goflare) MainInputFileRelativePath() string

MainInputFileRelativePath returns the relative path to the main input file This is used by devwatch to determine file ownership for Go files

func (*Goflare) Name

func (h *Goflare) Name() string

func (*Goflare) NewFileEvent

func (h *Goflare) NewFileEvent(fileName, extension, filePath, event string) error

NewFileEvent handles file change events for goflare This method is called by devwatch when a relevant file changes

func (*Goflare) SetCompilerMode

func (g *Goflare) SetCompilerMode(newValue string)

SetCompilerMode changes the compiler mode mode: "L" (Large fast/Go), "M" (Medium TinyGo debug), "S" (Small TinyGo production)

func (*Goflare) SetLog

func (g *Goflare) SetLog(f func(message ...any))

func (*Goflare) Shortcuts

func (h *Goflare) Shortcuts() []map[string]string

func (*Goflare) SupportedExtensions

func (h *Goflare) SupportedExtensions() []string

SupportedExtensions returns the file extensions that goflare monitors For edge workers, we primarily watch .go files

func (*Goflare) UnobservedFiles

func (h *Goflare) UnobservedFiles() []string

UnobservedFiles returns files that should be ignored by the file watcher These are output files generated by goflare that shouldn't trigger recompilation

func (*Goflare) Value

func (h *Goflare) Value() string