client

package module
v0.6.13 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: May 28, 2026 License: MIT Imports: 21 Imported by: 3

README

tinywasm/client

Build-only WebAssembly compilation manager for TinyWASM.

As of v2, client has a single responsibility: compile the WASM binary and serve it at /client.wasm. All JavaScript composition has moved to tinywasm/js.

Responsibilities

✅ Owns ❌ No longer owns
WASM compilation (Go stdlib / TinyGo) wasm_exec.js embedding
Serving /client.wasm via HTTP Javascript struct / GetSSRClientInitJS
3-mode compiler selection (L/M/S) Generating script.js content
File watcher for web/main.wasm.go WasmExecGoSignatures / WasmExecTinyGoSignatures
VS Code GOOS/GOARCH config ClearJavaScriptCache
Project scaffolding (CreateDefaultWasmFileClientIfNotExist)

CLI Tool

go install github.com/tinywasm/client/cmd/wasmbuild@latest
wasmbuild        # Go stdlib mode (L)  → writes web/public/client.wasm + script.js
wasmbuild -tinygo # TinyGo mode (S)

script.js is now generated via tinywasm/js.PageBootstrap() — the embedded wasm_exec.js lives in js/assets/ (single source of truth).

See cmd/wasmbuild for details.

🛠 Basic Usage

cfg := client.NewConfig()
cfg.SourceDir = func() string { return "web" }
cfg.OutputDir = func() string { return "web/public" }

twc := client.New(cfg)
twc.SetAppRootDir("/path/to/project")
twc.SetMainInputFile("app.go") // default: "client.go"
twc.SetOutputName("app")       // default: "client"
Mode switching
twc.Change("S") // "L" = Go, "M" = TinyGo debug, "S" = TinyGo prod
HTTP serving
twc.RegisterRoutes(mux) // registers /client.wasm (or /prefix/client.wasm)
ArgumentsForServer
// Returns []string{"-wasmsize_mode=L"} (for subprocess injection)
args := twc.ArgumentsForServer()

Storage modes

Mode Use case
In-Memory (default) Fast dev — compiles to buffer, served directly
Disk Static integration — compiles to OutputDir, served via http.ServeFile 
twc.UseDiskStorage()   // switch to disk
twc.UseMemoryStorage() // switch back to memory

Project Initialization

// Generates web/client.go + .vscode/settings.json if missing
twc.CreateDefaultWasmFileClientIfNotExist(false)

⚙️ Configuration

  • Config struct: shared deps (Store, Logger), directory functions (SourceDir, OutputDir). See config.go.
  • Setters: reactive — re-initialize internal state automatically.

📋 Requirements

  • Go 1.21+
  • TinyGo (optional — needed for M/S modes only)

JavaScript composition

All JS is now the responsibility of tinywasm/js:

import "github.com/tinywasm/js"

// In tinywasm/app boot:
js.SetRuntime(js.RuntimeGo) // or RuntimeTinyGo
scripts := []any{js.PageBootstrap()} // registers with assetmin

See tinywasm/js for the full typed API including ServiceWorker and WebWorker.

Documentation

Index

Constants

View Source 
const StoreKeySizeMode = "wasmsize_mode"

StoreKeySizeMode is the key used to store the current compiler mode in the Database

Variables

This section is empty.

Functions

func ParseWasmSizeModeFlag added in v0.0.80 

func ParseWasmSizeModeFlag() string

ParseWasmSizeModeFlag parses -wasmsize_mode flag from os.Args. Returns the value found, or empty string if not present.

func RunWasmBuild added in v0.6.1 

func RunWasmBuild(args WasmBuildArgs) error

RunWasmBuild performs the common logic for the wasmbuild CLI.

func SetRunWasmBuildHooks added in v0.6.1 

func SetRunWasmBuildHooks(h RunWasmBuildHooks) (restore func())

SetRunWasmBuildHooks updates RunWasmBuild dependencies for the duration of a test. It returns a restore function that should be deferred.

Types

type BuildStorage 

