fiber/docs/api/app.md at 9b47da0b2cf7e03e49ac3d3ed8fe625be06dba60 · gofiber/fiber

id	app
title	🚀 App
description	The `App` type represents your Fiber application.
sidebar_position	2

import Reference from '@site/src/components/reference';

Helpers

GetString

Returns s unchanged when Immutable is disabled or s resides in read-only memory. Otherwise, it returns a detached copy using strings.Clone.

func (app *App) GetString(s string) string

GetBytes

Returns b unchanged when Immutable is disabled or b resides in read-only memory. Otherwise, it returns a detached copy.

func (app *App) GetBytes(b []byte) []byte

ReloadViews

Reloads the configured view engine on demand by calling its Load method. Use this helper in development workflows (e.g., file watchers or debug-only routes) to pick up template changes without restarting the server. Returns an error if no view engine is configured or reloading fails.

func (app *App) ReloadViews() error

app := fiber.New(fiber.Config{Views: engine})

app.Get("/dev/reload", func(c fiber.Ctx) error {
    if err := app.ReloadViews(); err != nil {
        return err
    }
    return c.SendString("Templates reloaded")
})

Routing

import RoutingHandler from './../partials/routing/handler.md';

Route Handlers

Mounting

Mount another Fiber instance with app.Use, similar to Express's router.use.

package main

import (
    "log"

    "github.com/gofiber/fiber/v3"
)

func main() {
    app := fiber.New()
    micro := fiber.New()

    // Mount the micro app on the "/john" route
    app.Use("/john", micro) // GET /john/doe -> 200 OK

    micro.Get("/doe", func(c fiber.Ctx) error {
        return c.SendStatus(fiber.StatusOK)
    })

    log.Fatal(app.Listen(":3000"))
}

MountPath

The MountPath property contains one or more path patterns on which a sub-app was mounted.

func (app *App) MountPath() string

package main

import (
    "fmt"

    "github.com/gofiber/fiber/v3"
)

func main() {
    app := fiber.New()
    one := fiber.New()
    two := fiber.New()
    three := fiber.New()

    two.Use("/three", three)
    one.Use("/two", two)
    app.Use("/one", one)

    fmt.Println("Mount paths:")
    fmt.Println("one.MountPath():", one.MountPath())       // "/one"
    fmt.Println("two.MountPath():", two.MountPath())       // "/one/two"
    fmt.Println("three.MountPath():", three.MountPath())   // "/one/two/three"
    fmt.Println("app.MountPath():", app.MountPath())       // ""
}

:::caution Mounting order is important for MountPath. To get mount paths properly, you should start mounting from the deepest app. :::

Group

You can group routes by creating a *Group struct.

func (app *App) Group(prefix string, handlers ...any) Router

package main

import (
    "log"

    "github.com/gofiber/fiber/v3"
)

func main() {
    app := fiber.New()

    api := app.Group("/api", handler)  // /api

    v1 := api.Group("/v1", handler)    // /api/v1
    v1.Get("/list", handler)           // /api/v1/list
    v1.Get("/user", handler)           // /api/v1/user

    v2 := api.Group("/v2", handler)    // /api/v2
    v2.Get("/list", handler)           // /api/v2/list
    v2.Get("/user", handler)           // /api/v2/user

    log.Fatal(app.Listen(":3000"))
}

func handler(c fiber.Ctx) error {
    return c.SendString("Handler response")
}

RouteChain

Returns an instance of a single route, which you can then use to handle HTTP verbs with optional middleware.

Similar to Express.

func (app *App) RouteChain(path string) Register

Click here to see the `Register` interface

type Register interface {
    All(handler any, handlers ...any) Register
    Get(handler any, handlers ...any) Register
    Head(handler any, handlers ...any) Register
    Post(handler any, handlers ...any) Register
    Put(handler any, handlers ...any) Register
    Delete(handler any, handlers ...any) Register
    Connect(handler any, handlers ...any) Register
    Options(handler any, handlers ...any) Register
    Trace(handler any, handlers ...any) Register
    Patch(handler any, handlers ...any) Register

    Add(methods []string, handler any, handlers ...any) Register

    RouteChain(path string) Register
}

package main

import (
    "log"

    "github.com/gofiber/fiber/v3"
)

