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.
The documentation incorrectly referenced ComponentRoute and Component classes that don't exist. The Widget to Component rename was rolled back in the implementation but the docs were never updated. Changes: - Reverted ComponentRoute → WidgetRoute - Reverted Component → TemplateWidget/WebWidget - Reverted ListComponent, JsonComponent, RedirectComponent → ListWidget, JsonWidget, RedirectWidget - Updated RouteStaticDirectory → StaticRoute.directory() - Fixed method signature: HttpRequest request → Request request - Rewrote upgrade guide to reflect actual changes (Widget → TemplateWidget deprecation) - Added StaticRoute cache control examples using the newly static methods
Added detailed documentation for WebServer's advanced routing and middleware features, including: Routing: - Custom Route classes for REST APIs and custom response handling - HTTP method handling (GET, POST, PUT, DELETE, PATCH, etc.) - Path parameters and wildcard matching (*, **) - Fallback routes for 404 handling - Request object usage and query parameters Middleware: - Creating custom middleware functions - Authentication middleware patterns - CORS middleware implementation - Middleware execution order and path hierarchy - ContextProperty for request-scoped data - Built-in logRequests() middleware All examples are based on the Relic framework that WebServer is built on, with Serverpod-specific integration points highlighted.
Added comprehensive documentation for creating modular routes by overriding the injectIn method, including: - Detailed path parameters section with :paramName syntax - How to extract and validate path parameters using symbols (pathParameters[#id]) - Multiple path parameters in a single route - Complete CRUD module example using proper RESTful path parameters - Path parameter validation and error handling - Wildcards section (single-level * and multi-level **) - Pattern for composing multiple sub-modules into a parent module - Best practices for organizing complex APIs The injectIn override pattern enables: - Hierarchical route organization - Reusable route modules - Complex API composition from smaller focused modules - Separation of route registration from handler implementation Examples show practical RESTful API patterns: - GET /api/users - List all - GET /api/users/:id - Get by ID (access via pathParameters[#id]) - POST /api/users - Create - PUT /api/users/:id - Update by ID - DELETE /api/users/:id - Delete by ID All examples include proper path parameter extraction using symbols, validation, and error handling with appropriate HTTP status codes.
Expanded the ContextProperty section with detailed documentation on using context properties for request-scoped data: Overview: - Why use ContextProperty instead of modifying Request - Common use cases (auth, rate limiting, request IDs, multi-tenant, feature flags) Creating and Using: - How to define ContextProperty instances - Setting values in middleware - Accessing values in routes - Safe access with getOrNull() - Using default values Complete Examples: - Full authentication middleware with bearer token validation - Role-based authorization middleware (requireRole) - Multi-tenant application with multiple context properties - Request ID tracking and logging - Combining multiple properties in routes Best Practices: - Define as top-level constants or static fields - Use descriptive naming conventions - Set in middleware, read in routes - Use getOrNull() for optional values - Leverage type safety This pattern is essential for building production-ready web applications with proper separation of concerns between authentication, authorization, and business logic.
- Replace weak intensifier 'very easy' with 'simple' - Hyphenate 'third-party' as compound adjective - Keep 'gives you access to' for clarity over 'provides'
Restored from commit before rewrap (aefd54c) and reapplied content changes: - Relic framework context with link - Style improvements (simple, third-party) - Error handling elevation and clarification - Session vs ContextProperty distinction improvements Code blocks now properly formatted with correct indentation.
nielsenko
force-pushed
the
docs-3-webserver
branch
from
68bd650 to
4106f7e
Compare
Replace Dart comment pseudo-code with actual HTTP request/response format using http language tag. Separates initial and subsequent requests for clarity.
docs/06-concepts/18-webserver.md
Outdated
| Serverpod's web server is still experimental, and the APIs may change in the | ||
| future. This documentation should give you some hints on getting started, but we | ||
| plan to add more extensive documentation as the web server matures. |
There was a problem hiding this comment.
Should we drop this now? Or wait until Relic 1.0? Or even further?
There was a problem hiding this comment.
We should drop it. With Serverpod 3 the web server is no longer experimental :D
docs/06-concepts/18-webserver.md
Outdated
| In the future, we plan to add a widget library to Serverpod with widgets | ||
| corresponding to the standard widgets used by Flutter, such as Column, Row, | ||
| Padding, Container, etc. This would make it possible to render server-side | ||
| widgets with similar code used within Flutter. |
There was a problem hiding this comment.
Do we still, or are we aiming for good Jaspr support?
There was a problem hiding this comment.
I would remove this not to have promises in the docs. I think Jaspr is probably good enough.
docs/06-concepts/18-webserver.md
Outdated
| ### Modular routes with injectIn | ||
|
|
||
| As your web server grows, managing dozens of individual route registrations can | ||
| become unwieldy. Modular routes solve this by letting you group related | ||
| endpoints into reusable modules. For example, you might create a | ||
| `UserCrudModule` that handles all user-related endpoints (`GET /users`, | ||
| `POST /users`, `PUT /users/:id`, etc.) in a single cohesive unit. | ||
|
|
||
| The key to modular routes is the `injectIn()` method. When you call | ||
| `pod.webServer.addRoute(route, path)`, Serverpod calls `route.injectIn(router)` | ||
| on a router group for that path. By overriding `injectIn()`, you can register | ||
| multiple handler functions instead of implementing a single `handleCall()` | ||
| method. This pattern is perfect for REST resources, API modules, or any group of | ||
| related endpoints. | ||
|
|
||
| :::info Session Access in Modular Routes When using `injectIn()` with handler | ||
| functions (`router.get('/', _handler)`), your handlers receive only a `Request` | ||
| parameter. To access the `Session`, use `request.session`: | ||
|
|
||
| ```dart | ||
| Future<Result> _handler(Request request) async { | ||
| final session = request.session; // Extract Session from Request | ||
| // ... use session | ||
| } | ||
| ``` | ||
|
|
||
| This differs from `Route.handleCall()` which receives both Session and Request | ||
| as explicit parameters. The modular route pattern uses Relic's router directly, | ||
| which only provides Request to handlers. ::: |
There was a problem hiding this comment.
This is perhaps the primary reason I would like to get rid of the explicit handleCall method that takes a Session.
I still think it is acceptable to have user obtain the session from request.session.
SandPod
left a comment
SandPod
left a comment
There was a problem hiding this comment.
Comments before discussion.
docs/06-concepts/18-webserver.md
Outdated
| # Web server | ||
|
|
||
| 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 |
There was a problem hiding this comment.
Suggestion: Split this page up into suitable subpages.
Perhaps the first one should be named get started or introduction?
docs/06-concepts/18-webserver.md
Outdated
| Serverpod's web server is still experimental, and the APIs may change in the | ||
| future. This documentation should give you some hints on getting started, but we | ||
| plan to add more extensive documentation as the web server matures. |
There was a problem hiding this comment.
We should drop it. With Serverpod 3 the web server is no longer experimental :D
docs/06-concepts/18-webserver.md
Outdated
|
|
||
| When you create a new Serverpod project, it sets up a web server by default. When working with the web server, there are two main classes to understand; `ComponentRoute` and `Component`. The `ComponentRoute` provides an entry point for a call to the server and returns a `Component`. The `Component` renders a web page or response using templates, JSON, or other custom means. | ||
| When you create a new Serverpod project, it sets up a web server by default. | ||
| When working with the web server, there are two main classes to understand; |
There was a problem hiding this comment.
Suggestion: This is if someone wants to use our templating engine. Should perhaps start with registering routes and things like that? Or quickly browse through this in a get started section?
There was a problem hiding this comment.
This is inherited from the existing jobs (just rewrap really). I will move it to a less prominent spot.
docs/06-concepts/18-webserver.md
Outdated
| In the future, we plan to add a widget library to Serverpod with widgets | ||
| corresponding to the standard widgets used by Flutter, such as Column, Row, | ||
| Padding, Container, etc. This would make it possible to render server-side | ||
| widgets with similar code used within Flutter. |
There was a problem hiding this comment.
I would remove this not to have promises in the docs. I think Jaspr is probably good enough.
- 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
| For modern server-side HTML rendering with Serverpod, we recommend using | ||
| [Jaspr](https://docs.page/schultek/jaspr), which provides a Flutter-like API for | ||
| building web applications. You can integrate Jaspr with Serverpod's web server | ||
| using custom `Route` classes, giving you full control over request handling | ||
| while leveraging Jaspr's component model. |
There was a problem hiding this comment.
No, I don't think we should downplay our solution, just lift Jaspr as an alternative and perhaps show how to integrate it?
There was a problem hiding this comment.
This could be a section on this page further down. "Integrate 3rd party solutions" or something like that?
SandPod
left a comment
SandPod
left a comment
There was a problem hiding this comment.
Bunch of comments and suggestions.
I think we could attempt to keep it as simple and to the point as possible, we can reference the Relic documentation for further exploration so that we don't end up with duplicate documentation.
| @@ -0,0 +1,154 @@ | |||
| # Web Server Overview | |||
There was a problem hiding this comment.
Suggestion/Discussion: Should this just be Overview since we are already under the Web Server section?
| @@ -0,0 +1,4 @@ | |||
| { | |||
| "label": "Web Server", | |||
There was a problem hiding this comment.
Suggestion: Only use large caps for first word. please fix this for all sub pages as well.
| "label": "Web Server", | |
| "label": "Web server", |
docs/01-get-started/04-web-server.md
Outdated
| sidebar_label: 4. Working with the web server | ||
| --- | ||
|
|
||
| # Working with the web server |
There was a problem hiding this comment.
Question: The web server is a situational addition to Serverpod. Should it be included in the get started guide? This is perhaps a question for Viktor. It could be neat to have it included, as this would be a tour of the framework. But I'm not sure.
There was a problem hiding this comment.
Discussed with Viktor, remove the web server from the get started guide.
There was a problem hiding this comment.
I got the impression the last time around that is should, but I'll remove again.
docs/01-get-started/04-web-server.md
Outdated
|
|
||
| ## Building a REST API | ||
|
|
||
| Let's create a complete REST API for managing recipes with support for listing, creating, retrieving, and deleting recipes. Create a new file `magic_recipe_server/lib/src/routes/recipe_route.dart`: |
There was a problem hiding this comment.
Suggestion(If we are to keep it): Only implement one of these things, for example list.
I believe that would take us through all the required steps but not need us to show as much code.
docs/01-get-started/04-web-server.md
Outdated
|
|
||
| # Working with the web server | ||
|
|
||
| In addition to endpoints for your Flutter app, Serverpod includes a built-in web server for REST APIs, static files, and webhooks. This is useful when you need to integrate with third-party services, serve web pages, or provide public APIs. The web server gives you full access to your database and business logic through the `Session` object, just like regular endpoints. |
There was a problem hiding this comment.
Suggestion: Now we are not mentioning creating web pages at all. Should perhaps the other examples be more advanced examples, and we start out by focusing on only displaying a simple web page?
That would make this page significantly smaller as it would only include static file serving and a template page. The rest we could point to in the web server documentation?
There was a problem hiding this comment.
For example, a simple page to display all our recipes?
There was a problem hiding this comment.
That would allow us to continue with the guide but still explain some key concepts.
| - Works transparently - requesting `/static/logo@abc123.png` serves | ||
| `/static/logo.png` | ||
|
|
||
| ### Combining with cache control |
There was a problem hiding this comment.
Suggestion: This should already be explained in Cache control. Remove from here.
| @@ -0,0 +1,543 @@ | |||
| # Typed Headers | |||
There was a problem hiding this comment.
Suggestion: Slim this page down into a bare-bone example and then referenced the Relic documentation.
We should probably cover:
- Reading a header
- Setting a header
- Creating a custom header.
There was a problem hiding this comment.
This gives us less to maintain and reduced duplication.
| For modern server-side HTML rendering with Serverpod, we recommend using | ||
| [Jaspr](https://docs.page/schultek/jaspr), which provides a Flutter-like API for | ||
| building web applications. You can integrate Jaspr with Serverpod's web server | ||
| using custom `Route` classes, giving you full control over request handling | ||
| while leveraging Jaspr's component model. |
There was a problem hiding this comment.
No, I don't think we should downplay our solution, just lift Jaspr as an alternative and perhaps show how to integrate it?
| For modern server-side HTML rendering with Serverpod, we recommend using | ||
| [Jaspr](https://docs.page/schultek/jaspr), which provides a Flutter-like API for | ||
| building web applications. You can integrate Jaspr with Serverpod's web server | ||
| using custom `Route` classes, giving you full control over request handling | ||
| while leveraging Jaspr's component model. |
There was a problem hiding this comment.
This could be a section on this page further down. "Integrate 3rd party solutions" or something like that?
| When you create a new Serverpod project, it sets up a web server by default. | ||
| For simple HTML pages, you can use `WidgetRoute` and `TemplateWidget`. The | ||
| `WidgetRoute` provides an entry point for handling requests and returns a | ||
| `WebWidget`. The `TemplateWidget` renders web pages using Mustache templates. |
There was a problem hiding this comment.
Suggestion: I don't understand this section. The example below returns a TemplateWidget but the docs here mention that it should return a WebWidget.
Please rephrase this so that it can be understood without inspecting the code. What is a TemplateWidget, WidgetRoute, and WebWidget and how do they relate to each other.
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.