elm-pages 3.0.0-beta.2 → 3.0.0-beta.20

package/src/ApiRoute.elm

@@ -1,32 +1,164 @@
 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
+    , toJson, getBuildTimeRoutes, getGlobalHeadTagsBackendTask
     )
 
 {-| ApiRoute's are defined in `src/Api.elm` and are a way to generate files, like RSS feeds, sitemaps, or any text-based file that you output with an Elm function! You get access
-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.
+to a BackendTask 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 BackendTask 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 BackendTask'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 BackendTask exposing (BackendTask)
+    import Server.Request
+
+    routes :
+        BackendTask (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 ->
+                BackendTask.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 ->
+                    BackendTask.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
+                        |> BackendTask.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
@@ -36,12 +168,12 @@ DataSources dynamically.
 
 ## Internals
 
-@docs toJson, getBuildTimeRoutes, getGlobalHeadTagsDataSource
+@docs toJson, getBuildTimeRoutes, getGlobalHeadTagsBackendTask
 
 -}
 
-import DataSource exposing (DataSource)
-import DataSource.Http
+import BackendTask exposing (BackendTask)
+import FatalError exposing (FatalError)
 import Head
 import Internal.ApiRoute exposing (ApiRoute(..), ApiRouteBuilder(..))
 import Json.Decode as Decode
@@ -57,27 +189,38 @@ type alias ApiRoute response =
     Internal.ApiRoute.ApiRoute response
 
 
-{-| -}
-single : ApiRouteBuilder (DataSource String) (List String) -> 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 BackendTask with the list of dynamic segments to pre-render because there is only a single possible route.
+-}
+single : ApiRouteBuilder (BackendTask FatalError String) (List String) -> ApiRoute Response
 single handler =
     handler
-        |> preRender (\constructor -> DataSource.succeed [ constructor ])
+        |> preRender (\constructor -> BackendTask.succeed [ constructor ])
 
 
 {-| -}