type BuildStorage interface {
	// Compile performs the compilation.
	// For Memory: compiles to buffer.
	// For Disk: compiles to disk.
	Compile() error

	// RegisterRoutes registers the WASM file handler on the mux.
	RegisterRoutes(mux *http.ServeMux)

	// Name returns the Storage name for logging/debugging
	Name() string
}

BuildStorage defines the behavior for compiling and serving the WASM client.

type Config 

type Config struct {
	// SourceDir specifies the directory containing the Go source for the webclient (relative to AppRootDir).
	// e.g., "web"
	SourceDir func() string

	// OutputDir specifies the directory for WASM and related assets (relative to AppRootDir).
	// e.g., "web/public"
	OutputDir func() string

	// AssetsURLPrefix is an optional URL prefix/folder for serving the WASM file.
	// e.g. "assets" -> serves at "/assets/client.wasm"
	// default: "" -> serves at "/client.wasm"
	AssetsURLPrefix string

	// gobuild integration fields
	Callback           func(error)     // Optional callback for async compilation
	CompilingArguments func() []string // Build arguments for compilation (e.g., ldflags)
	Env                []string        // Environment variables, e.g., []string{"GOOS=js", "TINYGOROOT=/path"}

	Database         KeyValueDataBase // Key-Value store for state persistence
	OnWasmExecChange func()           // Callback for runtime/wasm_exec changes
}

Config holds configuration for WASM compilation

func NewConfig 

func NewConfig() *Config

NewConfig creates a WasmClient Config with sensible defaults

type DiskStorage added in v0.6.0 

type DiskStorage struct {
	Client *WasmClient
}

DiskStorage compiles WASM to disk and serves the static file.

func (*DiskStorage) Compile added in v0.6.0 

func (s *DiskStorage) Compile() error

func (*DiskStorage) Name added in v0.6.0 

func (s *DiskStorage) Name() string

func (*DiskStorage) RegisterRoutes added in v0.6.0 

func (s *DiskStorage) RegisterRoutes(mux *http.ServeMux)

type KeyValueDataBase 

type KeyValueDataBase interface {
	Get(key string) (string, error)
	Set(key, value string) error
}

KeyValueDataBase defines the interface for a key-value Storage system used to persist the compiler state (e.g. current mode).

type MemoryStorage added in v0.6.0 

type MemoryStorage struct {
	Client *WasmClient // Access to config and logger

	Mu          sync.RWMutex
	WasmContent []byte
	LastCompile time.Time
}

MemoryStorage compiles WASM to memory and serves it directly.

func (*MemoryStorage) Compile added in v0.6.0 

func (s *MemoryStorage) Compile() error

func (*MemoryStorage) Name added in v0.6.0 

func (s *MemoryStorage) Name() string

func (*MemoryStorage) RegisterRoutes added in v0.6.0 

func (s *MemoryStorage) RegisterRoutes(mux *http.ServeMux)

type RunWasmBuildClient added in v0.6.1 

type RunWasmBuildClient interface {
	SetMode(string)
	UseDiskStorage()
	SetLog(func(...any))
	Compile() error
	LogSuccessState(...any)
}

RunWasmBuildClient captures the subset of WasmClient methods used by RunWasmBuild. It is exported so tests can provide lightweight fakes without pulling in gobuild.

type RunWasmBuildHooks added in v0.6.1 

type RunWasmBuildHooks struct {
	EnsureTinyGoInstalled func() (string, error)
	TinyGoEnv             func() []string
	NewClient             func(*Config) RunWasmBuildClient
}

RunWasmBuildHooks lets tests override RunWasmBuild dependencies (installer, env provider, client factory). Use SetRunWasmBuildHooks in tests to temporarily replace these functions.

type SetModeArgs added in v0.6.0 

type SetModeArgs struct {
	Mode string `input:"required,enum=L;M;S"`
}

SetModeArgs defines arguments for the wasm_set_mode tool. ormc:formonly

func (*SetModeArgs) InputSchema added in v0.6.0 

func (a *SetModeArgs) InputSchema() string

Schema will be generated by ormc.

