Skip to content
GitHub

Strutvane 0.2 is still being built. These pages describe how it will work; anything marked "Coming in 0.2" doesn't exist yet. Release notes and support policy.

URL Generation

View as Markdownllms.txt

URL generation means letting the framework build addresses for you instead of typing them as strings. You name a route once (posts.show) and ask for its URL wherever you need it: in an API response, an email, a redirect. If the route’s path changes later, every link follows, and a typo in a route name is a compile error, not a broken link in production.

Name a route:

routes/api.ts
import { defineRoutes, Route } from '@strutvane/framework'
import { PostController } from '../app/http/controllers/post.controller.ts'
export default defineRoutes([
Route.apiResource('posts', PostController, { bindBy: 'slug' }), // posts.index, posts.show, …
])

Build its URL anywhere during a request:

app/http/controllers/post.controller.ts
import { Controller, route, type HttpContext } from '@strutvane/framework'
import { Post } from '../../models/post.ts'
export class PostController extends Controller {
show(ctx: HttpContext): Response {
const post = ctx.model(Post)
return ctx.json({ data: post, links: { self: route('posts.show', { post }), all: route('posts.index') } })
}
}

What you’ll see:

{ "data": { "id": 1, "title": "Hello World", "slug": "hello-world" }, "links": { "self": "/api/posts/hello-world", "all": "/api/posts" } }
Call Result
route('posts.index') /api/posts
route('posts.show', { post }) /api/posts/hello-world (a model fills {post:slug} with its slug)
route('posts.show', { post: 'hello-world' }) /api/posts/hello-world (a string or a number works too)
route('posts.index', { page: 2 }) /api/posts?page=2 (parameters the path doesn’t use become the query string)
route('posts.index', {}, { query: { page: 2, sort: '-created_at' } }) /api/posts?page=2&sort=-created_at
route('posts.show', { post }, { absolute: true }) http://localhost:3000/api/posts/hello-world

Values are URL-encoded for you, so a slug or search term with spaces or symbols is safe.

bootstrap/app.ts tells TypeScript about your routes once (new apps already have it), and from then on:

route('posts.shwo', { post }) // ✖ compile error: no route has that name
route('posts.show') // ✖ compile error: {post} is required
route('posts.show', { pots: post }) // ✖ compile error: wrong parameter name
route('admin.stats') // ✔ group name prefixes are typed too

When the name comes from a variable (so TypeScript can’t check it), the same mistakes are friendly runtime errors (see Common mistakes).

By default route() returns a path (/api/posts), which is what you want inside your own app. For anything that leaves the app (an email, a webhook, a QR code), ask for an absolute URL. It’s built from APP_URL, never from the request’s Host header, so a forged header can’t end up in a password-reset link:

route('posts.show', { post }, { absolute: true }) // → 'https://blog.example.com/api/posts/hello-world'

Set APP_URL to the address people use (with https:// in production). See Configuration.

For a path that isn’t a named route, url() makes it absolute from APP_URL:

import { url } from '@strutvane/framework'
url('/help/getting-started') // → 'https://blog.example.com/help/getting-started'
url('/search', { query: { q: 'launch' } }) // → 'https://blog.example.com/search?q=launch'

Prefer route() whenever a route has a name: a renamed path then can’t break the link.

A signed URL carries a signature made from your APP_KEY. Anyone can open it, but nobody can change any part of it (the id, the expiry) without breaking the signature. Use it for links you email: unsubscribe, download, confirm.

app/http/controllers/report.controller.ts
import { Controller, url, type HttpContext } from '@strutvane/framework'
export class ReportController extends Controller {
share(ctx: HttpContext): Response {
const link = url.temporarySignedRoute('reports.download', new Date(Date.now() + 30 * 60_000), { report: ctx.param('report') })
return ctx.json({ link })
}
}
routes/api.ts
Route.get('/reports/{report}/download', [ReportController, 'download']).name('reports.download').middleware('signed'),
Helper Makes
url.signedRoute(name, params) A signed link that doesn’t expire
url.signedRoute(name, params, { expiresIn: 3600 }) One that expires after an hour
url.signedRoute(name, params, { oneTime: true }) One that works once
url.temporarySignedRoute(name, expiresAt, params) One that expires at a given Date

What you’ll see when the link is opened: the route runs. A changed link answers 403 invalid_signature, an expired one 403 signature_expired, so your page can offer “send me a new link”. The same signer (an HMAC over the path, the sorted query, the expiry and a purpose) is used by sign-in emails and temporary file URLs. After node strut key:rotate, links made with the old key keep working. See Routing: Signed routes.

url.current() // the URL of this request, without the query string
url.full() // the same, with the query string
url.previous() // where the user came from (from the session), or a fallback

url.previous() reads the session, not the Referer header (which any client can fake or leave out), and only ever returns a same-site path, so it’s safe to redirect to. For “back to where you were going after sign-in”, use redirect().intended(ctx, '/dashboard') (Helpers).

Laravel’s URL::defaults(): when many routes share a parameter, such as {locale} or {team}, set it once per request (in a middleware) and route() fills it in:

url.defaults({ team: ctx.user?.team_slug ?? 'personal' })
route('team.projects.index') // → '/acme/projects', no need to pass { team }

The generated UI uses a typed client built from the same route table (.strutvane/client.gen.ts), so browser code gets the same compile errors for a wrong route or field. See Frontend.

Nothing changes, except one thing to check: APP_URL must be the address your browser uses (http://localhost:3000), not the container’s internal name, or absolute links in emails will point at an address nobody can open.

✖ No route is named "post.show".
→ Did you mean "posts.show"?

Why: the name came from a variable (so it wasn’t checked at compile time) and has a typo, or the route has no .name(). Fix: use the suggestion, or name the route; node strut route:list shows every name.

“route(‘…’) needs a value for {post}”

Section titled ““route(‘…’) needs a value for {post}””
✖ route('posts.show') needs a value for {post}.
→ Pass every parameter of /api/posts/{post:slug}: { post }.

Fix: pass the parameter: route('posts.show', { post }).

Why: APP_URL on the server is still http://localhost:3000, and absolute URLs are built from it. Fix: set APP_URL=https://your-domain.example in the server’s environment.

“route() was called outside a request or console command”

Section titled ““route() was called outside a request or console command””

Why: route() ran at the top level of a file, before any app was handling a request. Fix: call it inside a function, or wrap it: app.run(() => route('posts.index')). See Helpers.

Section titled “A signed link answers 403 “invalid_signature””

Why: something changed the URL after it was signed (an email client re-encoding it, a parameter added by hand), or the checking server has a different APP_KEY. Fix: send the link exactly as it was made, and give every server the same APP_KEY.

  • Routing: naming routes and binding parameters.
  • Helpers: redirect() and the other helpers.
  • Session: where the previous URL is kept.