Reference sections
Reference › Route parameters
You can include route parameters in your route paths by separating them with underscores and surrounding the parameter names in square brackets.
For example:
manage_[token]_[domain].socket.js
Will create a WebSocket endpoint at:
/manage/:token/:domain.socket
You can also intersperse path fragments with parameters:
books_[id]_pages_[page].page.js
Will make the dynamic page available for HTTP GET requests at:
/books/:id/pages/:page
So you can access the route via, say, https://my.site/books/3/pages/10.
You can also specify the same routes using folder structures. For example, the following directory structure will result in the same route as above:
my-site
╰ books
╰ [id]
╰ pages
╰ [page].page.js
Note that you could also have set the name of the page to index[page].page.js_. Using just [page].page.js for a parameterised index page is a shorthand.
You can decide which strategy to follow based on the structure of your app. If, for example, you could access not just the pages but the references and images of a book, it might make sense to use a folder structure:
my-site
╰ books
╰ [id]
├ pages
│ ╰ [page].page.js
├ references
│ ╰ [reference].page.js
╰ images
╰ [image].page.js
You may, or may not find that easier to manage than:
my-site
├ books_[id]_pages_[page].page.js
├ books_[id]_references_[reference].page.js
╰ books_[id]_images_[image].page.js
Kitten leaves the decision up to you.
To create an optional parameter, prefix your parameter name with optional- inside the square brackets.
For example, the following route:
delete
╰ index_[subdomain]_[optional-return-page].page.js
Will match both of the following paths:
- /delete/my-lovely-subdomain/
- /delete/my-other-subdomain/troubleshooting/
Finally, you can also use the special wildcard parameter to match any string:
my-site
╰ books_[any].page.js
The about route will match any path that begins with /books/.
Under the hood, Kitten uses Polka for its routing and translates Kitten’s file system-based naming syntax to Polka’s routing syntax.
When more than one route matches a request, the most specific one responds. Kitten orders routes by their URL patterns, whatever order the file system returns your files in, so your app behaves the same on every machine. Pages, HTTP routes, and static files follow the same rule.
Kitten compares two patterns segment by segment. At the first segment where they differ:
- a literal segment (e.g., about) comes before a parameter (e.g., [slug]),
- a parameter comes before an optional parameter (e.g., [optional-page]), and
- an optional parameter comes before the wildcard parameter ([any]).
If one pattern runs out of segments first, it comes first, unless its last segment is the wildcard or an optional parameter, in which case the longer pattern comes first.
This means that about.page.js responds at /about/ next to [slug].page.js, and docs/[any]/edit.page.js responds at /docs/a/edit/ next to docs/[any].page.js. (At the same URL, a .head.js route comes before a page, which would otherwise respond to HEAD requests, as Polka runs GET routes for them.)
Two routes with the same method at the same URL stop Kitten at start-up with a line that mentions both files and the URL. This ensures that one route never replaces or shadows another without you knowing. Each of these pairs stops Kitten, for example:
- about.page.js and about.page.ts
- page2.html and page2.page.js
- zz🔒.page.js and zz/index.page.js
- secret.page.js and secret🔒.page.js
- default.socket.js and index.page.js (whose page socket is at
/default.socket) in the same folder
Kitten compares URLs without case and without parameter names, so [slug].page.js and [name].page.js in one folder collide too. Routes whose patterns overlap but aren’t the same (e.g., index.page.js at / and [optional-page].page.js) don’t collide, and route order decides which one responds.