GopherJS Deployment and Usage Guide

Prerequisites

Go: Version 1.20 or newer installed
Node.js: Version 18 or newer (required only for gopherjs run and gopherjs test)
Operating System: Linux or macOS (Windows/FreeBSD users must set GOOS environment variable to linux or darwin)

Installation

Install GopherJS using go install:

go install github.com/gopherjs/gopherjs@v1.20.1

Note: Replace v1.20.1 with your desired version tag.

Handling Newer Go Versions

If your local Go version is newer than 1.20, you must install Go 1.20 separately and configure GOPHERJS_GOROOT:

# Install Go 1.20.14 via the Go downloader
go install golang.org/dl/go1.20.14@latest
go1.20.14 download

# Set environment variable (add to ~/.bashrc, ~/.zshrc, or equivalent)
export GOPHERJS_GOROOT="$(go1.20.14 env GOROOT)"

Verify installation:

gopherjs version

Configuration

Environment Variables

Variable	Description	Required
`GOPHERJS_GOROOT`	Path to Go 1.20 installation (required if system Go > 1.20)	Conditional
`GOOS`	Set to `linux` or `darwin` if running on unsupported platforms (Windows, FreeBSD)	Platform-dependent

Platform-Specific Setup

Windows/FreeBSD users must set GOOS before running GopherJS commands:

export GOOS=linux
# or
export GOOS=darwin

Build & Run

Development Mode

Use the built-in development server for automatic compilation and hot-reload:

# Start server on default port :8080
gopherjs serve

# Serve specific package
gopherjs serve github.com/user/project

# Serve from specific directory
gopherjs serve ./cmd/frontend

The server:

Compiles Go packages on-demand when accessed via browser
Serves generated JavaScript at http://localhost:8080/[package]/[name].js
Serves index.html if present, otherwise generates a minimal HTML file
Displays compilation errors in terminal and browser console
Provides source maps for debugging

Production Build

Compile Go to JavaScript for deployment:

# Build main package (outputs .js and .js.map)
gopherjs build .

# Build specific package
gopherjs build github.com/user/project

# Build with minification
gopherjs build -m .

# Build quietly (suppress warnings)
gopherjs build -q .

# Verbose output
gopherjs build -v .

Output files:

[package].js - Compiled JavaScript
[package].js.map - Source map for debugging

Install to GOPATH/bin

gopherjs install [package]

Running and Testing

Requires Node.js 18+:

# Run compiled JavaScript locally
gopherjs run [package]

# Run tests
gopherjs test [package]

Available Flags

View command-specific flags:

gopherjs help build
gopherjs help serve
gopherjs help test

Common flags:

-m, --minify: Minify generated JavaScript
-v, --verbose: Print package names during compilation
-q, --quiet: Suppress non-fatal warnings
--color: Enable colored output (auto-detected by default)

Deployment

GopherJS outputs pure JavaScript files compatible with any static web hosting platform.

Build for Production

# Create optimized build
gopherjs build -m -o dist/app.js .

Deployment Platforms

Deploy the generated .js file(s) and your index.html to any static hosting service:

Netlify/Vercel: Connect Git repository with gopherjs build as build command
GitHub Pages: Commit dist/ folder to gh-pages branch
AWS S3/CloudFront: Upload compiled assets to S3 bucket with static hosting enabled
CDN: Serve compiled JavaScript from any CDN (Cloudflare, jsDelivr, etc.)

Integration Example

Create an index.html that loads the compiled output:

<!DOCTYPE html>
<html>
<head>
    <title>Go App</title>
</head>
<body>
    <script src="app.js"></script>
</body>
</html>

Troubleshooting

"Go version mismatch" errors

Problem: Installed Go version is newer than 1.20.
Solution: Install Go 1.20.14 and set GOPHERJS_GOROOT:

go install golang.org/dl/go1.20.14@latest
go1.20.14 download
export GOPHERJS_GOROOT="$(go1.20.14 env GOROOT)"

"GOOS not supported" on Windows/FreeBSD

Problem: GopherJS only supports linux and darwin targets.
Solution: Set GOOS environment variable:

export GOOS=linux
gopherjs build .

Permission denied writing to $GOROOT/pkg

Problem: GopherJS cannot write compiled core packages to system GOROOT.
Solution: No action required. GopherJS automatically falls back to $GOPATH/pkg.

Node.js errors with `gopherjs run` or `gopherjs test`

Problem: Commands fail with execution errors.
Solution: Install Node.js 18 or newer:

node --version  # Should be v18.x.x or higher

Source maps not loading in browser

Problem: Cannot see original Go source in browser debugger.
Solution: Ensure $GOROOT and $GOPATH are accessible to the development server. gopherjs serve automatically serves these paths for source map resolution.

Compilation errors in browser but not terminal

Problem: gopherjs serve shows errors in browser console but terminal appears clean.
Solution: Check terminal output carefully; compilation errors are displayed in both locations during development server operation.

How to Deploy & Use gopherjs/gopherjs