Skip to content
Source
Sign inSign up
TanStack/query
Open History to see the last commit

ssr.md

144 lines4.3 KB

Lit Query can be used with server rendering by combining Lit SSR with TanStack Query Core hydration APIs re-exported from @tanstack/lit-query.

The runnable source for this guide is the SSR example.

Flow

Server rendering has three phases:

  1. Create a per-request QueryClient.
  2. Prefetch queries on the server and render Lit HTML with that client.
  3. Dehydrate the cache into the HTML, then hydrate a browser QueryClient before the client app renders.

Never share one server QueryClient between users or requests.

Server Prefetch and Render

import { render } from '@lit-labs/ssr'
import { collectResult } from '@lit-labs/ssr/lib/render-result.js'
import { QueryClient, dehydrate, noop } from '@tanstack/lit-query'
import { html } from 'lit'
import { dataQueries } from './services/data/queries.js'
import './app.js'

async function renderPage() {
  const apiBaseUrl = 'https://example.com'
  const queryClient = new QueryClient({
    defaultOptions: {
      queries: {
        staleTime: 30 * 1000,
      },
    },
  })

  await queryClient.query(dataQueries.detail(apiBaseUrl)).catch(noop)

  const appHtml = await collectResult(
    render(
      html`<ssr-app
        api-base-url=${apiBaseUrl}
        .queryClient=${queryClient}
      ></ssr-app>`,
    ),
  )

  const dehydratedState = dehydrate(queryClient)

  return { appHtml, dehydratedState }
}

The server passes the same client into the Lit element with a property binding. This lets createQueryController read the prefetched cache during server render. If your query function calls fetch during SSR, pass an absolute API origin instead of relying on a browser-relative URL.

Client Hydration

import '@lit-labs/ssr-client/lit-element-hydrate-support.js'
import { QueryClient, hydrate } from '@tanstack/lit-query'
import type { DehydratedState } from '@tanstack/lit-query'

const queryClient = new QueryClient({
  defaultOptions: {
    queries: {
      staleTime: 30 * 1000,
    },
  },
})

const dehydratedState = JSON.parse(
  document.getElementById('__QUERY_STATE__')?.textContent ?? 'null',
) as DehydratedState

queryClient.mount()
hydrate(queryClient, dehydratedState)

const appElement = document.querySelector('ssr-app') as
  | (HTMLElement & { queryClient?: QueryClient })
  | null

if (!appElement) {
  throw new Error('Expected the SSR app element to exist before hydration.')
}

appElement.queryClient = queryClient
await import('./app.js')

Unmount the client when the page is unloaded if you mounted it manually:

window.addEventListener(
  'pagehide',
  () => {
    queryClient.unmount()
  },
  { once: true },
)

Component Pattern

The SSR example creates its controller only after a queryClient property is available:

import { createQueryController } from '@tanstack/lit-query'
import { LitElement } from 'lit'
import { dataQueries } from './services/data/queries.js'
import type { QueryClient, QueryResultAccessor } from '@tanstack/lit-query'
import type { DataResponse } from './services/data/types.js'

class SsrApp extends LitElement {
  static properties = {
    apiBaseUrl: { attribute: 'api-base-url' },
    queryClient: { attribute: false },
  }

  apiBaseUrl = ''
  queryClient?: QueryClient
  private dataQuery?: QueryResultAccessor<DataResponse, Error>

  protected override willUpdate(): void {
    if (!this.dataQuery && this.queryClient) {
      this.dataQuery = createQueryController(
        this,
        dataQueries.detail(this.apiBaseUrl),
        this.queryClient,
      )
    }
  }
}

This explicit-client pattern is useful for SSR because the client is created by the renderer rather than discovered from a connected DOM provider.

Serialization

Embed dehydrated state as JSON in the HTML and escape characters that can break out of a script tag. The example server uses a small serializer before replacing __QUERY_STATE_JSON__ in the built HTML template.

Lit Query re-exports dehydrate and hydrate from TanStack Query Core. Use dehydrate(queryClient) after server prefetching to capture the cache state. In the browser, parse that state, create a fresh QueryClient, call hydrate(queryClient, dehydratedState), assign the client to the server-rendered element, and only then import the Lit component so it upgrades with the prefetched cache available.