Vugu Tools

Vugu includes/supports some command line utilities intended to make development simpler. One of the core philosophies of this project is that Vugu programs are just Go programs. Although there is code generation involved, normal Go tools like go generate and go build, the module system, etc., are all used in the usual way. These commands are here to make development more convenient and none of them are used at run time.


Easily run and automatically rebuild your Vugu program.

While developing a web UI application the task of having to constantly restart your server for every change can be come tedious. To address this vgrun is a wrapper around go generate and go build that builds and runs your Vugu program and starts a file system watcher. Any files with a .vugu extension being added/removed/written will result in the generate, build, run sequence again. It also starts a lightweight webserver which can be used to automatically refresh the page when your server is back up (the example in Getting Started with Vugu and others include this feature).

You should use vgrun from the folder where your project lives and specify what to run (a .go file for simple examples or the path to the package where main lives). Examples:

For a project with a simple single-file development server:
vgrun devserver.go
For a project with main package in the server folder:
vgrun server

It also has a feature to create new project from an existing sample application as well as an option to install the other tools on this page. See Getting Started.

Useful options:

  • -install-tools downloads and installs the other tools on this page via go get and go install.
  • -new-from-example=[name] creates a new project based on the example under vugu-examples. Follow it with the path of where to put the project.
  • -no-generate skip the go generate step
  • -watch-dir specify an alternate directory to (recursively) watch other than the current one
  • -v enable verbose output (like if you need to report a bug for example this is helpful info ☺️).
  • -1 run only once and exit. Disables the file watcher.


Generate .go files from your .vugu files.

vugugen is an important part of the Vugu ecosystem and provides the code generation functionality that converts .vugu files into .go files. It is a thin wrapper around the package. Output produced by vugugen goes into files that end with _vgen.go and they are normally included in .gitignore because they are re-created frequently.

The normal way to use vugugen is via go generate. For clarity and simplicity the recommendation is to place a file in your top level project directory called generate.go and put the appropriate generate comments in it. The rationale is that Vugu programs (and I would argue UI applications in general) often need their different packages to work together and generating everything for the project is frequent and usually necessary. If you discover that some portion of your application changes less frequently you can always move the generate comments into that package and run them manually when needed (in which case you should probably also commit those _vgen.go files it outputs to your versin control system).

Example generate.go file:

package yourpackage

//go:generate vugugen

Useful options:

  • -s will enable single-file mode where the output for each package is placed into a single file for the package (as opposed to a _vgen.go file corresponding to each individual .vugu file)
  • -r enables recursion into subdirectories


Generate route information from .vugu files.

The router is a work in progress. This page will be updated once some of the rough edges are smoothed out. But the idea is you can drop .vugu files in the same folder structure you want for your site/app and appropriate route information will be generated automatically from it (using this tool via go generate); so you can just put a .vugu file in place, browse right to it and hack away.