Vorladen (Preloading)

Preloading in TanStack Router ist eine Möglichkeit, eine Route vorzuladen, bevor der Benutzer tatsächlich zu ihr navigiert. Dies ist nützlich für Routen, die der Benutzer wahrscheinlich als nächstes besuchen wird. Wenn Sie beispielsweise eine Liste von Beiträgen haben und der Benutzer wahrscheinlich auf einen davon klickt, können Sie die Beitragsroute vorladen, damit sie bereit ist, wenn der Benutzer darauf klickt.

• Absicht
  • Preloading nach "Absicht" funktioniert, indem Hover- und Touch-Start-Ereignisse auf <Link>-Komponenten verwendet werden, um die Abhängigkeiten für die Zielroute vorzuladen.
  • Diese Strategie ist nützlich für das Vorladen von Routen, die der Benutzer wahrscheinlich als nächstes besuchen wird.
• Viewport-Sichtbarkeit
  • Preloading nach "Viewport" funktioniert, indem die Intersection Observer API verwendet wird, um die Abhängigkeiten für die Zielroute vorzuladen, wenn die <Link>-Komponente im Viewport sichtbar ist.
  • Diese Strategie ist nützlich für das Vorladen von Routen, die sich unterhalb der "fold" oder außerhalb des Bildschirms befinden.
• Rendern
  • Preloading nach "Rendern" funktioniert, indem die Abhängigkeiten für die Zielroute vorladen, sobald die <Link>-Komponente im DOM gerendert wird.
  • Diese Strategie ist nützlich für das Vorladen von Routen, die immer benötigt werden.

Vorab geladene Routen-Übereinstimmungen werden vorübergehend im Speicher zwischengespeichert, mit einigen wichtigen Einschränkungen.

• Nicht verwendete vorab geladene Daten werden standardmäßig nach 30 Sekunden entfernt. Dies kann durch Festlegen der Option defaultPreloadMaxAge Ihres Routers konfiguriert werden.
• Offensichtlich wird bei jedem Laden einer Route die vorab geladene Version davon in den normalen "pending matches"-Status des Routers verschoben.

Wenn Sie mehr Kontrolle über Preloading, Caching und/oder Garbage Collection von vorab geladenen Daten benötigen, sollten Sie eine externe Caching-Bibliothek wie TanStack Query verwenden.

Der einfachste Weg, Routen für Ihre Anwendung vorzuladen, ist das Festlegen der Option defaultPreload auf intent für Ihren gesamten Router.

import { createRouter } from '@tanstack/react-router'

const router = createRouter({
  // ...
  defaultPreload: 'intent',
})

import { createRouter } from '@tanstack/react-router'

const router = createRouter({
  // ...
  defaultPreload: 'intent',
})

Dadurch wird standardmäßig das intent-Preloading für alle <Link>-Komponenten in Ihrer Anwendung aktiviert. Sie können auch die preload-Prop auf einzelnen <Link>-Komponenten setzen, um das Standardverhalten zu überschreiben.

Standardmäßig beginnt das Preloading nach 50 ms, nachdem der Benutzer eine <Link>-Komponente berührt oder darüber fährt. Sie können diese Verzögerung ändern, indem Sie die Option defaultPreloadDelay auf Ihrem Router einstellen.

import { createRouter } from '@tanstack/react-router'

const router = createRouter({
  // ...
  defaultPreloadDelay: 100,
})

import { createRouter } from '@tanstack/react-router'

const router = createRouter({
  // ...
  defaultPreloadDelay: 100,
})

Sie können auch die preloadDelay-Prop auf einzelnen <Link>-Komponenten setzen, um das Standardverhalten für jede einzelne Verknüpfung zu überschreiben.

Wenn Sie die integrierten Loader verwenden, können Sie steuern, wie lange vorab geladene Daten als frisch gelten, bis ein weiteres Preload ausgelöst wird, indem Sie entweder routerOptions.defaultPreloadStaleTime oder routeOptions.preloadStaleTime auf eine Anzahl von Millisekunden setzen. Standardmäßig gelten vorab geladene Daten 30 Sekunden lang als frisch..

Um dies zu ändern, können Sie die Option defaultPreloadStaleTime auf Ihrem Router setzen.

import { createRouter } from '@tanstack/react-router'

const router = createRouter({
  // ...
  defaultPreloadStaleTime: 10_000,
})

