elm-ssr 0.1.0

package/lib/scaffold.mjs

@@ -0,0 +1,472 @@
+import { mkdir, writeFile } from "node:fs/promises";
+import { dirname, resolve } from "node:path";
+import { readWorkspaceConfig, writeWorkspaceConfig } from "./workspace.mjs";
+
+const toWords = (value) =>
+  value
+    .split(/[^a-zA-Z0-9]+/)
+    .map((part) => part.trim())
+    .filter(Boolean);
+
+const toPascalCase = (value) =>
+  toWords(value)
+    .map((part) => part[0].toUpperCase() + part.slice(1).toLowerCase())
+    .join("");
+
+const ensureValidName = (name) => {
+  if (!/^[a-z0-9-]+$/.test(name)) {
+    throw new Error("Example name must use lowercase letters, numbers, and dashes only.");
+  }
+};
+
+const ensureAppMissing = (config, name) => {
+  if (config.apps.some((app) => app.name === name)) {
+    throw new Error(`Example "${name}" already exists in elm-ssr.config.json.`);
+  }
+};
+
+const elmJsonTemplate = () => ({
+  type: "application",
+  "source-directories": [".elm-ssr", "src", ".elm-ssr/src"],
+  "elm-version": "0.19.1",
+  dependencies: {
+    direct: {
+      "elm/browser": "1.0.2",
+      "elm/core": "1.0.5",
+      "elm/html": "1.0.0",
+      "elm/json": "1.1.3",
+      "elm/url": "1.0.0"
+    },
+    indirect: {
+      "elm/time": "1.0.0",
+      "elm/virtual-dom": "1.0.3"
+    }
+  },
+  "test-dependencies": {
+    direct: {},
+    indirect: {}
+  }
+});
+
+const sharedTemplate = (namespace) => `module ${namespace}.View.Shared exposing (head, shell)
+
+import ElmSsr.Html exposing (Node, div, h1, text)
+import ElmSsr.Html.Attributes exposing (class)
+import ElmSsr.Page as Page
+
+
+head : List (Node msg)
+head =
+    [ Page.metaCharset "utf-8"
+    , Page.metaViewport "width=device-width, initial-scale=1"
+    , Page.stylesheet "/styles.css"
+    ]
+
+
+shell : String -> List (Node msg) -> Node msg
+shell heading body =
+    div [ class "shell" ] (h1 [] [ text heading ] :: body)
+`;
+
+const indexRouteTemplate = (namespace) => `module ${namespace}.Routes.Index exposing (page, action)
+
+-- File-based routing: this module maps to GET /.
+-- A page is stateless (no Model/Msg) and ships no client JavaScript.
+
+import ElmSsr.Action as Action exposing (Action)
+import ElmSsr.Document exposing (Document)
+import ElmSsr.Html exposing (a, p, text)
+import ElmSsr.Html.Attributes exposing (class, href)
+import ElmSsr.Loader as Loader exposing (Loader)
+import ElmSsr.Page as Page
+import ElmSsr.Route exposing (Request)
+import ${namespace}.View.Shared as Shared
+
+
+page : Request -> Loader (Document Never)
+page _ =
+    Loader.succeed view
+
+
+action : Request -> Action (Document Never)
+action _ =
+    Action.fail 405 "Method not allowed"
+
+
+view : Document Never
+view =
+    Page.page
+        { title = "Starter | elm-ssr"
+        , head = Shared.head
+        , body =
+            [ Shared.shell "elm-ssr starter"
+                [ p [] [ text "This page is stateless and renders on the edge with no client runtime." ]
+                , p [] [ a [ class "link", href "/counter" ] [ text "Open the interactive counter" ] ]
+                ]
+            ]
+        }
+`;
+
+const counterRouteTemplate = (namespace) => `module ${namespace}.Routes.Counter exposing (page, action)
+
+-- File-based routing: GET /counter. A static page that embeds an interactive
+-- island. The page ships no client runtime; the browser mounts the island
+-- separately, and only that root updates.
+
+import ElmSsr.Action as Action exposing (Action)
+import ElmSsr.Document exposing (Document)
+import ElmSsr.Html exposing (p, text)
+import ElmSsr.Loader as Loader exposing (Loader)
+import ElmSsr.Page as Page
+import ElmSsr.Route exposing (Request)
+import ${namespace}.Islands.Counter as Counter
+import ${namespace}.View.Shared as Shared
+
+
+page : Request -> Loader (Document Never)
+page _ =
+    Loader.succeed view
+
+
+action : Request -> Action (Document Never)
+action _ =
+    Action.fail 405 "Method not allowed"
+
+
+view : Document Never
+view =
+    Page.page
+        { title = "Counter | elm-ssr"
+        , head = Shared.head
+        , body =
+            [ Shared.shell "Counter"
+                [ p [] [ text "This page is static. Only the counter below is an interactive island." ]
+                , Counter.embed { start = 0 }
+                ]
+            ]
+        }
+`;
+
+const counterIslandTemplate = (namespace) => `module ${namespace}.Islands.Counter exposing
+    ( embed
+    , Flags, Model, Msg
+    , encodeFlags
+    , init, main, subscriptions, update, view
+    )
+
+-- A standard Browser.element island. The page only embeds a marker and props;
+-- the browser mounts this module normally using Elm's own runtime.
+
+import ElmSsr.Island as Island
+import ElmSsr.Html as SsrHtml exposing (Node)
+import ElmSsr.Html.Attributes as SsrAttributes
+import Browser
+import Html exposing (Html, button, div, span, text)
+import Html.Attributes exposing (class, type_)
+import Html.Events exposing (onClick)
+import Json.Encode as Encode
+
+
+embed : Flags -> Node msg
+embed =
+    Island.embed "Counter"
+        { encodeFlags = encodeFlags
+        , fallback = fallback
+        , id = Nothing
+        }
+
+
+type alias Flags =
+    { start : Int }
+
+
+type alias Model =
+    { count : Int }
+
+
+type Msg
+    = Increment
+    | Decrement
+
+
+encodeFlags : Flags -> Encode.Value
+encodeFlags flags =
+    Encode.object [ ( "start", Encode.int flags.start ) ]
+
+
+fallback : Flags -> List (Node msg)
+fallback flags =
+    [ SsrHtml.div [ SsrAttributes.class "counter fallback" ]
+        [ SsrHtml.span [ SsrAttributes.class "value" ] [ SsrHtml.text (String.fromInt flags.start) ] ]
+    ]
+
+
+main : Program Flags Model Msg
+main =
+    Browser.element
+        { init = init
+        , update = update
+        , view = view
+        , subscriptions = subscriptions
+        }
+
+
+init : Flags -> ( Model, Cmd Msg )
+init flags =
+    ( { count = flags.start }, Cmd.none )
+
+
+update : Msg -> Model -> ( Model, Cmd Msg )
+update msg model =
+    case msg of
+        Increment ->
+            ( { model | count = model.count + 1 }, Cmd.none )
+
+        Decrement ->
+            ( { model | count = model.count - 1 }, Cmd.none )
+
+
+subscriptions : Model -> Sub Msg
+subscriptions _ =
+    Sub.none
+
+
+view : Model -> Html Msg
+view model =
+    div [ class "counter" ]
+        [ button [ class "button", type_ "button", onClick Decrement ] [ text "-" ]
+        , span [ class "value" ] [ text (String.fromInt model.count) ]
+        , button [ class "button primary", type_ "button", onClick Increment ] [ text "+" ]
+        ]
+`;
+
+const notFoundRouteTemplate = (namespace) => `module ${namespace}.Routes.NotFound exposing (page, action)
+
+-- File-based routing: NotFound is the fallback when no other route matches.
+
+import ElmSsr.Action as Action exposing (Action)
+import ElmSsr.Document exposing (Document)
+import ElmSsr.Html exposing (p, text)
+import ElmSsr.Loader as Loader exposing (Loader)
+import ElmSsr.Page as Page
+import ElmSsr.Route exposing (Request)
+import ${namespace}.View.Shared as Shared
+
+
+page : Request -> Loader (Document Never)
+page _ =
+    Loader.succeed view
+
+
+action : Request -> Action (Document Never)
+action _ =
+    Action.fail 405 "Method not allowed"
+
+
+view : Document Never
+view =
+    Page.notFound
+        { title = "Not Found | elm-ssr"
+        , head = Shared.head
+        , body = [ Shared.shell "404" [ p [] [ text "This route does not exist." ] ] ]
+        }
+`;
+
+const runtimeTemplate = (name) => `import { createWorkerApp } from "elm-ssr";
+import { renderApp, type CompiledElmModule } from "elm-ssr/render";
+import type { RouteCatalog } from "elm-ssr/http";
+import { islands, bundleSource } from "../../generated/examples/${name}/islands-manifest";
+import { stylesheet } from "./styles";
+// @ts-expect-error Generated at build time.
+import ElmRuntime from "../../generated/examples/${name}/app.mjs";
+
+const elmModule = ElmRuntime as CompiledElmModule;
+
+export const routes: RouteCatalog = {
+  pages: [
+    {
+      path: "/",
+      methods: ["GET", "HEAD"],
+      description: "Stateless starter page rendered from Elm (no client runtime)."
+    },
+    {
+      path: "/counter",
+      methods: ["GET", "HEAD"],
+      description: "Interactive counter route rendered from Elm."
+    }
+  ],
+  assets: [
+    {
+      path: "/styles.css",
+      methods: ["GET", "HEAD"],
+      description: "Starter stylesheet."
+    },
+    {
+      path: "/__elm-ssr/islands.js",
+      methods: ["GET", "HEAD"],
+      description: "Island loader runtime."
+    },
+    {
+      path: "/__elm-ssr/islands-bundle.js",
+      methods: ["GET", "HEAD"],
+      description: "Shared Browser.element island bundle."
+    }
+  ],
+  utility: [
+    {
+      path: "/health",
+      methods: ["GET", "HEAD"],
+      description: "Plain text liveness endpoint."
+    }
+  ],
+  api: [
+    {
+      path: "/api/health",
+      methods: ["GET", "HEAD"],
+      description: "JSON health payload."
+    },
+    {
+      path: "/api/routes",
+      methods: ["GET", "HEAD"],
+      description: "Route registry for the starter app."
+    },
+    {
+      path: "/api/render",
+      methods: ["GET", "HEAD"],
+      description: "SSR preview endpoint."
+    }
+  ]
+};
+
+export const createFlags = ({ request, path, formData }: { request?: Request; url?: URL; path: string; formData?: Record<string, string> }) => {
+  const [pathname, search = ""] = path.split("?");
+
+  return {
+    method: request?.method ?? "GET",
+    path: pathname,
+    query: Object.fromEntries(new URLSearchParams(search)),
+    formData: formData ?? {}
+  };
+};
+
+export const renderPath = async (path: string) =>
+  renderApp(elmModule, createFlags({ path }));
+
+export const worker = createWorkerApp({
+  elmModule,
+  islands,
+  islandsBundle: bundleSource,
+  stylesheet,
+  routes,
+  createFlags
+});
+`;
+
+const workerTemplate = () => `import { worker } from "./runtime";
+
+export default worker;
+`;
+
+const stylesTemplate = () => `export const stylesheet = \`
+:root {
+  color-scheme: light;
+  font-family: "IBM Plex Sans", sans-serif;
+  background: #f3efe7;
+  color: #18222f;
+}
+
+body {
+  margin: 0;
+  background:
+    radial-gradient(circle at top, rgba(255, 255, 255, 0.85), transparent 45%),
+    linear-gradient(180deg, #f8f3ea 0%, #efe7dc 100%);
+}
+
+.shell {
+  max-width: 44rem;
+  margin: 0 auto;
+  padding: 4rem 1.5rem;
+}
+
+.counter {
+  display: grid;
+  grid-template-columns: auto 1fr auto;
+  gap: 0.75rem;
+  align-items: center;
+  margin: 2rem 0;
+}
+
+.button,
+.input {
+  border-radius: 999px;
+  border: 1px solid #18222f;
+  padding: 0.85rem 1.1rem;
+  font: inherit;
+  background: white;
+}
+
+.button {
+  cursor: pointer;
+}
+
+.value {
+  text-align: center;
+  font-size: 2rem;
+  font-weight: 700;
+}
+
+.form {
+  margin-top: 1rem;
+}
+
+.input {
+  width: 100%;
+  box-sizing: border-box;
+}
+\`;
+`;
+
+const filesForExample = (name) => {
+  const namespace = toPascalCase(name);
+
+  return {
+    configEntry: {
+      name,
+      root: `examples/${name}`,
+      module: namespace
+    },
+    files: [
+      { path: `examples/${name}/elm.json`, content: JSON.stringify(elmJsonTemplate(), null, 2) + "\n" },
+      { path: `examples/${name}/runtime.ts`, content: runtimeTemplate(name) },
+      { path: `examples/${name}/worker.ts`, content: workerTemplate() },
+      { path: `examples/${name}/styles.ts`, content: stylesTemplate() },
+      { path: `examples/${name}/src/${namespace}/View/Shared.elm`, content: sharedTemplate(namespace) },
+      { path: `examples/${name}/src/${namespace}/Routes/Index.elm`, content: indexRouteTemplate(namespace) },
+      { path: `examples/${name}/src/${namespace}/Routes/Counter.elm`, content: counterRouteTemplate(namespace) },
+      { path: `examples/${name}/src/${namespace}/Routes/NotFound.elm`, content: notFoundRouteTemplate(namespace) },
+      { path: `examples/${name}/src/${namespace}/Islands/Counter.elm`, content: counterIslandTemplate(namespace) }
+    ]
+  };
+};
+
+export const createExampleScaffold = async (rootPath, name) => {
+  ensureValidName(name);
+
+  const config = await readWorkspaceConfig(rootPath);
+  ensureAppMissing(config, name);
+
+  const { configEntry, files } = filesForExample(name);
+
+  for (const file of files) {
+    const filePath = resolve(rootPath, file.path);
+    await mkdir(dirname(filePath), { recursive: true });
+    await writeFile(filePath, file.content, "utf8");
+  }
+
+  await writeWorkspaceConfig(rootPath, {
+    ...config,
+    apps: [...config.apps, configEntry]
+  });
+
+  return configEntry;
+};

