Categorygithub.com/gobuffalo/buffalo
modulepackage
1.1.0
Repository: https://github.com/gobuffalo/buffalo.git
Documentation: pkg.go.dev
Versions
2
Dependencies
51
Dependents
310
Files
2.3k SLOC

# README

PkgGoDev Go Report Card Open Source Helpers

Buffalo

A Go web development eco-system, designed to make your project easier.

Buffalo helps you to generate a web project that already has everything from front-end (JavaScript, SCSS, etc.) to the 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.

I :heart: web dev in go again - Brian Ketelsen

Versions

The current stable version of Buffalo core is v1 (v1 branch).

Versions (branches):

  • main is for the current mainstream development.
  • v1 is the current stable release.

⚠️ Important

Buffalo works only with Go modules. GOPATH mode is likely to break most of the functionality of the Buffalo eco-system. Please see this blog post for more information.

Also, the Buffalo team actively gives support to the last 2 versions of Go, which at the moment are:

  • 1.16.x
  • 1.17.x

While Buffalo may work on older versions, we encourage you to upgrade to latest 2 versions of Go for a better development experience.

Documentation

Please visit http://gobuffalo.io for the latest documentation, examples, and more.

Quick Start

Shoulders of Giants

Buffalo would not be possible if not for all of the great projects it depends on. Please see SHOULDERS.md to see a list of them.

Templating

github.com/gobuffalo/plush - This templating package was chosen over the standard Go html/template package for a variety of reasons. The biggest of which is that it is significantly more flexible and easy to work with.

Routing

github.com/gorilla/mux - This router was chosen because of its stability and flexibility. There might be faster routers out there, but this one is definitely the most powerful!

Task Runner (Optional)

github.com/markbates/grift - If you're familiar with Rake tasks from Ruby, you'll be right at home using Grift. This package was chosen to allow for the easy running of simple, and common, tasks that most web applications need. Think things like seeding a database or taking in a CSV file and generating database records. Buffalo ships with an example routes task that prints of the defined routes and the function that handles those requests.

Models/ORM (Optional)

github.com/gobuffalo/pop - Accessing databases is nothing new in web applications. Pop, and its command line tool, Soda, were chosen because they strike a nice balance between simplifying common tasks, being idiomatic, and giving you the flexibility you need to build your app. Pop and Soda share the same core philosophies as Buffalo, so they were a natural choice.

Sessions, Cookies, WebSockets, and more

github.com/gorilla - The Gorilla toolkit is a great set of packages designed to improve upon the standard library for a variety of web-related packages. With these high-quality packages Buffalo can keep its "core" code to a minimum and focus on its goal of gluing them all together to make your life better.

Benchmarks

Oh, yeah, everyone wants benchmarks! What would a web framework be without its benchmarks? Well, guess what? I'm not giving you any! That's right. This is Go! I assure you that it is plenty fast enough for you. If you want benchmarks you can either a) check out any benchmarks that the GIANTS Buffalo is built upon having published, or b) run your own. I have no interest in playing the benchmark game, and neither should you.

Contributing

First, thank you so much for wanting to contribute! It means so much that you care enough to want to contribute. We appreciate every PR from the smallest of typos to the be biggest of features.

