feat: allow head route option to accept a static object

[WolfieLeader]

Feature Request

Description

The head route option currently only accepts a function:

export const Route = createFileRoute('/')({
  head: () => ({
    meta: [{ title: 'My App' }, { charSet: 'UTF-8' }],
    links: [{ rel: 'icon', href: '/favicon.ico' }],
  }),
})

Many routes have static head content that doesn't depend on route context (params, loaderData, etc.). For these cases, the function wrapper is unnecessary boilerplate. It would be nice to also accept a const/static object:

export const Route = createFileRoute('/')({
  head: {
    meta: [{ title: 'My App' }, { charSet: 'UTF-8' }],
    links: [{ rel: 'icon', href: '/favicon.ico' }],
  },
})

Precedent

The loader option already accepts both a function (RouteLoaderFn) and an object (RouteLoaderObject), so this pattern has precedent in the codebase.

Scope

This would only apply to head. The standalone scripts option has legitimate dynamic use cases (e.g., JSON-LD from loaderData), and headers could follow later if desired.

Implementation

The change is minimal:

• Type: Make head a union of the existing function type and the static object type (packages/router-core/src/route.ts)
• Runtime: Add a typeof === 'function' check before calling head (packages/router-core/src/load-matches.ts)

I'm happy to submit a PR for this.

[schiller-manuel]

The loader option already accepts both a function (RouteLoaderFn) and an object (RouteLoaderObject), so this pattern has precedent in the codebase.

no, that's just a different form of providing the loader function. not supplying static loader data.

For these cases, the function wrapper is unnecessary boilerplate.

not sure this is really that common and also it's saving you from only 4 chars

[WolfieLeader]

@schiller-manuel

Developer experience matters here. When you're defining a route and the head content is purely static, wrapping it in () => ({...}) is the kind of friction that feels small in isolation but adds up across a codebase. More importantly, it's unintuitive - developers will naturally try to pass a plain object first because that's what makes semantic sense for static data. Having to discover through a type error that you need a function wrapper for something that doesn't use any of the function's arguments is a minor papercut that chips away at the "it just works" feeling.

The precedent with loader already accepting both a function and an object makes this even more compelling. Developers who've used loader with a static object will expect head to work the same way. Inconsistency between sibling route options creates unnecessary cognitive load.

The implementation is also minimal and non-breaking - it's a pure additive change. Existing function-based head definitions continue to work exactly as before. This is a low-risk, high-signal DX improvement.

Thanks buddy

[schiller-manuel]

where are you copying your text from? there is no "precedent" with loader.

buddy

just don't

[WolfieLeader]

Bro IDK what are you upset about, if you don't like it you can just move on all good.
No need to be toxic about someone else's idea 😂

Have great day buddy

[hokkyss]

router/packages/router-core/src/route.ts

Line 301 in 75686c6

export type RouteLoaderObject<

RouteLoaderObject is just basically a loader function if you just take your time to look at what RouteLoaderObject is. It's NOT that the loader accepts staticData as it is.

Developers who've used loader with a static object

So that statement is debunked.

Developers who've used loader head with a static object will expect loader to work the same way. Inconsistency between sibling route options creates unnecessary cognitive load.

Now the full statement is back to you. But It makes sense if you handle head, loaders, and others together