tinywasm

tinywasm

Go package for intelligent WebAssembly compilation with automatic file detection and 3-mode compiler system.

Features

• 3-Mode Compiler System: Coding ("c"), Debug ("d"), Production ("p")
• DevTUI Integration: FieldHandler interface for interactive mode switching
• Smart file detection via prefixes (frontend/backend separation)
• Triple compiler support: Go standard (fast dev), TinyGo debug (-opt=1), TinyGo production (-opt=z)
• VS Code auto-configuration for WASM development
• Single output: All files → main.wasm

Quick Start

// Basic usage
config := tinywasm.NewConfig() // Pre-configured with defaults
config.WebFilesRootRelative = "web"
config.WebFilesSubRelative = "public"

tw := tinywasm.New(config)
tw.NewFileEvent("web/main.wasm.go", ".go", "web/main.wasm.go", "write")

// DevTUI Integration - 3 Mode System
fmt.Println("Current mode:", tw.Value())    // "c" (coding)
msg, err := tw.Change("d")                  // Switch to debug mode
fmt.Println("Status:", msg)                 // "Switching to debugging mode"

// Advanced configuration
config := &tinywasm.Config{
    WebFilesRootRelative: "web",
    WebFilesSubRelative:  "public",
    CodingShortcut:      "c",  // Customizable shortcuts
    DebuggingShortcut:   "d",
    ProductionShortcut:  "p",
}

DevTUI FieldHandler Interface

TinyWasm implements the DevTUI FieldHandler interface for interactive development:

// DevTUI Integration
label := tw.Label()           // "Compiler Mode"
current := tw.Value()         // Current mode shortcut ("c", "d", "p")
canEdit := tw.Editable()      // true
timeout := tw.Timeout()       // 0 (no timeout)

// Interactive mode change with validation
msg, err := tw.Change("d")
if err != nil {
    // Handle validation errors (invalid mode, missing TinyGo, etc.)
}
// msg contains success message or warning if auto-compilation fails

VS Code Integration

Auto-creates .vscode/settings.json with WASM environment:

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

API

Core:

• New(config *Config) *TinyWasm
• NewConfig() *Config - Pre-configured with sensible defaults
• NewFileEvent(fileName, ext, path, event string) error
• ShouldCompileToWasm(fileName, path string) bool

DevTUI FieldHandler Interface:

• Label() string - Returns "Compiler Mode"
• Value() string - Current mode shortcut ("c", "d", "p")
• Editable() bool - Returns true (field is editable)
• Change(newValue any) (string, error) - Switch compiler mode with validation
• Timeout() time.Duration - Returns 0 (no timeout)

Legacy Compiler Methods (deprecated):

• TinyGoCompiler() bool - Use Value() instead
• SetTinyGoCompiler(bool) error - Use Change() instead
• VerifyTinyGoInstallation() error

Utils:

• MainInputFileRelativePath() string
• UnobservedFiles() []string
• JavascriptForInitializing() (string, error)

Config

type Config struct {
	WebFilesRootRelative string    // root web folder (relative) eg: "web"
	WebFilesSubRelative  string    // subfolder under root (relative) eg: "public"
	Logger               func(message ...any) // For logging output to external systems (e.g., TUI, console)
	// NOTE: `TinyGoCompiler` was removed from the public `Config` to avoid
	// confusion. The compiler selection is controlled at runtime via the
	// TinyWasm instance. Use `tw.Change("c"|"d"|"p")` to switch modes and
	// `tw.Value()` to inspect the current mode. The internal boolean
	// `tinyGoCompiler` remains a private implementation detail.

	// NEW: Shortcut configuration (default: "c", "d", "p")
	CodingShortcut     string // coding "c" compile fast with go
	DebuggingShortcut  string // debugging "d" compile with tinygo debug
	ProductionShortcut string // production "p" 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)

}

// Pre-configured constructor (recommended)
func NewConfig() *Config

Mode Switching

tw.Change("p")  // production mode with TinyGo -opt=z
tw.Change("d")  // debug mode with TinyGo -opt=1
tw.Change("c")  // coding mode with Go standard

Requirements

• Go 1.20+
• TinyGo (optional, required for debug/production modes)
• DevTUI (optional, for interactive development)

Migration Guide

From TinyWasm v1.x:

Benefits:

• 🎯 3 optimized modes instead of binary choice
• 🔧 DevTUI integration for interactive development
• 📦 Smaller debug builds with TinyGo -opt=1
• ⚡ Auto-recompilation on mode switch
• 🛠️ Better error handling with validation

Contributing