Reference

Surface

webfluid.surface — the frontend layer: serving the UI, plus the bundled Node and Tailwind tooling that drives it. Most of this you reach through config and the CLI rather than directly.

Frontend

from webfluid.surface import Frontend — the object that covers an app or Additive with a frontend.

  • cover_fluid(fluid) / cover_additive(additive) — attach a frontend to the main app or an Additive (driven by APP_FRONTEND / the Additive manifest's frontend). Covering twice raises.
  • include() — the markup injected by the template frontend() helper (htmx / Alpine / Tailwind link).
  • vite() — the served Vite index, rewritten for HMR in debug. Serving it sets the vite_ns cookie that the asset catch-all resolves relative requests against; only registered namespaces are accepted and the resolved file must stay under the project root.
  • register_index (frontend config, default true) — for the vite type, auto-registers the / route; set it false to own / yourself.
  • generate_tailwind(frontend, static) — compile this surface's raw stylesheet, for the Vite source tree and / or the static folder.
  • Frontend.prepare(fluid) — wires the dev-server proxy (debug) or the check / build / mount flow (production, gated by WF_CHECK_FRONTEND and WF_BUILD_FRONTEND).

Configuration helpers

In webfluid.utils.surface:

  • setup_frontend(project) — downloads htmx/Alpine, the create-vite templates, Node and Tailwind, and writes the root package.json and orchestrating vite.config.js.
  • validate_config(dict) — validates an APP_FRONTEND / manifest frontend block (types: none, htmx, vite) and returns a (ok, value-or-reason) pair.
  • dist (in webfluid.surface) — the tooling directory where Node, Tailwind and the Vite templates are cached.

Node tooling

  • load_node(download_fn) — ensures a Node runtime (system or downloaded standalone).
  • node_cmd(cmd, cwd) — run a Node/npm command (raises NodeError on failure).
  • node_proc(cmd, cwd) — spawn a long-lived Node process.
  • CLI: wf node ....

Tailwind tooling

  • load_tailwind(download_fn) — ensures the standalone Tailwind CLI.
  • generate_tailwind_css(fluid) — compile every tailwind_raw.css in the app (and framework) on startup.
  • generate_tailwind_asset(in, out, cwd) / tailwind_cmd(args, cwd) — lower-level compile / passthrough.
  • CLI: wf tailwind -- ....

Continue reading

From here you can continue straight with Additives.