Misago removes React.js and adopts HTMX for UI interactivity

Misago removes React.js and adopts HTMX for UI interactivity

Why Misago is moving away from React.js

The current architecture renders pages twice: once with Django templates and again with React.js components, causing duplicated views, templates, API routes, JSON serialization, and translation files.

Problems with the current dual‑rendering approach

  • Every view accessible to users and guests must be implemented both as a Django view/template and as a React.js route/component, requiring an API and JSON serializers.
  • JSON serialization to pre‑bake data for the React.js app slows down response generation.
  • Translation messages exist in both django.po and djangojs.po, increasing download size.
  • Large JavaScript bundles hurt performance on older and slower mobile devices.
  • Plugins must provide both Django templates and React.js components, and the site would need a JavaScript build step in misago-docker.

Why HTMX was chosen over other alternatives

The author considered dropping Django views for a pure React.js SPA or adopting a server‑side rendered framework like Next.js or Remix.run, but noted that many forum software projects succeed with traditional server‑side rendering enhanced by small amounts of JavaScript. HTMX lets developers mark parts of HTML as dynamic islands that are swapped with new server‑rendered HTML on interaction, eliminating the need for JSON serialization, dedicated JavaScript, or React.js components. It is described as a declarative way of doing $.get("url", "#outlet\)), similar to jQuery or Rails Turbolinks.

Migration plan and progress so far

The move away from React.js will be carried out in incremental steps, starting with isolated UI pieces such as the navbar, thread lists, thread pages, and user profiles. Prerequisite work on plugins, permissions, and the parser must finish first, so the HTMX migration is slated for later 2024. Completed work includes:

  • The "Forum options" page replaced with an "Account settings" page built entirely with Django views and HTMX for dynamic updates (PR #1742).
  • Thread lists rewritten to use Django views and HTMX instead of React.js (PR #1758).

Impact on JavaScript bundle size

Before any changes, Misago 0.39 shipped the following JavaScript assets:

  • vendor.js: 679 KB (214 KB gzipped)
  • misago.js: 615 KB (124 KB gzipped)
  • django-i18n.js: 102 KB (25.4 KB gzipped)
  • Lazily loaded hljs.js: 144 KB (49 KB gzipped)
  • Lazily loaded zxcvbn.js: 820 KB (430 KB gzipped)

After the account‑settings page conversion, misago.js decreased to 578 KB (107 KB gzipped), a reduction of 37 KB uncompressed and 17 KB gzipped. After the thread‑lists conversion, misago.js further decreased to 530 KB (99 KB gzipped), a reduction of 48 KB uncompressed and 8 KB gzipped.

Transition period and fallback strategy

During the migration, some parts of Misago will temporarily have neither React.js nor HTMX, effectively behaving as a multi‑page application where links and forms cause full page reloads. The author plans to place placeholder AJAX (or HTMX) calls where a full reload would be unbearable, such as for liking posts or voting in polls.

Community reactions and considerations

Commenters highlighted both strengths and limitations of HTMX:

  • One noted that HTMX is a great fit for server‑rendered pages and that mini React or Vue apps can still be embedded for highly custom interactions.
  • Another pointed out that forum software mainly delivers static‑like content, making HTMX suitable for most interactivity, while a WYSIWYG editor or complex quote system might still require client‑side JavaScript.
  • A user reported success using HTMX with Django, TailwindCSS, and DaisyUI for near‑native PWAs.
  • Conversely, some warned that HTMX can become slow when large HTML fragments are returned, suggesting alternatives like Alpine JS for cases where the response size is large.
  • Concerns were raised about HTMX’s declarative nature being essentially imperative and about losing compile‑time safety compared to typed frameworks.
  • Others mentioned missing tooling such as Storybook support and expressed interest in pairing HTMX with WebComponents or server‑less backends.

These perspectives confirm that HTMX simplifies the majority of the needed interactivity for a forum while acknowledging that certain rich‑client features may still benefit from traditional JavaScript frameworks.

Sources