fix: generic env handling

[schiller-manuel]

Summary by CodeRabbit

• New Features

  • Added providerEnv option to configure a custom server environment for server functions

• Refactor

  • Improved plugin architecture to support per-environment configurations for client and server builds

[coderabbitai]

Walkthrough

Refactored the Vite plugin pipeline to support per-environment server function handling. The directive configuration is now dynamic via options. Plugins are generated per-environment rather than using a single multipurpose instance. A new providerEnv option allows customizing the server provider environment. Core plugin signatures updated to accept and propagate environment configurations throughout the compilation pipeline.

Changes

Cohort / File(s)	Summary
Directive Configuration packages/start-plugin-core/src/create-server-fn-plugin/handleCreateServerFn.ts	Changed the generated server-execute wrapper directive from hardcoded 'use server' to use the value of opts.directive, enabling dynamic directive specification.
Per-Environment Plugin Orchestration packages/start-plugin-core/src/create-server-fn-plugin/plugin.ts	Refactored from single plugin to per-environment plugin generator. Replaced Vite environment enum dependencies with per-environment configuration. Environment resolution now uses per-environment description (name and type) instead of global enum. Transform filters and module loading now reference per-environment code characteristics.
Main Plugin Configuration & Wiring packages/start-plugin-core/src/plugin.ts	Added providerEnv?: string option to serverFn config. Builds environments list dynamically and conditionally appends custom server environment. Refactored plugin invocation signatures to propagate environment array: startCompilerPlugin and createServerFnPlugin now accept environments parameter. Server function runtime environment selection now uses providerEnv with fallback to default.
Start Compiler Multi-Environment Plugin packages/start-plugin-core/src/start-compiler-plugin/plugin.ts	Converted from single plugin export to higher-order factory function. Introduced perEnvCompilerPlugin helper generating separate plugin objects per environment with environment-specific configuration. Transform filter consolidated into constant. Compilation pipeline now passes environment type to compiler and uses per-environment isolated transformation logic.

Sequence Diagram(s)

sequenceDiagram
    participant Vite as Vite
    participant Core as Main Plugin<br/>(plugin.ts)
    participant SC as StartCompiler<br/>Plugin
    participant SF as ServerFn<br/>Plugin
    participant Handler as handleCreateServerFn

    Vite->>Core: Init with options
    Note over Core: Build environments array<br/>(client, server, +custom if providerEnv)
    
    Core->>SC: startCompilerPlugin({framework, environments})
    Note over SC: Create per-env plugins
    SC->>SC: perEnvCompilerPlugin(client)
    SC->>SC: perEnvCompilerPlugin(server)
    
    Core->>SF: createServerFnPlugin({framework, directive, environments})
    Note over SF: Create per-env plugins
    SF->>SF: perEnvCompilerPlugin(client)
    SF->>SF: perEnvCompilerPlugin(server)
    
    Vite->>SC: Transform in client env
    Note over SC: Apply client-specific filters<br/>Environment type: 'client'
    
    Vite->>SC: Transform in server env
    Note over SC: Apply server-specific filters<br/>Environment type: 'server'
    
    Vite->>SF: Transform server function
    SF->>Handler: handleCreateServerFn
    Note over Handler: Generate wrapper with<br/>opts.directive (dynamic)

Loading

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~50 minutes

• create-server-fn-plugin/plugin.ts: Substantial refactoring with environment-aware orchestration, compiler map reorganization, and filter logic changes across multiple concerns (transform, handler, hotUpdate flows)
• plugin.ts: New option surface (providerEnv), environment list construction logic, and cascading signature changes affecting downstream plugin invocations
• start-compiler-plugin/plugin.ts: Factory pattern migration from single plugin to per-environment generator; requires careful understanding of how per-environment transformation isolation is achieved
• handleCreateServerFn.ts: Relatively straightforward, but coordinate understanding with directive flow from main plugin

Possibly related PRs

• TanStack/router#5712: Modifies server-function directive handling and wires configurable directive through the same create-server-fn compiler, evolving from hardcoded "use server" to parameterized directive.
• TanStack/router#5040: Directly implements the server-fn abstraction and per-environment server function handling via the same createServerFn and create-server-fn-plugin infrastructure.
• TanStack/router#5245: Introduces environment-aware plugin-per-env orchestration patterns, touching create-server-fn plugin and per-environment lookup/compile behavior.

Suggested labels

package: start-server-core, package: start-client-core

Poem

🐰 Environments now split and dance,
Per-env plugins get their chance,
Directives flow through options' grace,
No hardcoding in this place!
The server functions find their way,
With providerEnv leading the way.
Hop hop! 🎉

