client

package module
v0.3.16 Latest Latest
Warning

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

 Go to latest Published: Dec 22, 2025 License: MIT Imports: 16 Imported by: 0

README

tinywasm

Project Badges

Intelligent WebAssembly compilation manager for Go with automatic project detection and a 3-mode compiler system.

🚀 Features

  • 3-Mode Compiler System:
    • L (Large): Standard Go compiler for fast development.
    • M (Medium): TinyGo with debug optimizations (-opt=1).
    • S (Small): TinyGo with size optimizations (-opt=z).
  • Interactive Integration: Implements DevTUI FieldHandler for real-time mode switching.
  • Smart Detection: Automatically identifies WASM projects and compiler requirements.
  • Developer Experience: Auto-configures VS Code with appropriate GOOS/GOARCH settings.
  • Flexible Output: Support for in-memory serving or physical file output.

🛠 Usage

Basic Initialization
// Create configuration with sensible defaults
config := tinywasm.NewConfig()
config.SourceDir = "web"
config.OutputDir = "web/public"

tw := tinywasm.New(config)

// (Optional) Enable physical wasm_exec.js output for file watchers/debug
tw.SetWasmExecJsOutputDir("web/js")
Mode Switching (DevTUI Integration)

Switching modes is asynchronous and reports progress via a channel:

progress := make(chan string)
go func() {
    for p := range progress {
        fmt.Println("Status:", p)
    }
}()

// Switch to Small (Production) mode
tw.Change("S", progress)

🏗 Core Concepts

Dual Output Architecture

tinywasm handles two types of outputs to optimize the build pipeline:

  1. WASM Binary (via OutputDir): The final WebAssembly file loaded by the browser.
  2. JavaScript Runtime: Mode-specific wasm_exec.js.
    • Dynamic: Recommended to use tw.JavascriptForInitializing() to get the content directly for embedding or serving.
    • Disk-based: Use tw.SetWasmExecJsOutputDir() if you need a physical file for external bundlers or mode-transparency for other tools.
Serving Strategies

The library automatically selects the best way to compile and serve the WASM binary:

  • In-Memory: Compiles directly to a buffer (fastest for development).
  • External: Compiles and serves from disk (useful for static integration).

Logic details are available in strategies.go.

VS Code Integration

On initialization, tinywasm can auto-create .vscode/settings.json to ensure gopls correctly recognizes the WASM environment:

{"gopls": {"env": {"GOOS": "js", "GOARCH": "wasm"}}}

⚙️ Configuration

Detailed configuration options and defaults can be found in config.go.

📋 Requirements

  • Go 1.21+
  • TinyGo (optional, required for Medium/Small modes)

Contributing

Documentation

Index

Constants

View Source 
const StoreKeyMode = "tinywasm_mode"

StoreKeyMode is the key used to store the current compiler mode in the Store

Variables

This section is empty.

Functions

This section is empty.

Types

type ClientStrategy added in v0.3.13 

