refactor: start compiler (#5014)

Author: schiller-manuel

docs/start/framework/react/how-to/write-isomorphic-client-server-code.md

@@ -35,13 +35,13 @@ export const Route = createFileRoute('/products')({
 
 ### Server-Only APIs
 
-| API                | Use Case                  | Client Behavior           |
-| ------------------ | ------------------------- | ------------------------- |
-| `createServerFn()` | RPC calls, data mutations | Network request to server |
-| `serverOnly(fn)`   | Utility functions         | Throws error              |
+| API                      | Use Case                  | Client Behavior           |
+| ------------------------ | ------------------------- | ------------------------- |
+| `createServerFn()`       | RPC calls, data mutations | Network request to server |
+| `createServerOnlyFn(fn)` | Utility functions         | Throws error              |
 
 ```tsx
-import { createServerFn, serverOnly } from '@tanstack/react-start'
+import { createServerFn, createServerOnlyFn } from '@tanstack/react-start'
 
 // RPC: Server execution, callable from client
 const updateUser = createServerFn({ method: 'POST' })
@@ -52,22 +52,22 @@ const updateUser = createServerFn({ method: 'POST' })
   })
 
 // Utility: Server-only, client crashes if called
-const getEnvVar = serverOnly(() => process.env.DATABASE_URL)
+const getEnvVar = createServerOnlyFn(() => process.env.DATABASE_URL)
 ```
 
 ### Client-Only APIs
 
-| API              | Use Case                        | Server Behavior  |
-| ---------------- | ------------------------------- | ---------------- |
-| `clientOnly(fn)` | Browser utilities               | Throws error     |
-| `<ClientOnly>`   | Components needing browser APIs | Renders fallback |
+| API                      | Use Case                        | Server Behavior  |
+| ------------------------ | ------------------------------- | ---------------- |
+| `createClientOnlyFn(fn)` | Browser utilities               | Throws error     |
+| `<ClientOnly>`           | Components needing browser APIs | Renders fallback |
 
 ```tsx
-import { clientOnly } from '@tanstack/react-start'
+import { createClientOnlyFn } from '@tanstack/react-start'
 import { ClientOnly } from '@tanstack/react-router'
 
 // Utility: Client-only, server crashes if called
-const saveToStorage = clientOnly((key: string, value: any) => {
+const saveToStorage = createClientOnlyFn((key: string, value: any) => {
   localStorage.setItem(key, JSON.stringify(value))
 })
 
@@ -96,7 +96,7 @@ const getDeviceInfo = createIsomorphicFn()
 
 ## Key Distinctions
 
-### `createServerFn()` vs `serverOnly()`
+### `createServerFn()` vs `createServerOnlyFn()`
 
 ```tsx
 // createServerFn: RPC pattern - server execution, client callable
@@ -105,8 +105,8 @@ const fetchUser = createServerFn().handler(async () => await db.users.find())
 // Usage from client component:
 const user = await fetchUser() // ✅ Network request
 
-// serverOnly: Crashes if called from client
-const getSecret = serverOnly(() => process.env.SECRET)
+// createServerOnlyFn: Crashes if called from client
+const getSecret = createServerOnlyFn(() => process.env.SECRET)
 
 // Usage from client:
 const secret = getSecret() // ❌ Throws error
@@ -182,7 +182,7 @@ const storage = createIsomorphicFn()
 const apiKey = process.env.SECRET_KEY
 
 // ✅ Server-only access
-const apiKey = serverOnly(() => process.env.SECRET_KEY)
+const apiKey = createServerOnlyFn(() => process.env.SECRET_KEY)
 ```
 
 ### Incorrect Loader Assumptions
@@ -233,7 +233,7 @@ function CurrentTime() {
 ## Production Checklist
 
 - [ ] **Bundle Analysis**: Verify server-only code isn't in client bundle
-- [ ] **Environment Variables**: Ensure secrets use `serverOnly()` or `createServerFn()`
+- [ ] **Environment Variables**: Ensure secrets use `createServerOnlyFn()` or `createServerFn()`
 - [ ] **Loader Logic**: Remember loaders are isomorphic, not server-only
 - [ ] **ClientOnly Fallbacks**: Provide appropriate fallbacks to prevent layout shift
 - [ ] **Error Boundaries**: Handle server/client execution errors gracefully

e2e/react-start/server-functions/src/routes/env-only.tsx

@@ -1,9 +1,13 @@
 import { createFileRoute } from '@tanstack/react-router'
-import { clientOnly, createServerFn, serverOnly } from '@tanstack/react-start'
+import {
+  createClientOnlyFn,
+  createServerFn,
+  createServerOnlyFn,
+} from '@tanstack/react-start'
 import { useState } from 'react'
 
-const serverEcho = serverOnly((input: string) => 'server got: ' + input)
-const clientEcho = clientOnly((input: string) => 'client got: ' + input)
+const serverEcho = createServerOnlyFn((input: string) => 'server got: ' + input)
+const clientEcho = createClientOnlyFn((input: string) => 'client got: ' + input)
 
 const testOnServer = createServerFn().handler(() => {
   const serverOnServer = serverEcho('hello')

e2e/react-start/server-functions/tests/server-functions.spec.ts

@@ -119,11 +119,11 @@ test('env-only functions can only be called on the server or client respectively
     'server got: hello',
   )
   await expect(page.getByTestId('server-on-client')).toContainText(
-    'serverEcho threw an error: serverOnly() functions can only be called on the server!',
+    'serverEcho threw an error: createServerOnlyFn() functions can only be called on the server!',
   )
 
   await expect(page.getByTestId('client-on-server')).toContainText(
-    'clientEcho threw an error: clientOnly() functions can only be called on the client!',
+    'clientEcho threw an error: createClientOnlyFn() functions can only be called on the client!',
   )
   await expect(page.getByTestId('client-on-client')).toContainText(
     'client got: hello',

e2e/solid-start/server-functions/src/routes/env-only.tsx

@@ -1,9 +1,13 @@
 import { createFileRoute } from '@tanstack/solid-router'
-import { clientOnly, createServerFn, serverOnly } from '@tanstack/solid-start'
+import {
+  createClientOnlyFn,
+  createServerFn,
+  createServerOnlyFn,
+} from '@tanstack/solid-start'
 import { createSignal } from 'solid-js'
 
-const serverEcho = serverOnly((input: string) => 'server got: ' + input)
-const clientEcho = clientOnly((input: string) => 'client got: ' + input)
+const serverEcho = createServerOnlyFn((input: string) => 'server got: ' + input)
+const clientEcho = createClientOnlyFn((input: string) => 'client got: ' + input)
 
 const testOnServer = createServerFn().handler(() => {
   const serverOnServer = serverEcho('hello')

e2e/solid-start/server-functions/tests/server-functions.spec.ts

@@ -117,11 +117,11 @@ test('env-only functions can only be called on the server or client respectively
     'server got: hello',
   )
   await expect(page.getByTestId('server-on-client')).toContainText(
-    'serverEcho threw an error: serverOnly() functions can only be called on the server!',
+    'serverEcho threw an error: createServerOnlyFn() functions can only be called on the server!',
   )
 
   await expect(page.getByTestId('client-on-server')).toContainText(
-    'clientEcho threw an error: clientOnly() functions can only be called on the client!',
+    'clientEcho threw an error: createClientOnlyFn() functions can only be called on the client!',
   )
   await expect(page.getByTestId('client-on-client')).toContainText(
     'client got: hello',

packages/react-start-client/src/index.tsx

@@ -5,8 +5,8 @@ export {
   createMiddleware,
   registerGlobalMiddleware,
   globalMiddleware,
-  serverOnly,
-  clientOnly,
+  createServerOnlyFn,
+  createClientOnlyFn,
   json,
   createClientRpc,
 } from '@tanstack/start-client-core'

packages/solid-start-client/src/index.tsx

@@ -5,8 +5,8 @@ export {
   createMiddleware,
   registerGlobalMiddleware,
   globalMiddleware,
-  serverOnly,
-  clientOnly,
+  createServerOnlyFn,
+  createClientOnlyFn,
   json,
   createClientRpc,
 } from '@tanstack/start-client-core'

packages/start-client-core/src/envOnly.ts

@@ -2,8 +2,8 @@ type EnvOnlyFn = <TFn extends (...args: Array<any>) => any>(fn: TFn) => TFn
 
 // A function that will only be available in the server build
 // If called on the client, it will throw an error
-export const serverOnly: EnvOnlyFn = (fn) => fn
+export const createServerOnlyFn: EnvOnlyFn = (fn) => fn
 
 // A function that will only be available in the client build
 // If called on the server, it will throw an error
-export const clientOnly: EnvOnlyFn = (fn) => fn
+export const createClientOnlyFn: EnvOnlyFn = (fn) => fn

packages/start-client-core/src/index.tsx

@@ -21,7 +21,7 @@ export {
   type ClientOnlyFn,
   type IsomorphicFnBase,
 } from './createIsomorphicFn'
-export { serverOnly, clientOnly } from './envOnly'
+export { createServerOnlyFn, createClientOnlyFn } from './envOnly'
 export { createServerFn } from './createServerFn'
 export {
   createMiddleware,

packages/start-client-core/src/tests/envOnly.test-d.ts

@@ -1,5 +1,5 @@
 import { expectTypeOf, test } from 'vitest'
-import { clientOnly, serverOnly } from '../envOnly'
+import { createClientOnlyFn, createServerOnlyFn } from '../envOnly'
 
 const inputFn = () => 'output'
 
@@ -11,24 +11,24 @@ function overloadedFn(input: any) {
   return input
 }
 
-test("clientOnly returns the function it's given", () => {
-  const outputFn = clientOnly(inputFn)
+test("createClientOnlyFn returns the function it's given", () => {
+  const outputFn = createClientOnlyFn(inputFn)
   expectTypeOf(outputFn).toEqualTypeOf<typeof inputFn>()
 
-  const genericOutputFn = clientOnly(genericInputFn)
+  const genericOutputFn = createClientOnlyFn(genericInputFn)
   expectTypeOf(genericOutputFn).toEqualTypeOf<typeof genericInputFn>()
 
-  const overloadedOutputFn = clientOnly(overloadedFn)
+  const overloadedOutputFn = createClientOnlyFn(overloadedFn)
   expectTypeOf(overloadedOutputFn).toEqualTypeOf<typeof overloadedFn>()
 })
 
-test("serverOnly returns the function it's given", () => {
-  const outputFn = serverOnly(inputFn)
+test("createServerOnlyFn returns the function it's given", () => {
+  const outputFn = createServerOnlyFn(inputFn)
   expectTypeOf(outputFn).toEqualTypeOf<typeof inputFn>()
 
-  const genericOutputFn = serverOnly(genericInputFn)
+  const genericOutputFn = createServerOnlyFn(genericInputFn)
   expectTypeOf(genericOutputFn).toEqualTypeOf<typeof genericInputFn>()
 
-  const overloadedOutputFn = serverOnly(overloadedFn)
+  const overloadedOutputFn = createServerOnlyFn(overloadedFn)
   expectTypeOf(overloadedOutputFn).toEqualTypeOf<typeof overloadedFn>()
 })