fedora-llm-docs/Documents/pages/JavaScript.txt

= JavaScript Packaging Guidelines
:last-reviewed: 2019-01-17

== Overview

JavaScript code used for the web needs special consideration
to ensure that it meets the high standards expected of all code shipped by Fedora,
while still being useful
and complying with conventions already used on millions of websites.
Additionally, certain libraries typically used on the web
can also be useful in a server-side context
(by nodejs or rubygem-execjs),
so it's important to package JavaScript so
it meets the standards required of locally executed code as well.

Please note that this section really only applies to JavaScript libraries
intended for use on the web.
Server-side JavaScript runtimes like
Node.js xref:Node.js.adoc[have their own guidelines],
and software like GNOME which embeds JavaScript for extensions
have their own directories and policies as well.

== Naming Guidelines

The name of a JavaScript library package MUST start with
`+js-+` then the upstream name. For example: `+js-jquery+`.

== BuildRequires

To ensure the presence of the necessary RPM macros,
all packages that provide JavaScript in `+%{_jsdir}+` MUST have:

    BuildRequires: web-assets-devel

== Requires

To ensure the availability of the necessary directories,
all packages that provide JavaScript in `+%{_jsdir}+` MUST have:

    Requires: web-assets-filesystem

JavaScript packages MUST NOT have Requires on any
HTTP daemon-specific configuration package,
such as `+web-assets-httpd+`,
since they could be used by any HTTP daemon.

== RPM Macros

|===
|Macro |Normal Definition |Notes

|`+%{_jsdir}+` |`+%{_datadir}/javascript+` |The directory where JavaScript libraries are stored
|===

== Install Location

* If a JavaScript library can be executed locally
  or consists purely of JavaScript code,
  it MUST be installed into a subdirectory of `+%{_jsdir}+`.

* If a package contains JavaScript code,
  but is never useful outside the browser
  (e.g. if it is some sort of HTML user interface library)
  it may instead install to `+%{_assetdir}+`.
  For more information, see xref:Web_Assets.adoc[the Web Assets guidelines].

* If a package contains JavaScript code
  that is only used as part of a web application,
  and it is not useful to any other applications whatsoever,
  it may continue to ship that code along with the application.
  However, that does not absolve it from complying
  with the rest of these guidelines.

* If a package contains JavaScript code
  that is not useful on the web,
  but only in locally run software
  (e.g. xref:Node.js.adoc[Node.js] or GNOME shell extensions),
  it should use the appropriate directory for its runtime,
  not `+%{_jsdir}+`.

== Server Location

JavaScript code is included as part of the general xref:Web_Assets.adoc[Web Assets framework].
Therefore, `+%{_jsdir}+` is available on Fedora-provided web servers
by default at `+/_sysassets/javascript/+`.

For instance, jQuery may be installed in `+%{_jsdir}/jquery/jquery-min.js+`,
so web applications that need to use it can simply include this HTML tag:

----
<script type="text/javascript" src="/_sysassets/javascript/jquery/jquery-min.js"></script>;
----

Regardless, web applications may want to make
subdirectories of `+%{_jsdir}+` available
under their own directory via aliases or symlinks
for compatibility purposes
or to eliminate needless deviation from upstream.

== Compilation/Minification

If a JavaScript library typically is shipped as minified or compiled code,
it MUST be compiled or minified as part of the RPM build process.
Shipping pre-minified or pre-compiled code is unacceptable in Fedora.

The compiler or minifier used by upstream
should be used to compile or minify the code.
If the minifier used by upstream is unable to be included in Fedora,
an alternative minifier may be used.
See https://fedoraproject.org/wiki/JavaScript/Minification_Issues[this page]
for a list of known problem areas and suggestions for workarounds.

Additionally, the uncompiled/unminified version MUST be included
alongside the compiled/minified version.

Minified JavaScript is not useful for JavaScript run locally,
as the entire point of minification is to reduce HTTP transfer times.
Therefore, JavaScript not intended for the web
(e.g. for Node.js or GNOME Shell extensions)
MUST NOT be minified.

== Bundling of other Libraries

It is common for a single minified JavaScript file
to contain bundled code from other JavaScript libraries.
JavaScript is treated no differently
than other libraries in this respect,
so the
xref:index.adoc#bundling[Bundling Guidelines].
MUST still be followed.

== Wrappers for Other Languages or Environments

Sometimes there may exist a simple wrapper
from a foreign language
(like Ruby via rubygem-execjs or Java via rhino)
or server-side JavaScript environment
(like Node.js)
to a pure JavaScript library.
Such packages should delete the bundled library code
and instead point to and Require the code provided
by the primary Fedora package for that library.

== Node.js Modules that contain browser/pure-JS components

Some Node.js modules include parts that can be used in the browser
or by other server-side JavaScript engines.
Such packages should be shipped as one SRPM that contains two packages:

* One `+js-foo+` package that contains
  the pure JavaScript portion, following these guidelines.

* One `+nodejs-foo+` package that contains
  the Node.js module portion,
  following the xref:Node.js.adoc[Node.js guidelines].
  This may symlink to the necessary files or directories
  of the `+js-foo+` package.