js.Build

Hugo パイプは、 ESBuild で JavaScript ファイルを処理できます。

使用方法

任意の JavaScript リソースファイルは、ファイルパスの文字列または以下にリストされているオプションの dict のいずれかを引数として取る js.Build を使用して、トランスパイルおよび「Tree shaking」できます。

オプション

targetPath [string]: 設定されていない場合は、ソースパスがベースとなるターゲットパスとして使用されます。ターゲットパスの拡張子は、ソースが TypeScript である場合など、ターゲットの MIME タイプが異なる場合に変更される可能性があることに注意してください。
params [map or slice]: JS ファイルに JSON としてインポートできるパラメータです。たとえば、以下のようになります。

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

そして、JS ファイルでは、次のように記述します。

import * as params from '@params';

これはコンフィグ設定などの小さなデータセットのためのものであることに注意してください。大きなデータの場合は、ファイルを /assets に置いたりマウントしたりして、直接インポートしてください。

minify [bool]: ミニファイ (minification ) の処理は js.Build に任せます。
inject [slice]: このオプションは、グローバル変数を他のファイルからインポートして自動的に置き換えることができます。パス名は assets からの相対パスである必要があります。詳細は、 https://esbuild.github.io/api/#inject を参照してください。
shims [map]: このオプションは、コンポーネントを別のものと交換することができます。一般的な使用例は、本番環境では React などの依存関係を CDN から (shims を使用して) ロードすることですが、開発時には完全にバンドルされた node_modules 依存関係で実行します。

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

shim ファイルは、以下のようなものです。

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

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

以上により、これらのインポートは両方のシナリオで動作するはずです。

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

target [string]: 言語ターゲットです。値は、es5、es2015、es2016、es2017、es2018、es2019、es2020、esnext のいずれかです。デフォルトは esnext です。
externals [slice]: 外部依存関係です。これを使用して、決して実行されないことがわかっている依存関係を削除します。詳細は、https://esbuild.github.io/api/#external を参照してください
defines [map]: ビルド時に実行する一連の文字列置換を定義できます。各キーがその値に置き換えられるマップである必要があります。

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

format [string]: 出力形式です。値は、iife、cjs、esm のいずれかです。デフォルトは iife で、自己実行型の関数であり、タグとして含めるのに適しています。
sourceMap [string]: esbuild から inline または external のソースマップを生成するかどうかを指定します。外部ソースマップは、出力ファイル名 + “.map” でターゲットに書き込まれます。入力ソースマップは js.Build や node モジュールから読み込み、出力ソースマップに結合できます。デフォルトでは、ソースマップは作成されません。

/assets から JS コードをインポートする {“import-js-code-from-assets}

js.Build は Hugo モジュールで仮想ユニオンファイルシステムを完全にサポートしています。このテストプロジェクトでいくつかの簡単な例を見ることができますが、要するに、これは以下のことができることを意味します。

import { hello } from 'my/module';

そして、階層化されたファイルシステムの assets/my/module 内の最上位の index.{js,ts,tsx,jsx} に解決されます。

import { hello3 } from 'my/module/hello3';

上記のコードは、Assets/my/module 内の hello3.{js,ts,tsx,jsx} に解決されるでしょう。

. で始まるすべてのインポートは、現在のファイルからの相対パスで解決されます。

import { hello4 } from './lib';

その他のファイル (たとえば、JSON や CSS) については、たとえば以下のように、拡張子を含む相対パスで指定する必要があります。

import * as data from 'my/module/data.json';

/assets の外にあるファイルでのインポート、または /assets 内のコンポーネントに解決されないインポートは、ESBuild によって、プロジェクトディレクトリ を用いて解決ディレクトリとして解決されます (node_modules などを探すときの開始点として使用されます)。 hugo mod npm pack も参照してください。プロジェクトにインポートされた npm 依存関係がある場合は、hugo を実行する前に必ず npm install を実行する必要があります。

また、たとえば、以下のようにテンプレートから JS ファイルに渡すことができる新しい params オプションにも注意してください。

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

そして、JS ファイルでは、以下のコードを記述します。

import * as params from '@params';

Hugo はデフォルトで、インポートをマップする assets/jsconfig.json ファイルを生成します。これはコードエディター内のナビゲーションやインテリセンスヘルプに役立ちますが、必要ない/したくない場合は、オフにすることができます。

package.json / node_modules に依存関係を含める

npm パッケージ (別名、node_modules フォルダー内に存在するパッケージ) を解決するための開始ディレクトリは、常にメインプロジェクトフォルダーです。

注意: もし、インポートを前提としたテーマ/コンポーネントを開発しており、 package.json 内の依存関係に依存している場合は、プロジェクト内のすべての npm 依存関係を統合するツールである hugo mod npm pack を読むことを推奨します。

例

{{ $built := resources.Get "js/index.js" | js.Build "main.js" }}

あるいはオプションで、以下のように指定します。

{{ $externals := slice "react" "react-dom" }}
{{ $defines := dict "process.env.NODE_ENV" `"development"` }}

{{ $opts := dict "targetPath" "main.js" "externals" $externals "defines" $defines }}
{{ $built := resources.Get "scripts/main.js" | js.Build $opts }}
<script src="{{ $built.RelPermalink }}" defer></script>