Noções Básicas de WebAssembly & TinyGo

10 exemplos para você começar com WASM & TinyGo - 7 básicos e 3 intermediários.

Pré-requisitos

• Instale o Go 1.26.x em go.dev/dl.
• Instale um runtime WASI: brew install wasmtime (macOS) ou baixe de wasmtime.dev.
• Opcional: instale o TinyGo em tinygo.org/getting-started e verifique com tinygo version.
• Crie um módulo de rascunho: mkdir wasmdemo && cd wasmdemo && go mod init example.com/wasmdemo.

Exemplos Básicos

1. Compile "hello world" para WASI

A menor prova de que o Go emite um módulo .wasm executável.

package main
 
import "fmt"
 
func main() {
    fmt.Println("hello from wasip1/wasm")
}

GOOS=wasip1 GOARCH=wasm go build -o hello.wasm .
wasmtime run hello.wasm

• GOOS=wasip1 seleciona importações WASI Preview 1 em vez de chamadas de sistema Linux.
• A saída é um único artefato hello.wasm - sem binário Go separado.
• wasmtime run fornece as importações do host WASI que o módulo espera.

Relacionado: Compilando com GOOS=wasip1 GOARCH=wasm - flags e opções do linker

2. Remova símbolos de depuração para WASM menor

Reduza o tamanho do download com flags de linker padrão.

GOOS=wasip1 GOARCH=wasm go build -ldflags="-s -w" -o hello.wasm .

• -s omite a tabela de símbolos; -w omite informações de depuração DWARF.
• Seguro para builds de release; mantenha artefatos não despojados para profiling, se necessário.
• As reduções de tamanho são modestas em comparação com a escolha do TinyGo, mas as flags são gratuitas.

Relacionado: Otimização de Tamanho WASM: TinyGo vs gc WASM - táticas mais profundas de tamanho

3. Leia variáveis de ambiente WASI

WASI expõe os.Getenv através de importações do host.

package main
 
import (
    "fmt"
    "os"
)
 
func main() {
    fmt.Println("USER=", os.Getenv("USER"))
}

wasmtime run --env USER=ada hello-env.wasm

• Nem todo host pré-popula as mesmas chaves que o Linux.
• Passe flags --env explícitas no wasmtime para testes reproduzíveis.
• Trate o ambiente como uma capacidade que o host concede, não como estado global implícito.

4. Escreva um arquivo através de pré-abertura WASI

O acesso ao sistema de arquivos requer que o host pré-abra diretórios.

GOOS=wasip1 GOARCH=wasm go build -o write.wasm .
mkdir -p /tmp/wasmout
wasmtime run --dir /tmp/wasmout::/data write.wasm

os.WriteFile("/data/out.txt", []byte("ok"), 0o644)

• Caminhos dentro do guest são mapeados para diretórios do host usando a sintaxe --dir host::guest.
• Falha fechado se o diretório não for pré-aberto - bom para sandboxing.
• Espelhe este padrão no wazero com montagens de diretório FSConfig.

5. TinyGo "hello" em WASM

TinyGo emite módulos muito menores quando seu subconjunto da stdlib é suficiente.

package main
 
import "fmt"
 
func main() {
    fmt.Println("hello from tinygo wasm")
}

tinygo build -target=wasm -o tinyhello.wasm .
wasmtime run tinyhello.wasm

• -target=wasm seleciona o backend WASM genérico (verifique os targets específicos de placa separadamente).
• Confirme quais pacotes da stdlib sua versão do TinyGo suporta antes de portar bibliotecas.
• Espere inicializações a frio mais rápidas em hosts de borda sensíveis ao tamanho.

Relacionado: TinyGo para Microcontroladores e WASM Restrito - targets de placa

6. Esqueleto de build tag para navegador

Isole pontos de entrada exclusivos para navegador de builds WASI.

//go:build js && wasm
 
package main
 
import "syscall/js"
 
