elm-pages 3.0.0-beta.1 → 3.0.0-beta.12

package/generator/src/vite-utils.js

@@ -0,0 +1,78 @@
+/** This code is from https://github.com/sveltejs/kit/blob/3b457f67d4d7c59fc63bb3f600a490e4dacc2e62/packages/kit/src/exports/vite/utils.js */
+
+/**
+ * @param {...import('vite').UserConfig} configs
+ * @returns {import('vite').UserConfig}
+ */
+function merge_vite_configs(...configs) {
+  return deep_merge(
+    ...configs.map((config) => ({
+      ...config,
+      resolve: {
+        ...config.resolve,
+        alias: normalize_alias(config.resolve?.alias || {}),
+      },
+    }))
+  );
+}
+
+/**
+ * Takes zero or more objects and returns a new object that has all the values
+ * deeply merged together. None of the original objects will be mutated at any
+ * level, and the returned object will have no references to the original
+ * objects at any depth. If there's a conflict the last one wins, except for
+ * arrays which will be combined.
+ * @param {...Object} objects
+ * @returns {Record<string, any>} the merged object
+ */
+function deep_merge(...objects) {
+  const result = {};
+  /** @type {string[]} */
+  objects.forEach((o) => merge_into(result, o));
+  return result;
+}
+
+/**
+ * normalize kit.vite.resolve.alias as an array
+ * @param {import('vite').AliasOptions} o
+ * @returns {import('vite').Alias[]}
+ */
+function normalize_alias(o) {
+  if (Array.isArray(o)) return o;
+  return Object.entries(o).map(([find, replacement]) => ({
+    find,
+    replacement,
+  }));
+}
+
+/**
+ * Merges b into a, recursively, mutating a.
+ * @param {Record<string, any>} a
+ * @param {Record<string, any>} b
+ */
+function merge_into(a, b) {
+  /**
+   * Checks for "plain old Javascript object", typically made as an object
+   * literal. Excludes Arrays and built-in types like Buffer.
+   * @param {any} x
+   */
+  const is_plain_object = (x) =>
+    typeof x === "object" && x.constructor === Object;
+
+  for (const prop in b) {
+    if (is_plain_object(b[prop])) {
+      if (!is_plain_object(a[prop])) {
+        a[prop] = {};
+      }
+      merge_into(a[prop], b[prop]);
+    } else if (Array.isArray(b[prop])) {
+      if (!Array.isArray(a[prop])) {
+        a[prop] = [];
+      }
+      a[prop].push(...b[prop]);
+    } else {
+      a[prop] = b[prop];
+    }
+  }
+}
+module.exports = { merge_vite_configs };

package/generator/template/app/Api.elm

@@ -9,7 +9,7 @@ import Route exposing (Route)
 
 routes :
     DataSource (List Route)
-    -> (Html Never -> String)
+    -> (Maybe { indent : Int, newLines : Bool } -> Html Never -> String)
     -> List (ApiRoute ApiRoute.Response)
 routes getStaticRoutes htmlToString =
     []

package/generator/template/app/Site.elm

@@ -14,6 +14,11 @@ config =
 
 head : DataSource (List Head.Tag)
 head =
-    [ Head.sitemapLink "/sitemap.xml"
+    [ Head.metaName "viewport" (Head.raw "width=device-width,initial-scale=1")
+    , Head.metaName "mobile-web-app-capable" (Head.raw "yes")
+    , Head.metaName "theme-color" (Head.raw "#ffffff")
+    , Head.metaName "apple-mobile-web-app-capable" (Head.raw "yes")
+    , Head.metaName "apple-mobile-web-app-status-bar-style" (Head.raw "black-translucent")
+    , Head.sitemapLink "/sitemap.xml"
     ]
         |> DataSource.succeed

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "elm-pages",
-  "version": "3.0.0-beta.1",
+  "version": "3.0.0-beta.12",
   "homepage": "https://elm-pages.com",
   "moduleResolution": "node",
   "description": "Type-safe static sites, written in pure elm with your own custom elm-markup syntax.",
@@ -10,7 +10,6 @@
     "test": "./test.sh",
     "test:snapshot": "(cd examples/escaping && npm install && npm test) && (cd examples/base-path && npm install && npm test)",
     "cypress": "npm start & cypress run",
-    "prepare": "npm run build:generator",
     "build:generator": "elm-codegen install && (cd codegen && lamdera make Generate.elm --output elm-pages-codegen.js)",
     "review": "elm-review"
   },