func (*SetModeArgs) Pointers added in v0.6.0 

func (m *SetModeArgs) Pointers() []any

func (*SetModeArgs) Schema added in v0.6.0 

func (m *SetModeArgs) Schema() []fmt.Field

func (*SetModeArgs) Validate added in v0.6.0 

func (m *SetModeArgs) Validate(action byte) error

type WasmBuildArgs added in v0.6.1 

type WasmBuildArgs struct {
	Stdlib bool // true = Go standard compiler mode "L", false = TinyGo mode "S"
}

WasmBuildArgs defines the arguments for the RunWasmBuild function.

type WasmClient 

type WasmClient struct {
	*Config

	// EXISTING: Keep for installation detection (no compilerMode needed - activeSizeBuilder handles state)
	// EXISTING: Keep for installation detection (no compilerMode needed - activeSizeBuilder handles state)
	TinyGoCompilerFlag bool // Enable TinyGo compiler (default: false for faster development)
	TinyGoInstalled    bool // Cached TinyGo installation status

	// NEW: Explicit mode tracking to fix Value() method
	CurrentSizeMode string // Track current mode explicitly ("L", "M", "S")

	Storage BuildStorage // Storage for compilation and serving (In-Memory vs External)

	// Configuration fields moved from Config
	AppRootDir    string
	MainInputFile string
	OutputName    string

	ShouldCreateIDEConfig     func() bool
	ShouldGenerateDefaultFile func() bool
	Log                       func(message ...any)

	// OnCompile is invoked after each compilation triggered by NewFileEvent.
	// err==nil indicates success; err!=nil indicates failure.
	OnCompile func(err error)
	// contains filtered or unexported fields
}

WasmClient provides WebAssembly compilation capabilities with 3-mode compiler selection

func New 

func New(c *Config) *WasmClient

New creates a new WasmClient instance with the provided configuration

func (*WasmClient) ArgumentsForServer added in v0.0.77 

func (w *WasmClient) ArgumentsForServer() []string

ArgumentsForServer returns runtime args to pass to the server, including the -wasmsize_mode flag based on current compiler mode.

func (*WasmClient) Change 

func (w *WasmClient) Change(newValue string)

Change updates the compiler mode for WasmClient. Implements the HandlerEdit interface: Change(newValue string)

func (*WasmClient) Compile added in v0.5.52 

func (w *WasmClient) Compile() error

Compile performs a synchronous compilation using the current settings. This exposes the underlying Storage's Compile method.

func (*WasmClient) CreateDefaultWasmFileClientIfNotExist 

func (t *WasmClient) CreateDefaultWasmFileClientIfNotExist(skipIDEConfig bool) *WasmClient

CreateDefaultWasmFileClientIfNotExist creates a default WASM main.go file from the embedded markdown template It never overwrites an existing file and returns the WasmClient instance for method chaining.

func (*WasmClient) GetMCPTools added in v0.5.63 

func (w *WasmClient) GetMCPTools() []mcp.Tool

GetMCPTools returns metadata for all WasmClient MCP tools

func (*WasmClient) GetTinyGoVersion 

func (w *WasmClient) GetTinyGoVersion() (string, error)

GetTinyGoVersion returns the installed TinyGo version

func (*WasmClient) Label 

func (w *WasmClient) Label() string

Label returns the field label for DevTUI display

func (*WasmClient) LogSuccessState added in v0.0.73 

func (w *WasmClient) LogSuccessState(messages ...any)

LogSuccessState logs the standard success message with WASM details (Safe: Acquires Lock)

func (*WasmClient) Logger 

func (w *WasmClient) Logger(messages ...any)

func (*WasmClient) MainInputFileRelativePath 

func (w *WasmClient) MainInputFileRelativePath() string

MainInputFileRelativePath returns the relative path to the main WASM input file (e.g. "main.wasm.go").

func (*WasmClient) MainOutputFileAbsolutePath 

func (w *WasmClient) MainOutputFileAbsolutePath() string

MainOutputFileAbsolutePath returns the absolute path to the main WASM output file (e.g. "main.wasm").

