Skip to content

feat: add support for Zod v4 while maintaining v3 compatibility #6321

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
zackarychapple wants to merge 1 commit into
base: main
Choose a base branch
from
+93 −26
Open

feat: add support for Zod v4 while maintaining v3 compatibility #6321

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion packages/router-generator/package.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -72,7 +72,7 @@
"recast": "^0.23.11",
"source-map": "^0.7.4",
"tsx": "^4.19.2",
"zod": "^3.24.2"
"zod": "^3.25.0 || ^4.0.0"
},
"devDependencies": {
"@tanstack/react-router": "workspace:*"
Expand Down
25 changes: 24 additions & 1 deletion packages/router-generator/src/config.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,29 @@ import { z } from 'zod'
import { virtualRootRouteSchema } from './filesystem/virtual/config'
import type { GeneratorPlugin } from './plugin/types'

// Helper to create a function schema compatible with both Zod v3 and v4
function createFunctionSchema() {
// Try Zod v4 syntax first
if (typeof (z as any).function === 'function') {
try {
// Check if this is Zod v4 by testing for the new API
const testSchema = z.string()
if ('_zod' in testSchema) {
// Zod v4: use new function API
return (z as any).function({
input: [],
output: z.array(z.string()),
})
}
} catch (e) {
// Fall through to v3
}
}

// Zod v3: use old function API
return (z as any).function().returns(z.array(z.string()))
}
Comment on lines +7 to +28
Copy link
Contributor

@coderabbitai coderabbitai bot Jan 7, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟠 Major

🧩 Analysis chain

🏁 Script executed:

# First, let's locate and read the actual file
find . -name "config.ts" -path "*/router-generator/*" | head -5

Repository: TanStack/router

Length of output: 161

🏁 Script executed:

# Also check for package.json to understand dependencies
find . -name "package.json" -path "*/router-generator/*" | head -3

Repository: TanStack/router

Length of output: 99

🏁 Script executed:

# Look for tsconfig to verify strict mode
find . -name "tsconfig.json" | head -5

Repository: TanStack/router

Length of output: 314

🌐 Web query:

Zod v4 migration guide version detection API changes

💡 Result:

Summary of Zod v4 "version detection" / API changes (concise):

  • Subpath/versioning: Zod v4 is published under "zod/v4" (and v3 under "zod/v3") so consumers and library authors should use subpath imports to target a specific major version; later the package root ("zod") was switched to v4. This is the recommended way for libraries to detect/support v3 vs v4. [1]

  • Public API renames & reorganizations that affect detection by type/shape:

    • Many core types and issue types moved/renamed (e.g., Zod issue types now live under z.core.$ZodIssue*). This means runtime/type checks relying on old names (or instanceof of old classes) may break. [2]
    • Transforms, preprocessors, branded types, and refinements were reworked (ZodTransform / ZodPipe, checks concept), so code that inspected schema classes must be updated. [2][3]

  • Error/customization API changed: the old message/invalid_type_error/required_error/errorMap semantics were unified into a single error parameter/function, so libraries that detected Zod behavior by reading those options must adapt. [3]

  • Guidance for library authors: support both versions by importing the specific subpath(s) and feature-detecting differences (e.g., presence of z.core namespaces / new methods) rather than relying on package.json peer-dep resolution. The Zod docs explain this migration approach. [1]

References

  • Zod versioning & subpath migration guidance. [1]
  • Zod v4 changelog / breaking changes (issues, checks, transforms). [2]
  • Introducing Zod 4 (error API and examples). [3]

If you want, I can: (a) show small code snippets for feature-detection (runtime checks) to support both v3 and v4, or (b) scan your codebase for patterns that will break and suggest exact fixes.

🏁 Script executed:

# Read the actual config.ts file
cat -n ./packages/router-generator/src/config.ts | head -50

Repository: TanStack/router

Length of output: 2191

🏁 Script executed:

# Check router-generator package.json for Zod dependency
cat ./packages/router-generator/package.json | jq '.dependencies, .peerDependencies, .devDependencies | select(. != null) | with_entries(select(.key | contains("zod")))'

Repository: TanStack/router

Length of output: 94

🏁 Script executed:

# Find tsconfig.json closest to router-generator
cat ./packages/router-generator/tsconfig.json 2>/dev/null || cat ./tsconfig.json 2>/dev/null | head -30

Repository: TanStack/router

Length of output: 484

🏁 Script executed:

# Search for usages of createFunctionSchema to see if it's cached or called frequently
rg -n "createFunctionSchema" ./packages/router-generator/src/

Repository: TanStack/router

Length of output: 211

🏁 Script executed:

# Search for tests of this function
rg -n "createFunctionSchema" ./packages/router-generator/ --type ts --type tsx

Repository: TanStack/router

Length of output: 86

🏁 Script executed:

# Check root tsconfig.json for strict mode setting
cat ./tsconfig.json | jq '.compilerOptions.strict'

Repository: TanStack/router

Length of output: 63

🏁 Script executed:

# Check context around line 66 where createFunctionSchema is used
sed -n '60,80p' ./packages/router-generator/src/config.ts

Repository: TanStack/router

Length of output: 759

🏁 Script executed:

# Search for any version detection patterns in the codebase
rg -n "zod.*version|Zod.*v[34]|_zod|subpath.*zod" ./packages/router-generator/src/ --type ts

Repository: TanStack/router

Length of output: 596

🏁 Script executed:

# Check if Zod v4 actually has the _zod property by searching package
cat node_modules/zod/package.json 2>/dev/null | jq '.version' || echo "Zod not in node_modules or not accessible"

Repository: TanStack/router

Length of output: 41

🏁 Script executed:

# Let's verify if _zod is actually an internal property in Zod
# Check Zod's type definitions
cat node_modules/zod/lib/types.d.ts 2>/dev/null | head -100 || echo "Type defs not accessible"

Repository: TanStack/router

Length of output: 41

🏁 Script executed:

# Search for _zod in Zod source to understand if it's internal
rg -n "readonly _zod|_zod:|_zod =" node_modules/zod/lib/ 2>/dev/null | head -20 || echo "Search failed or no results"

Repository: TanStack/router

Length of output: 41

🏁 Script executed:

# Check Zod's official docs or package for version detection guidance
cat node_modules/zod/README.md 2>/dev/null | grep -A10 -i "version\|v3\|v4" | head -40 || echo "README not found"

Repository: TanStack/router

Length of output: 41

🏁 Script executed:

# Test if the detection logic actually works by checking what properties exist in Zod v4
python3 << 'EOF'
import subprocess
import json

# Get Zod version from node_modules
try:
    result = subprocess.run(['cat', 'node_modules/zod/package.json'], capture_output=True, text=True)
    pkg = json.loads(result.stdout)
    print(f"Zod version: {pkg.get('version', 'unknown')}")
except Exception as e:
    print(f"Error: {e}")
EOF

Repository: TanStack/router

Length of output: 145

🏁 Script executed:

# Search for how other projects or the Zod repo suggest version detection
rg -i "detect.*version|version.*detect|subpath" ./packages/router-generator/ --type ts

Repository: TanStack/router

Length of output: 41

🏁 Script executed:

# Check if there are any tests that verify the detection logic works
find ./packages/router-generator -name "*.test.*" -o -name "*.spec.*" | head -10

Repository: TanStack/router

Length of output: 273

🏁 Script executed:

# Look for any existing issues or comments about Zod v3/v4 compatibility
rg -i "zod.*compat|v3.*v4|version.*detect" ./packages/ --type ts --type tsx | head -20

Repository: TanStack/router

Length of output: 86

🏁 Script executed:

# Check the actual Zod exports to understand the API
# We'll look at what the z object actually exposes in v3 vs v4
ls -la node_modules/zod/lib/ 2>/dev/null | head -20 || echo "node_modules not accessible in current context"

Repository: TanStack/router

Length of output: 41

🏁 Script executed:

# Try to find Zod documentation or changelog in the repo
find . -name "*zod*" -type f \( -name "*.md" -o -name "CHANGELOG*" \) 2>/dev/null | head -10

Repository: TanStack/router

Length of output: 41

🏁 Script executed:

# Check the config test file for any tests related to createFunctionSchema
cat ./packages/router-generator/tests/config.test.ts

Repository: TanStack/router

Length of output: 882

🏁 Script executed:

# Look at what Zod v3 and v4 documentation say about the function schema API
# Search the web for specific API differences
web_search

Repository: TanStack/router

Length of output: 109

🏁 Script executed:

# Check if the function schema created actually works correctly
# Look for any error handling or validation around it
rg -B5 -A10 "createFunctionSchema" ./packages/router-generator/src/config.ts

Repository: TanStack/router

Length of output: 1154

Use official Zod version detection strategy instead of undocumented internal properties.

The detection mechanism relies on the _zod property, which is not part of Zod's documented public API. Official Zod v4 migration guidance recommends using subpath imports (zod/v3 and zod/v4) or feature-detection via try/catch on the actual API signature.

Current issues:

  1. API stability risk: The _zod property is undocumented and not guaranteed across minor/patch releases.
  2. Type safety: Multiple any casts violate TypeScript strict mode (enabled in this project).
  3. Unnecessary runtime overhead: Creates a test schema during schema initialization.
  4. Silent failures: Errors are swallowed without logging, making debugging harder if detection fails.

Replace with the simpler try/catch approach on the actual API signature:

Recommended fix 
 function createFunctionSchema() {
-  // Try Zod v4 syntax first
-  if (typeof (z as any).function === 'function') {
-    try {
-      // Check if this is Zod v4 by testing for the new API
-      const testSchema = z.string()
-      if ('_zod' in testSchema) {
-        // Zod v4: use new function API
-        return (z as any).function({
-          input: [],
-          output: z.array(z.string()),
-        })
-      }
-    } catch (e) {
-      // Fall through to v3
-    }
-  }
-
-  // Zod v3: use old function API
-  return (z as any).function().returns(z.array(z.string()))
+  try {
+    // Try v4 API - if it accepts an object config, it's v4
+    return (z as any).function({
+      input: [],
+      output: z.array(z.string()),
+    })
+  } catch {
+    // Fall back to v3 chained API
+    return (z as any).function().returns(z.array(z.string()))
+  }
 }
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
// Helper to create a function schema compatible with both Zod v3 and v4
function createFunctionSchema() {
// Try Zod v4 syntax first
if (typeof (z as any).function === 'function') {
try {
// Check if this is Zod v4 by testing for the new API
const testSchema = z.string()
if ('_zod' in testSchema) {
// Zod v4: use new function API
return (z as any).function({
input: [],
output: z.array(z.string()),
})
}
} catch (e) {
// Fall through to v3
}
}
// Zod v3: use old function API
return (z as any).function().returns(z.array(z.string()))
}
// Helper to create a function schema compatible with both Zod v3 and v4
function createFunctionSchema() {
try {
// Try v4 API - if it accepts an object config, it's v4
return (z as any).function({
input: [],
output: z.array(z.string()),
})
} catch {
// Fall back to v3 chained API
return (z as any).function().returns(z.array(z.string()))
}
}


export const baseConfigSchema = z.object({
target: z.enum(['react', 'solid', 'vue']).optional().default('react'),
virtualRouteConfig: virtualRootRouteSchema.or(z.string()).optional(),
Expand Down Expand Up @@ -40,7 +63,7 @@ export const configSchema = baseConfigSchema.extend({
routeTreeFileFooter: z
.union([
z.array(z.string()).optional().default([]),
z.function().returns(z.array(z.string())),
createFunctionSchema(),
])
.optional(),
autoCodeSplitting: z.boolean().optional(),
Expand Down
2 changes: 1 addition & 1 deletion packages/router-plugin/package.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -117,7 +117,7 @@
"babel-dead-code-elimination": "^1.0.11",
"chokidar": "^3.6.0",
"unplugin": "^2.1.2",
"zod": "^3.24.2"
"zod": "^3.25.0 || ^4.0.0"
},
"devDependencies": {
"@types/babel__core": "^7.20.5",
Expand Down
25 changes: 24 additions & 1 deletion packages/router-plugin/src/core/config.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,29 @@ import type {
} from '@tanstack/router-core'
import type { CodeSplitGroupings } from './constants'

// Helper to create a function schema compatible with both Zod v3 and v4
function createGenericFunctionSchema(): any {
// Try Zod v4 syntax first
if (typeof (z as any).function === 'function') {
try {
// Check if this is Zod v4 by testing for the new API
const testSchema = z.string()
if ('_zod' in testSchema) {
// Zod v4: use new function API with any input/output
return (z as any).function({
input: [z.any()],
output: z.any(),
})
}
} catch (e) {
// Fall through to v3
}
}

// Zod v3: use old function API
return (z as any).function()
}
Comment on lines +13 to +34
Copy link
Contributor

@coderabbitai coderabbitai bot Jan 7, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🔴 Critical

🧩 Analysis chain

🏁 Script executed:

cat -n packages/router-plugin/src/core/config.ts | head -100

Repository: TanStack/router

Length of output: 3699

🌐 Web query:

Zod v3 vs v4 differences and how to detect version at runtime

💡 Result:

Summary — main v3 → v4 differences

  • Packaging/versioning: v4 was released using subpaths (import * as z from "zod/v4") while "zod" root stayed v3 during transition; later zod@4 became the package root. [1][2]
  • Error API and error shape: unified error customization (message/required_error/invalid_type_error → single error param), renamed/merged issue types and changes to ZodError helpers (e.g., .format/.flatten replaced by z.treeifyError and other tools). [3][5]
  • Refinements / transforms / checks: v4 reworks refinements (checks) and introduces separate transform types/behavior (ZodTransform); transform/refine ordering/behavior changed in some cases. [6][3]
  • API renames/option changes: many validators/options renamed (e.g., message → error), some helper methods removed or replaced; expect breaking signatures for adding custom errors. [5][4]
  • Internal shape and types: many internal types/namespaces changed, so libraries depending on Zod internals often break. [3][7]

Sources: Zod docs & changelog, community migration notes. [1][3][5]

How to detect Zod v3 vs v4 at runtime
(Choose one depending on environment—Node, bundler, or browser)

  1. Check package.json version (Node / server-side)
  • const v = require('zod/package.json').version
  • if v.startsWith('4') → v4 else startsWith('3') → v3.
    (Works when package.json is available at runtime). [1]
  1. Feature-detection (safe in bundlers & runtime)
  • Check for v4-specific exports/APIs. Examples that indicate v4:
    • typeof z.treeifyError === 'function' // v4 error helpers. [3]
    • typeof z.toJSONSchema === 'function' // v4 added JSON Schema helpers. [6]
    • typeof (z as any).ZodTransform !== 'undefined' or 'check' on schema prototype — presence of ZodTransform/check indicates v4. [6][5]
      If any of those exist, treat as v4; otherwise treat as v3.
  1. Import-path detection (at build-time / when you control imports)
  • If your code imports from "zod/v4" you know it’s v4; "zod/v3" or root "zod" may be v3 during transition. [1]

Notes / practical tips

  • Prefer feature-detection (2) for runtime-bundled code (works even if package root changed). [6][1]
  • If you need binary compatibility for libraries, use subpath imports (zod/v3 and zod/v4) per Zod’s official guidance to support both in one package. [1]
  • For robust multi-version support consider using or inspecting compatibility libraries (example: @coji/zodix) which detect version via feature checks. [8]

References

  • Zod versioning & subpath strategy. [1]
  • Zod v4 changelog / migration guide (breaking changes, error API). [3][5]
  • Notes on transforms / refinement behavior and v4 runtime issues. [6][3]
  • Community compatibility / tools (examples). [8]

If you want, I can give a tiny code snippet for each detection method matching your runtime (Node, browser, bundler).

🌐 Web query:

Zod official documentation for function schema API between v3 and v4

💡 Result:

Short summary — function-schema API changed from v3 → v4

  • Zod v3: z.function(...) returned a Zod schema (function "factory") you could use as a schema type. Common forms: z.function(argsTuple, returnSchema) or z.function().args(...).returns(...). It could be used like other schemas (e.g., .optional()). [1][2]

  • Zod v4: z.function(...) no longer returns a Zod schema — it is a standalone "function factory" for building runtime-validated functions. The API requires you define input/output up front (input/output shape on the factory) and you cannot treat the result as an ordinary schema (so patterns like using it inside object schemas or calling .optional() no longer work). Workarounds include wrapping the factory with a custom schema (or using $ZodFunction metadata) when you need a schema-like value. [1][2][3]

References

  • Zod v4 changelog / migration guide (explains function-schema redesign). [1]
  • GitHub discussion: "v4: what is the replacement for using z.function as a schema?" (design notes & examples). [2]
  • zod2md / community docs: suggested workaround to convert a v4 function factory into a schema-like value. [3]

Would you like concrete code examples showing the v3 usage, the direct v4 factory usage, and the recommended v4 workaround?

🏁 Script executed:

# Check if there are any other version detection patterns in the codebase
rg "version|v3|v4" packages/router-plugin/src/core/config.ts -A 2 -B 2

# Look for how Zod is used elsewhere to understand compatibility patterns
fd "\.ts$" packages/router-plugin/src -type f | head -10

Repository: TanStack/router

Length of output: 902

🌐 Web query:

Zod v4 function factory schema workaround how to use z.function in object schema

💡 Result:

Short answer: you can't embed z.function(...) directly inside a z.object in Zod v4 because z.function now returns a "function factory" (not a Zod schema). Use a plain runtime function-check schema (z.custom / z.instanceof / z.unknown().refine) for objects, and keep z.function for separately creating/validating implemented functions. (github.com)

Examples:

  • Simple runtime function field:

    • Using z.custom (keeps TypeScript typing via generics)
      const Fn = z.custom<(...a: any[]) => any>(v => typeof v === 'function');
      const Obj = z.object({ evaluate: Fn });

    • Using instanceof:
      const Obj2 = z.object({ evaluate: z.instanceof(Function) });

    • Using refine on unknown:
      const Obj3 = z.object({ evaluate: z.unknown().refine(v => typeof v === 'function', { message: 'must be function' }) });

  • If you want Zod-validated call semantics for a function, define that with z.function separately and use .implement() (or .validate()) to produce a runtime-validated function; but you cannot place that factory value as a nested schema inside z.object. Use the runtime-check field above and pair it with a separately-created validated function when needed. (odocs-zod.vercel.app)

If you want, tell me which pattern you prefer and I’ll produce a copy-paste example tailored to your types (sync/async, args/return).

Citations:

Rewrite for Zod v3/v4 compatibility and address type safety violations.

The current implementation has a critical architectural flaw: Zod v4's z.function() returns a function factory (not a schema) and cannot be used directly in object schemas with methods like .optional(). The try-catch silently masks this incompatibility.

Additionally:

  1. Version detection is unreliable: The _zod property check is an internal/unstable Zod API. Use feature detection instead (e.g., check for typeof z.treeifyError === 'function' or typeof z.toJSONSchema === 'function').

  2. v4 incompatibility: For Zod v4, use z.custom<(...args: any[]) => any>(v => typeof v === 'function') or z.unknown().refine(v => typeof v === 'function', ...) instead of the function factory.

  3. Type safety: Replace any return type and type casts with proper union types or version-specific schema definitions.

  4. Silent error handling: The try-catch (lines 27–29) hides real errors. Either remove it once detection is reliable, or log errors for debugging.

  5. Redundant check: The typeof (z as any).function === 'function' check on line 16 is unnecessary since z.function exists in both versions.

Consider separating schemas by version or using a workaround that's compatible with both APIs.


export const splitGroupingsSchema = z
.array(
z.array(
Expand Down Expand Up @@ -73,7 +96,7 @@ export type CodeSplittingOptions = {
}

const codeSplittingOptionsSchema = z.object({
splitBehavior: z.function().optional(),
splitBehavior: createGenericFunctionSchema().optional(),
defaultBehavior: splitGroupingsSchema.optional(),
deleteNodes: z.array(z.string()).optional(),
addHmr: z.boolean().optional().default(true),
Expand Down
2 changes: 1 addition & 1 deletion packages/start-plugin-core/package.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -80,7 +80,7 @@
"ufo": "^1.5.4",
"vitefu": "^1.1.1",
"xmlbuilder2": "^4.0.3",
"zod": "^3.24.2"
"zod": "^3.25.0 || ^4.0.0"
},
"devDependencies": {
"@types/babel__code-frame": "^7.0.6",
Expand Down
63 changes: 42 additions & 21 deletions packages/start-plugin-core/src/schema.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,33 @@ import { z } from 'zod'
import { configSchema, getConfig } from '@tanstack/router-plugin'
import type { TanStackStartVitePluginCoreOptions } from './types'

// Helper to create a function schema compatible with both Zod v3 and v4
function createFunctionSchema(
args: any,
returns: any,
): any {
// Try Zod v4 syntax first
if (typeof (z as any).function === 'function') {
try {
// Check if this is Zod v4 by testing for the new API
const testSchema = z.string()
if ('_zod' in testSchema) {
// Zod v4: use new function API
return (z as any).function({
input: Array.isArray(args) ? args : [args],
output: returns,
})
}
} catch (e) {
// Fall through to v3
}
}

// Zod v3: use old function API
const argsArray = Array.isArray(args) ? args : [args]
return (z as any).function().args(...argsArray).returns(returns)
}
Comment on lines +6 to +31
Copy link
Contributor

@coderabbitai coderabbitai bot Jan 7, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟠 Major

Same fragile detection mechanism and type safety concerns.

This helper has identical issues to the one in packages/router-generator/src/config.ts:

  1. Internal API dependency: Relies on undocumented _zod property for version detection.
  2. Type safety violation: Parameters and return type use any, which contradicts the coding guideline requiring "TypeScript strict mode with extensive type safety."
  3. Performance: Detection logic executes on every call without memoization.
  4. Error handling: Silent catch block could mask real errors.
🔎 Proposed improvement with better type safety 
+// Cache the Zod version detection
+let cachedIsZodV4: boolean | undefined
+
+function isZodV4(): boolean {
+  if (cachedIsZodV4 !== undefined) return cachedIsZodV4
+  
+  try {
+    // Test if v4 API is available
+    const testFn = (z as any).function({ input: [], output: z.string() })
+    cachedIsZodV4 = testFn !== undefined
+  } catch {
+    cachedIsZodV4 = false
+  }
+  return cachedIsZodV4
+}
+
-function createFunctionSchema(
-  args: any,
-  returns: any,
-): any {
+function createFunctionSchema<TArgs extends z.ZodTypeAny | z.ZodTypeAny[], TReturn extends z.ZodTypeAny>(
+  args: TArgs,
+  returns: TReturn,
+): z.ZodType<(...args: any[]) => any> {
-  // Try Zod v4 syntax first
-  if (typeof (z as any).function === 'function') {
-    try {
-      // Check if this is Zod v4 by testing for the new API
-      const testSchema = z.string()
-      if ('_zod' in testSchema) {
-        // Zod v4: use new function API
-        return (z as any).function({
-          input: Array.isArray(args) ? args : [args],
-          output: returns,
-        })
-      }
-    } catch (e) {
-      // Fall through to v3
-    }
-  }
-
-  // Zod v3: use old function API
+  if (isZodV4()) {
+    return (z as any).function({
+      input: Array.isArray(args) ? args : [args],
+      output: returns,
+    })
+  }
+  
   const argsArray = Array.isArray(args) ? args : [args]
   return (z as any).function().args(...argsArray).returns(returns)
 }

As per coding guidelines requiring TypeScript strict mode with extensive type safety.

🤖 Prompt for AI Agents 
In @packages/start-plugin-core/src/schema.ts around lines 6 - 31,
createFunctionSchema currently uses a fragile per-call detection via the
internal `_zod` property, accepts/returns `any`, and swallows errors; change it
to perform a one-time memoized feature detection (e.g., a module-level flag like
isZodV4Detected computed once by safe feature checks on `z`), avoid referencing
`_zod`, and replace `any` with proper generics and Zod types for `args`,
`returns`, and the function return type (use Zod's exported types such as
ZodTypeAny/ZodTuple/ZodFunction to express signatures). Update the detection
branch to use stable public feature checks on `z` (e.g., presence/type of
`z.function` and expected API shape) and ensure the catch block does not
silently swallow exceptions — surface or log the error and fall back to the v3
path explicitly. Keep the exported symbol `createFunctionSchema(args, returns)`
but change its signature to typed generics and memoized detection to fix
performance, safety, and error handling.


const tsrConfig = configSchema
.omit({ autoCodeSplitting: true, target: true, verboseFileRoutes: true })
.partial()
Expand Down Expand Up @@ -94,16 +121,13 @@ const pagePrerenderOptionsSchema = z.object({
crawlLinks: z.boolean().optional(),
retryCount: z.number().optional(),
retryDelay: z.number().optional(),
onSuccess: z
.function()
.args(
z.object({
page: pageBaseSchema,
html: z.string(),
}),
)
.returns(z.any())
.optional(),
onSuccess: createFunctionSchema(
z.object({
page: pageBaseSchema,
html: z.string(),
}),
z.any(),
).optional(),
headers: z.record(z.string(), z.string()).optional(),
})

Expand Down Expand Up @@ -159,16 +183,13 @@ const tanstackStartOptionsSchema = z
serverFns: z
.object({
base: z.string().optional().default('/_serverFn'),
generateFunctionId: z
.function()
.args(
z.object({
filename: z.string(),
functionName: z.string(),
}),
)
.returns(z.string().optional())
.optional(),
generateFunctionId: createFunctionSchema(
z.object({
filename: z.string(),
functionName: z.string(),
}),
z.string().optional(),
).optional(),
})
.optional()
.default({}),
Expand All @@ -184,7 +205,7 @@ const tanstackStartOptionsSchema = z
.object({
enabled: z.boolean().optional(),
concurrency: z.number().optional(),
filter: z.function().args(pageSchema).returns(z.any()).optional(),
filter: createFunctionSchema(pageSchema, z.any()).optional(),
failOnError: z.boolean().optional(),
autoStaticPathsDiscovery: z.boolean().optional(),
maxRedirects: z.number().min(0).optional(),
Expand Down