JavaScript Packaging Guidelines

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 have their own guidelines, and software like GNOME which embeds JavaScript for extensions have their own directories and policies as well.

Packages containing JavaScript should make the best effort to regenerate any precompiled/minimized JS wherever possible, as this leads to more maintainable packages. Where this would result in a significant hardship, the bundled pregenerated JS may be shipped with a specfile comment explaining the decision. This does not eliminate the requirement to validate licenses of bundled code.

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 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. 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 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="/https/docs.fedoraproject.org/_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 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 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 Node.js guidelines. This may symlink to the necessary files or directories of the js-foo package.

Want to help? Learn how to contribute to Fedora Docs ›