func (*WasmClient) Name 

func (w *WasmClient) Name() string

Name returns the name of the WASM project

func (*WasmClient) NewFileEvent 

func (w *WasmClient) NewFileEvent(fileName, extension, filePath, event string) error

NewFileEvent handles file events for WASM compilation with automatic project detection fileName: name of the file (e.g., main.wasm.go) extension: file extension (e.g., .go) filePath: full path to the file (e.g., ./home/userName/ProjectName/web/public/main.wasm.go) event: type of file event (e.g., create, remove, write, rename)

func (*WasmClient) OutputRelativePath 

func (w *WasmClient) OutputRelativePath() string

OutputRelativePath returns the RELATIVE path to the final output file eg: "deploy/edgeworker/app.wasm" (relative to AppRootDir) This is used by file watchers to identify output files that should be ignored. The returned path always uses forward slashes (/) for consistency across platforms.

func (*WasmClient) RecompileMainWasm 

func (w *WasmClient) RecompileMainWasm() error

RecompileMainWasm recompiles the main WASM file using the current Storage mode.

func (*WasmClient) RegisterRoutes 

func (w *WasmClient) RegisterRoutes(mux *http.ServeMux)

RegisterRoutes registers the WASM client file route on the provided mux. It delegates to the active Storage.

func (*WasmClient) RequiresTinyGo added in v0.6.0 

func (w *WasmClient) RequiresTinyGo(mode string) bool

RequiresTinyGo checks if the mode requires TinyGo compiler

func (*WasmClient) SetAppRootDir 

func (w *WasmClient) SetAppRootDir(path string)

SetAppRootDir sets the application root directory (absolute).

func (*WasmClient) SetBuildShortcuts 

func (w *WasmClient) SetBuildShortcuts(large, medium, small string)

SetBuildShortcuts sets the shortcuts for the three compilation modes. If an empty string is provided for a shortcut, it remains unchanged.

func (*WasmClient) SetLog 

func (w *WasmClient) SetLog(f func(message ...any))

func (*WasmClient) SetMainInputFile 

func (w *WasmClient) SetMainInputFile(file string)

SetMainInputFile sets the main input file for WASM compilation (default: "client.go").

func (*WasmClient) SetMode added in v0.5.52 

func (w *WasmClient) SetMode(mode string)

SetMode explicitly sets the compilation mode (e.g., "S", "M", "L"). This is useful for CLI tools or programmatic control.

func (*WasmClient) SetOnCompile added in v0.6.2 

func (w *WasmClient) SetOnCompile(fn func(err error))

SetOnCompile. registers a callback invoked after each compilation triggered by a file event. err==nil indicates success.

func (*WasmClient) SetOutputName 

func (w *WasmClient) SetOutputName(name string)

SetOutputName sets the output name for WASM file (default: "client").

func (*WasmClient) SetShouldCreateIDEConfig 

func (w *WasmClient) SetShouldCreateIDEConfig(f func() bool)

SetShouldCreateIDEConfig sets a function that determines if IDE configuration files (like .vscode) should be created.

func (*WasmClient) SetShouldGenerateDefaultFile 

func (w *WasmClient) SetShouldGenerateDefaultFile(f func() bool)

SetShouldGenerateDefaultFile sets a function that determines if the default WASM client source file (usually client.go) should be created if it doesn't exist.

func (*WasmClient) Shortcuts 

func (w *WasmClient) Shortcuts() []map[string]string

func (*WasmClient) ShouldCompileToWasm 

func (w *WasmClient) ShouldCompileToWasm(fileName, filePath string) bool

ShouldCompileToWasm determines if a file should trigger WASM compilation

func (*WasmClient) SupportedExtensions 

func (w *WasmClient) SupportedExtensions() []string

func (*WasmClient) TinyGoCompiler 

func (w *WasmClient) TinyGoCompiler() bool

TinyGoCompiler returns if TinyGo compiler should be used (dynamic based on configuration)

func (*WasmClient) UnobservedFiles 

func (w *WasmClient) UnobservedFiles() []string

