elm-pages/docs/3.0-upgrade-notes.md

49 lines
3.5 KiB
Markdown
Raw Permalink Normal View History

2022-03-25 19:03:30 +03:00
# 3.0 Upgrade Notes
2022-10-27 14:58:56 +03:00
## File Structure
- `rm -rf .elm-pages`
- Add `app/` to `elm.json` `source-directories`
- `mkdir app && mv src/Page/ app/Route`
- Move `public/index.js` to the top-level project folder: `mv public/index.js index.js`
2022-03-25 19:03:30 +03:00
## `Shared.elm`
- Change `Cmd Msg` to `Effect Msg`
- `init` no longer passes in `Maybe Browser.Navigation.Key` - instead, `Effect.toCmd` receives the `Browser.Navigation.Key`
## Page -> RouteBuilder
- `buildWithLocalState` no longer receives `Maybe Browser.Navigation.Key` - use `Effect` instead
2022-10-27 14:58:56 +03:00
- `Page.prerender` -> `RouteBuilder.preRender`
## Secrets
- `Pages.Secrets` is no longer needed! It used to be necessary to ensure that server secrets didn't end up included in data for hydrating the page from your OptimizedDecoders. Now, only the final data payload is optimized (not intermediary data in the pipeline). So if your final `Data` and `ActionData` types on your page do not have any server secrets, then your hydrated data won't either.
- When you didn't use any secrets but did `Secrets.succeed` and pulled in no secrets, you can remove `Secrets.succeed`.
2023-01-02 01:44:11 +03:00
- When you need to use secrets (previously `Pages.Secrets.with`), instead of `Pages.Secrets`, you can now use `BackendTask.Env.expect` to pull in server
2022-10-27 14:58:56 +03:00
## Other Notes
- `import Page exposing (Page, StaticPayload)` -> `import RouteBuilder exposing (StatelessRoute, StaticPayload)`
- `Html.map Pages.Msg.UserMsg`
- In Shared.elm, `view` now returns a List of HTML instead of single HTML. The HTML elements in this list will be at the top-level of the `body` tag, with two hidden elements above them (rendered by the framework for accessibility functionality). `body : List (Html msg)`
- For `RouteBuilder.preRender` pages, the `Msg` must be defined as `type alias Msg = ()`
- Additional type variable in `StaticPayload`. `StaticPayload Data RouteParams` -> `StaticPayload Data ActionData RouteParams`
- Must expose `ActionData` from each Route Module
- Copy these files from example repo
- `app/ErrorPage.elm`
- `app/Effect.elm`
2023-04-06 18:55:01 +03:00
- `elm-pages add` is replaced by `elm-pages run` for running custom scripts - by convention a script/src/AddRoute.elm script is used for scaffolding a new route.
2022-10-27 14:58:56 +03:00
- `elm-pages codegen` command (to create generated files, helpful for build servers) is renamed to `elm-pages gen`
- Route modules exposed value defining the route used to be called `page`, now needs to be `route`
- In `Route.link` function, the `Route` used to be the first argument, it is now the last argument (works nicely if you pipe the Route in as an argument).
2023-01-02 01:44:11 +03:00
secrets that you need (just don't put sensitive data into your `Data` or `ActionData` types. Example: `BackendTask.Env.expect "MY_ENVIRONMENT_VARIABLE_SECRET" |> BackendTask.andThen (\secret -> myBackendTaskThatUsesASecret secret)`
2022-10-27 14:58:56 +03:00
- In Shared.elm and Route Modules, `init` and `update` functions no longer return a `Cmd msg` but instead an `Effect msg`
- `Maybe Browser.Navigation.Key` is no longer passed in to `Shared.init`. Instead, you get access to it in `Effect`, so you can create variants in your `Effect` type for anything that needs that type
- `SiteConfig` type no longer has any type variables `SiteConfig Data` -> `SiteConfig`
2023-01-02 01:44:11 +03:00
- `Site.config` no longer takes a `data : BackendTask Data` field. Instead, `{ head : BackendTask (List Head.Tag), ... }` is a BackendTask so you can resolve any data you need for global site head tags there.
2022-10-27 14:58:56 +03:00
- `SiteConfig` no longer includes a `manifest : ...` field. Instead, you can generate a manifest.json file in your `Api.elm` module (TODO link to example)