TanStack / TanStack/router

feat: add preloadResources option to control what gets preloaded (code vs code + data)

Open
#7,027 1 comment 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

enhancement
Dominant language
TypeScript
Stars
15.1k
Forks
1.9k
Avg merge
1d 20h
Merged PRs (30d)
143

Description

What is the problem?

defaultPreload: 'intent' preloads both the route's JS chunk and runs its loaders/data fetching on hover. There's no way to preload only the code chunk without triggering data fetching.

loadRouteChunk() exists for code-only preloading, but it's imperative — there's no declarative equivalent for <Link> or the router config.

Why does this matter?

Cost: In serverless deployments (e.g., Cloudflare Workers), each loader invocation is a billed request. Static assets (JS chunks) are served for free. Preloading data on hover intent wastes compute budget since users often hover over links without clicking.

Data freshness: defaultPreloadStaleTime is not a solution for apps with low staleness tolerance. If your app needs data to be current at the time of navigation, you can't cache preloaded data — but you still want instant code loading. There's currently no way to say "preload the code so navigation is fast, but fetch data fresh when the user actually navigates."

The current workarounds are:

  • Disabling preloading entirely (defaultPreload: false) — loses the UX benefit of instant navigation
  • Building a custom Link wrapper that calls loadRouteChunk() on hover — works but fragile and requires replacing every <Link> usage
Proposed solution

Add a separate option to control what gets preloaded:

const router = createRouter({
  defaultPreload: 'intent',
  defaultPreloadResources: 'chunk', // only preload JS chunks, skip loaders
})

// or per-link
<Link to="/posts" preloadResources="chunk">Posts</Link>

Values:

  • 'all' (default) — current behavior, preloads code + runs loaders
  • 'chunk' — preloads only the JS chunk via loadRouteChunk(), skips loaders

This keeps defaultPreload responsible for when to preload (intent, viewport, render) and defaultPreloadResources for what to preload.

Alternatives considered
  • Overloading defaultPreload with a 'code' value — conflates the "when" and "what" concerns
  • A boolean preloadData: false — less extensible if more resource types are added later

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by tracing createRouter's defaultPreload handling, the Link preload behavior, and loadRouteChunk(). Add the proposed 'all' and 'chunk' choices for router configuration and per-link usage, preserving current behavior by default. Done means chunk-only preloading skips loaders while navigation still fetches fresh data.

Written by the indexing model from the issue text.

Assessment

Tech stack
react, typescript
Domain
frontend
Issue type
Feature
Difficulty
4/5
Estimated time
3-5 days
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
55/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.