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

3.0 Upgrade Notes

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

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
• 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.
  • 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

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
• 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.
• 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). 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)
• 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
• 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.
• SiteConfig no longer includes a manifest : ... field. Instead, you can generate a manifest.json file in your Api.elm module (TODO link to example)