-serverRender : ApiRouteBuilder (Server.Request.Parser (DataSource (Server.Response.Response Never Never))) constructor -> ApiRoute Response
+serverRender : ApiRouteBuilder (Server.Request.Parser (BackendTask FatalError (Server.Response.Response Never Never))) constructor -> ApiRoute Response
 serverRender ((ApiRouteBuilder patterns pattern _ _ _) as fullHandler) =
     ApiRoute
         { regex = Regex.fromString ("^" ++ pattern ++ "$") |> Maybe.withDefault Regex.never
         , matchesToResponse =
-            \path ->
+            \serverRequest path ->
                 Internal.ApiRoute.tryMatch path fullHandler
                     |> Maybe.map
-                        (\toDataSource ->
-                            DataSource.Http.get
-                                "$$elm-pages$$headers"
-                                (toDataSource |> Server.Request.getDecoder |> Decode.map Just)
-                                |> DataSource.andThen
+                        (\toBackendTask ->
+                            Server.Request.getDecoder toBackendTask
+                                |> (\decoder ->
+                                        Decode.decodeValue decoder serverRequest
+                                            |> Result.mapError Decode.errorToString
+                                            |> BackendTask.fromResult
+                                            |> BackendTask.map Just
+                                   )
+                                |> BackendTask.onError
+                                    (\stringError ->
+                                        -- TODO make error with title and better context/formatting
+                                        FatalError.fromString stringError |> BackendTask.fail
+                                    )
+                                |> BackendTask.andThen
                                     (\rendered ->
                                         case rendered of
                                             Just (Ok okRendered) ->
@@ -88,21 +231,21 @@ serverRender ((ApiRouteBuilder patterns pattern _ _ _) as fullHandler) =
                                                     |> Server.Request.errorsToString
                                                     |> Server.Response.plainText
                                                     |> Server.Response.withStatusCode 400
-                                                    |> DataSource.succeed
+                                                    |> BackendTask.succeed
 
                                             Nothing ->
                                                 Server.Response.plainText "No matching request handler"
                                                     |> Server.Response.withStatusCode 400
-                                                    |> DataSource.succeed
+                                                    |> BackendTask.succeed
                                     )
                         )
-                    |> Maybe.map (DataSource.map (Server.Response.toJson >> Just))
+                    |> Maybe.map (BackendTask.map (Server.Response.toJson >> Just))
                     |> Maybe.withDefault
-                        (DataSource.succeed Nothing)
-        , buildTimeRoutes = DataSource.succeed []
+                        (BackendTask.succeed Nothing)
+        , buildTimeRoutes = BackendTask.succeed []
         , handleRoute =
             \path ->
-                DataSource.succeed
+                BackendTask.succeed
                     (case Internal.ApiRoute.tryMatch path fullHandler of
                         Just _ ->
                             True
@@ -117,26 +260,26 @@ serverRender ((ApiRouteBuilder patterns pattern _ _ _) as fullHandler) =
 
 
 {-| -}
-preRenderWithFallback : (constructor -> DataSource (List (List String))) -> ApiRouteBuilder (DataSource (Server.Response.Response Never Never)) constructor -> ApiRoute Response
+preRenderWithFallback : (constructor -> BackendTask FatalError (List (List String))) -> ApiRouteBuilder (BackendTask FatalError (Server.Response.Response Never Never)) constructor -> ApiRoute Response
 preRenderWithFallback buildUrls ((ApiRouteBuilder patterns pattern _ toString constructor) as fullHandler) =
     let
-        buildTimeRoutes__ : DataSource (List String)
+        buildTimeRoutes__ : BackendTask FatalError (List String)
         buildTimeRoutes__ =
             buildUrls (constructor [])
-                |> DataSource.map (List.map toString)
+                |> BackendTask.map (List.map toString)
     in
     ApiRoute
         { regex = Regex.fromString ("^" ++ pattern ++ "$") |> Maybe.withDefault Regex.never
         , matchesToResponse =
-            \path ->
+            \_ path ->
                 Internal.ApiRoute.tryMatch path fullHandler
-                    |> Maybe.map (DataSource.map (Server.Response.toJson >> Just))
+                    |> Maybe.map (BackendTask.map (Server.Response.toJson >> Just))
                     |> Maybe.withDefault
-                        (DataSource.succeed Nothing)
+                        (BackendTask.succeed Nothing)
         , buildTimeRoutes = buildTimeRoutes__
         , handleRoute =
             \path ->
-                DataSource.succeed
+                BackendTask.succeed
                     (case Internal.ApiRoute.tryMatch path fullHandler of
                         Just _ ->
                             True
@@ -159,42 +302,42 @@ encodeStaticFileBody fileBody =
 
 
 {-| -}
-preRender : (constructor -> DataSource (List (List String))) -> ApiRouteBuilder (DataSource String) constructor -> ApiRoute Response
+preRender : (constructor -> BackendTask FatalError (List (List String))) -> ApiRouteBuilder (BackendTask FatalError String) constructor -> ApiRoute Response
 preRender buildUrls ((ApiRouteBuilder patterns pattern _ toString constructor) as fullHandler) =
     let
-        buildTimeRoutes__ : DataSource (List String)
+        buildTimeRoutes__ : BackendTask FatalError (List String)
         buildTimeRoutes__ =
             buildUrls (constructor [])
-                |> DataSource.map (List.map toString)
+                |> BackendTask.map (List.map toString)
 
-        preBuiltMatches : DataSource (List (List String))
+        preBuiltMatches : BackendTask FatalError (List (List String))
         preBuiltMatches =
             buildUrls (constructor [])
     in
     ApiRoute
         { regex = Regex.fromString ("^" ++ pattern ++ "$") |> Maybe.withDefault Regex.never
         , matchesToResponse =
-            \path ->
+            \_ path ->
                 let
                     matches : List String
                     matches =
                         Internal.ApiRoute.pathToMatches path fullHandler
 
-                    routeFound : DataSource Bool
+                    routeFound : BackendTask FatalError Bool
                     routeFound =
                         preBuiltMatches
-                            |> DataSource.map (List.member matches)
+                            |> BackendTask.map (List.member matches)
                 in
                 routeFound
-                    |> DataSource.andThen
+                    |> BackendTask.andThen
                         (\found ->
                             if found then
                                 Internal.ApiRoute.tryMatch path fullHandler
-                                    |> Maybe.map (DataSource.map (encodeStaticFileBody >> Just))
-                                    |> Maybe.withDefault (DataSource.succeed Nothing)
+                                    |> Maybe.map (BackendTask.map (encodeStaticFileBody >> Just))
+                                    |> Maybe.withDefault (BackendTask.succeed Nothing)
 
                             else
-                                DataSource.succeed Nothing
+                                BackendTask.succeed Nothing
                         )
         , buildTimeRoutes = buildTimeRoutes__
         , handleRoute =
@@ -205,7 +348,7 @@ preRender buildUrls ((ApiRouteBuilder patterns pattern _ toString constructor) a
                         Internal.ApiRoute.pathToMatches path fullHandler
                 in
                 preBuiltMatches
-                    |> DataSource.map (List.member matches)
+                    |> BackendTask.map (List.member matches)
         , pattern = patterns
         , kind = "prerender"
         , globalHeadTags = Nothing
@@ -238,7 +381,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
@@ -287,25 +431,19 @@ capture (ApiRouteBuilder patterns pattern previousHandler toString constructor)
 
 {-| For internal use by generated code. Not so useful in user-land.
 -}
-getBuildTimeRoutes : ApiRoute response -> DataSource (List String)
+getBuildTimeRoutes : ApiRoute response -> BackendTask FatalError (List String)
 getBuildTimeRoutes (ApiRoute handler) =
     handler.buildTimeRoutes
 
 
 {-| Include head tags on every page's HTML.
 -}
-withGlobalHeadTags : DataSource (List Head.Tag) -> ApiRoute response -> ApiRoute response
+withGlobalHeadTags : BackendTask FatalError (List Head.Tag) -> ApiRoute response -> ApiRoute response
 withGlobalHeadTags globalHeadTags (ApiRoute handler) =
     ApiRoute { handler | globalHeadTags = Just globalHeadTags }
 
 
 {-| -}
-getGlobalHeadTagsDataSource : ApiRoute response -> Maybe (DataSource (List Head.Tag))
-getGlobalHeadTagsDataSource (ApiRoute handler) =
+getGlobalHeadTagsBackendTask : ApiRoute response -> Maybe (BackendTask FatalError (List Head.Tag))
+getGlobalHeadTagsBackendTask (ApiRoute handler) =
     handler.globalHeadTags
-
-
-
---captureRest : ApiRouteBuilder (List String -> a) b -> ApiRouteBuilder a b
---captureRest previousHandler =
---    Debug.todo ""

package/src/BackendTask/Custom.elm

@@ -0,0 +1,214 @@
+module BackendTask.Custom exposing
+    ( run
+    , Error(..)
+    )
+
+{-| In a vanilla Elm application, ports let you either send or receive JSON data between your Elm application and the JavaScript context in the user's browser at runtime.
+
+With `BackendTask.Custom`, you send and receive JSON to JavaScript running in NodeJS. As with any `BackendTask`, Custom BackendTask's are either run at build-time (for pre-rendered routes) or at request-time (for server-rendered routes). See [`BackendTask`](BackendTask) for more about the
+lifecycle of `BackendTask`'s.
+
+This means that you can call shell scripts, run NPM packages that are installed, or anything else you could do with NodeJS to perform custom side-effects, get some data, or both.
+
+A `BackendTask.Custom` will call an async JavaScript function with the given name from the definition in a file called `custom-backend-task.js` in your project's root directory. The function receives the input JSON value, and the Decoder is used to decode the return value of the async function.
+
+@docs run
+
+Here is the Elm code and corresponding JavaScript definition for getting an environment variable (or an `FatalError BackendTask.Custom.Error` if it isn't found). In this example,
+we're using `BackendTask.allowFatal` to let the framework treat that as an unexpected exception, but we could also handle the possible failures of the `FatalError` (see [`FatalError`](FatalError)).
+
+    import BackendTask exposing (BackendTask)
+    import BackendTask.Custom
+    import Json.Encode
+    import OptimizedDecoder as Decode
+
+    data : BackendTask FatalError String
+    data =
+        BackendTask.Custom.run "environmentVariable"
+            (Json.Encode.string "EDITOR")
+            Decode.string
+            |> BackendTask.allowFatal
+
+    -- will resolve to "VIM" if you run `EDITOR=vim elm-pages dev`
+
+```javascript
+// custom-backend-task.js
+
+module.exports =
+  /**
+   * @param { unknown } fromElm
+   * @returns { Promise<unknown> }
+   */
+  {
+    environmentVariable: async function (name) {
+      const result = process.env[name];
+      if (result) {
+        return result;
+      } else {
+        throw `No environment variable called ${name}
+
+Available:
+
+${Object.keys(process.env).join("\n")}
+`;
+      }
+    },
+  }
+```
+
+
+## Performance
+
+As with any JavaScript or NodeJS code, avoid doing blocking IO operations. For example, avoid using `fs.readFileSync`, because blocking IO can slow down your elm-pages builds and dev server. `elm-pages` performs all `BackendTask`'s in parallel whenever possible.
+So if you do `BackendTask.map2 Tuple.pair myHttpBackendTask myCustomBackendTask`, it will resolve those two in parallel. NodeJS performs best when you take advantage of its ability to do non-blocking I/O (file reads, HTTP requests, etc.). If you use `BackendTask.andThen`,
+it will need to resolve them in sequence rather than in parallel, but it's still best to avoid blocking IO operations in your Custom BackendTask definitions.
+
+
+## Error Handling
+
+There are a few different things that can go wrong when running a custom-backend-task. These possible errors are captured in the `BackendTask.Custom.Error` type.
+
+@docs Error
+
+Any time you throw a JavaScript exception from a BackendTask.Custom definition, it will give you a `CustomBackendTaskException`. It's usually easier to add a `try`/`catch` in your JavaScript code in `custom-backend-task.js`
+to handle possible errors, but you can throw a JSON value and handle it in Elm in the `CustomBackendTaskException` call error.
+
+-}
+
+import BackendTask
+import BackendTask.Http
+import BackendTask.Internal.Request
+import FatalError exposing (FatalError)
+import Json.Decode as Decode exposing (Decoder)
+import Json.Encode as Encode
+import TerminalText
+
+
+{-| -}
+run :
+    String
+    -> Encode.Value
+    -> Decoder b
+    -> BackendTask.BackendTask { fatal : FatalError, recoverable : Error } b
+run portName input decoder =
+    BackendTask.Internal.Request.request
+        { name = "port"
+        , body =
+            Encode.object
+                [ ( "input", input )
+                , ( "portName", Encode.string portName )
+                ]
+                |> BackendTask.Http.jsonBody
+        , expect =
+            Decode.oneOf
+                [ Decode.field "elm-pages-internal-error" Decode.string
+                    |> Decode.andThen
+                        (\errorKind ->
+                            if errorKind == "CustomBackendTaskNotDefined" then
+                                FatalError.recoverable
+                                    { title = "Custom BackendTask Error"
+                                    , body =
+                                        [ TerminalText.text "Something went wrong in a call to BackendTask.Custom.run. I expected to find a port named `"
+                                        , TerminalText.yellow portName
+                                        , TerminalText.text "` but I couldn't find it. Is the function exported in your custom-backend-task file?"
+                                        ]
+                                            |> TerminalText.toString
+                                    }
+                                    (CustomBackendTaskNotDefined { name = portName })
+                                    |> Decode.succeed
+
+                            else if errorKind == "ExportIsNotFunction" then
+                                Decode.field "error" Decode.string
+                                    |> Decode.maybe
+                                    |> Decode.map (Maybe.withDefault "")
+                                    |> Decode.map
+                                        (\incorrectType ->
+                                            FatalError.recoverable
+                                                { title = "Custom BackendTask Error"
+                                                , body =
+                                                    [ TerminalText.text "Something went wrong in a call to BackendTask.Custom.run. I found an export called `"
+                                                    , TerminalText.yellow portName
+                                                    , TerminalText.text "` but I expected its type to be function, but instead its type was: "
+                                                    , TerminalText.red incorrectType
+                                                    ]
+                                                        |> TerminalText.toString
+                                                }
+                                                ExportIsNotFunction
+                                        )
+
+                            else if errorKind == "MissingCustomBackendTaskFile" then
+                                FatalError.recoverable
+                                    { title = "Custom BackendTask Error"
+                                    , body =
+                                        [ TerminalText.text "Something went wrong in a call to BackendTask.Custom.run. I couldn't find your custom-backend-task file. Be sure to create a 'custom-backend-task.ts' or 'custom-backend-task.js' file."
+                                        ]
+                                            |> TerminalText.toString
+                                    }
+                                    MissingCustomBackendTaskFile
+                                    |> Decode.succeed
+
+                            else if errorKind == "ErrorInCustomBackendTaskFile" then
+                                Decode.field "error" Decode.string
+                                    |> Decode.maybe
+                                    |> Decode.map (Maybe.withDefault "")
+                                    |> Decode.map
+                                        (\errorMessage ->
+                                            FatalError.recoverable
+                                                { title = "Custom BackendTask Error"
+                                                , body =
+                                                    [ TerminalText.text "Something went wrong in a call to BackendTask.Custom.run. I couldn't import the port definitions file, because of this exception:\n\n"
+                                                    , TerminalText.red errorMessage
+                                                    , TerminalText.text "\n\nAre there syntax errors or exceptions thrown during import?"
+                                                    ]
+                                                        |> TerminalText.toString
+                                                }
+                                                ErrorInCustomBackendTaskFile
+                                        )
+
+                            else if errorKind == "CustomBackendTaskException" then
+                                Decode.field "error" Decode.value
+                                    |> Decode.maybe
+                                    |> Decode.map (Maybe.withDefault Encode.null)
+                                    |> Decode.map
+                                        (\portCallError ->
+                                            FatalError.recoverable
+                                                { title = "Custom BackendTask Error"
+                                                , body =
+                                                    [ TerminalText.text "Something went wrong in a call to BackendTask.Custom.run. I was able to import the port definitions file, but when running it I encountered this exception:\n\n"
+                                                    , TerminalText.red (Encode.encode 2 portCallError)
+                                                    , TerminalText.text "\n\nYou could add a `try`/`catch` in your `custom-backend-task` JavaScript code to handle that error."
+                                                    ]
+                                                        |> TerminalText.toString
+                                                }
+                                                (CustomBackendTaskException portCallError)
+                                        )
+
+                            else
+                                FatalError.recoverable
+                                    { title = "Custom BackendTask Error"
+                                    , body =
+                                        [ TerminalText.text "Something went wrong in a call to BackendTask.Custom.run. I expected to find a port named `"
+                                        , TerminalText.yellow portName
+                                        , TerminalText.text "`."
+                                        ]
+                                            |> TerminalText.toString
+                                    }
+                                    ErrorInCustomBackendTaskFile
+                                    |> Decode.succeed
+                        )
+                    |> Decode.map Err
+                , decoder |> Decode.map Ok
+                ]
+                |> BackendTask.Http.expectJson
+        }
+        |> BackendTask.andThen BackendTask.fromResult
+
+
+{-| -}
+type Error
+    = Error
+    | ErrorInCustomBackendTaskFile
+    | MissingCustomBackendTaskFile
+    | CustomBackendTaskNotDefined { name : String }
+    | CustomBackendTaskException Decode.Value
+    | ExportIsNotFunction