func main() {
    js.Global().Get("console").Call("log", "hello browser")
    select {}
}

GOOS=js GOARCH=wasm go build -o main.wasm .

• select {} mantém main vivo para que os callbacks possam ser acionados.
• Emparelhe com wasm_exec.js de $(go env GOROOT)/misc/wasm/wasm_exec.js em hosts de HTML.
• Não importe syscall/js em pacotes wasip1.

Relacionado: syscall/js: Go no Navegador - callbacks DOM

7. Liste exports WASM com wasm-tools

Inspecione a superfície do módulo antes de incorporar.

wasm-tools print hello.wasm | head

• Confirma _start, exportação de memória e nomes de importação WASI.
• Importações incompatíveis são o principal motivo pelo qual a instanciação falha nos hosts.
• Adicione wasm-tools via cargo install wasm-tools ou seu gerenciador de pacotes.

Exemplos Intermediários

8. Incorpore WASI em Go com wazero

Execute um módulo guest a partir de um serviço Go sem cgo.

package main
 
import (
    "context"
    "os"
 
    "github.com/tetratelabs/wazero"
    "github.com/tetratelabs/wazero/imports/wasi_snapshot_preview1"
)
 
func main() {
    ctx := context.Background()
    r := wazero.NewRuntime(ctx)
    defer r.Close(ctx)
    wasi_snapshot_preview1.MustInstantiate(ctx, r)
 
    wasmBytes, _ := os.ReadFile("hello.wasm")
    mod, _ := r.Instantiate(ctx, wasmBytes)
    defer mod.Close(ctx)
 
    start := mod.ExportedFunction("_start")
    _, _ = start.Call(ctx)
}

• wasi_snapshot_preview1 registra as importações WASI que o módulo Go precisa.
• Instantiate compila e carrega o bytecode; reutilize Runtime entre requisições em servidores.
• Passe deadlines de context para limitar o tempo de execução do guest.

Relacionado: Runtimes Host WASI: wasmtime, wazero & Spin - comparação de runtimes

9. Teste de fumaça de CI para artefatos WASM

Detecte builds quebrados antes do deploy.

GOOS=wasip1 GOARCH=wasm go build -o /tmp/app.wasm ./...
wasmtime run /tmp/app.wasm

• Adicione o job ao lado das verificações de compilação GOOS=linux GOARCH=amd64.
• Falhe o pipeline em códigos de saída wasmtime run diferentes de zero.
• Fixe as versões wasmtime e tinygo nas imagens de CI para reprodutibilidade.

Relacionado: Melhores Práticas de WebAssembly & TinyGo - CI e higiene de importação

10. Compare tamanhos de binário gc vs TinyGo

Faça escolhas de toolchain baseadas em dados.

GOOS=wasip1 GOARCH=wasm go build -ldflags="-s -w" -o gc.wasm .
tinygo build -target=wasm -o tiny.wasm .
ls -lh gc.wasm tiny.wasm

• Registre os tamanhos em ADRs ao escolher TinyGo vs gc para funções de borda.
• Emparelhe o tamanho com dados de benchmark - o runtime do TinyGo difere do scheduler do gc.
• Meça novamente após atualizações menores do Go; 1.26 melhorou a memória do heap, nem sempre o tamanho do arquivo.

Relacionado: Guia de Decisão: Go Nativo vs TinyGo vs Rust WASM - trade-offs classificados

Versões da Stack: Esta página foi escrita para Go 1.26.x (padrão Green Tea GC, go fix modernizers - verifique o patch na build), chi (última versão - verifique na build), gin (última versão - verifique na build), echo (última versão - verifique na build), google.golang.org/grpc (última versão - verifique na build), sigs.k8s.io/controller-runtime (última versão - verifique na build), kubebuilder (última versão - verifique na build), tinygo (última versão - verifique os targets de placa na build), wazero (última versão - verifique na build) e golangci-lint (última versão - verifique o conjunto de linters na build).