UnobservedFiles returns files that should not be watched for changes e.g: main.wasm

func (*WasmClient) UpdateCurrentBuilder added in v0.6.0 

func (w *WasmClient) UpdateCurrentBuilder(mode string)

UpdateCurrentBuilder sets the activeSizeBuilder based on mode and cancels ongoing operations

func (*WasmClient) UseDebugTinyGo added in v0.6.7 

func (w *WasmClient) UseDebugTinyGo()

UseDebugTinyGo configures the client to compile with TinyGo in debug mode. Useful when iterating locally and you need TinyGo-compatible builds with extra debug info; never for deploy.

func (*WasmClient) UseDiskStorage added in v0.6.6 

func (w *WasmClient) UseDiskStorage()

UseDiskStorage switches the client to disk-backed storage. Idempotent. Does NOT trigger compilation — the caller composes Compile() when needed.

func (*WasmClient) UseMemoryStorage added in v0.6.6 

func (w *WasmClient) UseMemoryStorage()

UseMemoryStorage switches the client to in-memory storage. Idempotent. Provided for symmetry and test usage; production code does not call this (memory is the default at construction).

func (*WasmClient) UseProductionTinyGo added in v0.6.7 

func (w *WasmClient) UseProductionTinyGo()

UseProductionTinyGo configures the client to compile with TinyGo in production (smallest possible binary). Callers (e.g. goflare) use this method instead of hardcoding the internal mode letter "S" — if the letter ever changes, only this method is updated, not every dependent.

Persists the mode to disk storage so it survives across runs and is not silently overridden by a stale value (e.g. a previous "L" run).

func (*WasmClient) UseStandardGo added in v0.6.7 

func (w *WasmClient) UseStandardGo()

UseStandardGo configures the client to compile with the standard Go compiler. Produces large binaries (2-10 MB) and is incompatible with edge environments that enforce a 1 MiB wasm limit. Useful only when binary size does not matter (e.g. local servers that load wasm in a desktop browser).

func (*WasmClient) UseTinyGo added in v0.0.77 

func (w *WasmClient) UseTinyGo() bool

UseTinyGo returns true if the current mode requires TinyGo's runtime

func (*WasmClient) ValidateMode added in v0.6.0 

func (w *WasmClient) ValidateMode(mode string) error

ValidateMode validates if the provided mode is supported

func (*WasmClient) Value 

func (w *WasmClient) Value() string

Value returns the current compiler mode shortcut (c, d, or p)

func (*WasmClient) VerifyTinyGoInstallation 

func (w *WasmClient) VerifyTinyGoInstallation() error

VerifyTinyGoInstallation checks if TinyGo is properly installed

func (*WasmClient) VerifyTinyGoProjectCompatibility 

func (w *WasmClient) VerifyTinyGoProjectCompatibility()

VerifyTinyGoProjectCompatibility checks if the project is compatible with TinyGo compilation

func (*WasmClient) VisualStudioCodeWasmEnvConfig 

func (w *WasmClient) VisualStudioCodeWasmEnvConfig()

VisualStudioCodeWasmEnvConfig automatically creates and configures VS Code settings for WASM development. This method resolves the "could not import syscall/js" error by setting proper environment variables in .vscode/settings.json file. On Windows, the .vscode directory is made hidden for a cleaner project view. This configuration enables VS Code's Go extension to properly recognize WASM imports and provide accurate IntelliSense, error detection, and code completion for syscall/js and other WASM-specific packages.

func (*WasmClient) WasmProjectTinyGoJsUse 

func (w *WasmClient) WasmProjectTinyGoJsUse(mode ...string) (isWasmProject bool, useTinyGo bool)

WasmProjectTinyGoJsUse returns dynamic state based on current configuration

func (*WasmClient) WebClientGenerator added in v0.6.1 

func (w *WasmClient) WebClientGenerator() *webClientGenerator

WebClientGenerator returns a handler that generates the default web/client.go file.

Source Files

View all Source files

Directories

Path Synopsis
benchmark
shared command
cmd
wasmbuild command

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.