[[rewrites]]

Serve another route under the requested URL: the browser keeps its address, routing and the cache see the target.

[[rewrites]]
from = "/latest"
to = "/posts/newest"

Reference

Behavior

• The request is routed as if the client had asked for to: the page, its getServerSideProps and the page cache key all use the target path. The query string is kept.
• Rewrites run after guards and redirects, and the first matching rule wins (gio.toml before middleware.ts).
• Guards and [[headers]] rules match the requested path, not the target: protect and decorate the URL people see.
• A target inside /_gio answers 404: the rewrite cannot reach the server's own endpoints.

Invalid rules

A rule that cannot be compiled stops startup with the file, line and reason, and --check-config reports it under errors:

gio.toml:7: invalid [[rewrites]] entry for "/a/:id": target references unknown capture 'slug'

Examples

A friendly URL for a dynamic route

[[rewrites]]
from = "/u/:user"
to = "/users/:user/profile"

/u/alice renders app/users/[user]/profile/page.tsx with user = "alice", and the address bar keeps /u/alice. A capture is always a whole segment: /@:user would be a literal segment.

Serve old URLs from new pages

[[rewrites]]
from = "/guide/*rest"
to = "/docs/*rest"

Good to know

• Only paths on this server: rewrites do not proxy to another host.
• Prefer a redirect when the old URL should disappear from search engines and bookmarks.
• A public/ file at the requested path is not served once a rewrite matched it.

Related

• Middleware
• [[redirects]], [[headers]] and [[guards]]
• Dynamic routes

Version history