Integration

A WebFluid app declares what kind of frontend it serves through a single config value: APP_FRONTEND. There are three flavours — plain server-rendered, htmx-enhanced, or a full Vite-driven SPA. We'll start with the small end and only serve the main app, then get fancy with multiple frontends once we reach Additives.

The frontend config

APP_FRONTEND is just a dictionary in your config class. Its type decides everything else:

• none — pure SSR, no client tooling.
• htmx — SSR plus htmx (and optionally Alpine) injected for you.
• vite — a real Vite app served and hot-reloaded by the framework.

The easy win: htmx

The lightest frontend needs no Node at all. Declare the htmx type and the framework hands your templates a frontend() helper that injects the right scripts (and the compiled Tailwind link):

from webfluid.core.config import register_config


@register_config(10)
class MyConfig:
    SESSION_COOKIE_SECURE = True

    APP_FRONTEND = {
        "type": "htmx",
        "alpine": True
    }

{% extends "fluid_base.html" %}

{% block head %}
    {{ frontend() if frontend else "" }}
{% endblock %}

{% block content %}
    <button hx-get="/health" hx-target="#out">{{ _('Ping') }}</button>
    <pre id="out"></pre>
{% endblock %}

That is genuinely the whole story for an htmx app. The frontend() call resolves to the htmx (and Alpine) script tags, and because we are extending fluid_base.html, everything else is already in place.

Going SPA: the fluid/frontend workspace

For a richer client you switch to the vite type. The main app's frontend lives in one place the framework knows to look for: a fluid/frontend directory, set up as an npm workspace. Three pieces make that work:

1. a root package.json that declares the workspace,
2. a root vite.config.js that orchestrates it (the framework writes this one for you),
3. the actual Vite app inside fluid/frontend.

For now we only have the main app, so the workspace list is tiny — just our one frontend. (We'll add additives/*/frontend to it later.)

{
  "name": "myapp",
  "private": true,
  "workspaces": [
    "fluid/frontend"
  ],
  "devDependencies": {
    "vite": "^8.0.0"
  }
}

Inside fluid/frontend you have an ordinary Vite project. The one thing the framework needs from its config is the right base: the built assets are served under /frontend/, while in development everything is proxied through /vite-dev/:

import { defineConfig } from 'vite'

export default defineConfig(({ command }) => ({
  base: command === 'build' ? '/frontend/' : '/vite-dev/',
}))

Tell the config which app this is and declare your APP_FRONTEND:

@register_config(10)
class MyConfig:
    APP_FRONTEND = {
        "type": "vite",
        "framework": "react",
        "typescript": False,
        "register_index": True
    }

How it gets served

When the type is vite, the framework takes over the / route and serves your Vite app's index for you — you don't register a home handler at all. That is the default (register_index: true); set register_index: false in your APP_FRONTEND if you would rather own the / route yourself. What happens behind that route depends on the mode:

• Development (wf run app -d): the bundled Node starts the Vite dev server, and the framework proxies it under /vite-dev/. You get hot module replacement for free, rewritten into your page on the fly.
• Production (no -d): the workspaces are built once on startup and the resulting dist is mounted as static files under /frontend.

Deciding what happens on a production boot

That build step is where the two remaining feature switches earn their keep. On a production start the framework runs, in order:

• WF_CHECK_FRONTEND — npm run check --workspaces. The scaffolder wires this script up for TypeScript templates, so a type error stops the boot instead of shipping. Off by default.
• WF_BUILD_FRONTEND — npm run build --workspaces, and a failing build aborts startup with the compiler output. On by default.

Both are worth turning off in an image that already built its assets at container build time — there is no reason to compile the same bundle again on every restart, and a container without a Node toolchain cannot anyway. The dist folders are mounted either way.

How a relative asset finds its workspace

One detail earns a paragraph, because it is the only place in the framework where a cookie decides which file gets read. A Vite index can ask for /logo.svg without saying which of your frontends it belongs to, so when the framework serves an index it sets a vite_ns cookie naming that workspace, and a catch-all route resolves later relative requests against it.

A cookie is client input, so it is treated as such: the namespace has to be one the app actually registered, and the resolved file has to sit inside the project root. Anything else is a 404 rather than a file. That check is new; without it, an empty cookie pointed the lookup at the project root itself and /app_configs/<app>.ini was a public URL.

Continue reading

From here you can continue straight with Template resolution.