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β
| Property | Type | Description | Default |
|---|---|---|---|
| Next | func(fiber.Ctx) bool | Skip when function returns true. | nil |
| RuleList | []Rule | Rules tried in order, first match wins; $1, $2 insert wildcard captures. | nil |
| Rules | map[string]string | Deprecated. 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.
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