-
-
Notifications
You must be signed in to change notification settings - Fork 1.2k
docs(start): createIsomorphicFn and envOnly #4806
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.
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
Conversation
a675dae
to
9cab129
Compare
### Complete Implementation | ||
|
||
```tsx | ||
const getEnv = createIsomorphicFn() |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
make those snippets complete by adding the import from '@tanstack/solid-start'
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
applies to all examples
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Done
@@ -0,0 +1,3 @@ | |||
--- |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
once we have settled on the text for react, please duplicate and change the imports to point to solid
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
@hokkyss see the docs in docs/router/framework/solid/devtools.md
which have a syntax for performing text replacements on the ref
doc. So you shouldn't need to duplicate the entire document.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Understood. Updated guys. Thank you
@@ -98,7 +98,7 @@ response?: 'data' | 'full' | 'raw' | |||
- From other server functions | |||
|
|||
> [!WARNING] | |||
> Server functions cannot be called from API Routes. If you need to share business logic between server functions and API Routes, extract the shared logic into utility functions that can be imported by both. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
i think we can now call server functions from API routes. please check and and if true, this text can be removed
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
@schiller-manuel is right. API routes as a whole became the new "Server Routes" which support calling Server Function.
This warning can be removed.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Noted, this is deleted
we also got those docs recently: b402bbc maybe just improve those where needed? |
@@ -98,7 +98,7 @@ response?: 'data' | 'full' | 'raw' | |||
- From other server functions | |||
|
|||
> [!WARNING] | |||
> Server functions cannot be called from API Routes. If you need to share business logic between server functions and API Routes, extract the shared logic into utility functions that can be imported by both. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
@schiller-manuel is right. API routes as a whole became the new "Server Routes" which support calling Server Function.
This warning can be removed.
@@ -0,0 +1,3 @@ | |||
--- |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
@hokkyss see the docs in docs/router/framework/solid/devtools.md
which have a syntax for performing text replacements on the ref
doc. So you shouldn't need to duplicate the entire document.
Use `createIsomorphicFn()` to define functions that behave differently depending on whether they are called on the client or the server. This is useful for safely sharing logic across environments while delegating environment-specific behavior to appropriate handlers. | ||
|
||
> [!WARNING] | ||
> Unimplemented function results in a no-op function. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Maybe instead of a warning, this could be a small heading like "What is a no-op?", that'd show the user the type of a no-op.
Perhaps something like this:
type NoOpFunction = () => undefined // add a comment here
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Thank you!
I have added an explanation at the end of createIsomorphicFn
as h4
docs/start/config.json
Outdated
@@ -122,6 +126,10 @@ | |||
"label": "Static Server Functions", | |||
"to": "framework/solid/static-server-functions" | |||
}, | |||
{ | |||
"label": "Environment Functions", | |||
"to": "framework/react/environment-functions" |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
"to": "framework/react/environment-functions" | |
"to": "framework/solid/environment-functions" |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Thank you! Updated.
9f6952d
to
f464374
Compare
WalkthroughAdds React and Solid "Environment Functions" documentation and navigation entries; introduces a React doc describing createIsomorphicFn, serverOnly, and clientOnly; Solid's page references the React doc via YAML front matter; removes a warning and two bullets from the React server-functions doc. Changes
Sequence Diagram(s)sequenceDiagram
participant App as Application Code
participant Iso as createIsomorphicFn
participant Server as Server runtime
participant Client as Client runtime
Note over App,Iso: Define isomorphic function with .server() and .client()
App->>Iso: invoke()
alt Running on Server
Iso->>Server: call server implementation
Server-->>App: return server result
else Running on Client
Iso->>Client: call client implementation
Client-->>App: return client result
end
Estimated code review effort🎯 2 (Simple) | ⏱️ ~10 minutes Poem
✨ Finishing Touches🧪 Generate unit tests
🪧 TipsChatThere are 3 ways to chat with CodeRabbit:
SupportNeed help? Create a ticket on our support page for assistance with any issues or questions. CodeRabbit Commands (Invoked using PR/Issue comments)Type Other keywords and placeholders
CodeRabbit Configuration File (
|
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Actionable comments posted: 0
🧹 Nitpick comments (11)
docs/start/config.json (1)
44-47
: Optional: Consider renaming “Environment Functions” to “Isomorphic Utilities”Since the PR description questions the naming, “Isomorphic Utilities” (or “Environment-aware Utilities”) may better convey the intent without implying only functions. If you prefer this, we should update both the page titles and these nav labels together.
Also applies to: 129-132
docs/start/framework/react/environment-functions.md (9)
10-15
: Grammar: “Start provides”Subject-verb agreement and light copy tweaks.
-Start provide three core environment functions: +Start provides three core environment functions:
45-48
: Grammar: “a no-op” and punctuationClarify the client behavior phrasing.
-// ℹ️ On the **client**, it is no-op (returns `undefined`) +// ℹ️ On the **client**, it is a no-op (returns `undefined`).
59-62
: Grammar: “a no-op” and punctuationSame tweak for the server-side note.
-// ℹ️ On the **server**, it is no-op (returns `undefined`) +// ℹ️ On the **server**, it is a no-op (returns `undefined`).
73-75
: Grammar: “a no-op” and punctuationApply the same phrasing/punctuation for consistency.
-// ℹ️ On both **client** and **server**, it is no-op (returns `undefined`) +// ℹ️ On both **client** and **server**, it is a no-op (returns `undefined`).
88-91
: Fix heading: backticks and casingCurrent “##
env
Only Functions” renders oddly. Prefer plain language.-## `env`Only Functions +## Environment-only Functions
117-123
: Tree-shaking section: wording and clarityMinor grammar improvements and clearer phrasing.
-Environment functions are tree-shaken based on the environment for each bundle produced. +Environment functions are tree-shaken per environment for each produced bundle. -Functions created using `createIsomorphicFn()` are tree-shaken. All codes inside `.client()` are not included in server bundle, and vice-versa. +Functions created using `createIsomorphicFn()` are tree-shaken. All code inside `.client()` is excluded from the server bundle, and vice versa. -On the server, implementation of `clientOnly` functions are replaced with a function that throws an `Error`. The reverse is true for `serverOnly` functions on the client. +In the server bundle, `clientOnly` implementations are replaced with a function that throws an `Error`. The reverse is true for `serverOnly` functions in the client bundle.
79-85
: TS typing for no-op exampleIf we want to be explicit for TypeScript users, “void” is the idiomatic return type for a no-op (you can still note that it evaluates to
undefined
at runtime).-// basic no-op implementation -function noop() {} +// basic no-op implementation (TypeScript) +const noop: () => void = () => {}
99-112
: Avoid locking docs to exact error message stringsThe quoted error texts might diverge from implementation over time. Suggest describing the behavior generically or quoting less rigidly (e.g., “throws an error on the client/server”).
Would you like me to replace the exact strings with a generic description, or verify the current runtime messages in the codebase to keep them accurate?
1-4
: Optional: Page title namingIf you decide to rename the nav label (e.g., to “Isomorphic Utilities”), mirror it here for consistency.
-title: Environment Functions +title: Isomorphic Utilitiesdocs/start/framework/solid/environment-functions.md (1)
1-4
: Consider adding a capitalized replacement and validate scopeIf the source doc contains “React” (capitalized) or other proper nouns, also add a case-sensitive replacement to ensure titles and prose read naturally for Solid. Example:
--- ref: docs/start/framework/react/environment-functions.md -replace: { 'react': 'solid' } +replace: + { + 'react': 'solid', + 'React': 'Solid' + } ---Also, confirm the replacement mechanism applies to code blocks as intended (e.g., it should convert
@tanstack/react-start
to@tanstack/solid-start
without affecting unrelated identifiers).
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
💡 Knowledge Base configuration:
- MCP integration is disabled by default for public repositories
- Jira integration is disabled by default for public repositories
- Linear integration is disabled by default for public repositories
You can enable these sources in your CodeRabbit configuration.
📒 Files selected for processing (4)
docs/start/config.json
(2 hunks)docs/start/framework/react/environment-functions.md
(1 hunks)docs/start/framework/react/server-functions.md
(0 hunks)docs/start/framework/solid/environment-functions.md
(1 hunks)
💤 Files with no reviewable changes (1)
- docs/start/framework/react/server-functions.md
🧰 Additional context used
🪛 LanguageTool
docs/start/framework/solid/environment-functions.md
[grammar] ~1-~1: Hier könnte ein Fehler sein.
Context: --- ref: docs/start/framework/react/environment-functions.md replace: { 'react': 'solid' } ---
(QB_NEW_DE)
docs/start/framework/react/environment-functions.md
[grammar] ~12-~12: There might be a mistake here.
Context: ... to both client and server environments. - serverOnly
: Ensures a function can only run on the...
(QB_NEW_EN)
[grammar] ~114-~114: There might be a mistake here.
Context: ...be called on the client!" ``` > [!NOTE] > These functions are useful for API acc...
(QB_NEW_EN)
[grammar] ~121-~121: There might be a mistake here.
Context: ...des inside .client()
are not included in server bundle, and vice-versa. On the ...
(QB_NEW_EN)
🔇 Additional comments (3)
docs/start/config.json (2)
44-47
: Nav entry for React looks goodThe route slug matches the new doc file and placement (after Static Server Functions) is consistent.
129-132
: Nav entry for Solid looks goodSlug matches the Solid doc and mirrors the React placement.
docs/start/framework/solid/environment-functions.md (1)
1-4
: Front matter approach looks goodUsing ref + replace keeps the content DRY across frameworks.
View your CI Pipeline Execution ↗ for commit 8ac6f28
☁️ Nx Cloud last updated this comment at |
More templates
@tanstack/arktype-adapter
@tanstack/directive-functions-plugin
@tanstack/eslint-plugin-router
@tanstack/history
@tanstack/react-router
@tanstack/react-router-devtools
@tanstack/react-router-ssr-query
@tanstack/react-start
@tanstack/react-start-client
@tanstack/react-start-plugin
@tanstack/react-start-server
@tanstack/router-cli
@tanstack/router-core
@tanstack/router-devtools
@tanstack/router-devtools-core
@tanstack/router-generator
@tanstack/router-plugin
@tanstack/router-ssr-query-core
@tanstack/router-utils
@tanstack/router-vite-plugin
@tanstack/server-functions-plugin
@tanstack/solid-router
@tanstack/solid-router-devtools
@tanstack/solid-start
@tanstack/solid-start-client
@tanstack/solid-start-plugin
@tanstack/solid-start-server
@tanstack/start-client-core
@tanstack/start-plugin-core
@tanstack/start-server-core
@tanstack/start-server-functions-client
@tanstack/start-server-functions-fetcher
@tanstack/start-server-functions-server
@tanstack/start-storage-context
@tanstack/valibot-adapter
@tanstack/virtual-file-routes
@tanstack/zod-adapter
commit: |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Actionable comments posted: 0
♻️ Duplicate comments (1)
docs/start/framework/solid/environment-functions.md (1)
1-4
: Good use of ref/replace to avoid duplication.The Solid doc correctly references the React doc and applies a replacement. This follows the prior guidance to avoid duplication.
🧹 Nitpick comments (10)
docs/start/framework/solid/environment-functions.md (1)
1-4
: Broaden replace mapping to handle case and future-proof wording.If the source doc ever uses "React" (capitalized), it won’t be replaced. Consider extending the mapping.
--- ref: docs/start/framework/react/environment-functions.md -replace: { 'react': 'solid' } +replace: { 'react': 'solid', 'React': 'Solid' } ---Please confirm the docs build system’s replace semantics are token-based (not substring-only) to avoid accidental replacements inside unrelated words.
docs/start/framework/react/environment-functions.md (9)
10-15
: Grammar and clarity: subject-verb agreement and naming.-Start provide three core environment functions: +React Start provides three core environment functions:
36-48
: Tighten “no-op” phrasing and punctuation.-// ℹ️ On the **client**, it is no-op (returns `undefined`) +// ℹ️ On the **client**, it's a no-op (returns `undefined`).
50-62
: Mirror the “no-op” phrasing for consistency.-// ℹ️ On the **server**, it is no-op (returns `undefined`) +// ℹ️ On the **server**, it's a no-op (returns `undefined`).
64-76
: Hyphenate compound modifier and add terminal punctuation.-Here is an example of `createIsomorphicFn()` without any environment specific implementation: +Here is an example of `createIsomorphicFn()` without any environment-specific implementation: @@ -// ℹ️ On both **client** and **server**, it is no-op (returns `undefined`) +// ℹ️ On both **client** and **server**, it's a no-op (returns `undefined`).
77-85
: Type hint for no-op in TS.In TS, an explicit
void
return improves clarity.-// basic no-op implementation -function noop() {} +// basic no-op implementation +const noop: () => void = () => {}
88-90
: Rename section header for readability.-## `env`Only Functions +## Environment-only helpers
99-101
: Avoid hard-coding exact error message text unless guaranteed stable.Prefer generic wording to prevent drift if messages change.
-// ❌ On client: throws "serverOnly() functions can only be called on the server!" +// ❌ On client: throws an Error.If the exact message is stable and tested, feel free to keep it—otherwise consider the generic phrasing.
110-112
: Mirror error-message guidance for clientOnly.-// ❌ On server: throws "clientOnly() functions can only be called on the client!" +// ❌ On server: throws an Error.
117-123
: Tree-shaking copy edits and singular “code”.-## Tree Shaking +## Tree-shaking @@ -Environment functions are tree-shaken based on the environment for each bundle produced. +Environment functions are tree-shaken per environment for each bundle produced. @@ -Functions created using `createIsomorphicFn()` are tree-shaken. All codes inside `.client()` are not included in server bundle, and vice-versa. +Functions created using `createIsomorphicFn()` are tree-shaken. All code inside `.client()` is excluded from the server bundle, and vice versa. @@ -On the server, implementation of `clientOnly` functions are replaced with a function that throws an `Error`. The reverse is true for `serverOnly` functions on the client. +On the server, the implementation of `clientOnly` functions is replaced with a function that throws an `Error`. The reverse is true for `serverOnly` functions on the client.
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
💡 Knowledge Base configuration:
- MCP integration is disabled by default for public repositories
- Jira integration is disabled by default for public repositories
- Linear integration is disabled by default for public repositories
You can enable these sources in your CodeRabbit configuration.
📒 Files selected for processing (4)
docs/start/config.json
(2 hunks)docs/start/framework/react/environment-functions.md
(1 hunks)docs/start/framework/react/server-functions.md
(0 hunks)docs/start/framework/solid/environment-functions.md
(1 hunks)
💤 Files with no reviewable changes (1)
- docs/start/framework/react/server-functions.md
🚧 Files skipped from review as they are similar to previous changes (1)
- docs/start/config.json
🧰 Additional context used
🪛 LanguageTool
docs/start/framework/react/environment-functions.md
[grammar] ~12-~12: There might be a mistake here.
Context: ... to both client and server environments. - serverOnly
: Ensures a function can only run on the...
(QB_NEW_EN)
[grammar] ~114-~114: There might be a mistake here.
Context: ...be called on the client!" ``` > [!NOTE] > These functions are useful for API acc...
(QB_NEW_EN)
[grammar] ~121-~121: There might be a mistake here.
Context: ...des inside .client()
are not included in server bundle, and vice-versa. On the ...
(QB_NEW_EN)
docs/start/framework/solid/environment-functions.md
[grammar] ~1-~1: Hier könnte ein Fehler sein.
Context: --- ref: docs/start/framework/react/environment-functions.md replace: { 'react': 'solid' } ---
(QB_NEW_DE)
🔇 Additional comments (2)
docs/start/framework/react/environment-functions.md (2)
24-34
: Examples look good.Clear server/client behavior; code imports are present and consistent.
94-112
: Great, focused examples for serverOnly/clientOnly.Concise and accurate usage guidance.
Please confirm the import path and symbol names (
createIsomorphicFn
,serverOnly
,clientOnly
) match the published API in@tanstack/react-start
.
Add docs for
createIsomorphicFn
,serverOnly
, andclientOnly
.I am not quite sure whether "environment functions" is a good name though
Summary by CodeRabbit