TanStack Start - 客户端入口点 (Client Entry Point)

配置客户端应用的水合和初始化。客户端入口点在默认情况下是可选的，如果未提供，TanStack Start 将自动处理。

概述

将 HTML 获取到客户端后，需要在路由解析到客户端后水合客户端 JavaScript。通过使用 StartClient 组件水合应用的根来实现：

tsx

// src/client.tsx
import { StartClient } from '@tanstack/react-start/client'
import { StrictMode } from 'react'
import { hydrateRoot } from 'react-dom/client'

hydrateRoot(
  document,
  <StrictMode>
    <StartClient />
  </StrictMode>,
)

这使我们能够在用户的初始服务端请求完成后启动客户端路由。

错误处理

用错误边界包装客户端入口点，以优雅地处理客户端错误：

tsx

// src/client.tsx
import { StartClient } from '@tanstack/react-start/client'
import { StrictMode } from 'react'
import { hydrateRoot } from 'react-dom/client'
import { ErrorBoundary } from './components/ErrorBoundary'

hydrateRoot(
  document,
  <StrictMode>
    <ErrorBoundary>
      <StartClient />
    </ErrorBoundary>
  </StrictMode>,
)

开发 vs 生产

tsx

// src/client.tsx
import { StartClient } from '@tanstack/react-start/client'
import { StrictMode } from 'react'
import { hydrateRoot } from 'react-dom/client'

const App = (
  <>
    {import.meta.env.DEV && <div>Development Mode</div>}
    <StartClient />
  </>
)

hydrateRoot(
  document,
  import.meta.env.DEV ? <StrictMode>{App}</StrictMode> : App,
)

高级配置

自定义水合选项

tsx

hydrateRoot(
  document,
  <StartClient />,
  {
    onRecoverableError: (error, errorInfo) => {
      console.error('Recoverable error:', error, errorInfo)
    },
  }
)

条件渲染

tsx

hydrateRoot(
  document,
  <>
    <StartClient />
    {import.meta.env.DEV && <DevTools />}
  </>
)

生产就绪的客户端入口点

tsx

// src/client.tsx
import { StartClient } from '@tanstack/react-start/client'
import { StrictMode } from 'react'
import { hydrateRoot } from 'react-dom/client'
import { ErrorBoundary } from './components/ErrorBoundary'

function ErrorFallback({ error }: { error: Error }) {
  return (
    <div style={{ padding: '20px', textAlign: 'center' }}>
      <h1>Something went wrong</h1>
      <p>{error.message}</p>
      <button onClick={() => window.location.reload()}>Reload Page</button>
    </div>
  )
}

if (import.meta.env.DEV) {
  hydrateRoot(
    document,
    <StrictMode>
      <ErrorBoundary FallbackComponent={ErrorFallback}>
        <StartClient />
      </ErrorBoundary>
    </StrictMode>,
  )
} else {
  hydrateRoot(
    document,
    <ErrorBoundary FallbackComponent={ErrorFallback}>
      <StartClient />
    </ErrorBoundary>,
  )
}

导入速查

导入	来源	用途
`StartClient`	`@tanstack/react-start/client`	客户端水合组件
`hydrateRoot`	`react-dom/client`	水合根元素
`StrictMode`	`react`	开发模式检查

环境变量

变量	用途
`import.meta.env.DEV`	开发模式
`import.meta.env.PROD`	生产模式
`import.meta.env.MODE`	当前模式
`import.meta.env.BASE_URL`	基础 URL