원클릭으로 Manus에서 모든 스킬 실행

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 저장소 열기 Creator 저장소 보기

다운로드

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