Scripts
Bundle local and external JavaScript files by intent and rendering impact.
Important
Hinode release v0.27.0 has overhauled the build pipeline of scripts and modules. The bundled files now support categorization by intent.
Hinodes bundles JavaScript files to optimize the page loading speed. By utilizing Hugo Modules, referenced JavaScript files are automatically ingested and version controlled. Since release v0.27.0 , Hinode also supports the grouping of scripts by their intent. Review the next sections to familiarize yourself with the build system.
Hinodes recognizes three types of integrations for JavaScript files. You can mount these files directly into Hugo’s virtual file system, or use modules instead.
In addition to their integration type, you can also bundle scripts by their intent category. You can use this intent category in combination with a Cookie Consent Manager to dynamically load scripts in compliance with privacy regulations. Hinodes supports the following categories. Refer to the Cookie Consent Categories for more details.
Hinode uses the following naming conventions for each type of script:
| Integration | Basename | Description |
|---|---|---|
| critical | critical.bundle |
Critical scripts are bundled by intent category. The target bundle’s filename uses critical.bundle as basename and the category name as suffix. When the category is other, the suffix is omitted. Localized modules trigger a language code extension. |
| core | core.bundle |
Core scripts are bundled similarly as critical scripts. The target bundle’s filename uses core.bundle as basename. |
| optional | <module name> |
Scripts that are part of an optional module are bundled by their module name and optional category. Similar to core scripts, optional scripts bundles can also receive a language code extension. |
Hinodes supports three types of integration approaches. The next paragraphs describe the available approaches in detail.
The main Hinode repository includes several scripts maintained within the assets/js folder. You can add (or mount) your own scripts to this folder to include them in the build pipeline. Hinode supports the following directories relative to the assets mount point:
| Category | Match (glob pattern) | Target bundle |
|---|---|---|
other |
js/critical/*.js |
/js/critical.bundle.js |
functional |
js/critical/functional/**.js |
/js/critical.bundle-functional.js |
analytics |
js/critical/analytics/**.js |
/js/critical.bundle-analytics.js |
performance |
js/critical/performance/**.js |
/js/critical.bundle-performance.js |
advertisement |
js/critical/advertisement/**.js |
/js/critical.bundle-advertisement.js |
core |
{js/*.js,js/vendor/**.js} |
/js/core.bundle.js |
Note
Review the Module Development Guidelines to see the detailed mounting requirements for the scripts embedded in a module.
Hinodes uses Modules to include features and functionality as needed. This reduces overhead and improves performance. Each module provides a default integration configuration. You can override these settings in your site’s parameters. The following example illustrates the default configuration of the Google Analytics module. Refer to the Module Configuration to see the available settings and values.
[params.modules.GoogleAnalytics]
integration = "core"
state = "async"
category = "analytics"Caution
In general, you are encouraged to embed external scripts within a module. This ensures the scripts are bundled together and are version controlled. Only use external links when absolute necessary.
You can also reference an external script by including its url in the module configuration. These external scripts are not bundled but included as reference instead. The module for CookieYes uses the following configuration to ensure the cookie script is always loaded first:
[params.modules.cookieyes]
integration = "critical"
url = "https://cdn-cookieyes.com/client_data/{ID redacted}/script.js"The following example illustrates the files as used by the Components Page on the Demo Site . The integrity hashes have been omitted for clarity.
js/critical/functional/**.js and js/critical/*.js respectively.js/core.bundle-analytics.en.min.js uses the script defined in the
Google Analytics
module. The other core file uses a mix of core modules (such as
Bootstrap
,
FlexSearch
, and
Font Awesome
) and scripts defined in the assets/js folder (without nesting).<!doctype html>
<html lang=en class=no-js>
<head>
1) External, critical URLs are referenced first
<script src="https://cdn-cookieyes.com/client_data/{ID redacted}/script.js"></script>
2) Critical bundle files are included next
<script src="/js/critical.bundle-functional.js" data-category="functional"></script>
<script src="/js/critical.bundle.js"></script>
[...]
</head>
<body>
[...]
3) External, core URLs are referenced here (N/A in this example)
4) Core bundle files are referenced near the body closing tag
<script src=/js/core.bundle-analytics.en.min.js data-category="analytics" async></script>
<script src=/js/core.bundle.en.min.js async></script>
5) Optional module file are referenced last
<script src=/js/leaflet.min.js></script>
<script src=/js/lottie.min.js></script>
<script src=/js/simple-datatables.js async></script>
</body>
</html>