Duolith docs

0031. Routes come from file names, layouts wrap folders, and an app is a stack of screens

  • Status: Accepted (Mik, 17 Nov 2026)
  • Date: 2026-11-14
  • Decided by: integrator (internal only), pending Mik's approval
  • Planning item: none

Context

Until now every page was its own HTML file and href made an element a plain link that reloaded the app. The framework is client-only (no server runtime) and will target iOS and Android, where navigation is a stack of screens that slide over each other, keep their state when covered, and pop back. Pages need parameters (/post/7), shared chrome (a tab bar), a not-found screen, and a way to read the route from the script.

Decision

Routes from file names. pages/post/[id].duo serves /post/:id; pages/docs/[...rest].duo serves one or more segments as rest (joined with /). Fixed segments win over parameters, which win over a rest, so the order of files never matters. Two pages for one route (E0141), two routes with the same shape ([id] and [slug] in one place, E0142) and malformed names (E0143) are diagnostics.

Reserved names. Files in pages/ starting with _ are not routes. _layout.duo wraps every screen in its folder and below, showing the screen where it writes <slot /> (E0145 without one); layouts nest, outermost first. pages/_not-found.duo is the screen for a path no page serves, inside the root layout. Any other _ name is E0144.

**route().** let { id } = route() unpacks the route's parameters, plus path and query (reserved, so not usable as parameter names). In a page it is the route the screen was opened for and never changes; a different route opens a new screen, as a native stack pushes a new view controller. In a layout, or in an expression evaluated later, it is the current route and expressions that read it follow navigation: current={route().path.startsWith("/feed")}. Unpacking a name the route does not give is E0146.

A stack of screens. Pressing an element with href, or navigate(path, { replace }), pushes a screen; back() pops one, or, when the app was opened at this screen, goes one level up the path. Layouts both routes share stay mounted with their state. A screen the user pushed past stays mounted, hidden, so back shows it exactly as left (state, typed text, scroll); it is dropped when the user goes back past it or its layout goes. Each screen is a frame that fills its outlet and scrolls on its own, as on native. A page's script now runs once per screen, in a setup function, so effects and resources stop when the screen is dropped; a page's script therefore cannot export (E0147).

Where navigation may go. An address handed to navigate often comes from the address bar (?next=), so anyone can write it. navigate follows only http: and https: addresses; any other scheme (javascript:, data:, blob:) is refused with an error and nothing happens. An address on another site (including //host/path) is opened with a full page load only for a push; navigate(href, { replace: true }), and so every guard redirect, stays on this site and refuses another one. A page that passes a query value on should still check it is a path in the app: it starts with one /, not // or /\.

Screen titles. <screen title="..."> or title={...} sets the document title while the screen is in front.

**current.** A new common attribute marks the current item of a set of links, such as the active tab; on the web it is aria-current="page", selectable in a style block.

Web mapping. duolith build emits one shell page, a route table (_duolith/routes.js) and one module per page and layout, loaded with dynamic import() on first use. Each static route also gets a copy of the shell with its title, module preloads and inline styles, so a deep link paints at once; 404.html is the shell every other path is served (static hosts serve it for unknown paths; duolith dev does the same). The History API carries the stack: each entry records its position, so back and forward pop and push, and reload keeps the route.

Alternatives considered

OptionWhy not
:id in file namesNot valid on Windows; brackets are what Next, Astro and SvelteKit users expect
route().params.idLonger for the common case; reserving path and query is a small price
Make page params reactive and reuse the screen for /post/1 → /post/2Native pushes a new screen; reuse would make state leak between posts
Re-make the previous screen on backLoses typed text and loaded data, and needs scroll guessing; native keeps it
Hash routing (#/post/7)Breaks deep links and sharing; static hosts handle a 404 fallback fine
Layouts as components the page importsEvery page would repeat the import, and the layout could not persist across screens

Consequences

Every app is now a single-page app on the web, and every example rebuilt that way without change. The glossary needs route (the path a page serves), layout (a _layout.duo file wrapping the screens of a folder) and guard (decision 0033); and <slot /> is now used by layouts as well as components (see 0015). Native targets implement the same Navigator contract (packages/client/src/navigation.ts). Per-tab history (each tab its own stack, as iOS does) is not done: pressing a tab pushes onto the one stack.