func main() {
    app := fiber.New()

    // Use `RouteChain` as a chainable route declaration method
    app.RouteChain("/test").Get(func(c fiber.Ctx) error {
        return c.SendString("GET /test")
    })

    app.RouteChain("/events").All(func(c fiber.Ctx) error {
        // Runs for all HTTP verbs first
        // Think of it as route-specific middleware!
    }).
    Get(func(c fiber.Ctx) error {
        return c.SendString("GET /events")
    }).
    Post(func(c fiber.Ctx) error {
        // Maybe add a new event...
        return c.SendString("POST /events")
    })

    // Combine multiple routes
    app.RouteChain("/reports").RouteChain("/daily").Get(func(c fiber.Ctx) error {
        return c.SendString("GET /reports/daily")
    })

    // Use multiple methods
    app.RouteChain("/api").Get(func(c fiber.Ctx) error {
        return c.SendString("GET /api")
    }).Post(func(c fiber.Ctx) error {
        return c.SendString("POST /api")
    })

    log.Fatal(app.Listen(":3000"))
}

Route

Defines routes with a common prefix inside the supplied function. Internally it uses Group to create a sub-router and accepts an optional name prefix.

func (app *App) Route(prefix string, fn func(router Router), name ...string) Router

app.Route("/test", func(api fiber.Router) {
    api.Get("/foo", handler).Name("foo") // /test/foo (name: test.foo)
    api.Get("/bar", handler).Name("bar") // /test/bar (name: test.bar)
}, "test.")

Domain

Creates a router scoped to a specific hostname pattern. Routes registered through the returned Router only match requests whose hostname (from c.Hostname()) matches the pattern. Domain names are matched case-insensitively per RFC 4343.

When TrustProxy is enabled and the proxy is trusted, the hostname may be derived from the X-Forwarded-Host header instead of the Host header. To prevent header spoofing, you must both enable TrustProxy and configure TrustProxyConfig with the IPs or ranges of your trusted proxies. See the TrustProxy documentation for details.

The pattern can contain parameters prefixed with :. Use DomainParam to retrieve them inside handlers.

Domain routing has zero performance impact on routes that don't use it — the hostname check is applied as a handler wrapper, not a change to the core router.

:::note Because domain filtering is applied at handler-execution time (not during route matching), Fiber's 405 Method Not Allowed logic may advertise methods from domain-scoped routes even when the requesting host does not match the domain pattern. This is a known trade-off of the handler-wrapping approach — it avoids core router changes while keeping non-domain routes unaffected. :::

:::note When mounting sub-applications via Domain(...).Use(*fiber.App), routes are cloned from the sub-app at mount time. This means the same sub-app can safely be mounted on multiple domains without double-wrapping, but routes registered on the sub-app after mounting will not inherit domain filtering. Register all sub-app routes before mounting. :::

func (app *App) Domain(host string) Router

package main

import (
    "log"

    "github.com/gofiber/fiber/v3"
)

func main() {
    app := fiber.New()

    // Static domain — only matches requests to api.example.com
    app.Domain("api.example.com").Get("/users", func(c fiber.Ctx) error {
        return c.SendString("API users list")
    })

    // Domain with parameter
    app.Domain(":user.blog.example.com").Get("/", func(c fiber.Ctx) error {
        user := fiber.DomainParam(c, "user")
        return c.SendString(user + "'s blog")
    })

    // Composable with groups and middleware
    admin := app.Domain("admin.example.com")
    admin.Use(func(c fiber.Ctx) error {
        // Only runs for admin.example.com
        c.Set("X-Admin", "true")
        return c.Next()
    })
    admin.Get("/dashboard", func(c fiber.Ctx) error {
        return c.SendString("Admin Dashboard")
    })

    // Mount sub-applications on domain routers
    subApp := fiber.New()
    subApp.Get("/users", func(c fiber.Ctx) error {
        return c.SendString("Users list")
    })
    app.Domain("api.example.com").Use("/api", subApp)

    // Fallback for unmatched domains
    app.Get("/", func(c fiber.Ctx) error {
        return c.SendString("Default site")
    })

    log.Fatal(app.Listen(":3000"))
}

DomainParam

Returns the value of a domain parameter captured by a Domain pattern. If the key is not found, the optional default value is returned.

func DomainParam(c Ctx, key string, defaultValue ...string) string

// Pattern: ":tenant.example.com"
// Request Host: acme.example.com