package/lib/workspace.mjs

@@ -0,0 +1,21 @@
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { dirname, resolve } from "node:path";
+
+export const configFileName = "elm-ssr.config.json";
+
+export const readJsonFile = async (filePath) =>
+  JSON.parse(await readFile(filePath, "utf8"));
+
+export const writeJsonFile = async (filePath, value) => {
+  await mkdir(dirname(filePath), { recursive: true });
+  await writeFile(filePath, `${JSON.stringify(value, null, 2)}\n`, "utf8");
+};
+
+export const workspaceConfigPath = (rootPath) =>
+  resolve(rootPath, configFileName);
+
+export const readWorkspaceConfig = async (rootPath) =>
+  readJsonFile(workspaceConfigPath(rootPath));
+
+export const writeWorkspaceConfig = async (rootPath, config) =>
+  writeJsonFile(workspaceConfigPath(rootPath), config);

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "elm-ssr",
+  "version": "0.1.0",
+  "description": "Elm-first SSR library and framework for Cloudflare Workers (and Bun): file-based routes/islands, backend-neutral effect adapters (KV/D1/Redis/Postgres), background tasks (waitUntil/Queues), SQL-file migrations, CLI scaffold + build.",
+  "license": "MIT",
+  "author": "Michał Majchrzak <michmajchrzak@gmail.com>",
+  "homepage": "https://github.com/the-man-with-a-golden-mind/elm-ssr#readme",
+  "bugs": {
+    "url": "https://github.com/the-man-with-a-golden-mind/elm-ssr/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/the-man-with-a-golden-mind/elm-ssr.git",
+    "directory": "packages/elm-ssr"
+  },
+  "keywords": [
+    "elm",
+    "ssr",
+    "server-side-rendering",
+    "cloudflare-workers",
+    "bun",
+    "islands",
+    "framework",
+    "edge",
+    "file-based-routing",
+    "migrations"
+  ],
+  "type": "module",
+  "scripts": {},
+  "bin": {
+    "elm-ssr": "bin/elm-ssr.mjs"
+  },
+  "main": "./src/app.ts",
+  "exports": {
+    ".": "./src/app.ts",
+    "./render": "./src/render.ts",
+    "./http": "./src/http.ts",
+    "./effects": "./src/effects.ts",
+    "./tasks": "./src/tasks.ts",
+    "./backends": "./src/backends.ts",
+    "./migrations": "./src/migrations.ts",
+    "./middleware": "./src/middleware.ts",
+    "./response-headers": "./src/response-headers.ts",
+    "./serialize": "./src/serialize.ts",
+    "./protocol": "./src/protocol.ts",
+    "./islands-runtime": "./src/client-runtime/islands.ts"
+  },
+  "files": [
+    "bin",
+    "lib",
+    "elm-src",
+    "src"
+  ],
+  "engines": {
+    "bun": ">=1.3"
+  },
+  "dependencies": {
+    "cookie": "^1.0.1"
+  }
+}

