Skip to main content
Version: v3.x

Rewrite

The Rewrite middleware remaps the request path using custom rules, helping with backward compatibility and cleaner URLs. Rules are tried in the order you write them and the first match wins.

Signatures​

func New(config ...Config) fiber.Handler

Config​

PropertyTypeDescriptionDefault
Nextfunc(fiber.Ctx) boolSkip when function returns true.nil
RuleList[]RuleRules tried in order, first match wins; $1, $2 insert wildcard captures.nil
Rulesmap[string]stringDeprecated. Use RuleList. A map has no order, so precedence is decided by a heuristic.nil

Set one of RuleList or Rules. With neither, the middleware rewrites nothing.

A rule's From is path text: * matches a run of any bytes but a newline, and every other byte stands for itself, so /preis-1.000-euro rewrites that path and not /preis-1X000-euro. There is no escape for a literal *.

A rule matches the whole path, trailing slash and letter case included: /old rewrites /old, but not /old/, /OLD, /old/x or /very/old.

In To, $1, $2 and so on stand for what the asterisks of From captured, in order. $10 is the tenth capture in a rule with ten or more asterisks; in a rule with fewer it reads as $1 followed by 0.

Setting both RuleList and Rules panics.

Rules match c.Path(), the path as the router normalized it, and the rewritten path goes through the same normalization. With UnescapePath that path is the decoded one, so a capture is escaped again before it is inserted: the %2e%2e that /files/%252e%252e/secret decoded to stays that name in /public/$1 rather than being decoded a second time into .. and resolving out of /public/.

A capture cannot add a . or .. segment either. {From: "/@*", To: "/users/$1"} cuts ../admin out of /@../admin, a path with no dot segment for the router to resolve, so a rewritten path holding more dot segments than To itself is not used: the next rule is tried and the path stays as it was. %2e counts as a dot there, and a backslash, %2f and %5c as a slash.

Rule order​

Rules are tried in the order you write them and the first one whose From matches answers, exactly as routes are matched. Nothing reorders a RuleList. Put the specific rules before the catch-alls:

RuleList: []rewrite.Rule{
{From: "/api/users", To: "/v2/users"}, // checked first
{From: "/api/*", To: "/v2/$1"}, // takes everything else
}

Written the other way round, /api/* answers /api/users too and the second rule never fires.

note

The deprecated Rules map has no order of its own, so Fiber sorts it: most path text before the first * wins, then most path text overall, then fewest asterisks, then the key itself. That is a rough reading of "most specific", not an exact one, so a long wildcard rule can still outrank a shorter exact one. RuleList is the exact control.

Middleware order​

After a rewrite, the request goes on to the routes registered after the middleware that match the new path. Middleware registered before it had its turn with the original path and is not run again, so register the rewrite ahead of the middleware that must see the new path, such as an auth guard for it. To run the whole chain for the new path, call RestartRouting from a handler of your own instead.

Examples​

package main

import (
"github.com/gofiber/fiber/v3"
"github.com/gofiber/fiber/v3/middleware/rewrite"
)

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

app.Use(rewrite.New(rewrite.Config{
RuleList: []rewrite.Rule{
{From: "/old", To: "/new"},
{From: "/old/*", To: "/new/$1"},
},
}))

app.Get("/new", func(c fiber.Ctx) error {
return c.SendString("Hello, World!")
})
app.Get("/new/*", func(c fiber.Ctx) error {
return c.SendString("Wildcard: " + c.Params("*"))
})

app.Listen(":3000")
}

Test​

curl http://localhost:3000/old
curl http://localhost:3000/old/hello