docs(examples): add serialization documentation to Supabase example #5685
Conversation
Add comprehensive documentation explaining server function serialization requirements when using Supabase with TanStack Start. Changes: - Add README.md with setup guide and serialization best practices - Add 40+ line JSDoc comment in __root.tsx explaining serialization constraints - Improve error handling (log errors instead of suppressing with _error) - Add inline examples showing correct vs incorrect patterns - Add commented examples for safely adding more user fields Fixes TanStack#3831 The code in the Supabase example is functionally correct, but lacked documentation explaining the serialization requirements for server functions. This caused confusion for developers who wanted to return additional user fields from Supabase. This PR helps developers understand: - Why only primitive values can be returned from server functions - What Supabase user objects contain (non-serializable data) - How to safely add more fields - Common errors and their solutions Testing: - Verified with real Supabase credentials - Confirmed no hydration errors exist - Confirmed no serialization errors in current implementation - Code pattern is correct, documentation was missing 🤖 Generated with Claude Code Co-Authored-By: Claude <[email protected]>
WalkthroughAdds a README for the TanStack Start + Supabase Basic example and updates the root route to enforce server-function serialization, narrow returned user data to primitives, and add explicit error handling in the Changes
Sequence Diagram(s)sequenceDiagram
participant Client
participant Route as __root.tsx
participant ServerClient as getSupabaseServerClient
participant Supabase as Supabase API
Client->>Route: Request page / load
Route->>ServerClient: getSupabaseServerClient() (no await required)
ServerClient->>Supabase: check session / fetch auth data
Supabase-->>ServerClient: returns session & user (may include non-serializable fields)
ServerClient->>Route: raw data.user
Note right of Route `#DDEBF7`: fetchUser filters to primitives\nreturns serializable object or null on error
Route-->>Client: serialized user object or null
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~20 minutes
Suggested labels
Suggested reviewers
Poem
Pre-merge checks and finishing touches✅ Passed checks (5 passed)
✨ Finishing touches🧪 Generate unit tests (beta)
📜 Recent review detailsConfiguration used: CodeRabbit UI Review profile: CHILL Plan: Pro 📒 Files selected for processing (1)
🚧 Files skipped from review as they are similar to previous changes (1)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Nitpick comments (2)
examples/react/start-supabase-basic/README.md (2)
7-12: Fix markdown linting issues in setup section.The bare URL and code block without language specifier trigger markdown linting warnings. While these don't affect functionality, addressing them improves documentation consistency.
Apply this diff:
-1. Create a Supabase project at https://supabase.com +1. Create a Supabase project at [Supabase](https://supabase.com) 2. Copy `.env` and fill in your Supabase credentials: - ``` + ```bash SUPABASE_URL=your-project-url SUPABASE_ANON_KEY=your-anon-key ```
100-100: Add language specifier to project structure code block.Apply this diff:
-``` +```text src/ ├── routes/
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (2)
examples/react/start-supabase-basic/README.md(1 hunks)examples/react/start-supabase-basic/src/routes/__root.tsx(1 hunks)
🧰 Additional context used
📓 Path-based instructions (3)
examples/{react,solid}/**
📄 CodeRabbit inference engine (AGENTS.md)
Keep example applications under examples/react/ and examples/solid/
Files:
examples/react/start-supabase-basic/README.mdexamples/react/start-supabase-basic/src/routes/__root.tsx
**/*.{ts,tsx}
📄 CodeRabbit inference engine (AGENTS.md)
Use TypeScript in strict mode with extensive type safety across the codebase
Files:
examples/react/start-supabase-basic/src/routes/__root.tsx
**/src/routes/**
📄 CodeRabbit inference engine (AGENTS.md)
Place file-based routes under src/routes/ directories
Files:
examples/react/start-supabase-basic/src/routes/__root.tsx
🧬 Code graph analysis (1)
examples/react/start-supabase-basic/src/routes/__root.tsx (1)
examples/react/start-supabase-basic/src/utils/supabase.ts (1)
getSupabaseServerClient(4-24)
🪛 markdownlint-cli2 (0.18.1)
examples/react/start-supabase-basic/README.md
7-7: Bare URL used
(MD034, no-bare-urls)
9-9: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
100-100: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
🔇 Additional comments (7)
examples/react/start-supabase-basic/README.md (4)
16-60: Excellent documentation of serialization requirements.This section clearly explains the serialization constraints and provides practical examples. The distinction between serializable primitives and non-serializable types (functions, class instances, Date objects) is accurate and well-presented.
61-97: LGTM! Practical troubleshooting guide.The common errors section addresses real issues developers will encounter. The code examples show clear before/after patterns, and the
?? nulloperator usage is idiomatic for handling undefined values.
120-169: LGTM! Implementation examples are accurate.The "How It Works" section provides clear explanations with code examples that match the actual implementation. The emphasis on serialization in the fetchUser example (line 134) reinforces the key concept introduced earlier.
170-196: LGTM! Helpful resources and troubleshooting tips.The documentation links and troubleshooting section provide good next steps for developers. The deployment platform compatibility list is accurate for TanStack Start applications.
examples/react/start-supabase-basic/src/routes/__root.tsx (3)
18-53: Excellent inline documentation for serialization requirements.This comprehensive JSDoc comment provides clear guidance right where developers need it. The examples of wrong vs correct patterns, along with the serializable types reference, will help prevent the common serialization errors this PR aims to address.
54-62: LGTM! Improved error handling with explicit logging.The change from
_error(intentionally ignored) toerrorwith explicitconsole.errorlogging is a debugging improvement. The contextual prefix[fetchUser]makes error source identification easier during troubleshooting.
64-77: LGTM! Serialization implementation is correct and well-documented.The return statement correctly extracts only primitive fields from the Supabase user object. The commented examples provide clear guidance for safely adding additional fields, including the
?? nullpattern for handling potentially undefined values fromuser_metadata.
|
View your CI Pipeline Execution ↗ for commit 939c66a
☁️ Nx Cloud last updated this comment at |
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Nitpick comments (2)
examples/react/start-supabase-basic/README.md (2)
7-7: Wrap bare URLs in markdown link syntax.Lines 7 and 182 contain bare URLs that should be wrapped in markdown link syntax for consistency and better rendering.
Apply this diff to fix the bare URLs:
-1. Create a Supabase project at https://supabase.com +1. Create a Supabase project at [https://supabase.com](https://supabase.com)- - [Supabase Auth Documentation](https://supabase.com/docs/guides/auth) + - [Supabase Auth Documentation](https://supabase.com/docs/guides/auth)Also applies to: 182-182
9-9: Add language specifications to fenced code blocks.Lines 9 and 103 have fenced code blocks without language identifiers. Specify
bashfor the.envblock andtextorplaintextfor the file structure.Apply these diffs:
- ``` + ```bash SUPABASE_URL=your-project-url SUPABASE_ANON_KEY=your-anon-key - ``` + ```-\`\`\` +\`\`\`plaintext src/ ├── routes/ │ ├── __root.tsx # Root layout with user fetching @@ -117,7 +117,7 @@ src/ │ └── posts.ts └── styles/ └── app.css -\`\`\` +\`\`\`Also applies to: 103-103
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
examples/react/start-supabase-basic/README.md(1 hunks)
🧰 Additional context used
📓 Path-based instructions (1)
examples/{react,solid}/**
📄 CodeRabbit inference engine (AGENTS.md)
Keep example applications under examples/react/ and examples/solid/
Files:
examples/react/start-supabase-basic/README.md
🪛 markdownlint-cli2 (0.18.1)
examples/react/start-supabase-basic/README.md
7-7: Bare URL used
(MD034, no-bare-urls)
9-9: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
103-103: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
🔇 Additional comments (1)
examples/react/start-supabase-basic/README.md (1)
1-209: Comprehensive and well-structured documentation.The README effectively documents the serialization constraints and provides clear, practical guidance. The "Server Function Serialization" section (lines 16–60) directly addresses the core issue #3831 with concrete examples, a helpful reference table, and common error solutions. The "How It Works" section ties the documentation to the actual code patterns. Project structure and troubleshooting sections enhance clarity for new users.
Minor markdown linting issues aside (bare URLs and missing code block language specs), the content quality and completeness are excellent for onboarding developers using TanStack Start with Supabase auth.
- Wrap bare URL in markdown link syntax - Add language specifiers to code blocks (bash, text) - Address CodeRabbitAI review feedback 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]>
1 participant
Summary
Adds comprehensive documentation explaining server function serialization requirements when using Supabase with TanStack Start.
Problem
The Supabase example works correctly but lacks documentation explaining why only primitive values are returned from the
fetchUserserver function. This causes confusion for developers who want to add more user fields.Changes
1. New
README.md(245 lines)2. Enhanced
__root.tsxWhat's Serializable?
"hello"42truenull{ name: "Alice" }[1, 2, 3]Testing
Fixes
Fixes #3831
Additional Context
The existing code is functionally correct - it already returns only the
emailfield (a primitive). This PR adds the missing documentation that explains:This helps developers understand the pattern and avoid mistakes when extending the example.
🤖 Generated with Claude Code
Co-Authored-By: Claude [email protected]
Summary by CodeRabbit
Documentation
Bug Fixes