Pre-merge checks and finishing touches

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	You can run @coderabbitai generate docstrings to improve docstring coverage.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'fix: generic env handling' accurately describes the main objective of the PR, which introduces generic environment handling across multiple plugin files by replacing hardcoded environment dependencies with dynamic, per-environment configuration patterns.

✨ Finishing touches

• 📝 Generate docstrings

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch generic-env

---

📜 Recent review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 1b75808 and 1fcdd98.

📒 Files selected for processing (4)

• packages/start-plugin-core/src/create-server-fn-plugin/handleCreateServerFn.ts (1 hunks)
• packages/start-plugin-core/src/create-server-fn-plugin/plugin.ts (6 hunks)
• packages/start-plugin-core/src/plugin.ts (4 hunks)
• packages/start-plugin-core/src/start-compiler-plugin/plugin.ts (2 hunks)

🧰 Additional context used

📓 Path-based instructions (2)

**/*.{ts,tsx}

📄 CodeRabbit inference engine (AGENTS.md)

Use TypeScript in strict mode with extensive type safety across the codebase

Files:

• packages/start-plugin-core/src/create-server-fn-plugin/handleCreateServerFn.ts
• packages/start-plugin-core/src/create-server-fn-plugin/plugin.ts
• packages/start-plugin-core/src/start-compiler-plugin/plugin.ts
• packages/start-plugin-core/src/plugin.ts

packages/{*-start,start-*}/**

📄 CodeRabbit inference engine (AGENTS.md)

Name and place Start framework packages under packages/-start/ or packages/start-/

Files:

• packages/start-plugin-core/src/create-server-fn-plugin/handleCreateServerFn.ts
• packages/start-plugin-core/src/create-server-fn-plugin/plugin.ts
• packages/start-plugin-core/src/start-compiler-plugin/plugin.ts
• packages/start-plugin-core/src/plugin.ts

🧬 Code graph analysis (3)

packages/start-plugin-core/src/create-server-fn-plugin/plugin.ts (2)

packages/start-plugin-core/src/start-compiler-plugin/compilers.ts (1)

• CompileStartFrameworkOptions (18-18)

packages/start-plugin-core/src/create-server-fn-plugin/compiler.ts (1)

• ServerFnCompiler (56-504)

packages/start-plugin-core/src/start-compiler-plugin/plugin.ts (3)

packages/start-plugin-core/src/constants.ts (1)

• TRANSFORM_ID_REGEX (26-26)

packages/start-server-core/src/virtual-modules.ts (1)

• VIRTUAL_MODULES (1-5)

packages/start-plugin-core/src/start-compiler-plugin/compilers.ts (2)

• CompileStartFrameworkOptions (18-18)
• compileStartOutputFactory (22-172)

packages/start-plugin-core/src/plugin.ts (3)

packages/start-plugin-core/src/constants.ts (1)

• VITE_ENVIRONMENT_NAMES (1-6)

packages/start-plugin-core/src/start-compiler-plugin/plugin.ts (1)

• startCompilerPlugin (69-111)

packages/start-plugin-core/src/create-server-fn-plugin/plugin.ts (1)

• createServerFnPlugin (42-168)

🪛 ast-grep (0.39.9)

packages/start-plugin-core/src/create-server-fn-plugin/plugin.ts

[warning] 158-158: Regular expression constructed from variable input detected. This can lead to Regular Expression Denial of Service (ReDoS) attacks if the variable contains malicious patterns. Use libraries like 'recheck' to validate regex safety or use static patterns.
Context: new RegExp(${SERVER_FN_LOOKUP}$)
Note: [CWE-1333] Inefficient Regular Expression Complexity [REFERENCES]
- https://owasp.org/www-community/attacks/Regular_expression_Denial_of_Service_-_ReDoS
- https://cwe.mitre.org/data/definitions/1333.html

(regexp-from-variable)

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (4)

• GitHub Check: Preview
• GitHub Check: Test
• GitHub Check: Preview
• GitHub Check: Test

🔇 Additional comments (4)

packages/start-plugin-core/src/start-compiler-plugin/plugin.ts (1)

69-110: Per-environment compiler split looks solid. Mapping each plugin instance via applyToEnvironment keeps compilation scoped to the configured env while reusing the shared factory output.

packages/start-plugin-core/src/create-server-fn-plugin/handleCreateServerFn.ts (1)

149-150: Directive parameterization aligns with options. Passing opts.directive straight into the directive literal cleanly syncs the emitted wrapper with the caller-configured directive.

packages/start-plugin-core/src/create-server-fn-plugin/plugin.ts (1)

148-165: Shared capture plugin still covers dev ingestion. The applyToEnvironment guard now mirrors the expanded environments list so fetchModule continues to populate each env’s compiler cache during dev.

packages/start-plugin-core/src/plugin.ts (1)

109-121: Provider environment propagation wired correctly. Extending the environments array before invoking startCompilerPlugin and createServerFnPlugin keeps the optional providerEnv in lockstep with downstream transforms.

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[nx-cloud]

View your CI Pipeline Execution ↗ for commit 1fcdd98

Command	Status	Duration	Result
nx affected --targets=test:eslint,test:unit,tes...	✅ Succeeded	5m 38s	View ↗
nx run-many --target=build --exclude=examples/*...	✅ Succeeded	1s	View ↗

---

☁️ Nx Cloud last updated this comment at 2025-11-10 23:34:01 UTC

[pkg-pr-new]

More templates

• tanstack-router-solid-example-basic
• tanstack-router-solid-example-basic-devtools-panel
• tanstack-router-solid-example-basic-file-based
• tanstack-router-solid-example-basic-non-nested-devtools
• tanstack-router-solid-example-basic-solid-query
• tanstack-router-solid-example-basic-solid-query-file-based
• tanstack-router-solid-example-basic-ssr-streaming-file-based
• tanstack-router-solid-example-kitchen-sink-file-based
• tanstack-router-solid-example-kitchen-sink-solid-query
• tanstack-router-solid-example-kitchen-sink-solid-query-file-based
• tanstack-router-solid-example-quickstart-file-based
• tanstack-solid-start-example-bare
• tanstack-solid-start-example-basic
• tanstack-solid-start-example-basic-auth
• tanstack-solid-start-example-basic-cloudflare
• tanstack-solid-start-example-basic-netlify
• tanstack-solid-start-example-basic-nitro
• tanstack-start-example-basic-solid-query
• tanstack-solid-start-example-basic-static
• tanstack-solid-start-example-basic-supabase
• tanstack-solid-start-example-convex-better-auth
• tanstack-router-react-example-authenticated-routes
• tanstack-router-react-example-authenticated-routes-firebase
• tanstack-router-react-example-basic
• tanstack-router-react-example-basic-default-search-params
• tanstack-router-react-example-basic-devtools-panel
• tanstack-router-react-example-basic-file-based
• tanstack-router-react-example-basic-non-nested-devtools
• tanstack-router-react-example-react-query
• tanstack-router-react-example-basic-react-query-file-based
• tanstack-router-react-example-basic-ssr-file-based
• tanstack-router-react-example-basic-ssr-streaming-file-based
• tanstack-router-react-example-basic-virtual-file-based
• tanstack-router-react-example-basic-virtual-inside-file-based
• tanstack-router-react-example-deferred-data
• tanstack-router-i18n-paraglide
• tanstack-router-react-example-kitchen-sink
• tanstack-router-react-example-kitchen-sink-file-based
• tanstack-router-react-example-kitchen-sink-react-query
• tanstack-router-react-example-kitchen-sink-react-query-file-based
• tanstack-router-react-example-large-file-based
• tanstack-router-react-example-location-masking
• tanstack-router-react-example-navigation-blocking
• tanstack-router-react-example-quickstart
• tanstack-router-react-example-quickstart-esbuild-file-based
• tanstack-router-react-example-quickstart-file-based
• tanstack-router-react-example-quickstart-rspack-file-based
• tanstack-router-react-example-quickstart-webpack-file-based
• router-monorepo-react-query
• router-mono-simple
• router-mono-simple-lazy
• tanstack-router-react-example-scroll-restoration
• tanstack-search-validator-adapters
• tanstack-start-example-bare
• tanstack-start-example-basic
• tanstack-start-example-basic-auth
• tanstack-start-example-basic-cloudflare
• tanstack-start-example-basic-react-query
• tanstack-start-example-basic-static
• tanstack-start-bun-hosting
• tanstack-start-example-clerk-basic
• tanstack-start-example-convex-trellaux
• tanstack-start-example-counter
• tanstack-start-i18n-paraglide
• tanstack-start-example-large
• tanstack-start-example-material-ui
• tanstack-start-streaming-data-from-server-functions
• tanstack-start-example-supabase-basic
• tanstack-start-tailwind-v4
• tanstack-start-example-trellaux
• tanstack-start-example-workos
• tanstack-router-react-example-view-transitions
• tanstack-router-react-example-with-framer-motion
• tanstack-router-react-example-with-trpc
• tanstack-router-react-example-with-trpc-react-query

@tanstack/arktype-adapter

npm i https://pkg.pr.new/TanStack/router/@tanstack/arktype-adapter@5811

@tanstack/directive-functions-plugin

npm i https://pkg.pr.new/TanStack/router/@tanstack/directive-functions-plugin@5811

@tanstack/eslint-plugin-router

npm i https://pkg.pr.new/TanStack/router/@tanstack/eslint-plugin-router@5811

@tanstack/history

npm i https://pkg.pr.new/TanStack/router/@tanstack/history@5811

@tanstack/nitro-v2-vite-plugin

npm i https://pkg.pr.new/TanStack/router/@tanstack/nitro-v2-vite-plugin@5811

@tanstack/react-router

npm i https://pkg.pr.new/TanStack/router/@tanstack/react-router@5811

@tanstack/react-router-devtools

npm i https://pkg.pr.new/TanStack/router/@tanstack/react-router-devtools@5811

@tanstack/react-router-ssr-query

npm i https://pkg.pr.new/TanStack/router/@tanstack/react-router-ssr-query@5811

@tanstack/react-start

npm i https://pkg.pr.new/TanStack/router/@tanstack/react-start@5811

@tanstack/react-start-client

npm i https://pkg.pr.new/TanStack/router/@tanstack/react-start-client@5811

@tanstack/react-start-server

npm i https://pkg.pr.new/TanStack/router/@tanstack/react-start-server@5811

@tanstack/router-cli

npm i https://pkg.pr.new/TanStack/router/@tanstack/router-cli@5811

@tanstack/router-core

npm i https://pkg.pr.new/TanStack/router/@tanstack/router-core@5811

@tanstack/router-devtools

npm i https://pkg.pr.new/TanStack/router/@tanstack/router-devtools@5811

@tanstack/router-devtools-core

npm i https://pkg.pr.new/TanStack/router/@tanstack/router-devtools-core@5811

@tanstack/router-generator

npm i https://pkg.pr.new/TanStack/router/@tanstack/router-generator@5811

@tanstack/router-plugin

npm i https://pkg.pr.new/TanStack/router/@tanstack/router-plugin@5811

@tanstack/router-ssr-query-core

npm i https://pkg.pr.new/TanStack/router/@tanstack/router-ssr-query-core@5811

@tanstack/router-utils

npm i https://pkg.pr.new/TanStack/router/@tanstack/router-utils@5811

@tanstack/router-vite-plugin

npm i https://pkg.pr.new/TanStack/router/@tanstack/router-vite-plugin@5811

@tanstack/server-functions-plugin

npm i https://pkg.pr.new/TanStack/router/@tanstack/server-functions-plugin@5811

@tanstack/solid-router

npm i https://pkg.pr.new/TanStack/router/@tanstack/solid-router@5811

@tanstack/solid-router-devtools

npm i https://pkg.pr.new/TanStack/router/@tanstack/solid-router-devtools@5811

@tanstack/solid-router-ssr-query

npm i https://pkg.pr.new/TanStack/router/@tanstack/solid-router-ssr-query@5811

@tanstack/solid-start

npm i https://pkg.pr.new/TanStack/router/@tanstack/solid-start@5811

@tanstack/solid-start-client

npm i https://pkg.pr.new/TanStack/router/@tanstack/solid-start-client@5811

@tanstack/solid-start-server

npm i https://pkg.pr.new/TanStack/router/@tanstack/solid-start-server@5811

@tanstack/start-client-core

npm i https://pkg.pr.new/TanStack/router/@tanstack/start-client-core@5811

@tanstack/start-plugin-core

npm i https://pkg.pr.new/TanStack/router/@tanstack/start-plugin-core@5811

@tanstack/start-server-core

npm i https://pkg.pr.new/TanStack/router/@tanstack/start-server-core@5811

@tanstack/start-static-server-functions

npm i https://pkg.pr.new/TanStack/router/@tanstack/start-static-server-functions@5811

@tanstack/start-storage-context

npm i https://pkg.pr.new/TanStack/router/@tanstack/start-storage-context@5811

@tanstack/valibot-adapter

npm i https://pkg.pr.new/TanStack/router/@tanstack/valibot-adapter@5811

@tanstack/virtual-file-routes

npm i https://pkg.pr.new/TanStack/router/@tanstack/virtual-file-routes@5811

@tanstack/zod-adapter

npm i https://pkg.pr.new/TanStack/router/@tanstack/zod-adapter@5811

commit: 1fcdd98