.. _javascript-practices:

====================
JavaScript practices
====================

While JavaScript is useful to make complex data entry and interaction tasks
easier, there is value in maintaining a functional plain HTML interface, and in
modern browsers, HTML plus CSS interfaces can go a long way.

When there is a UI task, like sorting a list, which would have a significantly
better UI with the help of JavaScript, we can do it via incremental
improvement, with a basic HTML interface that is hidden when JavaScript is
enabled, and replaced with a different scripted one.

Data submitted from data entry enhanced with JavaScript should match the form
data submitted with the HTML-only form inputs, so that server-side validation
and handling can be reused for both.

In those cases where a UI task is not at all possible without JavaScript, we
can make its support mandatory as long as the same goal can be otherwise
achieved using the ``debusine`` client command.


Target browsers
---------------

We target the main browsers shipped in Debian stable, and oldstable as long as
it's still officially supported by Debian.

As of September 2025, this means ``firefox-esr 115`` and ``chrome 135``.

We are therefore allowed to use:

* The full ECMAScript 2015 featureset
* CSS3, with the ``attr()`` function limited to the ``content`` property


Modules
-------

We use `JavaScript modules <https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Modules>`
to structure our code. The ``web/_base.html`` base template defines an
``importmap`` that can be extended by other templates.



Linting and formatting
----------------------

We do not yet have infrastructure to lint and format JavaScript code.


Testing
-------

We do not yet have infrastructure to perform unit testing and functional
testing of JavaScript code, and we rely on manual testing.
