Full-stack application in Go: Quick start

There are a few rules that you have to keep in mind to write your build automation:

• File(s) must start with //go:build mage in its own line. Other build tags are allowed if necessary.
• Task file(s) must belong to the main package. Other packages may be added.
• One exported function per task, i.e., starting with a capital letter.
• The first sentence of the comment above the exported function is the short description of the task.
• The full comment is the long description printed with -h and the task name.
• A comment above the package declaration is printed before the list of tasks.

Using these rules, we can write the seed of the build automation "script." I am using sh.Run() here, that is a helper provided by Mage to run commands with arguments and return an error, if needed. This function will not display the output of the command unless we run mage with the -v flag.

  //go:build mage

  // Automated build tasks for development and release to production.
  package main

  import "github.com/magefile/mage/sh"

  // Build front end application
  func Build() error {
  	return sh.Run("go", "build", "-o", "target/rexlists-fe", "cmd/rexlists-fe/main.go")
  }

Remember to get this module so it is available during compilation.

  go get github.com/magefile/mage/sh

Although this is very simple, we can now build the front end without specifying all the parameters to the build subcommand. Running mage from the project root returns the list of tasks, and mage build produces the front-end executable.

% mage
Automated build tasks for development and release to production.

Targets:
  build    front end application
% mage build
% rm -f target/rexlists-*
% mage -v build
Running target: Build
exec: go "build" "-o" "target/rexlists-fe" "cmd/rexlists-fe/main.go"
% ls target
rexlists-fe

Wow! With just three comments and five lines of code, we've made solid progress. Mage offers even more capabilities. I'll walk through a few additional features and finish the first version of the build automation.

Mage really helps to have a streamlined build process that applies the best practices. Let's cover some of the more frequently used ones.

  const appName = "rexlists"
  const targetDir = "target"

  // Build front end application
  func BuildFrontEnd() error {
  	fmt.Println("Building front end.")
  	return buildVariant(appName, "fe")
  }

  // Build back end application
  func BuildBackEnd() error {
  	fmt.Println("Building back end.")
  	return buildVariant(appName, "be")
  }

  func buildVariant(appName, variant string) error {
  	var bin = fmt.Sprintf("target/%s-%s", appName, variant)
  	var src = fmt.Sprintf("cmd/%s-%s/main.go", appName, variant)

  	return sh.Run("go", "build", "-o", bin, src)
  }

  // Build both applications
  func BuildAll() {
  	mg.Deps(BuildFrontEnd, BuildBackEnd)
  }

  // Run linters.
  func CheckLint() error {
  	fmt.Println("Run Linters.")
  	return sh.RunV("golangci-lint", "run")
  }

  // Namespaces
  type Build mg.Namespace
  type Check mg.Namespace

  // Build front end application
  func (Build) FrontEnd() error {
  	//...
  }

  // Build back end application
  func (Build) BackEnd() error {
  	//...
  }

  // Builg both applications
  func (Build) All() {
  	//...
  }

  // Run linters.
  func (Check) Lint() error {
  	//...
  }

  // Check code quality.
  func (Check) All() {
  	mg.Deps(Check.Lint)
  }

  var Aliases = map[string]interface{}{
  	"b":  Build.All,
  	"bf": Build.FrontEnd,
  	"bb": Build.BackEnd,
  	"c":  Check.All,
  }

  var Default = Build.All

  //go:build mage

  // Automated build tasks for development and release to production.
  package main

  import (
  	"fmt"

  	"github.com/magefile/mage/mg"
  	"github.com/magefile/mage/sh"
  )

  const appName = "rexlists"
  const targetDir = "target"

  var Aliases = map[string]interface{}{
  	"b":  Build.All,
  	"bf": Build.FrontEnd,
  	"bb": Build.BackEnd,
  	"c":  Check.All,
  }

  // Default target to run when none is specified
  // If not set, running mage will list available targets
  var Default = Build.All

  // Namespaces
  type Build mg.Namespace
  type Check mg.Namespace

  // Build front end application
  func (Build) FrontEnd() error {
  	fmt.Println("Building front end.")
  	return buildVariant(appName, "fe")

  }

  // Build back end application
  func (Build) BackEnd() error {
  	fmt.Println("Building back end.")
  	return buildVariant(appName, "be")
  }

  func buildVariant(appName, variant string) error {
  	var bin = fmt.Sprintf("target/%s-%s", appName, variant)
  	var src = fmt.Sprintf("cmd/%s-%s/main.go", appName, variant)
  	return sh.Run("go", "build", "-o", bin, src)
  }

  // Build both applications
  func (Build) All() {
  	mg.Deps(Build.FrontEnd, Build.BackEnd)
  }

  // Run linters.
  func (Check) Lint() error {
  	fmt.Println("Run Linters.")
  	return sh.RunV("golangci-lint", "run")
  }

  // Check code quality.
  func (Check) All() {
  	mg.Deps(Check.Lint)
  }

