# Negroni [](http://godoc.org/github.com/codegangsta/negroni) [](https://app.wercker.com/project/bykey/13688a4a94b82d84a0b8d038c4965b61) [](https://codebeat.co/projects/github-com-codegangsta-negroni)
Negroni is an idiomatic approach to web middleware in Go. It is tiny, non-intrusive, and encourages use of `net/http` Handlers.
If you like the idea of [Martini ](https://github.com/go-martini/martini ), but you think it contains too much magic, then Negroni is a great fit.
Language Translations:
* [Português Brasileiro (pt_BR) ](translations/README_pt_br.md )
* [繁體中文 (zh_tw) ](translations/README_zh_tw.md )
* [简体中文 (zh_cn) ](translations/README_zh_cn.md )
* [German (de_DE) ](translations/README_de_de.md )
## Getting Started
After installing Go and setting up your
[GOPATH ](http://golang.org/doc/code.html#GOPATH ), create your first `.go` file.
We'll call it `server.go` .
~~~ go
package main
import (
"github.com/codegangsta/negroni"
"net/http"
"fmt"
)
func main() {
mux := http.NewServeMux()
mux.HandleFunc("/", func(w http.ResponseWriter, req *http.Request) {
fmt.Fprintf(w, "Welcome to the home page!")
})
n := negroni.Classic() // Includes some default middlewares
n.UseHandler(mux)
http.ListenAndServe(":3000", n)
}
~~~
Then install the Negroni package (**go 1.1** and greater is required):
~~~
go get github.com/codegangsta/negroni
~~~
Then run your server:
~~~
go run server.go
~~~
You will now have a Go net/http webserver running on `localhost:3000` .
## Need Help?
If you have a question or feature request, [go ask the mailing list ](https://groups.google.com/forum/#!forum/negroni-users ). The GitHub issues for Negroni will be used exclusively for bug reports and pull requests.
## Is Negroni a Framework?
Negroni is **not** a framework. It is a library that is designed to work directly with net/http.
## Routing?
Negroni is BYOR (Bring your own Router). The Go community already has a number of great http routers available, Negroni tries to play well with all of them by fully supporting `net/http` . For instance, integrating with [Gorilla Mux ](https://github.com/gorilla/mux ) looks like so:
~~~ go
router := mux.NewRouter()
router.HandleFunc("/", HomeHandler)
n := negroni.New(Middleware1, Middleware2)
// Or use a middleware with the Use() function
n.Use(Middleware3)
// router goes last
n.UseHandler(router)
http.ListenAndServe(":3000", n)
~~~
## `negroni.Classic()`
`negroni.Classic()` provides some default middleware that is useful for most applications:
* `negroni.Recovery` - Panic Recovery Middleware.
* `negroni.Logger` - Request/Response Logger Middleware.
* `negroni.Static` - Static File serving under the "public" directory.
This makes it really easy to get started with some useful features from Negroni.
## Handlers
Negroni provides a bidirectional middleware flow. This is done through the `negroni.Handler` interface:
~~~ go
type Handler interface {
ServeHTTP(rw http.ResponseWriter, r *http.Request, next http.HandlerFunc)
}
~~~
If a middleware hasn't already written to the ResponseWriter, it should call the next `http.HandlerFunc` in the chain to yield to the next middleware handler. This can be used for great good:
~~~ go
func MyMiddleware(rw http.ResponseWriter, r *http.Request, next http.HandlerFunc) {
// do some stuff before
next(rw, r)
// do some stuff after
}
~~~
And you can map it to the handler chain with the `Use` function:
~~~ go
n := negroni.New()
n.Use(negroni.HandlerFunc(MyMiddleware))
~~~
You can also map plain old `http.Handler` s:
~~~ go
n := negroni.New()
mux := http.NewServeMux()
// map your routes
n.UseHandler(mux)
http.ListenAndServe(":3000", n)
~~~
## `Run()`
Negroni has a convenience function called `Run` . `Run` takes an addr string
identical to
[http.ListenAndServe ](http://golang.org/pkg/net/http#ListenAndServe ).
~~~ go
n := negroni.Classic()
n.Run(":8080")
~~~
In general, you will want to use `net/http` methods and just pass `negroni` has
a handler as this is more flexible.
E.g.
~~~ go
mux := http.NewServeMux()
mux.HandleFunc("/", func(w http.ResponseWriter, req *http.Request) {
fmt.Fprintf(w, "Welcome to the home page!")
})
n := negroni.Classic() // Includes some default middlewares
n.UseHandler(mux)
s := & http.Server{
Addr: ":8080",
Handler: n,
ReadTimeout: 10 * time.Second,
WriteTimeout: 10 * time.Second,
MaxHeaderBytes: 1 < < 20 ,
}
log.Fatal(s.ListenAndServe())
~~~
## Route Specific Middleware
If you have a route group of routes that need specific middleware to be executed, you can simply create a new Negroni instance and use it as your route handler.
~~~ go
router := mux.NewRouter()
adminRoutes := mux.NewRouter()
// add admin routes here
// Create a new negroni for the admin middleware
router.PathPrefix("/admin").Handler(negroni.New(
Middleware1,
Middleware2,
negroni.Wrap(adminRoutes),
))
~~~
If you are using [Gorilla Mux ](http://github.com/gorilla/mux ) here is an example using a subrouter.
~~~go
router := mux.NewRouter()
subRouter := mux.NewRouter().PathPrefix("/subpath").Subrouter().StrictSlash(true)
subRouter.HandleFunc("/", someSubpathHandler) // "/subpath/"
subRouter.HandleFunc("/:id", someSubpathHandler) // "/subpath/:id"
// "/subpath" is necessary to ensure the subRouter and main router linkup
router.PathPrefix("/subpath").Handler(negroni.New(
Middleware1,
Middleware2,
negroni.Wrap(subRouter),
))
~~~
## Third Party Middleware
Here is a current list of Negroni compatible middlware. Feel free to put up a PR linking your middleware if you have built one:
| Middleware | Author | Description |
| -----------|--------|-------------|
| [RestGate ](https://github.com/pjebs/restgate ) | [Prasanga Siripala ](https://github.com/pjebs ) | Secure authentication for REST API endpoints |
| [Graceful ](https://github.com/tylerb/graceful ) | [Tyler Bunnell ](https://github.com/tylerb ) | Graceful HTTP Shutdown |
| [secure ](https://github.com/unrolled/secure ) | [Cory Jacobsen ](https://github.com/unrolled ) | Middleware that implements a few quick security wins |
| [JWT Middleware ](https://github.com/auth0/go-jwt-middleware ) | [Auth0 ](https://github.com/auth0 ) | Middleware checks for a JWT on the `Authorization` header on incoming requests and decodes it|
| [binding ](https://github.com/mholt/binding ) | [Matt Holt ](https://github.com/mholt ) | Data binding from HTTP requests into structs |
| [logrus ](https://github.com/meatballhat/negroni-logrus ) | [Dan Buch ](https://github.com/meatballhat ) | Logrus-based logger |
| [render ](https://github.com/unrolled/render ) | [Cory Jacobsen ](https://github.com/unrolled ) | Render JSON, XML and HTML templates |
| [gorelic ](https://github.com/jingweno/negroni-gorelic ) | [Jingwen Owen Ou ](https://github.com/jingweno ) | New Relic agent for Go runtime |
| [gzip ](https://github.com/phyber/negroni-gzip ) | [phyber ](https://github.com/phyber ) | GZIP response compression |
| [oauth2 ](https://github.com/goincremental/negroni-oauth2 ) | [David Bochenski ](https://github.com/bochenski ) | oAuth2 middleware |
| [sessions ](https://github.com/goincremental/negroni-sessions ) | [David Bochenski ](https://github.com/bochenski ) | Session Management |
| [permissions2 ](https://github.com/xyproto/permissions2 ) | [Alexander Rødseth ](https://github.com/xyproto ) | Cookies, users and permissions |
| [onthefly ](https://github.com/xyproto/onthefly ) | [Alexander Rødseth ](https://github.com/xyproto ) | Generate TinySVG, HTML and CSS on the fly |
| [cors ](https://github.com/rs/cors ) | [Olivier Poitrey ](https://github.com/rs ) | [Cross Origin Resource Sharing ](http://www.w3.org/TR/cors/ ) (CORS) support |
| [xrequestid ](https://github.com/pilu/xrequestid ) | [Andrea Franz ](https://github.com/pilu ) | Middleware that assigns a random X-Request-Id header to each request |
| [VanGoH ](https://github.com/auroratechnologies/vangoh ) | [Taylor Wrobel ](https://github.com/twrobel3 ) | Configurable [AWS-Style ](http://docs.aws.amazon.com/AmazonS3/latest/dev/RESTAuthentication.html ) HMAC authentication middleware |
| [stats ](https://github.com/thoas/stats ) | [Florent Messa ](https://github.com/thoas ) | Store information about your web application (response time, etc.) |
| [prometheus ](https://github.com/zbindenren/negroni-prometheus ) | [Rene Zbinden ](https://github.com/zbindenren ) | Easily create metrics endpoint for the [prometheus ](http://prometheus.io ) instrumentation tool |
| [delay ](https://github.com/jeffbmartinez/delay ) | [Jeff Martinez ](https://github.com/jeffbmartinez ) | Add delays/latency to endpoints. Useful when testing effects of high latency |
## Examples
[Alexander Rødseth ](https://github.com/xyproto ) created [mooseware ](https://github.com/xyproto/mooseware ), a skeleton for writing a Negroni middleware handler.
## Live code reload?
[gin ](https://github.com/codegangsta/gin ) and [fresh ](https://github.com/pilu/fresh ) both live reload negroni apps.
## Essential Reading for Beginners of Go & Negroni
* [Using a Context to pass information from middleware to end handler ](http://elithrar.github.io/article/map-string-interface/ )
* [Understanding middleware ](https://mattstauffer.co/blog/laravel-5.0-middleware-filter-style )
## About
Negroni is obsessively designed by none other than the [Code Gangsta ](https://codegangsta.io/ )
