tinywasm

README

tinywasm

Go package for intelligent WebAssembly compilation with automatic file detection.

Features

• Smart file detection via prefixes (frontend/backend separation)
• Dual compiler support: TinyGo (production, 47KB) / Go standard (dev, 1.6MB)
• VS Code auto-configuration for WASM development
• Single output: All files → main.wasm

Quick Start

config := &tinywasm.Config{
    WebFilesFolder: func() (string, string) { return "web", "public" },
    FrontendPrefix: []string{"f.", "ui."},
}
tw := tinywasm.New(config)
tw.NewFileEvent("main.wasm.go", ".go", "web/main.wasm.go", "write")

File Detection

Compiles: *.wasm.go, frontend prefixes (f.*.go), modules/*/ Ignores: Backend prefixes (b.*.go), root main.go, non-Go files

VS Code Integration

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

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

API

Core:

• New(config *Config) *TinyWasm
• NewFileEvent(fileName, ext, path, event string) error
• ShouldCompileToWasm(fileName, path string) bool

Compiler:

• TinyGoCompiler() bool / SetTinyGoCompiler(bool) error
• VerifyTinyGoInstallation() error

Utils:

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

Config

type Config struct {
    WebFilesFolder func() (string, string) // web dir, public dir
    FrontendPrefix []string                // frontend prefixes
    Log io.Writer                          // compilation output
    Callback func(string, error)          // optional callback
    CompilingArguments func() []string     // compiler args
}

Requirements

Go 1.20+, TinyGo (optional)

Documentation

Index

• func GetModuleName(filePath string) (string, error)
• type Config
• type TinyWasm
  • func New(c *Config) *TinyWasm
  • func (t *TinyWasm) GetTinyGoVersion() (string, error)
  • func (w *TinyWasm) IsFrontendFile(filename string) bool
  • func (h *TinyWasm) JavascriptForInitializing() (js string, err error)
  • func (w *TinyWasm) MainOutputFile() string
  • func (w *TinyWasm) NewFileEvent(fileName, extension, filePath, event string) error
  • func (w *TinyWasm) OutputPathMainFileWasm() string
  • func (w *TinyWasm) SetTinyGoCompiler(newValue any) (string, error)
  • func (w *TinyWasm) ShouldCompileToWasm(fileName, filePath string) bool
  • func (w *TinyWasm) TinyGoCompiler() bool
  • func (w *TinyWasm) UnobservedFiles() []string
  • func (t *TinyWasm) VerifyTinyGoInstallation() error
  • func (w *TinyWasm) VerifyTinyGoProjectCompatibility()
  • func (w *TinyWasm) VisualStudioCodeWasmEnvConfig()
  • func (w *TinyWasm) WasmProjectTinyGoJsUse() (bool, bool)

Functions

func GetModuleName

func GetModuleName(filePath string) (string, error)

GetModuleName extracts module name from file path

Types

type Config

type Config struct {
	// WebFilesFolder returns root web folder and subfolder eg: "web","public"
	WebFilesFolder func() (string, string)
	Writer         io.Writer // For logging output to external systems (e.g., TUI, console)
	FrontendPrefix []string  // Prefixes used to identify frontend files (e.g., "f.", "front.")
	TinyGoCompiler bool      // Enable TinyGo compiler (default: false for faster development)

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

Config holds configuration for WASM compilation

type TinyWasm

type TinyWasm struct {
	*Config
	ModulesFolder string // default "modules". for test change eg: "test/modules"
	// contains filtered or unexported fields
}

TinyWasm provides WebAssembly compilation capabilities with dynamic compiler selection

func New

func New(c *Config) *TinyWasm

New creates a new TinyWasm instance with the provided configuration Timeout is set to 40 seconds maximum as TinyGo compilation can be slow Default values: ModulesFolder="modules", mainInputFile="main.wasm.go"

func (*TinyWasm) GetTinyGoVersion

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

GetTinyGoVersion returns the installed TinyGo version

func (*TinyWasm) IsFrontendFile

func (w *TinyWasm) IsFrontendFile(filename string) bool

IsFrontendFile checks if a file should trigger WASM compilation based on frontend prefixes

func (*TinyWasm) JavascriptForInitializing

func (h *TinyWasm) JavascriptForInitializing() (js string, err error)

JavascriptForInitializing returns the JavaScript code needed to initialize WASM

func (*TinyWasm) MainOutputFile

func (w *TinyWasm) MainOutputFile() string

MainOutputFile returns the complete path to the main WASM output file

func (*TinyWasm) NewFileEvent

func (w *TinyWasm) 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., web/public/wasm/main.wasm.go, modules/users/wasm/users.wasm.go, modules/auth/f.logout.go) event: type of file event (e.g., create, remove, write, rename)

func (*TinyWasm) OutputPathMainFileWasm

func (w *TinyWasm) OutputPathMainFileWasm() string

OutputPathMainFileWasm returns the output path for the main WASM file e.g: web/public/wasm/main.wasm

func (*TinyWasm) SetTinyGoCompiler

func (w *TinyWasm) SetTinyGoCompiler(newValue any) (string, error)

SetTinyGoCompiler validates and sets the TinyGo compiler preference Automatically recompiles main.wasm.go when compiler type changes

func (*TinyWasm) ShouldCompileToWasm

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

ShouldCompileToWasm determines if a file should trigger WASM compilation

func (*TinyWasm) TinyGoCompiler

func (w *TinyWasm) TinyGoCompiler() bool

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

func (*TinyWasm) UnobservedFiles

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

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

func (*TinyWasm) VerifyTinyGoInstallation

func (t *TinyWasm) VerifyTinyGoInstallation() error

VerifyTinyGoInstallation checks if TinyGo is properly installed

func (*TinyWasm) VerifyTinyGoProjectCompatibility

func (w *TinyWasm) VerifyTinyGoProjectCompatibility()

VerifyTinyGoProjectCompatibility checks if the project is compatible with TinyGo compilation

func (*TinyWasm) VisualStudioCodeWasmEnvConfig

func (w *TinyWasm) 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 (*TinyWasm) WasmProjectTinyGoJsUse

func (w *TinyWasm) WasmProjectTinyGoJsUse() (bool, bool)

WasmProjectTinyGoJsUse returns dynamic state based on current configuration