Air will handle live reloading of the front end when we change anything, but we need to provide it with some information for that. We have to create a configuration file using air init and edit the resulting file .air.toml to capture our needs.

  root = "."
  testdata_dir = "testdata"
  tmp_dir = "tmp"

  [build]
    args_bin = []
    bin = "./target/rexlists-fe"
    cmd = "go build -o ./target/rexlists-fe cmd/rexlists-fe/main.go"
    delay = 1000
    exclude_dir = ["assets", "tmp", "vendor", "testdata"]
    exclude_file = []
    exclude_regex = ["_test.go"]
    exclude_unchanged = false
    follow_symlink = false
    full_bin = ""
    include_dir = []
    include_ext = ["go", "tpl", "tmpl", "html"]
    include_file = []
    kill_delay = "0s"
    log = "build-errors.log"
    poll = false
    poll_interval = 0
    post_cmd = []
    pre_cmd = []
    rerun = false
    rerun_delay = 500
    send_interrupt = false
    stop_on_error = false

  [color]
    app = ""
    build = "yellow"
    main = "magenta"
    runner = "green"
    watcher = "cyan"

  [log]
    main_only = false
    silent = false
    time = false

  [misc]
    clean_on_exit = false

  [proxy]
    app_port = 0
    enabled = false
    proxy_port = 0

  [screen]
    clear_on_rebuild = false
    keep_scroll = true

Our front end will have an HTTP server and an HTTP client that talks to the back end. The server sends the browser the HTML and assets needed to render and interact with the user interface. The client makes requests to the back end to access and modify the data.

First, we add a new directory named app at the root of the project to hold the front-end application code. Inside app, we create an app.go file and define a struct for the application. This struct will store the configuration and any needed dependencies.

  // Package app provides the front-end application code.
  package app

  type App struct {
  	serverAddr string
  	serverPort uint16
  }

This new type will define methods for controlling the application and contain the necessary configuration. The most obvious one would be a method for launching the HTTP server, but we also want to have a constructor function to load or set the configuration.

  func New() App {
  	var port int
  	var err error
  	if port, err = strconv.Atoi(config.GetFromEnvOrDefault("FRONTEND_PORT", "4000")); err != nil {
  		port = 4000
  	}
  	return App{
  		serverAddr: config.GetFromEnvOrDefault("FRONTEND_ADDR", "localhost"),
  		serverPort: uint16(port),
  	}
  }

  func (app *App) Start() error {
  	log.Printf("Launching RexLists front-end server: http://%s:%d\n", app.serverAddr, app.serverPort)
  	return http.ListenAndServe(fmt.Sprintf("%s:%d", app.serverAddr, app.serverPort), nil)
  }

I have chosen to use a pointer receiver –*App– instead of a value one, because the struct is going to grow and I don't want to refactor it later.

The method can now be used in the main function (in rexlists-fe/main.go), after creating an instance of the type with the constructor.

  import (
  	"log"

  	"rexlists/app"
  )

  func main() {
  	log.Println("Running front end")
  	app := app.New()
  	log.Fatal(app.Start())
  }

This should be enough to use the configuration data and run with those values or the defaults. We can try that using the following commands.

  mage bf
  target/rexlists-fe

The front-end server should be up and running and you can connect to it from the browser using the default URL http://localhost:4000/. However, your welcome message is going to be more disappointing than warm: "404 page not found". But fear not! That is expected because there is no content being served yet.

You can use a different port, though. Just run the command preceded by the corresponding environment variable and the application will use the designated port, for example 5646.

  FRONTEND_PORT=5646 target/rexlists-fe