import { createRouter } from '@tanstack/react-router'

const router = createRouter({
  // ...
  defaultPreloadStaleTime: 10_000,
})

Oder Sie können die Option routeOptions.preloadStaleTime für einzelne Routen verwenden.

// src/routes/posts.$postId.tsx
export const Route = createFileRoute('/posts/$postId')({
  loader: async ({ params }) => fetchPost(params.postId),
  // Preload the route again if the preload cache is older than 10 seconds
  preloadStaleTime: 10_000,
})

// src/routes/posts.$postId.tsx
export const Route = createFileRoute('/posts/$postId')({
  loader: async ({ params }) => fetchPost(params.postId),
  // Preload the route again if the preload cache is older than 10 seconds
  preloadStaleTime: 10_000,
})

Bei der Integration externer Caching-Bibliotheken wie React Query, die eigene Mechanismen zur Bestimmung veralteter Daten haben, möchten Sie möglicherweise die Standard-Preloading- und Stale-While-Revalidate-Logik von TanStack Router überschreiben. Diese Bibliotheken verwenden oft Optionen wie staleTime, um die Aktualität von Daten zu steuern.

Um das Preloading-Verhalten in TanStack Router anzupassen und die Caching-Strategie Ihrer externen Bibliothek voll auszuschöpfen, können Sie das integrierte Caching umgehen, indem Sie routerOptions.defaultPreloadStaleTime oder routeOptions.preloadStaleTime auf 0 setzen. Dies stellt sicher, dass alle Preloads intern als veraltet markiert werden und Loader immer aufgerufen werden, wodurch Ihre externe Bibliothek, wie z. B. React Query, die Datenladung und das Caching verwalten kann.

Zum Beispiel

import { createRouter } from '@tanstack/react-router'

const router = createRouter({
  // ...
  defaultPreloadStaleTime: 0,
})

import { createRouter } from '@tanstack/react-router'

const router = createRouter({
  // ...
  defaultPreloadStaleTime: 0,
})

Dies würde es Ihnen dann beispielsweise ermöglichen, eine Option wie die staleTime von React Query zu verwenden, um die Aktualität Ihrer Preloads zu steuern.

Wenn Sie eine Route manuell vorladen müssen, können Sie die Methode des Routers preloadRoute verwenden. Sie akzeptiert ein Standard-TanStack NavigateOptions-Objekt und gibt ein Promise zurück, das aufgelöst wird, wenn die Route vorab geladen ist.

function Component() {
  const router = useRouter()

  useEffect(() => {
    async function preload() {
      try {
        const matches = await router.preloadRoute({
          to: postRoute,
          params: { id: 1 },
        })
      } catch (err) {
        // Failed to preload route
      }
    }

    preload()
  }, [router])

  return <div />
}

function Component() {
  const router = useRouter()

  useEffect(() => {
    async function preload() {
      try {
        const matches = await router.preloadRoute({
          to: postRoute,
          params: { id: 1 },
        })
      } catch (err) {
        // Failed to preload route
      }
    }

    preload()
  }, [router])

  return <div />
}

Wenn Sie nur den JS-Chunk einer Route vorladen müssen, können Sie die Methode des Routers loadRouteChunk verwenden. Sie akzeptiert ein Routenobjekt und gibt ein Promise zurück, das aufgelöst wird, wenn der Routen-Chunk geladen ist.

function Component() {
  const router = useRouter()

  useEffect(() => {
    async function preloadRouteChunks() {
      try {
        const postsRoute = router.routesByPath['/posts']
        await Promise.all([
          router.loadRouteChunk(router.routesByPath['/']),
          router.loadRouteChunk(postsRoute),
          router.loadRouteChunk(postsRoute.parentRoute),
        ])
      } catch (err) {
        // Failed to preload route chunk
      }
    }

    preloadRouteChunks()
  }, [router])

  return <div />
}

function Component() {
  const router = useRouter()

  useEffect(() => {
    async function preloadRouteChunks() {
      try {
        const postsRoute = router.routesByPath['/posts']
        await Promise.all([
          router.loadRouteChunk(router.routesByPath['/']),
          router.loadRouteChunk(postsRoute),
          router.loadRouteChunk(postsRoute.parentRoute),
        ])
      } catch (err) {
        // Failed to preload route chunk
      }
    }

    preloadRouteChunks()
  }, [router])

  return <div />
}