elm-pages 2.0 public beta instructions and feedback!

[dillonkearns]

I'm officially opening up the elm-pages 2.0 public beta. Here are the instructions for setting up a fresh elm-pages 2.0 beta project.

Let's use this thread to track feedback. Please comment with anything you find to be confusing, missing, or that could be improved. I'd love to hear any and all thoughts here!

My Current Todo List

• Update meta tags in docs site
• Remove lorem ipsum text for lower icons section in landing page
• Update code snippets on landing page to reflect recent API changes
• Finish package docs for
  • Glob
  • QueryParams
  • DataSource.File
  • Dedupe/clean up docs for DataSource & DataSource.Http
  • Pages.PageUrl
• Cache showcase images (either DPR or cloudinary)

[wolfadex]

When creating a dynamic page the RouteParams doesn't place a space between arguments.

See the String,splat which should be String, splat.

Super minor but probably a nice little polish thing.

[dillonkearns]

Good catch! I agree, those little details make things feel more solid and are definitely worth polishing 👍

[iffies]

When adding a page with the following command (assuming we must keep using the npx command during the beta) with npx dillonkearns/elm-pages#8ccdf30 add Sponsors, its view function is generated as:

view : StaticPayload Data RouteParams -> Document Msg
view static =
    Document.placeholder "Sponsors"

Should this be View instead of Document? If so, Page.buildNoState demands a more nuanced definition of view, similar to that provided by the autogenerated Index.elm file:

view :
    Maybe PageUrl
    -> Shared.Model
    -> StaticPayload Data RouteParams
    -> View Msg
view maybeUrl sharedModel static =
    View.placeholder "Sponsors"

Curious if Document is legacy naming or if you're encouraging developers to create a custom wrapper for View.

[dillonkearns]

Oh yes, good catch! I changed the name from Document to View. I pushed a fix for the elm-pages add command.

You can run it with the latest commit there: npx dillonkearns/elm-pages#badd971d add Sponsors.

And by the way, the reason I use a specific hash instead of a branch name is because unfortunately npx will cache the branch at a fixed point. So at least doing it with a commit hash removes the confusion around being stuck on an old version implicitly. I wish there was an easy way to force it to use the latest version 🤷‍♂️

[ringods]

Hello @dillonkearns, you already pointed me to some video resources on the 2.0 beta which are most helpful.

One thing I still want to mention as a newbie is this: in the videos and the examples, every page template(?) calls into the Page module, e.g. Page.singleRoute.

The Page module is not in the package, which means there is no documentation generated for it:

https://elm-doc-preview.netlify.app/?repo=dillonkearns%2Felm-pages&version=static-files

The module is in the generated (git-ignored) .elm-pages folder inside my project setup.

Will this change for the final 2.0?

[dillonkearns]

Hello @ringods, thank you for the feedback!

This is a challenging one because the Pages.elm module is generated and available locally in order to minimize the number of type variables you have to use. If Page.elm wasn't a generated file, then it would need type variables to reference the following types:

• View.View
• Shared.Model
• Shared.SharedMsg
• Shared.Data

So moving it into the published package would mean it would be more verbose to create type annotations, and in some cases the error messages would be less helpful because those types can't be anything, they must be exactly referring to those type definitions in the user's codebase.

I've just pushed up an experiment to try a local docs page, but it does have some shortcomings. You can try it out if you update to the latest version (should be something like cd elm-pages && git pull if you have an existing elm-pages 2.0 beta setup).

If you run npm install && npx elm-pages docs (you might need to npm install to get the new dependency I added), that command gives a local docs preview using https://github.com/dmy/elm-doc-preview. It looks like this:

The main shortcoming is that if you have a compiler error, you won't see the docs until you resolve that error. So let's consider this an experimental idea given the known limitation. I'm open to other ideas to make it easy to navigate the generated APIs, but unfortunately I think there are no easy answers but more clever solutions with different tradeoffs.

[dillonkearns]

Also, it's worth noting that when this is a published Elm package, I believe this sidebar will only display the generated modules, not all of the elm-pages module docs. The elm-pages docs from the published package would be available by clicking to them under the "dependencies" section. Not a bad thing I think, but worth noting.

[MarcoDaniels]

Hi, I found an interesting issue.

When using DataSource to create routes dynamically, if the url from the data source starts with a slash /about-us it will display a "Page not found." when running the dev server. But it works when running build.

The same happens when just doing something like:

routes =
    DataSource.succeed [ { slug = "/about-us" } ]

[dillonkearns]

That's a good catch, thanks for reporting that!

I'm thinking it might make sense to just URL encode those route params. It's a little confusing either way, but it is valid to have %2F (an encoded /) in a URL, so there should be a way to express that.

[tennety]

Found what looks like a tiny typo while going through the docs.

Also, question: do you already have docs for an upgrade path from v1 (I'm using the starter repo)? I'm thinking it would be getting rid of src and gen and bootstrapping a fresh project.

[tennety]

My bad, found the docs within the submodule. You think of everything!

[dillonkearns]

Fixed the typo, thanks!

[dillonkearns]

Also, question: do you already have docs for an upgrade path from v1 (I'm using the starter repo)? I'm thinking it would be getting rid of src and gen and bootstrapping a fresh project.

I'm working on migration instructions here: https://github.com/dillonkearns/elm-pages/blob/static-files/docs/migrating-from-1-to-2.md. If there are some particular questions that come up, let me know and I'll try to add some details about it in that document!

[bdukes]

I'm running this on Windows, and when I call npx dillonkearns/elm-pages#static-files add Articles.Category_, the generated code has, e.g., import Page.Articles\Category_ instead of import Page.Articles.Category_. All throughout Route.elm and TemplateModulesBeta.elm it's being included as Articles\Category_.

Looks like maybe you should be splitting on path.sep instead of "/"

elm-pages/generator/src/generate-template-module-connector.js

Line 13 in aa0381c

return path.join(captures[0], captures[1]).split("/");

[dillonkearns]

Good catch! Thanks for pointing me to that line of code. I just pushed up a change. Could you try out the latest one and let me know how it goes?

Also, I've noticed that the npx command sometimes caches the branch's commit and doesn't fetch the latest one, so you may need to point to the latest commit, 22a3d88, instead of the branch.

[bdukes]

That fixed it, thanks for the quick reply!

[dillonkearns]

Fantastic! Thanks so much for reporting the issue and testing it out 🙏