docs: Add documentation for Serverpod 3 WebServer" #342
Conversation
|
Important Review skippedAuto reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the You can disable this status message by setting the Note Other AI code review bot(s) detectedCodeRabbit has detected other AI code review bot(s) in this pull request and will avoid duplicating their findings in the review comments. This may lead to a less comprehensive review. 📝 WalkthroughWalkthroughDocumentation updated to reflect a widget-centric web-server API: types and examples renamed (ComponentRoute → WidgetRoute, Component → WebWidget/TemplateWidget), build signatures changed to return TemplateWidget, and upgrade guidance revised for static routes and caching factories. Changes
Estimated code review effort🎯 2 (Simple) | ⏱️ ~12 minutes
Pre-merge checks and finishing touches✅ Passed checks (3 passed)
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 review |
✅ Actions performedReview triggered.
|
![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 (1)
docs/06-concepts/18-webserver.md (1)
3-8: Address static analysis hints for stronger, more accurate language.Three style/grammar issues should be corrected:
- Line 5: "very easy" uses a weak intensifier. Consider replacing with a stronger verb or more specific description.
- Line 8: "3rd party" should be hyphenated as "third-party" for proper compound adjective formatting.
- Line 167: "gives you access to" uses a weak verb. Consider "provides" or a more specific term.
These are minor polish issues but will improve documentation quality per static analysis feedback.
Apply this diff to fix these issues:
-In addition to the application server, Serverpod comes with a built-in web -server. The web server allows you to access your database and business layer the -same way you would from a method call from an app. This makes it very easy to -share data for applications that need both an app and traditional web pages. You -can also use the web server to create webhooks or generate custom REST APIs to -communicate with 3rd party services. +In addition to the application server, Serverpod comes with a built-in web +server. The web server allows you to access your database and business layer the +same way you would from a method call from an app. This makes it simple to +share data for applications that need both an app and traditional web pages. You +can also use the web server to create webhooks or generate custom REST APIs to +communicate with third-party services.And for line 167, update it from "gives you access to" to "provides" when you encounter it in context.
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
⛔ Files ignored due to path filters (1)
package-lock.jsonis excluded by!**/package-lock.json
📒 Files selected for processing (2)
docs/06-concepts/18-webserver.md(1 hunks)docs/08-upgrading/06-upgrade-to-three.md(1 hunks)
🧰 Additional context used
🪛 LanguageTool
docs/06-concepts/18-webserver.md
[style] ~5-~5: As an alternative to the over-used intensifier ‘very’, consider replacing this phrase.
Context: ... method call from an app. This makes it very easy to share data for applications that nee...
(EN_WEAK_ADJECTIVE)
[grammar] ~8-~8: Use a hyphen to join words.
Context: ...custom REST APIs to communicate with 3rd party services. :::caution Serverpod's...
(QB_NEW_EN_HYPHEN)
[style] ~167-~167: Try using a synonym here to strengthen your writing.
Context: ...idgetRouteclass'build` method. This gives you access to all the features you typicall...
(GIVE_PROVIDE)
🔇 Additional comments (7)
docs/06-concepts/18-webserver.md (5)
25-67: Well-structured introduction to basic routing with clear examples.The section correctly introduces
WidgetRouteandTemplateWidgetterminology. Code examples at lines 44–46 and 57–58 are clear and idiomatic. Explanation of template values and thevaluesfield is helpful for developers new to this pattern.
69-162: Excellent coverage of static file handling and cache-busting strategy.The section provides clear motivation and comprehensive examples for the
CacheBustingConfigfeature. The explanation of content-based hashing, custom separators, and transparent URL rewriting is well-structured and should help developers implement effective caching strategies. The conditional request support (ETags, Last-Modified) documentation adds important context for cache validation.One minor readability note: the
StaticRoute.directory()example (lines 102–104) is quite dense with nested method calls. Consider breaking it across more lines for improved readability in the actual documentation (if not already formatted that way in the source).
171-467: Comprehensive advanced routing section with clear patterns and practical examples.This section effectively covers:
- Custom route handlers via the
Routebase class andhandleCall()override- HTTP method routing with switch expressions
- Path parameters using symbol syntax (
request.pathParameters[#paramName])—correctly implemented and consistent- Wildcard routing with clear distinction between
/*(single-level) and/**(tail-match with O(h) performance guarantee, as per PR objectives)- Modular route composition via
injectIn()with realistic CRUD and nested module examplesThe note about
ContextPropertyat lines 330–339 correctly distinguishes betweenRoute.handleCall()(which receivesSessionandRequest) and modular handlers (which only receiveRequest, accessed viarequest.session). This detail prevents a common confusion point.
469-789: Excellent middleware documentation with clear patterns and thorough ContextProperty coverage.The middleware section provides:
- Clear examples of basic, logging, authentication, CORS, and error-handling middleware
- Explicit documentation of middleware execution order with visual explanation (lines 586–593)
- A particularly strong subsection on
ContextProperty(lines 595–778) that thoroughly addresses a potentially confusing patternThe
ContextPropertydocumentation is exemplary—it explains the why (Request immutability), provides multiple realistic examples (request ID tracking, tenant identification, feature flags, rate limiting), includes safe access patterns (getOrNull()), and lists best practices. The multi-tenant example (lines 695–735) is production-grade and instructive.The distinction between middleware execution and the
Sessionparameter availability (lines 609–612) prevents a common misunderstanding about scoped context.
791-1101: Comprehensive typed headers documentation with exemplary custom header creation guide.The typed headers section provides:
- Clear motivation for typed headers over manual string parsing
- Accessible examples of common request/response headers
- Detailed subsections for each major header type (Authorization, CacheControl, ContentDisposition, Cookie)
- Production-grade complete examples (secure API, file download, session management)
The custom typed headers section (lines 986–1101) is particularly strong:
- Clear 3-step process (class definition with parsing logic,
HeaderCodec,HeaderAccessor)- Realistic
ApiVersionHeaderexample with proper validation- Multi-value header pattern with
CustomTagsHeader- Extension methods pattern for ergonomic property-style access
- Concise best-practices summary (lines 1103–1110)
This enables developers to confidently extend the system for application-specific headers. The pattern documentation is clear enough for a developer to apply it to their own headers without confusion.
docs/08-upgrading/06-upgrade-to-three.md (2)
3-33: Clear widget class naming migration guidance with helpful before/after example.The widget naming section correctly explains:
Widget→TemplateWidgetrenameAbstractWidget→WebWidgetrename- Legacy names remain available for backward compatibility
WidgetRouteclass remains unchangedThe before/after code example (lines 19–32) clearly demonstrates the migration pattern. Marking the old class with a deprecation comment would be a minor enhancement but is not required—the surrounding text makes it clear this is deprecated.
35-93: Effective static route migration guide with clear before/after examples.The static route section correctly documents:
- Migration from
RouteStaticDirectorytoStaticRoute.directory()- Available cache control factory methods (lines 74–77)
- Both built-in and custom cache control factory patterns
The before/after code examples (lines 42–57) clearly show the API transition. The custom factory function example (lines 81–92) demonstrates that developers have flexibility beyond the built-in factories.
Minor observation: The factory method descriptions at lines 74–77 (e.g.,
StaticRoute.public(maxAge: seconds)) could be slightly more explicit about whethermaxAgeis required or optional. However, this level of detail is appropriate for an upgrade guide; developers can check the API documentation or IDE hints for parameter signatures. The examples provided are sufficient for migration purposes.
There was a problem hiding this comment.
Pull Request Overview
This PR updates the Serverpod web server documentation to reflect the Serverpod 3.0 implementation, correcting outdated class references and adding comprehensive coverage of routing, middleware, typed headers, and static file handling.
Key changes:
- Corrects
Component*class references to actualWidget*classes (fixes rolled-back rename that was never updated in docs) - Updates upgrade guide with correct API changes and new
StaticRoutepatterns - Adds extensive documentation for routing (custom routes, HTTP methods, path parameters, wildcards, modular routes)
- Documents middleware system (creation, error handling, CORS, API validation, ContextProperty)
- Documents typed headers system (AuthorizationHeader, CacheControlHeader, cookies, custom headers)
- Documents static file handling (cache-busting, ETags, Last-Modified)
Reviewed Changes
Copilot reviewed 2 out of 3 changed files in this pull request and generated 8 comments.
| File | Description |
|---|---|
| docs/08-upgrading/06-upgrade-to-three.md | Updates upgrade guide to reflect actual Serverpod 3.0 widget class naming and StaticRoute API changes |
| docs/06-concepts/18-webserver.md | Comprehensive expansion covering routing, middleware, typed headers, and static file handling |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
|
@copilot All the broken formatting of code-snippets should be reverted now. Please check, and close resolved comments. |
|
@nielsenko I've opened a new pull request, #343, to work on those changes. Once the pull request is ready, I'll request review from you. |
|
@copilot I fixed the formatting. Just verify and close your comments |
|
@nielsenko I've opened a new pull request, #344, to work on those changes. Once the pull request is ready, I'll request review from you. |
|
Fuck off @copilot 😡 |
|
@nielsenko I've opened a new pull request, #345, to work on those changes. Once the pull request is ready, I'll request review from you. |
|
@coderabbitai review |
✅ Actions performedReview triggered.
|
There was a problem hiding this comment.
Actionable comments posted: 1
🧹 Nitpick comments (2)
docs/06-concepts/18-webserver.md (2)
195-210: HTTP request/response examples should use dedicated HTTP code blocks.The HTTP examples at lines 195-210 are currently embedded as Dart comments within a code fence. Consider moving these to a separate HTTP code block for clarity:
# Client first request GET /static/logo.png HTTP/1.1 Host: example.com HTTP/1.1 200 OK ETag: "abc123" Last-Modified: Tue, 15 Nov 2024 12:00:00 GMT Content-Length: 12345 [file content] # Client subsequent request GET /static/logo.png HTTP/1.1 Host: example.com If-None-Match: "abc123" HTTP/1.1 304 Not Modified ETag: "abc123" [no body - saves bandwidth]This improves readability and makes the examples scannable.
10-14: Optional: Consider style improvement for "giving you access."Static analysis suggests replacing "giving you access" with a synonym like "providing" for variety. While not critical, this could strengthen the writing:
- Serverpod's web server is built on the [Relic](https://github.com/serverpod/relic) framework, giving you access to its routing engine, middleware system, and typed headers. + Serverpod's web server is built on the [Relic](https://github.com/serverpod/relic) framework, providing access to its routing engine, middleware system, and typed headers.
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
docs/06-concepts/18-webserver.md(3 hunks)
🧰 Additional context used
🪛 LanguageTool
docs/06-concepts/18-webserver.md
[style] ~11-~11: Try using a synonym here to strengthen your writing.
Context: .../github.com/serverpod/relic) framework, giving you access to its routing engine, middlewar...
(GIVE_PROVIDE)
[style] ~219-~219: Try using a synonym here to strengthen your writing.
Context: ...idgetRouteclass'build` method. This gives you access to all the features you typicall...
(GIVE_PROVIDE)
[grammar] ~800-~800: Use a hyphen to join words.
Context: ...y-catch blocks to every route, use error handling middleware to catch exceptions ...
(QB_NEW_EN_HYPHEN)
[grammar] ~803-~803: Use a hyphen to join words.
Context: ... consistent error responses. #### Error handling middleware Error handling midd...
(QB_NEW_EN_HYPHEN)
[grammar] ~805-~805: Use a hyphen to join words.
Context: .... #### Error handling middleware Error handling middleware wraps all your route...
(QB_NEW_EN_HYPHEN)
[grammar] ~841-~841: Use a hyphen to join words.
Context: ...andlingMiddleware, '/'); ``` With error handling middleware in place, your route...
(QB_NEW_EN_HYPHEN)
[grammar] ~850-~850: Use a hyphen to join words.
Context: ...ver Error response. However, using error handling middleware gives you control ov...
(QB_NEW_EN_HYPHEN)
🔇 Additional comments (5)
docs/06-concepts/18-webserver.md (5)
24-30: Clear terminology introduction—terminology shift well-established.The section correctly introduces
WidgetRouteandTemplateWidgetas primary concepts, aligning with the Serverpod 3.0 widget-centric model mentioned in the PR objectives.
49-78: Widget terminology correctly applied throughout examples.The
WidgetRouteandTemplateWidgetusage is consistent and correct. Thesuper(name: 'my_page')pattern for template identification is clearly demonstrated.
317-376: Path parameters and modular routes comprehensively documented.The use of symbols for path parameter access (
request.pathParameters[#id]) is clearly demonstrated and consistently applied across multiple examples (lines 335, 372-375, 494, 543, 582, 1431). The modular route pattern withinjectIn()is well-explained with clear examples.
875-1141: ContextProperty patterns are comprehensive and well-documented.The section clearly demonstrates context property definition, middleware usage for setting values, and route usage for reading values. The multi-tenant example and safe access patterns (
getOrNull()) are helpful real-world scenarios.
1155-1681: Typed headers comprehensively documented with practical examples.The section covers reading, setting, and creating custom typed headers. Authentication schemes (Bearer, Basic, Digest), cache directives, and cookie security patterns (SameSite, HttpOnly, Secure) are all clearly explained with working examples. The custom header creation section with
HeaderCodecandHeaderAccessoris well-structured.
nielsenko
force-pushed
the
docs-3-webserver
branch
from
68bd650 to
4106f7e
Compare
SandPod
left a comment
SandPod
left a comment
There was a problem hiding this comment.
Comments before discussion.
- Created docs/06-concepts/18-webserver/ directory with 7 focused pages - Added docs/01-get-started/05-web-server.md quick start guide - Organized content by feature: routing, modular routes, middleware, static files, typed headers, server-side HTML - De-emphasized WidgetRoute/TemplateWidget with Jaspr recommendation - Added _category_.json for Docusaurus sidebar navigation - Improved discoverability with navigation between related topics - Remove experimental warnings from web server documentation
nielsenko
force-pushed
the
docs-3-webserver
branch
from
e15e37e to
e641afe
Compare
|
Rebased on main |
Update WebServer Documentation
Summary
Updates the WebServer documentation to match the Serverpod 3.0 implementation and adds coverage of routing, middleware, typed headers, and static file handling.
Changes
Fixes
Component*references to actualWidget*classes (rolled-back rename was never fixed in docs)StaticRoutecache control methods static (implementation bug fix)New Sections
Routing
handleCall()pathParameters[#id])/*and/**(tail-match only, O(h) performance)injectIn()overrideMiddleware
Typed Headers
Static Files
Summary by CodeRabbit
Documentation
Refactor
✏️ Tip: You can customize this high-level summary in your review settings.