Buffalo Documentation

Package buffalo is a Go web development eco-system, designed to make your life easier.

Buffalo helps you to generate a web project that already has everything from front-end (JavaScript, SCSS, etc.) to back-end (database, routing, etc.) already hooked up and ready to run. From there it provides easy APIs to build your web application quickly in Go.

Buffalo isn't just a framework, it's a holistic web development environment and project structure that lets developers get straight to the business of, well, building their business.

The initial setup command will do a deploy at the end, but after that you'll want to use the buffalo heroku deploy command to push a new version of your application, it'll even try to run your migrations for you.

Plugins can be configured via the ./config/buffalo-plugins.toml file that acts as the official list of plugins the application depends on. This is file is optional, until using the install and remove commands.

With no config file the output of buffalo plugins list and plugins.List() does not change. Once a configuration file is in place, then that file will dictate the output of those commands.

In Buffalo v0.13.1-beta.1 events are now emitted with the buffalo setup command. The buffalo-plugins command will listen for this event and install the necessary plugins for an application. When completed it will emit the plugins.EvtSetupFinished event. This event should be listened to by other plugins to run their setup commands.

The popmw.Transaction will wrap each request inside of a new database transaction and automatically commit, or rollback, based on whether or not an error was returned from an upstream buffalo.Handler or buffalo.MiddlewareFunc.

First you need to add the middleware to your application giving it access to your *pop.Connection, typically found at models.DB.

By default events implements a basic manager for you. Should you want to replace that with your own implementation, perhaps that's backed by a proper message queue, you can implement the events#Manager interface.

var _ events.Manager = MyManager{}
events.SetManager(MyManager{})

Once Buffalo is actively emitting events, plugins, will be able to listen those events via their CLIs.

To do so you can set the BuffaloCommand to events when telling Buffalo which plugin in commands are available. Buffalo will create a new listener that says the JSON version of the event to that command in question.

The first step in using Packr is to create a new box. A box represents a folder on disk. Once you have a box you can get string or []byte representations of the file.

// set up a new box by giving it a (relative) path to a folder on disk:
box := packr.NewBox("./templates")
// Get the string representation of a file, or an error if it doesn't exist:
html, err := box.FindString("index.html")
// Get the []byte representation of a file, or an error if it doesn't exist:
html, err := box.FindBytes("index.html")

A box represents a folder, and any sub-folders, on disk that you want to have access to in your binary. When compiling a binary using the packr CLI the contents of the folder will be converted into Go files that can be compiled inside of a "standard" go binary. Inside of the compiled binary the files will be read from memory. When working locally the files will be read directly off of disk. This is a seamless switch that doesn't require any special attention on your part.

Assume the follow directory structure:

├── main.go
└── templates
├── admin
│ └── index.html
└── index.html

The following program will read the ./templates/admin/index.html file and print it out.

In order to get static files into a Go binary, those files must first be converted to Go code. To do that, Packr, ships with a few tools to help build binaries. See below.

During development, however, it is painful to have to keep running a tool to compile those files.

Packr uses the following resolution rules when looking for a file:

Look for the file in-memory (inside a Go binary)

Look for the file on disk (during development)

Because Packr knows how to fall through to the file system, developers don't need to worry about constantly compiling their static files into a binary. They can work unimpeded.

Packr takes file resolution a step further. When declaring a new box you use a relative path, ./templates. When Packr receives this call it calculates out the absolute path to that directory. By doing this it means you can be guaranteed that Packr can find your files correctly, even if you're not running in the directory that the box was created in. This helps with the problem of testing, where Go changes the pwd for each package, making relative paths difficult to work with. This is not a problem when using Packr.

A box implements the http.FileSystem interface, meaning it can be used to serve static files.

When it comes time to build, or install, your Go binary, simply use packr build or packr install just as you would go build or go install. All flags for the go tool are supported and everything works the way you expect, the only difference is your static assets are now bundled in the generated binary. If you want more control over how this happens, looking at the following section on building binaries (the hard way).

Before you build your Go binary, run the packr command first. It will look for all the boxes in your code and then generate .go files that pack the static files into bytes that can be bundled into the Go binary.

$ packr

Then run your go build command like normal.

NOTE: It is not recommended to check-in these generated -packr.go files. They can be large, and can easily become out of date if not careful. It is recommended that you always run packr clean after running the packr tool.

When you're done it is recommended that you run the packr clean command. This will remove all of the generated files that Packr created for you.

$ packr clean

Why do you want to do this? Packr first looks to the information stored in these generated files, if the information isn't there it looks to disk. This makes it easy to work with in development.

When it comes to building multiple releases you typically want that release to be built in a specific directory.

For example: ./releases

However, because passing a .go file requires absolute paths, we must compile the release in the appropriate absolute path.

GOOS=linux GOARCH=amd64 packr build

Now your project_name binary will be built at the root of your project dir. Great!

All that is left to do is to move that binary to your release dir:

Linux/macOS/Windows (bash)

mv ./project_name ./releases

Windows (cmd):

move ./project_name ./releases

Powershell:

Move-Item -Path .\project_name -Destination .\releases\

If you target for Windows when building don't forget that it's project_name.exe

Now you can make multiple releases and all of your needed static files will be available!

The packr command passes all arguments down to the underlying go command, this includes the -v flag to print out go build information. Packr looks for the -v flag, and will turn on its own verbose logging. This is very useful for trying to understand what the packr command is doing when it is run.

Often it is useful to load a series of data into the database at the start of the test to make testing easier. For example, you need to have a user in the database to log a person into the application, or you need some data in the database to test destroying that data. Fixtures let us solve these problems easily.

First you need to setup your test suite to use fixtures. You can do this by using suite.NewActionWithFixtures or suite.NewModelWithFixtures methods to create new test suites that take a packd.Box pointing to where the files for this suite live.

Easily build HTML tags in Go! This package is especially useful when using http://gobuffalo.io.

Tags has a minimum Go dependency of 1.8.1.

To get this lib just get it via go get

go get -u -v github.com/gobuffalo/tags/...

In order to run the tests just do it with a regular

go test ./...

Documentation is currently in this repository Wiki, you can find there instructions on how to use tags within your app.

If you want to contribute, please read this article first: Contributing to Open Source Git Repositories in Go. It shows how to configure your git environment to avoid common pitfalls. This article is recommended to all those who are looking to contribute to any Go projects.

In the previous example I wrote a single Validator for the User struct. To really get the benefit of using go-validator, as well as the Go language, I would recommend creating distinct validators for each thing you want to validate, that way they can be run concurrently.

Grift is a very simple library that allows you to write simple "task" scripts in Go and run them by name without having to write big main type of wrappers. Grift is similar to, and inspired by, Rake.

Excellent question! When building applications there comes a point where you need different scripts to do different things. For example, you might want a script to seed your database, or perhaps a script to parse some logs, etc...

Grift lets you write these scripts using Go in a really simple and extensible way.

Installation is really easy using go get.

$ go get github.com/markbates/grift

You can confirm the installation by running:

$ grift jim

Apart from having the binary installed, the only other requirement is that the package you place your grifts in is called grifts. That's it.

By running the following command:

$ grift init

When you run the init sub-command Grift will generate a new grifts package and create a couple of simple grifts for you.

$ grift list

$ grift hello

That's really it! Grift is meant to be simple. Write your grifts, use the full power of Go to do it.