package/src/app.ts

@@ -0,0 +1,74 @@
+import type {
+  RenderFlagsFactory,
+  RouteCatalog,
+  WorkerExecutionContext,
+  WorkerHandler
+} from "./http";
+import {
+  composeMiddleware,
+  errorMiddleware,
+  headMiddleware,
+  loggingMiddleware,
+  requestIdMiddleware,
+  timingMiddleware
+} from "./middleware";
+import { type EffectRunner } from "./effects";
+import { createRequestHandler } from "./request-handler";
+import { type CompiledElmModule } from "./render";
+
+export interface IslandMetadata {
+  module: string;
+}
+
+export interface WorkerAppOptions {
+  elmModule: CompiledElmModule;
+  islands?: Record<string, IslandMetadata>;
+  islandsBundle?: string;
+  stylesheet: string;
+  routes: RouteCatalog;
+  createFlags: RenderFlagsFactory;
+  effects?: EffectRunner;
+  log?: (entry: string) => void;
+}
+
+export const createWorkerApp = ({
+  elmModule,
+  islands,
+  islandsBundle,
+  stylesheet,
+  routes,
+  createFlags,
+  effects,
+  log
+}: WorkerAppOptions): WorkerHandler => {
+  const handler = createRequestHandler({
+    elmModule,
+    islands,
+    islandsBundle,
+    stylesheet,
+    routes,
+    createFlags,
+    effects
+  });
+
+  const appHandler = composeMiddleware(handler, [
+    errorMiddleware,
+    requestIdMiddleware,
+    timingMiddleware,
+    loggingMiddleware(log),
+    headMiddleware
+  ]);
+
+  return {
+    fetch(request: Request, env?: unknown, executionCtx?: WorkerExecutionContext) {
+      return appHandler({
+        request,
+        url: new URL(request.url),
+        requestId: "",
+        startedAt: performance.now(),
+        executionCtx,
+        env: (env ?? undefined) as Record<string, unknown> | undefined
+      });
+    }
+  };
+};