type ClientStrategy interface {
	// Compile performs the compilation.
	// For InMemory: compiles to buffer.
	// For External: compiles to disk.
	Compile() error

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

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

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

type Config 

type Config struct {

	// AppRootDir specifies the application root directory (absolute).
	// e.g., "/home/user/project". If empty, defaults to "." to preserve existing behavior.
	AppRootDir string

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

	// OutputDir specifies the directory for WASM and related assets (relative to AppRootDir).
	// e.g., "web/public"
	OutputDir 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

	MainInputFile string // main input file for WASM compilation (default: "client.go")
	OutputName    string // output name for WASM file (default: "client")
	Logger        func(message ...any)

	BuildLargeSizeShortcut  string // "L" (Large) compile with go
	BuildMediumSizeShortcut string // "M" (Medium) compile with tinygo debug
	BuildSmallSizeShortcut  string // "S" (Small) compile with tinygo minimal binary size

	// gobuild integration fields
	Callback           func(error)     // Optional callback for async compilation
	CompilingArguments func() []string // Build arguments for compilation (e.g., ldflags)

	// DisableWasmExecJsOutput prevents automatic creation of wasm_exec.js file
	// Useful when embedding wasm_exec.js content inline (e.g., Cloudflare Pages Advanced Mode)
	DisableWasmExecJsOutput bool

	Store            Store  // Key-Value store for state persistence
	OnWasmExecChange func() // Callback for wasm_exec.js changes
	// contains filtered or unexported fields
}

Config holds configuration for WASM compilation

func NewConfig 

func NewConfig() *Config

NewConfig creates a WasmClient Config with sensible defaults

type ParameterMetadata 

type ParameterMetadata struct {
	Name        string
	Description string
	Required    bool
	Type        string
	EnumValues  []string
	Default     any
}

ParameterMetadata describes a tool parameter

type Store added in v0.3.7 

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

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

type TinyWasm added in v0.3.7 

type TinyWasm = WasmClient

TinyWasm is an alias for WasmClient to maintain backward compatibility

type ToolExecutor 

type ToolExecutor func(args map[string]any, progress chan<- any)

ToolExecutor defines how a tool should be executed Channel accepts string messages (no binary data in tinywasm)

type ToolMetadata 

type ToolMetadata struct {
	Name        string
	Description string
	Parameters  []ParameterMetadata
	Execute     ToolExecutor // Execution function
}

ToolMetadata provides MCP tool configuration metadata

type WasmClient 

type WasmClient struct {
	*Config
	// 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 Timeout is set to 40 seconds maximum as TinyGo compilation can be slow Default values: MainInputFile in Config defaults to "main.wasm.go"

func (*WasmClient) Change 

func (w *WasmClient) Change(newValue string, progress chan<- string)

Change updates the compiler mode for WasmClient and reports progress via the provided channel. Implements the HandlerEdit interface: Change(newValue string, progress chan<- string) NOTE: The caller (devtui) is responsible for closing the progress channel, NOT the handler.

func (*WasmClient) ClearJavaScriptCache 

func (h *WasmClient) ClearJavaScriptCache()

ClearJavaScriptCache clears both cached JavaScript strings to force regeneration

func (*WasmClient) CreateDefaultWasmFileClientIfNotExist 

func (t *WasmClient) CreateDefaultWasmFileClientIfNotExist() *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) GetLastOperationID added in v0.3.11 

func (w *WasmClient) GetLastOperationID() string

func (*WasmClient) GetMCPToolsMetadata 

func (w *WasmClient) GetMCPToolsMetadata() []ToolMetadata

GetMCPToolsMetadata returns metadata for all WasmClient MCP tools

func (*WasmClient) GetTinyGoVersion 

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

GetTinyGoVersion returns the installed TinyGo version

func (*WasmClient) GetWasmExecJsPathGo 

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

GetWasmExecJsPathGo returns the path to Go's wasm_exec.js file

func (*WasmClient) GetWasmExecJsPathTinyGo 

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

GetWasmExecJsPathTinyGo returns the path to TinyGo's wasm_exec.js file

func (*WasmClient) JavascriptForInitializing 

func (h *WasmClient) JavascriptForInitializing(customizations ...string) (js string, err error)

JavascriptForInitializing returns the JavaScript code needed to initialize WASM.

Parameters (variadic):

  • customizations[0]: Custom header string to prepend to wasm_exec.js content. If not provided, defaults to "// WasmClient: mode=<current_mode>\n"
  • customizations[1]: Custom footer string to append after wasm_exec.js content. If not provided, defaults to WebAssembly initialization code with fetch and instantiate.

Examples:

  • JavascriptForInitializing() - Uses default header and footer
  • JavascriptForInitializing("// Custom Header\n") - Custom header, default footer
  • JavascriptForInitializing("// Custom Header\n", "console.log('loaded');") - Both custom

func (*WasmClient) Label 

func (w *WasmClient) Label() string

Label returns the field label for DevTUI display

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 if it exists

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 strategy.

func (*WasmClient) SetLastOperationID added in v0.3.11 

func (w *WasmClient) SetLastOperationID(id string)

func (*WasmClient) SetWasmExecJsOutputDir 

func (w *WasmClient) SetWasmExecJsOutputDir(path string)

SetWasmExecJsOutputDir sets the output directory for wasm_exec.js. This is primarily intended for tests/debug where physical file output is required. Setting a non-empty path will trigger a project detection and, if detected, write/update the wasm_exec.js file to that directory.

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) Value 

func (w *WasmClient) Value() string

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

func (*WasmClient) VerifyTinyGoInstallation 

func (t *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) WasmExecJsOutputPath 

func (w *WasmClient) WasmExecJsOutputPath() string

WasmExecJsOutputPath returns the output path for wasm_exec.js

func (*WasmClient) WasmProjectTinyGoJsUse 

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

WasmProjectTinyGoJsUse returns dynamic state based on current configuration

Source Files

View all Source files

Directories

Path Synopsis
benchmark
shared 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.