Provide a way to render static 404 pages using elm-pages

[adamdicarlo0]

See what Dillon wrote in a below comment - excerpt:

the main goal here is to have a way for static sites to serve up a 404 page using an elm-pages Route (ideally the ErrorPage NotFound rendering, which currently only works for server-rendered error pages).

---

On the Elm Slack, @supermario shared a work-around for showing 404 pages at arbitrary URLs. Trying to use it, I realized it's only possible if you bypass the routing system in Elm Pages; his site (Elmcraft) is using a single (root-level) SPLAT__ route; in other words, he's catching all requests in that one Elm Pages route and then using his own logic to decide what to show.

Here's what I did, not realizing the single SPLAT__ route was necessary:

• Added a static route called PageNotFound (RouteBuilder.single |> RouteBuilder.buildNoState)

• After building the site, ran

  cp dist/page-not-found/index.html dist/404.html

• Deployed to AWS

We have ~CloudFlare~ (AWS) CloudFront serving that 404.html for 404s. It works for half a second -- that is, the static HTML is shown for half a second, until the page hydrates. Then the main routing logic in .elm-pages/Main.elm (generated by this code) decides that the current URL path doesn't match any routes, so it re-renders the page with a fallback "This page could not be found" message. The effect is "flash of real 404 page followed by plain white fallback error page".

Screen capture gif showing what happens


[adamdicarlo0]

My work-around for this, for now, is adding this logic to my elm-pages.config.mjs adapter function:

  //
  // Hack: Work around an Elm Pages bug in our 404 page by removing its script tags.
  //
  // The bug: ErrorPage is shown as-is very briefly, but upon the Elm app hydrating and running, it
  // decides that the current route has no matches, and the routing logic hits a fallback that makes
  // it display a hard-coded "This page could not be found" message, instead of our ErrorPage.
  //
  // Search `.elm-pages/Main.elm` for "This page could" to see the (generated) code responsible.
  //
  // Issue: https://github.com/dillonkearns/elm-pages/issues/432
  //
  // We can't solve this by making the page a root-level "splat", either:
  // https://github.com/dillonkearns/elm-pages/issues/407
  //
  // Related: https://github.com/dillonkearns/elm-pages/issues/397
  //
  const notFoundPath = "dist/page-not-found/index.html";
  const html = await readFile(notFoundPath, "utf-8");

  // The tags look like this:
  // <script defer src="/elm.fcba9bad.js" type="text/javascript"></script>
  // <script type="module" crossorigin src="/assets/index-06bd4283.js"></script>
  const fixedHtml = html
    .replace(
      /<script defer src="\/elm\..{8}\.js" type="text\/javascript"><\/script>/,
      ""
    )
    .replace(
      /<script type="module" crossorigin src="\/assets\/index-.{8}\.js"><\/script>/,
      ""
    );
  await writeFile(notFoundPath, fixedHtml, "utf-8");

Here's the import for the file functions:

import { readFile, writeFile } from "node:fs/promises";

[dillonkearns]

To try to summarize the situation concisely for anyone who is trying to understand this GitHub Issue, the main goal here is to have a way for static sites to serve up a 404 page using an elm-pages Route (ideally the ErrorPage NotFound rendering, which currently only works for server-rendered error pages).

One of the core challenges here is that elm-pages makes some assumptions that the URL it is being loaded at is from the static files it generates. If you use redirects or nginx rules, etc. to serve up something like /not-found when the actual URL that is visited is /this/url/does/not/exist, then elm-pages tries to resolve the URL using its routing so when it hydrates it can cause errors.