Decide to use htmx or not

[6543]

We do a lot of server-side rendering. And if we want to keep it at least partially, we cannot fully use Vue 3 for that.

htmx fills the gap to do so while making the site more interactive. Though I'm not contributing much to the frontend lately, I did hear only good stuff about it. And if you look at the two pull requests, making the two components interactive in Vue 3 would have been more or less a complete rewrite. The pull requests only had to undergo minor code changes to make it work.

In terms of maintenance and refactoring, that is a huge advantage.

---

example pulls:

• Don't do a full page load when clicking the subscribe button #28871
• Don't do a full page load when clicking the follow button #28872
• Introduce htmx and use it to avoid full page load on Subscribe and Follow #28908

[yardenshoham]

I think adding htmx is a good idea. The pull requests speak for themselves, they are small and easy to maintain. htmx fits Gitea very well.

[denyskon]

HTMX makes it easier to develop interactive UI using our already present template structure. And I think it is better to introduce something we can use to make existing UI better than to wait for someone to rebuild everything using a new framework.

[wxiaoguang]

My question is: does htmx really help and will be widely used in Gitea?

I have been following htmx for some time. My feeling is:

• How does htmx handle error messages and network failure in Gitea? How does it handle the "loading" indicator?
• The basic feature like "replace inner html" could be easily implement by a few lines in our framework, ex: we already have "link-action" and "form-fetch-action"
• Does it need to repeatly write hx-headers='{"x-csrf-token": "{{.CsrfToken}}"}' for every reuqest? link-action and form-fetch-action already handles CSRF token automatically.
• Some advanced features overlaps with existing mechanisms, eg: modal. Should new code use Fomantic/Gitea Modal, or htmx's modal? What if Vue component needs to show a modal, htmx isn't designed to work with Vue IMO.
• Some advanced features like "htmx script" is quite fragile and I don't know how to lint/test them. It would cause maintainability problems.

The samples PRs #28871 and #28872 are good demo for htmx, but they are too simple and didn't handle error messages / loading indicators. Are there some complex samples for showing how htmx would work for a complex case in Gitea? For example, comment editing, PR merging?

So, IMO the only useful part of htmx at the moment is the "replacing inner/outer html by ajax", while it is quite simple and could (should) be implemented by existing "link-action" and "form-fetch-action". Other htmx features are unlikely useful in foreseeable future.

