js.Batch

Syntax

js.Batch [ID]

Returns

js.Batcher

The Batch ID is used to create the base directory for this batch. Forward slashes are allowed. js.Batch returns an object with an API with this structure:

Group
- Script
  - SetOptions
- Instance
  - SetOptions
- Runner
  - SetOptions
- Config
  - SetOptions

Group

The Group method take an ID (string) as argument. No slashes. It returns an object with these methods:

Script

The Script method takes an ID (string) as argument. No slashes. It returns an OptionsSetter that can be used to set script options for this script.

{{ with js.Batch "js/mybatch" }}
  {{ with .Group "mygroup" }}
      {{ with .Script "myscript" }}
          {{ .SetOptions (dict "resource" (resources.Get "myscript.js")) }}
      {{ end }}
  {{ end }}
{{ end }}

SetOptions takes a script options map. Note that if you want the script to be handled by a runner, you need to set the export option to match what you want to pass on to the runner (default is *).

Instance

The Instance method takes two string arguments SCRIPT_ID and INSTANCE_ID. No slashes. It returns an OptionsSetter that can be used to set params options for this instance.

{{ with js.Batch "js/mybatch" }}
  {{ with .Group "mygroup" }}
      {{ with .Instance "myscript" "myinstance" }}
          {{ .SetOptions (dict "params" (dict "param1" "value1")) }}
      {{ end }}
  {{ end }}
{{ end }}

SetOptions takes a params options map. The instance options will be passed to any runner script in the same group, as JSON.

Runner

The Runner method takes an ID (string) as argument. No slashes. It returns an OptionsSetter that can be used to set script options for this runner.

{{ with js.Batch "js/mybatch" }}
  {{ with .Group "mygroup" }}
      {{ with .Runner "myrunner" }}
          {{ .SetOptions (dict "resource" (resources.Get "myrunner.js")) }}
      {{ end }}
  {{ end }}
{{ end }}

SetOptions takes a script options map.

The runner will receive a data structure with all instances for that group with a live binding of the JavaScript import of the defined export.

The runner script’s export must be a function that takes one argument, the group data structure. An example of a group data structure as JSON is:

{
    "id": "leaflet",
    "scripts": [
        {
            "id": "mapjsx",
            "binding": JAVASCRIPT_BINDING,
            "instances": [
                {
                    "id": "0",
                    "params": {
                        "c": "h-64",
                        "lat": 48.8533173846729,
                        "lon": 2.3497416090232535,
                        "r": "map.jsx",
                        "title": "Cathédrale Notre-Dame de Paris",
                        "zoom": 23
                    }
                },
                {
                    "id": "1",
                    "params": {
                        "c": "h-64",
                        "lat": 59.96300872062237,
                        "lon": 10.663529183196863,
                        "r": "map.jsx",
                        "title": "Holmenkollen",
                        "zoom": 3
                    }
                }
            ]
        }
    ]
}

Below is an example of a runner script that uses React to render elements. Note that the export (default) must match the export option in the script options (default is the default value for runner scripts) (runnable versions of examples on this page can be found at js.Batch Demo Repo):

import * as ReactDOM from 'react-dom/client';
import * as React from 'react';

export default function Run(group) {
	console.log('Running react-create-elements.js', group);
	const scripts = group.scripts;
	for (const script of scripts) {
		for (const instance of script.instances) {
			/* This is a convention in this project. */
			let elId = `${script.id}-${instance.id}`;
			let el = document.getElementById(elId);
			if (!el) {
				console.warn(`Element with id ${elId} not found`);
				continue;
			}
			const root = ReactDOM.createRoot(el);
			const reactEl = React.createElement(script.binding, instance.params);
			root.render(reactEl);
		}
	}
}

Config

Returns an OptionsSetter that can be used to set build options for the batch.

These are mostly the same as for js.Build, but note that:

targetPath is set automatically (there may be multiple outputs).
format must be esm, currently the only format supporting code splitting.
params will be available in the @params/config namespace in the scripts. This way you can import both the script or runner params and the config params with:

import * as params from "@params";
import * as config from "@params/config";

Setting the Config for a batch can be done from any template (including shortcode templates), but will only be set once (the first will win):

{{ with js.Batch "js/mybatch" }}
  {{ with .Config }}
       {{ .SetOptions (dict
        "target" "es2023"
        "format" "esm"
        "jsx" "automatic"
        "loaders" (dict ".png" "dataurl")
        "minify" true
        "params" (dict "param1" "value1")
        )
      }}
  {{ end }}
{{ end }}

Options

Build Options

format: (string) Currently only esm is supported in ESBuild’s code splitting.

params: (map or slice) Params that can be imported as JSON in your JS files, e.g.

{{ $js := resources.Get "js/main.js" | js.Build (dict "params" (dict "api" "https://example.org/api")) }}

And then in your JS file:

import * as params from '@params';

Note that this is meant for small data sets, e.g. configuration settings. For larger data, please put/mount the files into /assets and import them directly.

minify: (bool)Let js.Build handle the minification.
loaders: (map) New in v0.140.0 Configuring a loader for a given file type lets you load that file type with an import statement or a require call. For example configuring the .png file extension to use the data URL loader means importing a .png file gives you a data URLcontaining the contents of that image. Loaders available are none, base64, binary, copy, css, dataurl, default, empty, file, global-css, js, json, jsx, local-css, text, ts, tsx. See https://esbuild.github.io/api/#loader
inject: (slice) This option allows you to automatically replace a global variable with an import from another file. The path names must be relative to assets. See https://esbuild.github.io/api/#inject
shims: (map) This option allows swapping out a component with another. A common use case is to load dependencies like React from a CDN (with shims) when in production, but running with the full bundled node_modules dependency during development:

