Request in.Document out.

Worker handles framework assets first.

The request handler serves /styles.css, /__elm-ssr/islands.js, /__elm-ssr/islands-bundle.js, /health, /api/health, /api/routes, and /api/render before falling through to page rendering.

Read methods use the Loader.

GET and HEAD render through the route's page : Request -> Loader (Document msg). Unsupported methods return 405; POST-style work belongs in action.

Elm describes effects.

A Loader or Action can pause on effects like fetch, cache, SQL, env, cookie, queue, or session. The Worker runs the effect and resumes Elm with decoded data.

The result chooses the HTTP response.

The runtime returns a redirect, JSON, or a serialized Document. Action cookies are appended as Set-Cookie headers.

The generated Elm module plugs into createWorkerApp.

The app supplies the compiled Elm module, stylesheet text, route catalog, island metadata, an optional island bundle, a flag factory, and optional effects.

export const worker = createWorkerApp({
  elmModule: Main,
  stylesheet,
  routes,
  islands,
  islandsBundle,
  createFlags,
  effects: cloudflareEffects(env)
});

Cache first

Cache helpers are backend-neutral; the selected TS-side effect runner decides whether the backing store is local, KV, Redis, or another adapter.

Loader.cacheGet
    { key = "home:data"
    , decoder = dataDecoder
    }

SQL query

query, queryOne, and execute use SQL plus JSON params. Actions can reuse them through Action.fromLoader.

Loader.queryOne
    { sql = "select * from posts where slug = ?"
    , params = [ Encode.string slug ]
    , decoder = postDecoder
    }

Background task

enqueue describes fire-and-forget work. The Worker task adapter decides how to run it, including waitUntil or queues.

Loader.enqueue
    { task = "send-welcome"
    , payload = Encode.string email
    }

Cookie response

Actions can attach cookies to redirects, JSON responses, failures, or documents.

Action.redirect "/dashboard"
    |> Action.setCookie
        (Action.sessionCookie "session" sid)

Constraint-safe write

softExecute and softQueryOne return Ok / Err ConstraintError instead of failing the Loader — handle UNIQUE violations as a normal business case.

Loader.softExecute
    { sql = "insert into subscribers(email) values (?)"
    , params = [ Encode.string email ]
    }
-- Ok { rowsAffected } | Err (ConstraintError msg)

Atomic transaction

Loader.transaction wraps multi-step writes. If any step fails, everything rolls back. Requires sqlTransaction on the adapter.

Loader.transaction
    (Loader.execute
        { sql = "update orders set status = 'placed'"
             ++ " where id = ?"
        , params = [ Encode.string orderId ]
        }
    )

Custom effect

Loader.custom is the escape hatch for one typed Worker operation. Use it for parallel queries, AI calls, search, or a backend API that should not leak into route code.

Loader.custom
    { kind = "parallelDashboard"
    , payload = Encode.object []
    , decoder = dashboardDecoder
    }

Background job

Loader.startJob returns a job id immediately. Loader.jobStatus decodes queued, running, done, failed, or missing states from the TS-side job store.

Loader.startJob
    { kind = "generateReport"
    , payload = Encode.object [ ( "month", Encode.string month ) ]
    }

Loader.jobStatus { jobId = id, decoder = reportDecoder }

import { cloudflareEffects } from "elm-ssr/effects";
import { withTasks } from "elm-ssr/tasks";

const effects = withTasks(
  cloudflareEffects({ cacheBinding: "CACHE", dbBinding: "DB" }),
  { sendEmail, warmCache }
);

const effects = withTasks(
  withCache(
    inMemoryEffects({ sql: postgresSql(pg), env }),
    redisCache(redis)
  ),
  { sendEmail, warmCache }
);

Schema changes can ship with the app.

The README documents SQL-file migrations with a tracking table. Files apply in alphabetical order, and each migration plus its tracking insert runs transactionally when the adapter supports transactions.

Streams are Worker endpoints plus island subscriptions.

createSseStream returns a text/event-stream response. ElmSsr.Island.Sse opens an EventSource per URL and feeds messages into an island subscription.

return createSseStream(request, async (send, signal) => {
  while (!signal.aborted) {
    send(JSON.stringify({ time: Date.now() }));
    await new Promise((r) => setTimeout(r, 1000));
  }
});

Server markup first. Client app only at the marker.

Island.embed renders an elm-ssr-island element with data-elmssr-island, encoded props, an optional stable id, and fallback children. The browser runtime finds that marker and starts the island's own Elm main.

What you can rely on.

• SSR render is request-scoped, including env and bindings on the effect runner.
• Island state is client-scoped and isolated per mounted root.
• Pages without island markers do not load the island runtime.
• Worker concerns stay outside author-facing Elm route modules.