一键在 Manus 中运行任何 Skill

tanstack-start-boundaries

星标2

分支2

更新时间2025年12月31日 18:45

TanStack Start server/client code boundary patterns. Use when: debugging virtual module resolution errors (tanstack-start-injected-head-scripts, tanstack-start-manifest, #tanstack-router-entry), importing from @tanstack/react-start/server, using getCookie/getRequestHeaders/getRequestUrl, adding providers to router.tsx, or when Vite fails to resolve TanStack Start imports. Covers createServerFn patterns, dynamic imports, and proper placement of server-only code.

安装

用 Codex 或 Claude 帮你安装复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。

在 Manus 中运行

来源

wodsmith

wodsmith/thewodapp

打开 GitHub 仓库查看创作者相关仓库

下载

在 Manus 中运行

TanStack Start Server/Client Boundaries

The Problem

TanStack Start uses Vite's environment API to register virtual modules (tanstack-start-injected-head-scripts:v, tanstack-start-manifest:v, etc.) only for the server environment. When you import server-only code at the top level of files that are also bundled for the client, Vite fails to resolve these virtual modules.

Error Signatures

Failed to resolve import "tanstack-start-injected-head-scripts:v"
Failed to resolve import "tanstack-start-manifest:v"
Could not resolve "#tanstack-router-entry"
Could not resolve "#tanstack-start-entry"

Root Cause

Top-level imports from @tanstack/react-start/server in files processed by both client AND server:

// __root.tsx, router.tsx, or any route file
import { getCookie } from "@tanstack/react-start/server"  // BREAKS CLIENT BUNDLE

Problematic Files

These files are bundled for BOTH client and server:

src/router.tsx
src/routes/__root.tsx
src/routes/**/*.tsx (all route files)
Any file imported by the above

Problematic Imports

Never import these at top level in client-bundled files:

// FROM @tanstack/react-start/server
import { getCookie, setCookie } from "@tanstack/react-start/server"
import { getRequestHeaders } from "@tanstack/react-start/server"
import { getRequestUrl } from "@tanstack/react-start/server"
import { getRequest } from "@tanstack/react-start/server"

// FROM @tanstack/react-start-server (internal package)
import { getCookie } from "@tanstack/react-start-server"

Solutions

Solution 1: Use createServerFn with Dynamic Import

Wrap server-only code in a server function using dynamic imports:

// server-fns/cookie-fns.ts
import { createServerFn } from "@tanstack/react-start"

export const getThemeCookieFn = createServerFn({ method: "GET" }).handler(
  async () => {
    const { getCookie } = await import("@tanstack/react-start/server")
    return getCookie("theme")
  },
)

Then use the server function instead:

// routes/__root.tsx
import { getThemeCookieFn } from "@/server-fns/cookie-fns"

beforeLoad: async () => {
  const theme = await getThemeCookieFn()  // Safe - calls server function
  return { theme }
}

Solution 2: Keep Server Imports in server-fns/ Files

Server function files (src/server-fns/*.ts) can use top-level imports from @tanstack/react-start/server IF they only export createServerFn functions:

// server-fns/auth-fns.ts - OK because only exports server functions
import { createServerFn } from "@tanstack/react-start"
import { getCookie } from "@tanstack/react-start/server"  // OK here

export const getSessionFn = createServerFn({ method: "GET" }).handler(
  async () => {
    const sessionId = getCookie("session")
    // ...
  },
)

Warning: If any non-server-function code imports from this file, the chain breaks.

Solution 3: Move Client Providers Out of router.tsx

The router.tsx file's InnerWrap runs during SSR. Client-only providers here cause issues:

// router.tsx - BAD
import { PostHogProvider } from "./lib/posthog/provider"  // Client-only!

export const getRouter = () => {
  const router = createRouter({
    routeTree,
    InnerWrap: ({ children }) => (
      <PostHogProvider>{children}</PostHogProvider>  // Breaks SSR
    ),
  })
  return router
}

Move providers to __root.tsx RootDocument:

// routes/__root.tsx - GOOD
import { PostHogProvider } from "@/lib/posthog/provider"

function RootDocument({ children }) {
  return (
    <html>
      <body>
        <PostHogProvider>
          {children}
        </PostHogProvider>
      </body>
    </html>
  )
}

File Organization Pattern

src/
├── router.tsx              # NO server imports, NO client-only providers
├── routes/
│   ├── __root.tsx          # NO direct server imports, use server-fns
│   └── *.tsx               # NO direct server imports, use server-fns
├── server-fns/             # Server functions with createServerFn
│   ├── auth-fns.ts         # Can import from @tanstack/react-start/server
│   └── cookie-fns.ts       # Wraps getCookie in createServerFn
└── lib/
    └── posthog/
        └── provider.tsx    # "use client" - add to __root.tsx body, not router.tsx

Quick Diagnostic

When you see virtual module errors:

Search for @tanstack/react-start/server imports outside server-fns/:

grep -r "@tanstack/react-start/server" src/ --include="*.tsx" | grep -v server-fns

Check router.tsx for client-only provider imports
Look for import chains that pull server code into client bundles

GitHub References

Issue #5196: Server imports in route files
Issue #6189: Virtual module resolution failures
Issue #5795: #tanstack-router-entry resolution

同仓库更多 Skills

同仓库

alchemy-cloudflare

wodsmith/thewodapp

Alchemy IaC patterns for deploying TanStack Start apps to Cloudflare Workers with PlanetScale databases via Hyperdrive. Use when setting up new TanStack Start projects, configuring Alchemy deployments, working with PlanetScale/Drizzle migrations, local development with Cloudflare bindings, or deploying to custom domains.

2026-03-142

integration-test

wodsmith/thewodapp

Guide for writing integration tests with Vitest and Testing Library. Use when testing multi-component workflows, database interactions, React components with context providers, or full user flows. Covers the Testing Trophy philosophy (integration > unit), factory patterns for test data, MSW for network mocking, async testing patterns (waitFor, findBy), and custom render with providers. Use this for tests that cross multiple modules or layers of the application.

2026-03-142

local-db

wodsmith/thewodapp

Handle local database schema changes with Drizzle and PlanetScale. Use when making schema changes to src/db/schema.ts, adding/modifying database tables or columns, or when asked about database migrations. Covers the push-based local development workflow and when to generate migrations.

2026-03-142

tanstack-start-server-only

wodsmith/thewodapp

TanStack Start server-only patterns using createServerOnlyFn and cloudflare:workers env access. Use when: accessing Cloudflare environment variables (APP_URL, STRIPE_SECRET_KEY, etc.), creating server-only utility functions, working with Stripe or other server-only APIs, or when you need to ensure code only runs on the server and throws if called from client. Covers createServerOnlyFn vs createServerFn differences, env access patterns, and centralized server-only utilities.

2026-03-142

claim-url-lookup

wodsmith/thewodapp

Look up claim URLs for placeholder users created via manual registration. Use when needing to find the sign-up claim link for a specific email address, debug claim token issues, or verify claim tokens exist in local KV. Triggers on "claim URL", "claim token", "claim link", "placeholder user sign-up link", or requests to find the registration invite link for an email.

2026-02-272

team-memory

wodsmith/thewodapp

Store, search, and manage team memory from AI coding sessions. Use /remember to save observations (conventions, gotchas, debugging tips, architecture decisions, workflows). Use /recall to search memories by semantic query. Use /feedback to rate memory quality (helpful/harmful/irrelevant). Triggers on any request to save, recall, search, or rate team knowledge.

2026-02-202

name

tanstack-start-boundaries

description

TanStack Start Server/Client Boundaries

The Problem

Error Signatures

Failed to resolve import "tanstack-start-injected-head-scripts:v"
Failed to resolve import "tanstack-start-manifest:v"
Could not resolve "#tanstack-router-entry"
Could not resolve "#tanstack-start-entry"

Root Cause

Top-level imports from @tanstack/react-start/server in files processed by both client AND server:

// __root.tsx, router.tsx, or any route file
import { getCookie } from "@tanstack/react-start/server"  // BREAKS CLIENT BUNDLE

Problematic Files

These files are bundled for BOTH client and server:

src/router.tsx
src/routes/__root.tsx
src/routes/**/*.tsx (all route files)
Any file imported by the above

Problematic Imports

Never import these at top level in client-bundled files:

// FROM @tanstack/react-start/server
import { getCookie, setCookie } from "@tanstack/react-start/server"
import { getRequestHeaders } from "@tanstack/react-start/server"
import { getRequestUrl } from "@tanstack/react-start/server"
import { getRequest } from "@tanstack/react-start/server"

// FROM @tanstack/react-start-server (internal package)
import { getCookie } from "@tanstack/react-start-server"

Solutions

Solution 1: Use createServerFn with Dynamic Import

Wrap server-only code in a server function using dynamic imports:

// server-fns/cookie-fns.ts
import { createServerFn } from "@tanstack/react-start"

export const getThemeCookieFn = createServerFn({ method: "GET" }).handler(
  async () => {
    const { getCookie } = await import("@tanstack/react-start/server")
    return getCookie("theme")
  },
)

Then use the server function instead:

// routes/__root.tsx
import { getThemeCookieFn } from "@/server-fns/cookie-fns"

beforeLoad: async () => {
  const theme = await getThemeCookieFn()  // Safe - calls server function
  return { theme }
}

Solution 2: Keep Server Imports in server-fns/ Files

Server function files (src/server-fns/*.ts) can use top-level imports from @tanstack/react-start/server IF they only export createServerFn functions:

// server-fns/auth-fns.ts - OK because only exports server functions
import { createServerFn } from "@tanstack/react-start"
import { getCookie } from "@tanstack/react-start/server"  // OK here

export const getSessionFn = createServerFn({ method: "GET" }).handler(
  async () => {
    const sessionId = getCookie("session")
    // ...
  },
)

Warning: If any non-server-function code imports from this file, the chain breaks.

Solution 3: Move Client Providers Out of router.tsx

The router.tsx file's InnerWrap runs during SSR. Client-only providers here cause issues:

// router.tsx - BAD
import { PostHogProvider } from "./lib/posthog/provider"  // Client-only!

export const getRouter = () => {
  const router = createRouter({
    routeTree,
    InnerWrap: ({ children }) => (
      <PostHogProvider>{children}</PostHogProvider>  // Breaks SSR
    ),
  })
  return router
}

Move providers to __root.tsx RootDocument:

// routes/__root.tsx - GOOD
import { PostHogProvider } from "@/lib/posthog/provider"

function RootDocument({ children }) {
  return (
    <html>
      <body>
        <PostHogProvider>
          {children}
        </PostHogProvider>
      </body>
    </html>
  )
}

File Organization Pattern

src/
├── router.tsx              # NO server imports, NO client-only providers
├── routes/
│   ├── __root.tsx          # NO direct server imports, use server-fns
│   └── *.tsx               # NO direct server imports, use server-fns
├── server-fns/             # Server functions with createServerFn
│   ├── auth-fns.ts         # Can import from @tanstack/react-start/server
│   └── cookie-fns.ts       # Wraps getCookie in createServerFn
└── lib/
    └── posthog/
        └── provider.tsx    # "use client" - add to __root.tsx body, not router.tsx

Quick Diagnostic

When you see virtual module errors:

Search for @tanstack/react-start/server imports outside server-fns/:

grep -r "@tanstack/react-start/server" src/ --include="*.tsx" | grep -v server-fns

Check router.tsx for client-only provider imports
Look for import chains that pull server code into client bundles

GitHub References

Issue #5196: Server imports in route files
Issue #6189: Virtual module resolution failures
Issue #5795: #tanstack-router-entry resolution