Getting Started

Let's make a basic working Vugu application that runs in your browser. A few commands will get you started and a minimal Vugu application is quite small. Make sure you have at least Go 1.14 installed.

  1. Install vgrun and related utilities with the commands:

    go get -u github.com/vugu/vgrun
    vgrun -install-tools

  2. Create a new empty folder anywhere you like. From that directory, tell vgrun to make you an example application:

    vgrun -new-from-example=simple .

    All this does is ask git to download the example project for you.

  3. Now run the development server with vgrun:

    vgrun devserver.go
    Note that this also starts a file watcher to automatically reload the page when you change .vugu files. (You can disable it and tell it to only run once with vgrun -1 devserver.go)

    Again, all vgrun is doing here is providing some additional convenience. You can just also just go run devserver.go you'd like.

  4. Browse to it: http://127.0.0.1:8844/ and marvel at the wonder you have created. Now let's take a quick look at the files that were produced.

  5. Aside from familiar files like .gitignore and README.md and go.mod, there is a generate.go file which just has the appropriate Go generate comment in it to invokve the Vugu code generator:

    //go:generate vugugen -s
    (The -s flag tells it to put the generated code in a single file. -r is available too for recursive operation.)
  6. The file root.vugu Contains a simple Vugu component that demonstrates how HTML elements and Go code are combined together. It looks like so (abbreviated for clarity):

    <div>
      <main role="main" class="container text-center">
        <div class="mt-5">
          <h1>Welcome to Vugu</h1>
          <p class="lead">This page is being rendered via 
            <a @click='event.PreventDefault();c.ShowWasm=!c.ShowWasm' 
               href="https://webassembly.org/">WebAssembly</a>...
          </p>
          <div vg-if='c.ShowWasm' class="alert 
               alert-primary" role="alert">
            <strong>WebAssembly</strong> (abbreviated Wasm) is a 
            binary instruction format...
          </div>
        </div>
      </main>
    </div>
    
    <script type="application/x-go">
    type Root struct {
        ShowWasm bool `vugu:"data"`
    }
    </script>
  7. The file devserver.go is a simple development web server. Note that this does not get compiled to WebAssembly. This is a server which serves your program up to the browser. It starts an http server, a wasm compiler tool (a thin wrapper around GOOS=js GOARCH=wasm go build) and hooks up a default index page, the necessary JS support file and includes Bootstrap. (Which is just an example, Vugu has no dependency on bootstrap or any other CSS/JS framework.) These pieces are easily customizable, see the docs.

    // +build ignore
    
    package main
    
    import (
    	"log"
    	"net/http"
    
    	"github.com/vugu/vugu/devutil"
    )
    
    func main() {
    	l := "127.0.0.1:8844"
    	log.Printf("Starting HTTP Server at %q", l)
    
    	wc := devutil.NewWasmCompiler().SetDir(".")
    	mux := devutil.NewMux()
    	mux.Match(devutil.NoFileExt, devutil.DefaultAutoReloadIndex.Replace(
    		`<!-- styles -->`,
    		`<link rel="stylesheet" href="https://stackpath.bootstrapcdn.com/bootstrap/4.4.1/css/bootstrap.min.css">`))
    	mux.Exact("/main.wasm", devutil.NewMainWasmHandler(wc))
    	mux.Exact("/wasm_exec.js", devutil.NewWasmExecJSHandler(wc))
    	mux.Default(devutil.NewFileServer().SetDir("."))
    
    	log.Fatal(http.ListenAndServe(l, mux))
    }