Update docs.

This commit is contained in:
Dillon Kearns 2023-05-05 10:13:58 -07:00
parent 81014aa143
commit f951b98e03

View File

@ -46,8 +46,6 @@ Some of the core features include
## Server-Rendered elm-pages Use Cases
`elm-pages` is a full-stack Elm framework which can also be used to pre-render static routes.
`elm-pages` server-rendered routes are a good fit for applications with needs such as:
- Dynamic and/or user-specific content
@ -90,3 +88,11 @@ Some examples of this include:
Consider a server-rendered route where you show some paid content if there is a logged in user with an active subscription, or a preview of the content with a call to action to sign up otherwise. This is a great use case for server-rendered routes. You will need to be more careful to handle your [`FatalError`](https://package.elm-lang.org/packages/dillonkearns/elm-pages/latest/BackendTask#FatalError) cases in your `BackendTask`s for that Route because you don't want the user to get a 500 error page. However, server-rendered routes give you the power to give a rich logged-in user experience with the ease of cookie-based sessions and the simplicity of data from a `BackendTask` that is available without any loading states to deal with (for the user or the developer). Imagine building that same route in a traditional Elm app. You would need to manage your user session using a JWT or similar client-side authentication technique, and your view would need to handle the intermediary states of authenticating, stale login session, or loading data from the backend. With a server-rendered route, since you have Elm code running on the server-side you can handle stale sessions with a server redirect response, and your loading states are resolved on the server-side before rendering.
If you are dealing with more static, public content, then pre-rendered routes come with some benefits. Consider a blog or documentation site. You don't need to be as careful with `FatalError`'s if you are using pre-rendered routes because you will have a chance to fix any errors that come up before the site goes live to your users (any `FatalError`'s your Routes resolve to will result in a build error). There is a tradeoff with flexibility, and there are reasons you may want to dynamically render content even if it seems relatively static. For example, you may want new articles, or edits, to go live immediately for a news site. If you pre-render your site, then you will need to build all of the your routes any time there is new or updated content. If you use server-rendered routes, this content would be live immediately since it is resolved on-demand at request-time.
## What's Not a Good Fit for elm-pages?
`elm-pages` is built around the architecture of serving Routes through an Elm Backend (either dynamic server or static build server). Some applications aren't a good fit for this kind of architecture at all. If the set of core features in [Server-Rendered Routes](#server-rendered-elm-pages-use-cases) and [Pre-Rendered Routes](#pre-rendered-elm-pages-use-cases) don't apply to your use case, then it may be possible to build your app with `elm-pages` but will likely feel like fitting a square peg in a round hole. So a good rule of thumb for deciding whether `elm-pages` is a good architecture for your application is considering whether you can benefit from communicating with an Elm Backend since this is the backbone of the featureset in `elm-pages`.
For example, if you're building an interactive game, the core experience of the application will likely be on a single route for most of the session. Serving the page with initial data from your Elm Backend in an `elm-pages` app would have neglible benefit, especially for loading the kinds of larger assets that are used in games. You would likely want to have a loading screen as part of the in-game experience, rather than a quick and slim set of initial data that can speed up the initial page load by resolving data on the server to minimize the latency. In this case, you may want to consider using a traditional Elm app with a client-side router. You can still use `elm-pages` for your settings pages, login, and landing pages. However, you will probably be able to define better abstractions for your game experience using traditional client-side rendered Elm app.
For similar reasons, an app like Figma isn't likely to be a good fit for `elm-pages`.