preload function

Page and layout components can have a preload property that is a function that will be called before the page is rendered:

Avoiding waterfalls

You may think that the preload function is similar to getServerSideProps or getStaticProps from Next.js or loader from Remix but it's not the case. The preload function does not always run on the server, in fact, on the first render, it will run on the server and then again on the client. Its purpose is not data fetching but optimization. Preloading the data into the query cache like in the above example is a way to start fetching early:

Consider a scenario where both a page and its parent layout need to fetch some data. Since the page is a child of the layout, its data fetching hook will not be rendered until the parent layout is rendered. If the data fetched by the page is not dependent on the data fetched by the layout, there is no reason to wait until the parent finishes. In this case, you can use the page's preload function like in the above example to start fetching immediately. This works because preload functions of the page and all its parent layouts are called in parallel.

For this purpose, you can use the ctx.queryClient.prefetchQuery function in your preload function. To avoid repeating the same code in multiple places, you can use the queryOptions API to define a function that can build query options suitable to be passed to prefetchQuery and useQuery. There us no separate serverSideQueryOptions API, you can use runServerSideQuery in your query function to run code on the server.

Head tags

When using streaming SSR, Head components may be discovered after the document head has been sent. To avoid SEO problems, Rakkas will hold the stream until the page is fully rendered when it detects that the request is coming from a bot. But in some cases, you may want the correct status, headers, and head tags to be sent even to browsers. preload offers a way to do this like in the above example.

Another important thing to consider is out-of-order hydration. React may hydrate your components in a different order than you expect: If it detects the user is trying to interact with a component, its hydration will be prioritized. This can cause Head tags to be rendered out-of-order, causing back-and-forth switching of the document title when you have more than one Head component in the tree. Only using preload for rendering head tags will prevent this potential issue.

Redirection

preload functions can also redirect the request by returning an object like this:

return {
  redirect: {
    href: "/redirect/to",
    permanent: true,
  },
};