Routing

Named routes & URL generation

A URL written by hand is a path duplicated: change the route and every hard-coded link rots. Name the route instead and generate its URL from the name, so the path lives in one place and links follow it automatically.

#Name once, generate everywhere

The principle

A path is an implementation detail of a route. Referring to routes by a stable name instead of their current path decouples every caller from that detail, so paths can change freely.

In Stone.js

Give a route a name, then ask the router to build its URL with router.generate(...), filling in parameters and query. The path exists in exactly one place: the route definition.

app/Tasks.tsts

@Get('/tasks/:id', { name: 'tasks.show' })
show (event: IncomingHttpEvent) { /* ... */ }

#Generating a URL

From anywhere with the router (injected, or via useRouter() in a component), generate a URL by name. Parameters and query are filled and encoded for you.

app/example.tsts

const url = router.generate({
  name: 'tasks.show',
  params: { id: 42 },
  query: { ref: 'email' }
})
// -> "/tasks/42?ref=email"

#Links in the UI

On the frontend, generate the URL by name and hand it to StoneLink, so navigation and server links share one source of truth.

app/pages/TaskRow.tsxtsx

const router = useRouter()

<StoneLink to={router.generate({ name: 'tasks.show', params: { id: task.id } })}>
  {task.title}
</StoneLink>

Name the route once. Every link becomes a reference, not a copy.