(I don't mean objection, while I think these questions needs to be clearly answered and some should be written into the guideline / devtest.tmpl if most people would like to use htmx)

[jolheiser]

I would be for using htmx over our home-rolled solutions, and for slowly increasing its usage where it would be beneficial.
But I also agree we need to come up with some solid plan for reducing our fracture of JS solutions.
With our current mix I think new additions need to planned out carefully.

[yardenshoham]

How does htmx handle error messages and network failure in Gitea?

From https://htmx.org/docs/#requests:

In the event of an error response from the server (e.g. a 404 or a 501), htmx will trigger the htmx:responseError event, which you can handle.

In the event of a connection error, the htmx:sendError event will be triggered.

How does it handle the "loading" indicator?

https://htmx.org/docs/#indicators

The basic feature like "replace inner html" could be easily implement by a few lines in our framework, ex: we already have "link-action" and "form-fetch-action"

Why would we recreate the logic htmx excels at and maintain it?

Does it need to repeatly write hx-headers='{"x-csrf-token": "{{.CsrfToken}}"}' for every reuqest? link-action and form-fetch-action already handles CSRF token automatically.

We can use https://htmx.org/docs/#inheritance to set it on a root tag, that way all requests include it

Some advanced features overlaps with existing mechanisms, eg: modal. Should new code use Fomantic/Gitea Modal, or htmx's modal? What if Vue component needs to show a modal, htmx isn't designed to work with Vue IMO.

I don't have experience creating modals. I don't think that the fact htmx has features we already implemented should block us from using it, or any other library that implements functionality we have. I wouldn't use htmx with Vue, I'd use htmx when I don't need the power of Vue.

Some advanced features like "htmx script" is quite fragile and I don't know how to lint/test them. It would cause maintainability problems.

What do you mean by fragile? Yes, linting is missing in htmx, what kind of rules would you like to enforce?

The samples PRs #28871 and #28872 are good demo for htmx, but they are too simple and didn't handle error messages / loading indicators.

What's wrong with their error handling? I can work to change it. Just like the previous behavior of the buttons I changed, there were no loading indicators.

Are there some complex samples for showing how htmx would work for a complex case in Gitea? For example, comment editing, PR merging?

It's not supposed to be used in complex cases, at least I won't force it to.

So, IMO the only useful part of htmx at the moment is the "replacing inner/outer html by ajax", while it is quite simple and could (should) be implemented by existing "link-action" and "form-fetch-action". Other htmx features are unlikely useful in foreseeable future.

I don't think you've considered the varying possibilities to "replacing inner/outer html by ajax". Are we going to reimplement hx-target, hx-swap, and hx-select? This is no small feat, it's a maintenance challenge

(I don't mean objection, while I think these questions needs to be clearly answered and some should be written into the guideline / devtest.tmpl if most people would like to use htmx)

I am very new to htmx. Those PRs are the first time I used it. We should try it out and play with it instead of immediately enforcing some prematurely written guidelines.

[wxiaoguang]

Thank you for the detailed answers.

The basic feature like "replace inner html" could be easily implement by a few lines in our framework, ex: we already have "link-action" and "form-fetch-action"

Why would we recreate the logic htmx excels at and maintain it?

That's a complex question, and I do not think it could be easily answered by yes or no.

Let's see some examples:

• Gitea was using unrolled/render, but it had to be dropped Drop "unrolled/render" package #23965
• Golang has a official and widely used template system, but we have to customize it a lot ("template context" support)
• There is "autoresize" https://github.com/github/textarea-autosize, but Gitea has to copy & rewrite all the code.
• Gitea has to use its own methods to show/hide elements (showElem/hideElem)
• There are many modern editors, but Gitea has to write its own one.

Gitea is not a small project, so there are a lot of details which are not easy to be satisfied by 3rdparty library, they need to be customized somewhat.

For "htmx": I am just showing a choice for "not introducing if there are some foreseeable problems".

And I have a feeling that "replacing inner/outer html by ajax" is not that complex in Gitea, no need to fully "reimplement hx-target, hx-swap, and hx-select" like htmx or reinvent the wheel again.

(I just would like to express the background, don't mean yes / no here)

The samples PRs #28871 and #28872 are good demo for htmx, but they are too simple and didn't handle error messages / loading indicators.

What's wrong with their error handling? I can work to change it. Just like the previous behavior of the buttons I changed, there were no loading indicators.

I didn't mean they were wrong, but the previous behavior is not ideal doesn't mean the new behavior is right.

And actually the behaviors are changed, that why I asked the questions about error handling / loading indicator:

• Old behavior: if there is a network error, then the users are able to see an error page
• New behavior: according to my test, if there is a network error, there is no UI response when I click the button. That's why I do not think it is ideal.

Since we are improving the UI, I think it is a good chance to give end users better UI responses.

In my mind, our link-action and form-fetch-action could handle this case well. If we use htmx, do we need to remind every contributor to manually addd error handling / loading indicator?

Are there some complex samples for showing how htmx would work for a complex case in Gitea? For example, comment editing, PR merging?

It's not supposed to be used in complex cases, at least I won't force it to.

If let us predict, after introducing htmx, in which case the link-action / form-fetch-action should be used, and in which case htmx should be used?

[puni9869]

Having experience with both htmx and vuejs, I currently utilize htmx for smaller applications. However, I've encountered limitations when integrating it into big project, especially on complex screens such as code review and the front landing page, where various UI elements are in play. Considering the challenges faced, I believe using to Vue3 would be a more favorable option. It allows us to leverage existing solutions and avoid reinventing the wheel. I leave the final decision to the TOC/maintainers for their consideration.

[yardenshoham]

Thanks for the detailed comment.

Gitea is not a small project, so there are a lot of details which are not easy to be satisfied by 3rdparty library, they need to be customized somewhat.

Sure, but we have more libraries we don't customize than ones we do.

And I have a feeling that "replacing inner/outer html by ajax" is not that complex in Gitea, no need to fully "reimplement hx-target, hx-swap, and hx-select" like htmx or reinvent the wheel again.

I'd love to see the sample PRs recreated in link-action / form-fetch-action to compare maintainability.

And actually the behaviors are changed, that why I asked the questions about error handling / loading indicator:

Regarding the error handling and loading indicator, I am open to add changes, I don't see these as blockers to use htmx.

If let us predict, after introducing htmx, in which case the link-action / form-fetch-action should be used, and in which case htmx should be used?

The distinction seems pretty clear to me, link-action / form-fetch-action if you want a full page load, otherwise htmx.

[wxiaoguang]

I'd love to see the sample PRs recreated in link-action / form-fetch-action to compare maintainability.
Regarding the error handling and loading indicator, I am open to add changes, I don't see these as blockers to use htmx.

I am not sure whether I have enough time recently to work on a sample. So feel free to continue the htmx related design. I think there might be some htmx options or mechanisms to make the error handling / loading indicator easier (no need to write them everytime).

The distinction seems pretty clear to me, link-action / form-fetch-action if you want a full page load, otherwise htmx.

I think it is feasible. And at the moment we had better forbid some htmx features like "htmx modal" / "htmx script" to make sure there are consistent designs in code base (unless there is another complete plan to refactor existing code to a new framework).

---

My opinion: I could vote for htmx if the standards could be defined (including: general error handling, avoid some unnecessary features like htmx script).

[yardenshoham]

@go-gitea/technical-oversight-committee please write here your official decision if we can add htmx or not