app.Domain(":tenant.example.com").Get("/", func(c fiber.Ctx) error {
    tenant := fiber.DomainParam(c, "tenant")           // "acme"
    missing := fiber.DomainParam(c, "missing", "none") // "none"
    return c.SendString(tenant + " " + missing)
})

HandlersCount

Returns the number of registered handlers.

func (app *App) HandlersCount() uint32

Stack

Returns the underlying router stack.

func (app *App) Stack() [][]*Route

package main

import (
    "encoding/json"
    "log"

    "github.com/gofiber/fiber/v3"
)

var handler = func(c fiber.Ctx) error { return nil }

func main() {
    app := fiber.New()

    app.Get("/john/:age", handler)
    app.Post("/register", handler)

    data, _ := json.MarshalIndent(app.Stack(), "", "  ")
    fmt.Println(string(data))

    log.Fatal(app.Listen(":3000"))
}

Click here to see the result

[
  [
    {
      "method": "GET",
      "path": "/john/:age",
      "params": [
        "age"
      ]
    }
  ],
  [
    {
      "method": "HEAD",
      "path": "/john/:age",
      "params": [
        "age"
      ]
    }
  ],
  [
    {
      "method": "POST",
      "path": "/register",
      "params": null
    }
  ]
]

Name

This method assigns the name to the latest created route.

func (app *App) Name(name string) Router

package main

import (
    "encoding/json"
    "fmt"
    "log"

    "github.com/gofiber/fiber/v3"
)

func main() {
    var handler = func(c fiber.Ctx) error { return nil }

    app := fiber.New()

    app.Get("/", handler)
    app.Name("index")
    app.Get("/doe", handler).Name("home")
    app.Trace("/tracer", handler).Name("tracert")
    app.Delete("/delete", handler).Name("delete")

    a := app.Group("/a")
    a.Name("fd.")

    a.Get("/test", handler).Name("test")

    data, _ := json.MarshalIndent(app.Stack(), "", "  ")
    fmt.Println(string(data))

    log.Fatal(app.Listen(":3000"))
}

Click here to see the result

[
  [
    {
      "method": "GET",
      "name": "index",
      "path": "/",
      "params": null
    },
    {
      "method": "GET",
      "name": "home",
      "path": "/doe",
      "params": null
    },
    {
      "method": "GET",
      "name": "fd.test",
      "path": "/a/test",
      "params": null
    }
  ],
  [
    {
      "method": "HEAD",
      "name": "",
      "path": "/",
      "params": null
    },
    {
      "method": "HEAD",
      "name": "",
      "path": "/doe",
      "params": null
    },
    {
      "method": "HEAD",
      "name": "",
      "path": "/a/test",
      "params": null
    }
  ],
  null,
  null,
  [
    {
      "method": "DELETE",
      "name": "delete",
      "path": "/delete",
      "params": null
    }
  ],
  null,
  null,
  [
    {
      "method": "TRACE",
      "name": "tracert",
      "path": "/tracer",
      "params": null
    }
  ],
  null
]

GetRoute

This method retrieves a route by its name.

The returned Route can be inspected or used to generate a URL directly with route.URL(params).

func (app *App) GetRoute(name string) Route

package main

import (
    "encoding/json"
    "fmt"
    "log"

    "github.com/gofiber/fiber/v3"
)

func main() {
    app := fiber.New()

    app.Get("/", handler).Name("index")
    app.Get("/user/:name/:id", handler).Name("user")

    route := app.GetRoute("index")

    data, _ := json.MarshalIndent(route, "", "  ")
    fmt.Println(string(data))

    userRoute := app.GetRoute("user")
    location, _ := userRoute.URL(fiber.Map{"name": "john", "id": 1})
    fmt.Println(location) // /user/john/1

    log.Fatal(app.Listen(":3000"))
}

Click here to see the result

{
  "method": "GET",
  "name": "index",
  "path": "/",
  "params": null
}

GetRoutes

This method retrieves all routes.

func (app *App) GetRoutes(filterUseOption ...bool) []Route

When filterUseOption is set to true, it filters out routes registered by middleware.

package main

import (
    "encoding/json"
    "fmt"
    "log"

    "github.com/gofiber/fiber/v3"
)

func main() {
    app := fiber.New()

    app.Post("/", func(c fiber.Ctx) error {
        return c.SendString("Hello, World!")
    }).Name("index")

    routes := app.GetRoutes(true)

    data, _ := json.MarshalIndent(routes, "", "  ")
    fmt.Println(string(data))

    log.Fatal(app.Listen(":3000"))
}