{{ $shims := dict "react" "js/shims/react.js"  "react-dom" "js/shims/react-dom.js" }}
{{ $js = $js | js.Build dict "shims" $shims }}

The shim files may look like these:

// js/shims/react.js
module.exports = window.React;

// js/shims/react-dom.js
module.exports = window.ReactDOM;

With the above, these imports should work in both scenarios:

import * as React from 'react';
import * as ReactDOM from 'react-dom/client';

target: (string) The language target. One of: es5, es2015, es2016, es2017, es2018, es2019, es2020 or esnext. Default is esnext.
platform New in v0.140.0: (string) One of browser, node, neutral. Default is browser. See https://esbuild.github.io/api/#platform
externals: (slice) External dependencies. Use this to trim dependencies you know will never be executed. See https://esbuild.github.io/api/#external
defines: (map) Allow to define a set of string replacement to be performed when building. Should be a map where each key is to be replaced by its value.

{{ $defines := dict "process.env.NODE_ENV" `"development"` }}

sourceMap: (string) Whether to generate inline, linked or external source maps from esbuild. Linked and external source maps will be written to the target with the output file name + “.map”. When linked a sourceMappingURL will also be written to the output file. By default, source maps are not created. Note that the linked option was added in Hugo 0.140.0.
sourcesContent New in v0.140.0: (bool) Whether to include the content of the source files in the source map. By default, this is true.
JSX New in v0.124.0: (string) How to handle/transform JSX syntax. One of: transform, preserve, automatic. Default is transform. Notably, the automatic transform was introduced in React 17+ and will cause the necessary JSX helper functions to be imported automatically. See https://esbuild.github.io/api/#jsx
JSXImportSource New in v0.124.0: (string) Which library to use to automatically import its JSX helper functions from. This only works if JSX is set to automatic. The specified library needs to be installed through npm and expose certain exports. See https://esbuild.github.io/api/#jsx-import-source

The combination of JSX and JSXImportSource is helpful if you want to use a non-React JSX library like Preact, e.g.:

{{ $js := resources.Get "js/main.jsx" | js.Build (dict "JSX" "automatic" "JSXImportSource" "preact") }}

With the above, you can use Preact components and JSX without having to manually import h and Fragment every time:

import { render } from 'preact';

const App = () => <>Hello world!</>;

const container = document.getElementById('app');
if (container) render(<App />, container);

Script Options

resource: The resource to build. This can be a file resource or a virtual resource.
export: The export to bind the runner to. Set it to * to export the entire namespace. Default is default for runner scripts and * for other scripts.
importContext: An additional context for resolving imports. Hugo will always check this one first before falling back to assets and node_modules. A common use of this is to resolve imports inside a page bundle. See import context.
params: A map of parameters that will be passed to the script as JSON. These gets bound to the @params namespace:

import * as params from '@params';

Script Options

Params Options

params: A map of parameters that will be passed to the script as JSON.

Import Context

Hugo will, by default, first try to resolve any import in assets and, if not found, let ESBuild resolve it (e.g. from node_modules). The importContext option can be used to set the first context for resolving imports. A common use of this is to resolve imports inside a page bundle.

{{ $common := resources.Match "/js/headlessui/*.*" }}
{{ $importContext := (slice $.Page ($common.Mount "/js/headlessui" ".")) }}

You can pass any object that implements Resource.Get. Pass a slice to set multiple contexts.

The example above uses Resources.Mount to resolve a folder inside assets relative to the page bundle.

OptionsSetter

An OptionsSetter is a special object that is returned once only. This means that you should wrap it with with:

{{ with .Script "myscript" }}
    {{ .SetOptions (dict "resource" (resources.Get "myscript.js"))}}
{{ end }}

Build

The Build method returns an object with the following structure:

Groups (map)
- Resources

Eeach Resource will be of media type application/javascript or text/css.

In a template you would typically hande one group with a given ID (e.g. scripts for the current section). Because of the concurrent build, this needs to be done in a templates.Defer block:

{{ $group := .group }}
{{ with (templates.Defer (dict "key" $group "data" $group )) }}
  {{ with (js.Batch "js/mybatch") }}
    {{ with .Build }}
      {{ with index .Groups $ }}
        {{ range . }}
          {{ $s := . }}
          {{ if eq $s.MediaType.SubType "css" }}
            <link href="{{ $s.RelPermalink }}" rel="stylesheet" />
          {{ else }}
            <script src="{{ $s.RelPermalink }}" type="module"></script>
          {{ end }}
        {{ end }}
      {{ end }}
  {{ end }}
{{ end }}

Known Issues

In the official documentation for ESBuild’s code splitting, there’s a warning note in the header. The two issues are:

esm is currently the only implementd output format. This means that it will not work for very old browsers. See caniuse.
There’s a known import ordering issue.

We have not seen the ordering issue as a problem during our extensive testing of this new feature with different libraries. There are two main cases:

Undefined execution order of imports, see this comment
Only one execution order of imports, see this comment

Many would say that both of the above are code smells. The first one has a simple workaround in Hugo. Define the import order in its own script and make sure it gets passed early to ESBuild, e.g. by putting it in a script goup with a name that comes early in the alphabet.

import './lib2.js';
import './lib1.js';

console.log('entrypoints-workaround.js');

js.Batch

Group

Script

Instance

Runner

Config

Options

Build Options

Script Options

Script Options

Params Options

Import Context

OptionsSetter

Build

Known Issues

See also

Last updated: December 4, 2024: Update JS docs vs Hugo v0.140 (4d3195223)