Skip to content
A compiler from Go to JavaScript for running Go code in a browser
Branch: master
Clone or download
Pull request Compare This branch is 30 commits ahead, 66 commits behind gopherjs:master.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
.circleci
build compiler: upgrade to Go 1.12 (#41) Mar 10, 2019
compiler compiler: upgrade to Go 1.12 (#41) Mar 10, 2019
doc doc: Document Node.js version 10.0.0 requirement. Jun 28, 2018
internal/sysutil internal/sysutil: Fix build error on FreeBSD due to Rlimit.Cur type m… Feb 14, 2018
js js: add MakeFullWrapper to expose exported methods and struct fields. ( Jul 7, 2018
node-syscall
nosync WIP: nosync: Implement sync.Map. Aug 25, 2017
testdata compiler: upgrade to Go 1.12 (#41) Mar 10, 2019
tests compiler: upgrade to Go 1.12 (#41) Mar 10, 2019
.gitignore Initial module-aware changes for Go1.11 (#14) Aug 10, 2018
.std_test_pkg_exclusions compiler: upgrade to Go 1.12 (#41) Mar 10, 2019
.vet_exclusions compiler: upgrade to Go 1.12 (#41) Mar 10, 2019
LICENSE Added LICENSE. Nov 8, 2013
README.md README: update note on modules in README (#34) Nov 27, 2018
genmodstubbs.go build: almost complete module support (#33) Nov 27, 2018
go.mod compiler: upgrade to Go 1.11.5 (#43) Mar 8, 2019
go.sum compiler: upgrade to Go 1.12 (#41) Mar 10, 2019
package-lock.json test: use github.com/rogpeppe/go-internal (#29) Nov 23, 2018
package.json compiler/prelude: format .js files using prettier (#4) Jul 2, 2018
script_test.go build: almost complete module support (#33) Nov 27, 2018
tool.go compiler: upgrade to Go 1.11.5 (#43) Mar 8, 2019
tool_deps.go Initial module-aware changes for Go1.11 (#14) Aug 10, 2018
tools.go ci: fix various breakages (#22) Sep 1, 2018

README.md

GopherJS - A compiler from Go to JavaScript

Sourcegraph Circle CI

GopherJS compiles Go code (golang.org) to pure JavaScript code. Its main purpose is to give you the opportunity to write front-end code in Go which will still run in all browsers.

Playground

Give GopherJS a try on the GopherJS Playground.

What is supported?

Nearly everything, including Goroutines (compatibility table). Performance is quite good in most cases, see HTML5 game engine benchmark. Cgo is not supported.

This fork of GopherJS has almost complete support for modules in Go 1.11. There are also fairly extensive tests to ensure that GopherJS works in both GOPATH and module modes. For more up-to-date commentary on modules support, please see https://github.com/myitcv/gopherjs/wiki/Go-1.11-and-GopherJS.

Installation and Usage

If you already have github.com/gopherjs/gopherjs installed:

cd $(go list -f "{{.Dir}}" github.com/gopherjs/gopherjs)
git remote add myitcv https://github.com/myitcv/gopherjs
git fetch myitcv
git checkout -f master
git reset --hard myitcv/master
git branch --set-upstream-to=myitcv/master
GO111MODULE=on go install

Or for a fresh install:

git clone https://github.com/myitcv/gopherjs "$(cut -d':' -f1 <<< $GOPATH)/src/github.com/gopherjs/gopherjs"
cd "$(cut -d':' -f1 <<< $GOPATH)/src/github.com/gopherjs/gopherjs"
GO111MODULE=on go install

Now you can use gopherjs build [package], gopherjs build [files] or gopherjs install [package] which behave similar to the go tool. For main packages, these commands create a .js file and .js.map source map in the current directory or in $GOPATH/bin. The generated JavaScript file can be used as usual in a website. Use gopherjs help [command] to get a list of possible command line flags, e.g. for minification and automatically watching for changes.

gopherjs uses your platform's default GOOS value when generating code. Supported GOOS values are: linux, darwin. If you're on a different platform (e.g., Windows or FreeBSD), you'll need to set the GOOS environment variable to a supported value. For example, GOOS=linux gopherjs build [package].

Note: GopherJS will try to write compiled object files of the core packages to your $GOROOT/pkg directory. If that fails, it will fall back to $GOPATH/pkg.

gopherjs run, gopherjs test

If you want to use gopherjs run or gopherjs test to run the generated code locally, install Node.js 10.0.0 (or newer), and the source-map-support module:

npm install --global source-map-support

On supported GOOS platforms, it's possible to make system calls (file system access, etc.) available. See doc/syscalls.md for instructions on how to do so.

gopherjs serve

gopherjs serve is a useful command you can use during development. It will start an HTTP server serving on ":8080" by default, then dynamically compile your Go packages with GopherJS and serve them.

For example, navigating to http://localhost:8080/example.com/user/project/ should compile and run the Go package example.com/user/project. The generated JavaScript output will be served at http://localhost:8080/example.com/user/project/project.js (the .js file name will be equal to the base directory name). If the directory contains index.html it will be served, otherwise a minimal index.html that includes <script src="project.js"></script> will be provided, causing the JavaScript to be executed. All other static files will be served too.

Refreshing in the browser will rebuild the served files if needed. Compilation errors will be displayed in terminal, and in browser console. Additionally, it will serve $GOROOT and $GOPATH for sourcemaps.

If you include an argument, it will be the root from which everything is served. For example, if you run gopherjs serve github.com/user/project then the generated JavaScript for the package github.com/user/project/mypkg will be served at http://localhost:8080/mypkg/mypkg.js.

Performance Tips

Community

Getting started

Interacting with the DOM

The package github.com/gopherjs/gopherjs/js (see documentation) provides functions for interacting with native JavaScript APIs. For example the line

document.write("Hello world!");

would look like this in Go:

js.Global.Get("document").Call("write", "Hello world!")

You may also want use the DOM bindings, the jQuery bindings (see TodoMVC Example) or the AngularJS bindings. Those are some of the bindings to JavaScript APIs and libraries by community members.

Providing library functions for use in other JavaScript code

Set a global variable to a map that contains the functions:

package main

import "github.com/gopherjs/gopherjs/js"

func main() {
	js.Global.Set("pet", map[string]interface{}{
		"New": New,
	})
}

type Pet struct {
	name string
}

func New(name string) *js.Object {
	return js.MakeWrapper(&Pet{name})
}

func (p *Pet) Name() string {
	return p.name
}

func (p *Pet) SetName(name string) {
	p.name = name
}

For more details see Jason Stone's blog post about GopherJS.

Architecture

General

GopherJS emulates a 32-bit environment. This means that int, uint and uintptr have a precision of 32 bits. However, the explicit 64-bit integer types int64 and uint64 are supported. The GOARCH value of GopherJS is "js". You may use it as a build constraint: // +build js.

Application Lifecycle

The main function is executed as usual after all init functions have run. JavaScript callbacks can also invoke Go functions, even after the main function has exited. Therefore the end of the main function should not be regarded as the end of the application and does not end the execution of other goroutines.

In the browser, calling os.Exit (e.g. indirectly by log.Fatal) also does not terminate the execution of the program. For convenience, it calls runtime.Goexit to immediately terminate the calling goroutine.

Goroutines

Goroutines are fully supported by GopherJS. The only restriction is that you need to start a new goroutine if you want to use blocking code called from external JavaScript:

js.Global.Get("myButton").Call("addEventListener", "click", func() {
  go func() {
    [...]
    someBlockingFunction()
    [...]
  }()
})

How it works:

JavaScript has no concept of concurrency (except web workers, but those are too strictly separated to be used for goroutines). Because of that, instructions in JavaScript are never blocking. A blocking call would effectively freeze the responsiveness of your web page, so calls with callback arguments are used instead.

GopherJS does some heavy lifting to work around this restriction: Whenever an instruction is blocking (e.g. communicating with a channel that isn't ready), the whole stack will unwind (= all functions return) and the goroutine will be put to sleep. Then another goroutine which is ready to resume gets picked and its stack with all local variables will be restored.

GopherJS Development

If you're looking to make changes to the GopherJS compiler, see Developer Guidelines for additional developer information.

You can’t perform that action at this time.