Hugo ESBuild: npm-packages bundelen via js.Build

Definitie

Hugo heeft ingebouwde ESBuild-ondersteuning via de js.Build pipe-functie. Hiermee kunnen npm-packages uit node_modules gebundeld worden in Hugo-assets zonder externe buildtools zoals Webpack of Vite.

Context

Standaard laadt Hugo JS-bestanden via resources.Get "js/foo.js" zonder transformatie. Zodra een bestand import-statements bevat (bijv. naar een npm-package), moet js.Build gebruikt worden. Dit is relevant voor Hugo-projecten die een beperkte JS-dependency willen toevoegen zonder een volledig frontend-buildproces op te zetten.

Kernpunten

Vereisten

• package.json aanwezig in de Hugo-projectroot (niet in de theme-map)
• node_modules/ aanwezig na npm install
• Het JS-bronbestand moet een ES-module zijn (geen IIFE met import erin; imports moeten op het hoogste niveau staan)

Template-aanroep

{{ $js := resources.Get "js/wordweb.js" | js.Build (dict "format" "iife" "target" "es2017") | fingerprint }}
<script src="{{ $js.RelPermalink }}" defer></script>

• format "iife" wikkelt de output in een IIFE zodat globale scope niet vervuild wordt
• target "es2017" transpileert naar brede browsercompatibiliteit
• fingerprint voegt een content-hash toe voor cache-busting

Globals van CDN

Als een library zoals D3 via CDN als global geladen wordt, hoeft die niet in node_modules te staan. ESBuild laat onbekende identifiers in IIFE-output staan als globals. D3-referenties zoals d3.forceSimulation() werken gewoon als d3 als global beschikbaar is via een eerder script-tag.

ES-module vereiste

De IIFE-wrapper uit de broncode verwijderen; ESBuild voegt die toe via format "iife". import-statements moeten op het hoogste niveau van het bestand staan, niet in een functie.

Geen aparte bundler nodig

Hugo roept intern ESBuild aan. Er is geen vite.config.js, webpack.config.js of bun build-script nodig. hugo server en hugo bundelen automatisch bij iedere wijziging.

Beperking

Hugo’s js.Build ondersteunt geen code-splitting of dynamische imports. Voor kleine, gerichte dependencies (zoals Pretext voor tekstmeting) is dit geen probleem.

Verbanden

• Zie ook: wiki-hugo-dict-scope-with-block

• Gerelateerd project: jimvandenbreemen.nl (Woordenweb)

• Gerelateerd artikel: wiki-pretext-d3-nodemeting

• Zie ook: wiki-cursor-scrub-gallery-mechaniek — conceptually_related_to

Bronnen

Hugo documentatie. (2026). js.Build. https://gohugo.io/hugo-pipes/js/

Sessie-herkomst

• raw-sessie-2026-04-27-woordenweb-pretext-integratie