File-Based Routing

Blitz uses a file-system based router that’s built on

Next.js.

  • All components in pages/ are mapped to a URL. (Pages documentation)
  • All http handlers in api/ are mapped to a URL. (API routes documentation)
  • Queries and mutations are automatically exposed as an API endpoint
    • The app/projects/queries/getProjects.js query is exposed at /api/projects/queries/getProjects
    • See the RPC Specification for more details

Index routes

The router will automatically route files named

index to the root of the directory.

  • app/pages/index.js → /
  • app/pages/blog/index.js → /blog

Nested routes

The router supports nested files. If you create a nested folder structure files will be automatically routed in the same way still.

  • app/pages/blog/first-post.js → /blog/first-post
  • app/pages/dashboard/settings/username.js → /dashboard/settings/username

Dynamic route segments

To match a dynamic segment you can use the bracket syntax. This allows you to match named parameters.

  • app/pages/blog/[slug].js → /blog/:slug (/blog/hello-world)
  • app/pages/[username]/settings.js → /:username/settings (/foo/settings)
  • app/pages/post/[...all].js → /post/* (/post/2020/id/title)

Consider the following page

app/pages/post/[pid].js:

  1. import {useParam} from "blitz"const Post = () => {  const pid = useParam("pid")  return <p>Post: {pid}</p>}export default Post

Any route like

/post/1, /post/abc, etc. will be matched by app/pages/post/[pid].js. The matched path parameter will be sent as a query parameter to the page, and it will be merged with the other query parameters.

For example, the route

/post/abc will have the following query object:

  1. {"pid": "abc"}

Similarly, the route

/post/abc?foo=bar will have the following query object:

  1. {"foo": "bar", "pid": "abc"}

However, route parameters will override query parameters with the same name. For example, the route

/post/abc?pid=123 will have the following query object:

  1. {"pid": "abc"}

Multiple dynamic route segments work the same way. The page

app/pages/post/[pid]/[comment].js will match the route /post/abc/a-comment and its query object will be:

  1. {"pid": "abc", "comment": "a-comment"}

Catch all routes

Dynamic routes can be extended to catch all paths by adding three dots (

...) inside the brackets. For example:

  • app/pages/post/[...slug].js matches /post/a, but also /post/a/b, /post/a/b/c and so on.

Note: You can use names other than

slug, such as: [...param]

Matched parameters will be sent as a query parameter (

slug in the example) to the page, and it will always be an array, so, the path /post/a will have the following query object:

  1. {"slug": ["a"]}

And in the case of

/post/a/b, and any other matching path, new parameters will be added to the array, like so:

  1. {"slug": ["a", "b"]}

Optional catch all routes

Catch all routes can be made optional by including the parameter in double brackets (

[[...slug]]).

For example,

app/pages/post/[[...slug]].js will match /post, /post/a, /post/a/b, and so on.

The

query objects are as follows:

  1. { } // GET `/post` (empty object){ "slug": ["a"] } // `GET /post/a` (single-element array){ "slug": ["a", "b"] } // `GET /post/a/b` (multi-element array)

Caveats

  • Predefined routes take precedence over dynamic routes, and dynamic routes over catch all routes. Take a look at the following examples:

    • app/pages/post/create.js - Will match /post/create
    • app/pages/post/[pid].js - Will match /post/1, /post/abc, etc. But not /post/create
    • app/pages/post/[...slug].js - Will match /post/1/2, /post/a/b/c, etc. But not /post/create, /post/abc

  • Pages that are statically optimized by

    Automatic Static Optimization will be hydrated without their route parameters provided, i.e query will be an empty object ({}).

    After hydration, Blitz will trigger an update to your application to provide the route parameters in the query object.