elm-pages-v3-beta/docs/7.0.0-elm-package-upgrade-guide.md

# 7.0.0 Elm package upgrade guide

Please ensure that you're on the latest elm-pages version of both the Elm package _and_ the NPM package before following these steps.

There are two new beta features, which you can opt into by running a different build command (see 2) or calling a new generated function (see 3).

There are 3 broad areas of change in this release.

1. Breaking API changes
2. Beta build command
3. Beta Template Modules feature

You can ignore (2) and (3) if you aren't interested in beta features. And even if you do choose to try these beta features, I recommend starting with (1) and getting things compiling without using any beta features first.

## 1 - Breaking API changes

### Manifest.Config now has `icons`

- The `icons` field in the manifest config will only be used for the beta, no-webpack build (see section 2). If you aren't using it, you can simply pass in an empty list for icons. The new field in the Manifest.Config has this type `icons : List.List (Pages.Manifest.Icon pathKey)`.
- `Program model msg metadata view` changed to `Program model msg metadata view pathKey`. That means there is a new type variable in `Pages.Platform.Program`. You can fix this by adding `Pages.PathKey` (a type defined in the generated Pages.elm module) as the last type variable wherever you had an annotation using the `Pages.Platform.Program` type.

The following functions in `Pages.Platform.init` have also changed:

```elm
            , onPageChange :
                  Maybe
                      (
                      { path : PagePath pathKey
                      , query : Maybe String
                      , fragment : Maybe String
                      }
                      -> msg
                      )
            , onPageChange :
                  Maybe.Maybe
                      (
                      { path : Pages.PagePath.PagePath pathKey
                      , query : Maybe.Maybe String.String
                      , fragment : Maybe.Maybe String.String
                      , metadata : metadata
                      }
                      -> msg
                      )
            , init :
                  Maybe
                      { path : PagePath pathKey
                      , query : Maybe String
                      , fragment : Maybe String
                      }
                  -> ( model, Cmd msg )
            , init :
                  Maybe.Maybe
                      { path :
                            { path : Pages.PagePath.PagePath pathKey
                            , query : Maybe.Maybe String.String
                            , fragment : Maybe.Maybe String.String
                            }
                      , metadata : metadata
                      }
                  -> ( model, Platform.Cmd.Cmd msg )
            , subscriptions : model -> Sub msg
            , subscriptions :
                  metadata
                  -> Pages.PagePath.PagePath pathKey
                  -> model
                  -> Platform.Sub.Sub msg
```

## 2 - Beta build command

You can run the regular build command and the beta build command side by side, and have the beta entrypoints living next to the current JS entrypoint you have (index.js). Hopefully that makes it easy to try out the beta and experiment with it without needing to change over right away.

- `elm-pages build` and `elm-pages develop` use the `index.js` entrypoint.
- A new command, `elm-pages-beta` (doesn't take any arguments) uses the `beta-index.js` and `beta-style.css` entrypoints.

Note that before you would use webpack to import CSS from the JS entrypoint (or something that was imported from there). Now there are separate entrypoints for JS and CSS.

Some key points about the no-webpack build:

- Whether you're using the beta no-webpack build or the previous build, you will see significant performance improvements for StaticHttp
- You can continue using the current elm-pages build and elm-pages develop commands. If you do that, you can just pass in icons = [] for the manifest config as the icons are only read for the new beta build.
- For the beta build, you can use the Manifest config's icons to set the PWA icon set, and you can set the favicon set using head tags an example here: https://github.com/dillonkearns/elm-pages/blob/5ad85cad0d5de9631ea06f98bba8ef1c96b1908a/examples/simple/src/Main.elm#L41-L130. Note that the beta build does not generate icons for you (I'm using cloudinary in the example, and it works way better and doesn't slow down the build). The beta build also doesn't do all of these things to remove bloat and give the user more control, while also making the elm-pages build more focused on doing a great job with the Elm code: https://github.com/dillonkearns/elm-pages/issues/148
- To use the elm-pages-beta, you just need to create beta-index.js (using ES module syntax, see this example: https://github.com/dillonkearns/elm-pages/blob/elm-to-html/examples/simple/beta-index.js), and a beta-style.css entrypoint (this only using @import syntax, see https://github.com/dillonkearns/elm-pages/blob/elm-to-html/examples/simple/beta-style.css - you can bundle CSS code to this entrypoint if you need CSS bundling).

---- Head - MINOR ----

    Added:
        appleTouchIcon :
            Maybe.Maybe Basics.Int
            -> Pages.ImagePath.ImagePath pathKey
            -> Head.Tag pathKey
        icon :
            List.List ( Basics.Int, Basics.Int )
            -> MimeType.MimeImage
            -> Pages.ImagePath.ImagePath pathKey
            -> Head.Tag pathKey

## 3 - Beta Template Modules feature

Pre conditions to using template modules

- Instead of using `Pages.Platform.init` directly, start building your app with `TemplateModulesBeta.mainTemplate`, see an example here: https://github.com/dillonkearns/elm-pages/blob/3aa978578b152ea74352d97e7b362cecc4da09a4/examples/docs/src/Main.elm#L61
- You must have a module called `Shared.elm`, like this example: https://github.com/dillonkearns/elm-pages/blob/dfa71340a21f4d07e835d240b09ab3d990c05f7a/examples/docs/src/`Shared.elm`. That module must expose a `template` value. You must also expose the following types from `Shared`:
  - `RenderedBody` -
  - `SharedMsg` - a union of all the Msg's that can be sent from a Template Module and handled by `Shared` to update the shared state.
  - `Msg` - the Shared Msg type for events that can happen and be received by the Shared module.
  - `Model` - the Shared module, which can also be accessed by Template Modules if the wire that in with the `Template.elm` builder functions to access that state.
- You must have a module called `TemplateType`, which exposes a custom type called `TemplateType.TemplateType`, with a variant for each of your Template Modules (files in the `src/Template` folder) with a corresponding variant name. The variant must have exactly 1 argument, which is the metadata type for that Template. See this example: https://github.com/dillonkearns/elm-pages/blob/dd3f824e4e4aab38cb5633909061418338ee0392/examples/docs/src/TemplateType.elm#L6
- You must have at least 1 template module (see Generating a Template Module).

### Generating a Template Module

Template modules live in the `src/Template` directory.

- You can add a new Template Module using `elm-pages-generate Recipe`
- The `gen/Template.elm` module provides a builder-style API for each Template. You can add complexity as needed, starting from the generated starting point.
- Each module must expose a value called `template`, and a type called `Msg` and `Model` (they can be `()` and `Never` if you don't use them, as in the scaffolded code).
- You can see the Elm docs for the generated `gen/Template.elm` module if you install elm-doc-preveiw (`npm i -g elm-doc-preview`), copy [this file](https://github.com/dillonkearns/elm-pages/blob/7fbcfb60d8b7a6422cc34667979bb09084c01a3f/examples/docs/elm-application.json) to your project, and run `elm-doc-preview` from the top-level folder.