Click here to see the result

[
    {
        "method": "POST",
        "name": "index",
        "path": "/",
        "params": null
    }
]

Config

Config returns the app config as a value (read-only).

func (app *App) Config() Config

Handler

Handler returns the server handler that can be used to serve custom \*fasthttp.RequestCtx requests.

func (app *App) Handler() fasthttp.RequestHandler

ErrorHandler

ErrorHandler executes the process defined for the application in case of errors. This is used in some cases in middlewares.

func (app *App) ErrorHandler(ctx Ctx, err error) error

NewWithCustomCtx

NewWithCustomCtx creates a new *App and sets the custom context factory function at construction time.

func NewWithCustomCtx(fn func(app *App) CustomCtx, config ...Config) *App

package main

import (
    "log"

    "github.com/gofiber/fiber/v3"
)

type CustomCtx struct {
    fiber.DefaultCtx
}

func (c *CustomCtx) Params(key string, defaultValue ...string) string {
    return "prefix_" + c.DefaultCtx.Params(key)
}

func main() {
    app := fiber.NewWithCustomCtx(func(app *fiber.App) fiber.CustomCtx {
        return &CustomCtx{
            DefaultCtx: *fiber.NewDefaultCtx(app),
        }
    })

    app.Get("/:id", func(c fiber.Ctx) error {
        return c.SendString(c.Params("id"))
    })

    log.Fatal(app.Listen(":3000"))
}

RegisterCustomBinder

You can register custom binders to use with Bind().Custom("name"). They should be compatible with the CustomBinder interface.

func (app *App) RegisterCustomBinder(binder CustomBinder)

package main

import (
    "log"

    "github.com/gofiber/fiber/v3"
    "gopkg.in/yaml.v2"
)

type User struct {
    Name string `yaml:"name"`
}

type customBinder struct{}

func (*customBinder) Name() string {
    return "custom"
}

func (*customBinder) MIMETypes() []string {
    return []string{"application/yaml"}
}

func (*customBinder) Parse(c fiber.Ctx, out any) error {
    // Parse YAML body
    return yaml.Unmarshal(c.Body(), out)
}

func main() {
    app := fiber.New()

    // Register custom binder
    app.RegisterCustomBinder(&customBinder{})

    app.Post("/custom", func(c fiber.Ctx) error {
        var user User
        // Use Custom binder by name
        if err := c.Bind().Custom("custom", &user); err != nil {
            return err
        }
        return c.JSON(user)
    })

    app.Post("/normal", func(c fiber.Ctx) error {
        var user User
        // Custom binder is used by the MIME type
        if err := c.Bind().Body(&user); err != nil {
            return err
        }
        return c.JSON(user)
    })

    log.Fatal(app.Listen(":3000"))
}

RegisterCustomConstraint

RegisterCustomConstraint allows you to register custom constraints.

func (app *App) RegisterCustomConstraint(constraint CustomConstraint)

See the Custom Constraint section for more information.

SetTLSHandler

Use SetTLSHandler to set ClientHelloInfo when using TLS with a Listener.

func (app *App) SetTLSHandler(tlsHandler *TLSHandler)

Test

Testing your application is done with the Test method. Use this method for creating _test.go files or when you need to debug your routing logic. The default timeout is 1s; to disable a timeout altogether, pass a TestConfig struct with Timeout: 0.

func (app *App) Test(req *http.Request, config ...TestConfig) (*http.Response, error)

package main

import (
    "fmt"
    "io"
    "log"
    "net/http"
    "net/http/httptest"

    "github.com/gofiber/fiber/v3"
)

func main() {
    app := fiber.New()

    // Create route with GET method for test:
    app.Get("/", func(c fiber.Ctx) error {
        fmt.Println(c.BaseURL())              // => http://google.com
        fmt.Println(c.Get("X-Custom-Header")) // => hi
        return c.SendString("hello, World!")
    })

    // Create http.Request
    req := httptest.NewRequest("GET", "http://google.com", nil)
    req.Header.Set("X-Custom-Header", "hi")

    // Perform the test
    resp, _ := app.Test(req)

    // Do something with the results:
    if resp.StatusCode == fiber.StatusOK {
        body, _ := io.ReadAll(resp.Body)
        fmt.Println(string(body)) // => hello, World!
    }
}

If not provided, TestConfig is set to the following defaults:

config := fiber.TestConfig{
  Timeout:      time.Second,
  FailOnTimeout: true,
}

:::caution

This is not the same as supplying an empty TestConfig{} to `app.Test(), but rather be the equivalent of supplying:

cfg := fiber.TestConfig{
  Timeout:      0,
  FailOnTimeout: false,
}

This would make a Test that has no timeout.

:::

Hooks

Hooks is a method to return the hooks property.

func (app *App) Hooks() *Hooks

RebuildTree

The RebuildTree method is designed to rebuild the route tree and enable dynamic route registration. It returns a pointer to the App instance.

func (app *App) RebuildTree() *App

Note: Use this method with caution. It is not thread-safe and calling it can be very performance-intensive, so it should be used sparingly and only in development mode. Avoid using it concurrently.

Example Usage

Here’s an example of how to define and register routes dynamically:

package main

import (
    "log"

    "github.com/gofiber/fiber/v3"
)

func main() {
    app := fiber.New()

    app.Get("/define", func(c fiber.Ctx) error {
        // Define a new route dynamically
        app.Get("/dynamically-defined", func(c fiber.Ctx) error {
            return c.SendStatus(fiber.StatusOK)
        })

        // Rebuild the route tree to register the new route
        app.RebuildTree()

        return c.SendStatus(fiber.StatusOK)
    })

    log.Fatal(app.Listen(":3000"))
}

In this example, a new route is defined and then RebuildTree() is called to ensure the new route is registered and available.

RemoveRoute

This method removes a route by path. You must call the RebuildTree() method after the removal to finalize the update and rebuild the routing tree. If no methods are specified, the route will be removed for all HTTP methods defined in the app. To limit removal to specific methods, provide them as additional arguments.

func (app *App) RemoveRoute(path string, methods ...string)

package main

import (
    "log"

    "github.com/gofiber/fiber/v3"
)

func main() {
    app := fiber.New()

    app.Get("/api/feature-a", func(c fiber.Ctx) error {
           app.RemoveRoute("/api/feature", fiber.MethodGet)
           app.RebuildTree()
           // Redefine route
           app.Get("/api/feature", func(c fiber.Ctx) error {
                   return c.SendString("Testing feature-a")
           })

           app.RebuildTree()
           return c.SendStatus(fiber.StatusOK)
    })
    app.Get("/api/feature-b", func(c fiber.Ctx) error {
           app.RemoveRoute("/api/feature", fiber.MethodGet)
           app.RebuildTree()
           // Redefine route
           app.Get("/api/feature", func(c fiber.Ctx) error {
                   return c.SendString("Testing feature-b")
           })

           app.RebuildTree()
           return c.SendStatus(fiber.StatusOK)
    })

    log.Fatal(app.Listen(":3000"))
}

RemoveRouteByName

This method removes a route by name. If no methods are specified, the route will be removed for all HTTP methods defined in the app. To limit removal to specific methods, provide them as additional arguments.

func (app *App) RemoveRouteByName(name string, methods ...string)

RemoveRouteFunc

This method removes a route by function having *Route parameter. If no methods are specified, the route will be removed for all HTTP methods defined in the app. To limit removal to specific methods, provide them as additional arguments.

func (app *App) RemoveRouteFunc(matchFunc func(r *Route) bool, methods ...string)

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Helpers

GetString

GetBytes

ReloadViews

Routing

Route Handlers

Mounting

MountPath

Group

RouteChain

Route

Domain

DomainParam

HandlersCount

Stack

Name

GetRoute

GetRoutes

Config

Handler

ErrorHandler

NewWithCustomCtx

RegisterCustomBinder

RegisterCustomConstraint

SetTLSHandler

Test

Hooks

RebuildTree

Example Usage

RemoveRoute

RemoveRouteByName

RemoveRouteFunc

Uh oh!

FilesExpand file tree

app.md

Latest commit

History

app.md

File metadata and controls

Helpers

GetString

GetBytes

ReloadViews

Routing

Route Handlers

Mounting

MountPath

Group

RouteChain

Route

Domain

DomainParam

HandlersCount

Stack

Name

GetRoute

GetRoutes

Config

Handler

ErrorHandler

NewWithCustomCtx

RegisterCustomBinder

RegisterCustomConstraint

SetTLSHandler

Test

Hooks

RebuildTree

Example Usage

RemoveRoute

RemoveRouteByName

RemoveRouteFunc