Here are the core rules to respect:

  • If you have any question, please consider using the Slack channel (-#buffalo-, #buffalo_fr or #buffalo-dev for contribution related questions) or Stack Overflow. We use GitHub issues for bug reports and feature requests only.
  • All contributors of this project are working on their free time: be patient and kind. :-
  • Consider opening an issue BEFORE creating a Pull request (PR): you won't lose your time on fixing non-existing bugs, or fixing the wrong bug. Also we can help you to produce the best PR!
  • Open a PR against the main branch if your PR is for mainstream or version specific branch e.g. v1 if your PR is for specific version. Note that the valid branch for a new feature request PR should be main while a PR against a version specific branch are allowed only for bugfixes.

For the full contribution guidelines, please read CONTRIBUTING.

# Packages

# Functions

Grifts decorates the app with tasks.
LoadPlugins will add listeners for any plugins that support "events".
MethodOverride is the default implementation for the Options#MethodOverride.
New returns a new instance of App and adds some sane, and useful, defaults.
NewFS returns a new FS that wraps the given directory and embedded FS.
NewOptions returns a new Options instance with sensible defaults.
RequestLoggerFunc is the default implementation of the RequestLogger.
WrapBuffaloHandler wraps a buffalo.Handler to a standard http.Handler NOTE: A buffalo Handler expects a buffalo Context.
WrapBuffaloHandlerFunc wraps a buffalo.Handler to a standard http.HandlerFunc NOTE: A buffalo Handler expects a buffalo Context.
WrapHandler wraps a standard http.Handler and transforms it into a buffalo.Handler.
WrapHandlerFunc wraps a standard http.HandlerFunc and transforms it into a buffalo.Handler.

# Constants

AssetsAgeVarName is the ENV variable used to specify max age when ServeFiles is used.
EvtAppStart is emitted when buffalo.App#Serve is called.
EvtAppStartErr is emitted when an error occurs calling buffalo.App#Serve.
EvtAppStop is emitted when buffalo.App#Stop is called.
EvtAppStopErr is emitted when an error occurs calling buffalo.App#Stop.
EvtFailureErr is emitted when something can't be processed at all.
EvtRouteErr is emitted when there is a problem handling processing a route.
EvtRouteFinished is emitted when a requested route is completed.
EvtRouteStarted is emitted when a requested route is being processed.
EvtServerStart is emitted when buffalo is about to start servers.
EvtServerStartErr is emitted when an error occurs when starting servers.
EvtServerStop is emitted when buffalo is about to stop servers.
EvtServerStopErr is emitted when an error occurs when stopping servers.
EvtWorkerStart is emitted when buffalo is about to start workers.
EvtWorkerStartErr is emitted when an error occurs when starting workers.
EvtWorkerStop is emitted when buffalo is about to stop workers.
EvtWorkerStopErr is emitted when an error occurs when stopping workers.

# Variables

RequestLogger can be be overridden to a user specified function that can be used to log the request.

# Structs

App is where it all happens! It holds on to options, the underlying router, the middleware, and more.
BaseResource fills in the gaps for any Resource interface functions you don't want/need to implement.
Cookies allows you to easily get cookies from the request, and set cookies on the response.
DefaultContext is, as its name implies, a default implementation of the Context interface.
ErrorResponse is a used to display errors as JSON or XML.
Flash is a struct that helps with the operations over flash messages.
FS wraps a directory and an embed FS that are expected to have the same contents.
Home is a container for Domains and Groups that independently serves a group of pages with its own Middleware and ErrorHandlers.
HTTPError a typed error returned by http Handlers and used for choosing error handlers.
MiddlewareStack manages the middleware stack for an App/Group.
Options are used to configure and define how your application should run.
Response implements the http.ResponseWriter interface and allows for the capture of the response status and size to be used for things like logging requests.
RouteInfo provides information about the underlying route that was built.
Session wraps the "github.com/gorilla/sessions" API in something a little cleaner and a bit more useable.

# Interfaces

Context holds on to information as you pass it down through middleware, Handlers, templates, etc..
Middler can be implemented to specify additional middleware specific to the resource.
ParamValues will most commonly be url.Values, but isn't it great that you set your own? :).
Resource interface allows for the easy mapping of common RESTful actions to a set of paths.
RouteNamer is in charge of naming a route from the path assigned, this name typically will be used if no name is assined with .Name(...).

# Type aliases

ErrorHandler interface for handling an error for a specific status code.
ErrorHandlers is used to hold a list of ErrorHandler types that can be used to handle specific status codes.
Handler is the basis for all of Buffalo.
Logger interface is used throughout Buffalo apps to log a whole manner of things.
MiddlewareFunc defines the interface for a piece of Buffalo Middleware.
PreWare takes an http.Handler and returns an http.Handler and acts as a pseudo-middleware between the http.Server and a Buffalo application.
RouteHelperFunc represents the function that takes the route and the opts and build the path.
RouteList contains a mapping of the routes defined in the application.