@@ -27,14 +26,14 @@
   "dependencies": {
     "busboy": "^1.0.0",
     "chokidar": "^3.5.3",
-    "commander": "^9.4.0",
+    "commander": "9.4.1",
     "connect": "^3.7.0",
     "cookie-signature": "^1.1.0",
     "cross-spawn": "7.0.3",
     "devcert": "^1.2.2",
     "elm-doc-preview": "^5.0.5",
     "elm-hot": "^1.1.6",
-    "esbuild": "^0.15.5",
+    "esbuild": "^0.15.14",
     "fs-extra": "^10.1.0",
     "globby": "11.0.4",
     "gray-matter": "^4.0.3",
@@ -45,26 +44,26 @@
     "node-fetch": "^2.6.7",
     "object-hash": "^2.2.0",
     "serve-static": "^1.15.0",
-    "terser": "^5.14.2",
-    "vite": "^3.0.9",
+    "terser": "^5.15.1",
+    "vite": "^3.2.4",
     "which": "^2.0.2"
   },
   "devDependencies": {
     "@types/cross-spawn": "^6.0.2",
     "@types/fs-extra": "^9.0.13",
     "@types/micromatch": "^4.0.2",
-    "@types/node": "12.20.12",
+    "@types/node": "^18.11.9",
     "@types/serve-static": "^1.15.0",
-    "cypress": "^10.6.0",
+    "cypress": "^11.1.0",
     "elm-codegen": "^0.2.0",
-    "elm-optimize-level-2": "^0.1.5",
-    "elm-review": "^2.7.4",
-    "elm-test": "^0.19.1-revision9",
-    "elm-tooling": "^1.8.0",
+    "elm-optimize-level-2": "^0.3.5",
+    "elm-review": "^2.8.2",
+    "elm-test": "^0.19.1-revision10",
+    "elm-tooling": "^1.10.0",
     "elm-verify-examples": "^5.2.0",
     "elmi-to-json": "^1.2.0",
     "mocha": "^10.0.0",
-    "typescript": "^4.7.4"
+    "typescript": "^4.9.3"
   },
   "files": [
     "generator/src/",

package/src/ApiRoute.elm

@@ -1,8 +1,9 @@
 module ApiRoute exposing
-    ( ApiRoute, ApiRouteBuilder, Response
+    ( single, preRender
+    , serverRender
+    , preRenderWithFallback
+    , ApiRoute, ApiRouteBuilder, Response
     , capture, literal, slash, succeed
-    , single, preRender
-    , preRenderWithFallback, serverRender
     , withGlobalHeadTags
     , toJson, getBuildTimeRoutes, getGlobalHeadTagsDataSource
     )
@@ -11,22 +12,153 @@ module ApiRoute exposing
 to a DataSource so you can pull in HTTP data, etc. Because ApiRoutes don't hydrate into Elm apps (like pages in elm-pages do), you can pull in as much data as you want in
 the DataSource for your ApiRoutes, and it won't effect the payload size. Instead, the size of an ApiRoute is just the content you output for that route.
 
-In a future release, ApiRoutes may be able to run at request-time in a serverless function, allowing you to use pure Elm code to create dynamic APIs, and even pulling in data from
-DataSources dynamically.
+Similar to your elm-pages Route Modules, ApiRoute's can be either server-rendered or pre-rendered. Let's compare the differences between pre-rendered and server-rendered ApiRoutes, and the different
+use cases they support.
 
-@docs ApiRoute, ApiRouteBuilder, Response
 
-@docs capture, literal, slash, succeed
+## Pre-Rendering
 
+A pre-rendered ApiRoute is just a generated file. For example:
 
-## Pre-Rendering
+  - [An RSS feed](https://github.com/dillonkearns/elm-pages/blob/131f7b750cdefb2ba7a34a06be06dfbfafc79a86/examples/docs/app/Api.elm#L77-L84) ([Output file](https://elm-pages.com/blog/feed.xml))
+  - [A calendar feed in the ical format](https://github.com/dillonkearns/incrementalelm.com/blob/d4934d899d06232dc66dcf9f4b5eccc74bbc60d3/src/Api.elm#L51-L60) ([Output file](https://incrementalelm.com/live.ics))
+  - A redirect file for a hosting provider like Netlify
+
+You could even generate a JavaScript file, an Elm file, or any file with a String body! It's really just a way to generate files, which are typically used to serve files to a user or Browser, but you execute them, copy them, etc. The only limit is your imagination!
+The beauty is that you have a way to 1) pull in type-safe data using DataSource's, and 2) write those files, and all in pure Elm!
 
 @docs single, preRender
 
 
 ## Server Rendering
 
-@docs preRenderWithFallback, serverRender
+You could use server-rendered ApiRoutes to do a lot of similar things, the main difference being that it will be served up through a URL and generated on-demand when that URL is requested.
+So for example, for an RSS feed or ical calendar feed like in the pre-rendered examples, you could build the same routes, but you would be pulling in the list of posts or calendar events on-demand rather
+than upfront at build-time. That means you can hit your database and serve up always-up-to-date data.
+
+Not only that, but your server-rendered ApiRoutes have access to the incoming HTTP request payload just like your server-rendered Route Modules do. Just as with server-rendered Route Modules,
+a server-rendered ApiRoute accesses the incoming HTTP request through a [Server.Request.Parser](Server-Request). Consider the use cases that this opens up:
+
+  - Serve up protected assets. For example, gated content, like a paid subscriber feed for a podcast that checks authentication information in a query parameter to authenticate that a user has an active paid subscription before serving up the Pro RSS feed.
+  - Serve up user-specific content, either through a cookie or other means of authentication
+  - Look at the [accepted content-type in the request headers](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Accept) and use that to choose a response format, like XML or JSON ([full example](https://github.com/dillonkearns/elm-pages/blob/131f7b750cdefb2ba7a34a06be06dfbfafc79a86/examples/end-to-end/app/Api.elm#L76-L107)).
+  - Look at the [accepted language in the request headers](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Accept-Language) and use that to choose a language for the response data.
+
+@docs serverRender
+
+You can also do a hybrid approach using `preRenderWithFallback`. This allows you to pre-render a set of routes at build-time, but build additional routes that weren't rendered at build-time on the fly on the server.
+Conceptually, this is just a delayed version of a pre-rendered route. Because of that, you _do not_ have access to the incoming HTTP request (no `Server.Request.Parser` like in server-rendered ApiRoute's).
+The strategy used to build these routes will differ depending on your hosting provider and the elm-pages adapter you have setup, but generally ApiRoute's that use `preRenderWithFallback` will be cached on the server
+so within a certain time interval (or in the case of [Netlify's DPR](https://www.netlify.com/blog/2021/04/14/distributed-persistent-rendering-a-new-jamstack-approach-for-faster-builds/), until a new build is done)
+that asset will be served up if that URL was already served up by the server.
+
+@docs preRenderWithFallback
+
+
+## Defining ApiRoute's
+
+You define your ApiRoute's in `app/Api.elm`. Here's a simple example:
+
+    module Api exposing (routes)
+
+    import ApiRoute
+    import DataSource exposing (DataSource)
+    import Server.Request
+
+    routes :
+        DataSource (List Route)
+        -> (Maybe { indent : Int, newLines : Bool } -> Html Never -> String)
+        -> List (ApiRoute.ApiRoute ApiRoute.Response)
+    routes getStaticRoutes htmlToString =
+        [ preRenderedExample
+        , requestPrinterExample
+        ]
+
+    {-| Generates the following files when you
+    run `elm-pages build`:
+
+      - `dist/users/1.json`
+      - `dist/users/2.json`
+      - `dist/users/3.json`
+
+    When you host it, these static assets will
+    be served at `/users/1.json`, etc.
+
+    -}
+    preRenderedExample : ApiRoute.ApiRoute ApiRoute.Response
+    preRenderedExample =
+        ApiRoute.succeed
+            (\userId ->
+                DataSource.succeed
+                    (Json.Encode.object
+                        [ ( "id", Json.Encode.string userId )
+                        , ( "name", "Data for user " ++ userId |> Json.Encode.string )
+                        ]
+                        |> Json.Encode.encode 2
+                    )
+            )
+            |> ApiRoute.literal "users"
+            |> ApiRoute.slash
+            |> ApiRoute.capture
+            |> ApiRoute.literal ".json"
+            |> ApiRoute.preRender
+                (\route ->
+                    DataSource.succeed
+                        [ route "1"
+                        , route "2"
+                        , route "3"
+                        ]
+                )
+
+    {-| This returns a JSON response that prints information about the incoming
+    HTTP request. In practice you'd want to do something useful with that data,
+    and use more of the high-level helpers from the Server.Request API.
+    -}
+    requestPrinterExample : ApiRoute ApiRoute.Response
+    requestPrinterExample =
+        ApiRoute.succeed
+            (Server.Request.map4
+                (\rawBody method cookies queryParams ->
+                    Encode.object
+                        [ ( "rawBody"
+                          , rawBody
+                                |> Maybe.map Encode.string
+                                |> Maybe.withDefault Encode.null
+                          )
+                        , ( "method"
+                          , method
+                                |> Server.Request.methodToString
+                                |> Encode.string
+                          )
+                        , ( "cookies"
+                          , cookies
+                                |> Encode.dict
+                                    identity
+                                    Encode.string
+                          )
+                        , ( "queryParams"
+                          , queryParams
+                                |> Encode.dict
+                                    identity
+                                    (Encode.list Encode.string)
+                          )
+                        ]
+                        |> Response.json
+                        |> DataSource.succeed
+                )
+                Server.Request.rawBody
+                Server.Request.method
+                Server.Request.allCookies
+                Server.Request.queryParams
+            )
+            |> ApiRoute.literal "api"
+            |> ApiRoute.slash
+            |> ApiRoute.literal "request-test"
+            |> ApiRoute.serverRender
+
+@docs ApiRoute, ApiRouteBuilder, Response
+
+@docs capture, literal, slash, succeed
 
 
 ## Including Head Tags
@@ -57,7 +189,9 @@ type alias ApiRoute response =
     Internal.ApiRoute.ApiRoute response
 
 
-{-| -}
+{-| Same as [`preRender`](#preRender), but for an ApiRoute that has no dynamic segments. This is just a bit simpler because
+since there are no dynamic segments, you don't need to provide a DataSource with the list of dynamic segments to pre-render because there is only a single possible route.
+-}
 single : ApiRouteBuilder (DataSource String) (List String) -> ApiRoute Response
 single handler =
     handler
@@ -238,7 +372,8 @@ toJson ((ApiRoute { kind }) as apiRoute) =
         ]
 
 
-{-| -}
+{-| A literal String segment of a route.
+-}
 literal : String -> ApiRouteBuilder a constructor -> ApiRouteBuilder a constructor
 literal segment (ApiRouteBuilder patterns pattern handler toString constructor) =
     ApiRouteBuilder

package/src/DataSource/Env.elm

@@ -1,6 +1,28 @@
 module DataSource.Env exposing (get, expect)
 
-{-|
+{-| Because DataSource's in `elm-pages` never run in the browser (see [the DataSource docs](DataSource)), you can access environment variables securely. As long as the environment variable isn't sent
+down into the final `Data` value, it won't end up in the client!
+
+    import DataSource exposing (DataSource)
+    import DataSource.Env
+
+    type alias EnvVariables =
+        { sendGridKey : String
+        , siteUrl : String
+        }
+
+    sendEmail : Email -> DataSource ()
+    sendEmail email =
+        DataSource.map2 EnvVariables
+            (DataSource.Env.expect "SEND_GRID_KEY")
+            (DataSource.Env.get "BASE_URL"
+                |> DataSource.map (Maybe.withDefault "http://localhost:1234")
+            )
+            |> DataSource.andThen (sendEmailDataSource email)
+
+    sendEmailDataSource : Email -> EnvVariables -> DataSource ()
+    sendEmailDataSource email envVariables =
+        Debug.todo "Not defined here"
 
 @docs get, expect
 
@@ -13,7 +35,8 @@ import Json.Decode as Decode
 import Json.Encode as Encode
 
 
-{-| -}
+{-| Get an environment variable, or Nothing if there is no environment variable matching that name.
+-}
 get : String -> DataSource (Maybe String)
 get envVariableName =
     DataSource.Internal.Request.request
@@ -25,7 +48,8 @@ get envVariableName =
         }
 
 
-{-| -}
+{-| Get an environment variable, or a DataSource failure if there is no environment variable matching that name.
+-}
 expect : String -> DataSource String
 expect envVariableName =
     envVariableName

package/src/DataSource/File.elm

@@ -171,7 +171,7 @@ just the metadata.
             (Decode.field "tags" (Decode.list Decode.string))
 
 If you wanted to use this to get this metadata for all blog posts in a folder, you could use
-the [`DataSource`](DataSource) API along with [`DataSource.Glob`](DataSource.Glob).
+the [`DataSource`](DataSource) API along with [`DataSource.Glob`](DataSource-Glob).
 
     import DataSource exposing (DataSource)
     import DataSource.File as File

package/src/DataSource/Internal/Request.elm

@@ -1,10 +1,5 @@
 module DataSource.Internal.Request exposing (request)
 
-{-| Build a `DataSource.Http` request (analogous to [Http.request](https://package.elm-lang.org/packages/elm/http/latest/Http#request)).
-This function takes in all the details to build a `DataSource.Http` request, but you can build your own simplified helper functions
-with this as a low-level detail, or you can use functions like [DataSource.Http.get](#get).
--}
-
 import DataSource exposing (DataSource)
 import DataSource.Http exposing (Body, Expect)