README

Flamingo Framework

Go Report Card GoDoc Tests Release TODOs

Flamingo is a web framework based on Go.
It is designed to build pluggable and maintainable web projects. It is production ready, field tested and has a growing ecosystem.

Quick start

See "examples/hello-world"

Initialize an empty project:

mkdir helloworld
cd helloworld
go mod init helloworld

Create your project main file:

cat main.go
package main

import (
	"flamingo.me/dingo"
	"flamingo.me/flamingo/v3"
)

func main() {
	flamingo.App([]dingo.Module{
	})
}

If you then start your project you will see a list of registered commands:

go run main.go

It will print something like:

Flamingo main

Usage:
  main [command]

Examples:
Run with -h or -help to see global debug flags

Available Commands:
  config      Config dump
  handler     Dump the Handlers and its registered methods
  help        Help about any command
  routes      Routes dump
  serve       Default serve command - starts on Port 3322

Flags:
  -h, --help   help for main

Use "main [command] --help" for more information about a command.

To start the server use the following sub command:

go run main.go serve

And open http://localhost:3322

Hello World Example:

To extend this empty flamingo project with a "Hello World" output please create a new module "helloworld" like this:

mkdir helloworld
cat helloworld/module.go

With the following code in module.go:

package helloworld

import (
        "context"
        "net/http"
        "strings"
        
        "flamingo.me/dingo"
        "flamingo.me/flamingo/v3/framework/web"
)

type Module struct{}

func (*Module) Configure(injector *dingo.Injector) {
        web.BindRoutes(injector, new(routes))
}

type routes struct{}

func (*routes) Routes(registry *web.RouterRegistry) {
        registry.Route("/", "home")
        registry.HandleAny("home", indexHandler)
}

func indexHandler(ctx context.Context, req *web.Request) web.Result {
        return &web.Response{
            Status: http.StatusOK,
            Body:   strings.NewReader("Hello World!"),
        }
}

This file now defines a very simple module, that can be used in the Flamingo bootstrap. In this case it registers a new handler that renders a simple "Hello World" message and binds the route "/" to this handler. Now please include this new module in your existing main.go file:

package main

import (
	"flamingo.me/dingo"
	"flamingo.me/flamingo/v3"
	"helloworld/helloworld"
)

func main() {
	flamingo.App([]dingo.Module{
        new(helloworld.Module),
	})
}

If you now run the server again

go run main.go serve

And open http://localhost:3322 you will see your "Hello World!" output.

Getting started

To learn more about Flamingo you can check out the full hello-world example tutorial and read the documentation under docs.flamingo.me

Getting Help

If you need help you can:

Framework Details

Feature List

  • dependency injection with Dingo
  • Flexible templating engines. (gotemplates and pugtemplates)
  • configuration concepts using cue with support for multiple config areas and additional config contexts
  • A module concept for building modular and pluggable applications based on Dingo
  • Authentication concepts and security middleware
  • Flexible routing with support for prefix routes and reverse routing
  • Web controller concept with request/response abstraction; form handling etc
  • Operational readiness: logging, (distributed) tracing, metrics and healthchecks with separate endpoint
  • Localisation support
  • Commands using Cobra
  • Event handling
  • Sessionhandling and Management (By default uses Gorilla)

Ecosystem

  • GraphQL Module (and therefore support to build SPA and PWAs on top of it)
  • Caching modules providing resilience and caching for external APIs calls.
  • pugtemplate template engine for server side rendering with the related frontend tooling Flamingo Carotene
  • Flamingo Commerce is an active projects that offer rich and flexible features to build modern e-commerce applications.
Expand ▾ Collapse ▴

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func App

func App(modules []dingo.Module, options ...ApplicationOption)

    App is the default app-runner for flamingo

    Types

    type Application

    type Application struct {
    	// contains filtered or unexported fields
    }

      Application contains a main flamingo application

      func NewApplication

      func NewApplication(modules []dingo.Module, options ...ApplicationOption) (*Application, error)

        NewApplication loads a new application for running the Flamingo application with the given modules, loaded configs etc

        func (*Application) ConfigArea

        func (app *Application) ConfigArea() *config.Area

          ConfigArea returns the initialized configuration area

          func (*Application) Run

          func (app *Application) Run() error

            Run runs the Root Cmd and triggers the standard event

            type ApplicationOption

            type ApplicationOption func(config *Application)

              ApplicationOption configures an Application

              func ChildAreas

              func ChildAreas(areas ...*config.Area) ApplicationOption

                ChildAreas allows to define additional config areas for roots

                func ConfigDir

                func ConfigDir(configdir string) ApplicationOption

                  ConfigDir configuration ApplicationOption

                  func DefaultContext

                  func DefaultContext(name string) ApplicationOption

                    DefaultContext for flamingo to start with

                    func SetEagerSingletons

                    func SetEagerSingletons(enabled bool) ApplicationOption

                      SetEagerSingletons controls if eager singletons will be created

                      func WithArgs

                      func WithArgs(args ...string) ApplicationOption

                        WithArgs sets the initial arguments different than os.Args[1:]

                        func WithRoutes

                        func WithRoutes(routesModule web.RoutesModule) ApplicationOption

                          WithRoutes configures a given RoutesModule for usage in the flamingo app

                          Source Files

                          Directories

                          Path Synopsis
                          core
                          healthcheck
                          Package healthcheck provides a healthcheck endpoint under the default route /status/healthcheck Usage: Register your own Status via Dingo: injector.BindMap(new(healthcheck.Status), "yourServiceName").To(yourServiceNameApi.Status{})
                          Package healthcheck provides a healthcheck endpoint under the default route /status/healthcheck Usage: Register your own Status via Dingo: injector.BindMap(new(healthcheck.Status), "yourServiceName").To(yourServiceNameApi.Status{})
                          zap
                          examples
                          Package framework provides the most necessary basics, such as - service_locator - router - web (including context and response) - web/responder Additionally it provides a router at /_flamingo/json/{handler} for convenient access to DataControllers Additionally it registers two template functions, `get(...)` and `url(...)`
                          Package framework provides the most necessary basics, such as - service_locator - router - web (including context and response) - web/responder Additionally it provides a router at /_flamingo/json/{handler} for convenient access to DataControllers Additionally it registers two template functions, `get(...)` and `url(...)`
                          cmd
                          config
                          Package config provides supporting code for multi-tenant setups
                          Package config provides supporting code for multi-tenant setups
                          web