hugo/docs/content/en/hugo-pipes/js.md

172 lines
6.3 KiB
Markdown
Raw Normal View History

---
title: JavaScript Building
description: Hugo Pipes can process JavaScript files with [ESBuild](https://github.com/evanw/esbuild).
date: 2020-07-20
publishdate: 2020-07-20
lastmod: 2020-07-20
categories: [asset management]
keywords: []
menu:
docs:
parent: "pipes"
weight: 45
weight: 45
sections_weight: 45
draft: false
---
Any JavaScript resource file can be transpiled and "tree shaken" using `js.Build` which takes for argument either a string for the filepath or a dict of options listed below.
### Options
targetPath [string]
: If not set, the source path will be used as the base target path.
Note that the target path's extension may change if the target MIME type is different, e.g. when the source is TypeScript.
Squashed 'docs/' changes from 57c1d1a67..1de7a358c 1de7a358c Clarify that "with" blocks do not render with empty values (#1287) b48de8b0a Update js.md e0124e4b1 Update js.md 087b39d74 Update hosting-on-render.md (#1286) 8f02b5412 Update js.md (#1284) 8dd8a8d1d Add link to "Build Websites with Hugo" book (#1174) ae2dc138a Fix typo in page bundles (#1283) ab14bfec3 Update configuration directory section 17da77ff1 Update multilingual.md (#1280) 5bce8db3a Fix for site-hierarchy image, issue #60 9d7a2366d Fix typo ad4210c41 Fix typo c88bc0383 Fix orphan branch url (#1262) 1cf6cf5b3 Hugo 0.78.2 538c3cb86 Merge branch 'tempv0.78.2' e5e07fc81 releaser: Add release notes to /docs for release of 0.78.2 120a61a47 Fixed wrong var assignment example 4cebbb1a7 Ignore remote JSON errors (for now) 618fcf9ba Add a link to modules config option 'replacements' e12722779 Fix typo ("wil" -> "will") (#1273) 0670e9894 Update js.md 5bde834cf Update GH docs to say "main" as default branch 26312f93d Update index.md eb6f51df1 Update js.md b890dc84d Merge branch 'tempv0.78.1' 6b73ea450 releaser: Add release notes to /docs for release of 0.78.1 46e582112 Update starter-kits.md (#1268) a62786235 Update 404 docs: GitLab auto-detects 404.html (#1173) cbd4fd2d9 Fix typo (#1271) 2ba3f9386 Update js.md 7b5109d90 Update js.md bc75bc962 Release 0.78.0 0b2e8b0f1 releaser: Add release notes to /docs for release of 0.78.0 9ecba8480 Merge commit 'b74591123eac47a20d1f26ff3e2d291cd9c5cfc0' 60a475df7 js: Add avoidTDZ option 3b895261f Make js.Build fully support modules git-subtree-dir: docs git-subtree-split: 1de7a358cac94ac09a513456bdaae65e6ae94859
2020-11-27 08:26:24 +00:00
params [map or slice] {{< new-in "0.78.0" >}}
: Params that can be imported as JSON in your JS files, e.g.:
```go-html-template
{{ $js := resources.Get "js/main.js" | js.Build (dict "params" (dict "api" "https://example.org/api")) }}
```
And then in your JS file:
```js
import * as params from '@params';
```
Note that this is meant for small data sets, e.g. config settings. For larger data, please put/mount the files into `/assets` and import them directly.
minify [bool]
: Let `js.Build` handle the minification.
inject [slice] {{< new-in "0.81.0" >}}
: 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 {{< new-in "0.81.0" >}}
: 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
// js/shims/react.js
module.exports = window.React;
```
```js
// js/shims/react-dom.js
module.exports = window.ReactDOM;
```
With the above, these imports should work in both scenarios:
```js
import * as React from 'react'
import * as ReactDOM from 'react-dom';
```
target [string]
: The language target.
One of: `es5`, `es2015`, `es2016`, `es2017`, `es2018`, `es2019`, `es2020` or `esnext`.
Default is `esnext`.
externals [slice]
: External dependencies. Use this to trim dependencies you know will never be executed. See https://esbuild.github.io/api/#external
Squashed 'docs/' changes from 4895c29c5..9abd3043a 9abd3043a Add docs for shimming JS libraries 6a1c8dcd7 Update sitemap-template.md (#1245) 37c397332 Update frontends.md a0f86f6df Update configuration.md bb00cb2c1 Update page-bundles.md 773212de6 Restructure and simplify fcba7dddf Some minor clarifications of weight sorting 759b967fc Update configuration-markup.md 56708f0b7 module import path remove slash at end 59f4f4acd Doc: Fix typo in hugo command faacf2e97 Clarify pagination documentation (#1208) d8eb60887 netlify: Bump to 0.75.1 8cedf6231 Merge branch 'temp751' 188e2bf56 releaser: Add release notes to /docs for release of 0.75.1 c96d4b7a3 Update index.md 1a9d192f7 Update index.md 32731b916 Update index.md a5bfa0c9a Restore the ... home page b6850bf96 Release 0.75.0 d6e5e624f releaser: Add release notes to /docs for release of 0.75.0 8cd6b4f47 typo: already -> already 2cb2b22bb Merge commit '534ae9c57a902aea9ed6e62390dec11fa74b7122' e3525de23 docs: Regen docs helper fd746dd83 docs: Regenerate CLI docs e20127980 Add "hugo mod npm pack" 8e82c7ce1 markup/highlight: Add support to linkable line anchors on Chroma 21e94911b markup/asciidocext: Fix AsciiDoc TOC with code 50b8dace5 modules: Add noVendor to module config d05b541fe modules: Make ignoreVendor a glob pattern c946082e7 docs: Update replaceRE func 149054341 docs: Update replace func d917567df docs: Update merge function f1e093c92 docs: Regen CLI docs c7bac967d docs: Regen docs helper 7a38f7a45 Merge commit '7d7771b673e5949f554515a2c236b23192c765c8' 1a5a7263a markup/asciidoc: Add support for .TableOfContents git-subtree-dir: docs git-subtree-split: 9abd3043a9214b390e8cc148f4588bf630620851
2020-10-06 14:22:20 +00:00
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.
```go-html-template
{{ $defines := dict "process.env.NODE_ENV" `"development"` }}
```
format [string] {{< new-in "0.74.3" >}}
: The output format.
One of: `iife`, `cjs`, `esm`.
Squashed 'docs/' changes from 57c1d1a67..1de7a358c 1de7a358c Clarify that "with" blocks do not render with empty values (#1287) b48de8b0a Update js.md e0124e4b1 Update js.md 087b39d74 Update hosting-on-render.md (#1286) 8f02b5412 Update js.md (#1284) 8dd8a8d1d Add link to "Build Websites with Hugo" book (#1174) ae2dc138a Fix typo in page bundles (#1283) ab14bfec3 Update configuration directory section 17da77ff1 Update multilingual.md (#1280) 5bce8db3a Fix for site-hierarchy image, issue #60 9d7a2366d Fix typo ad4210c41 Fix typo c88bc0383 Fix orphan branch url (#1262) 1cf6cf5b3 Hugo 0.78.2 538c3cb86 Merge branch 'tempv0.78.2' e5e07fc81 releaser: Add release notes to /docs for release of 0.78.2 120a61a47 Fixed wrong var assignment example 4cebbb1a7 Ignore remote JSON errors (for now) 618fcf9ba Add a link to modules config option 'replacements' e12722779 Fix typo ("wil" -> "will") (#1273) 0670e9894 Update js.md 5bde834cf Update GH docs to say "main" as default branch 26312f93d Update index.md eb6f51df1 Update js.md b890dc84d Merge branch 'tempv0.78.1' 6b73ea450 releaser: Add release notes to /docs for release of 0.78.1 46e582112 Update starter-kits.md (#1268) a62786235 Update 404 docs: GitLab auto-detects 404.html (#1173) cbd4fd2d9 Fix typo (#1271) 2ba3f9386 Update js.md 7b5109d90 Update js.md bc75bc962 Release 0.78.0 0b2e8b0f1 releaser: Add release notes to /docs for release of 0.78.0 9ecba8480 Merge commit 'b74591123eac47a20d1f26ff3e2d291cd9c5cfc0' 60a475df7 js: Add avoidTDZ option 3b895261f Make js.Build fully support modules git-subtree-dir: docs git-subtree-split: 1de7a358cac94ac09a513456bdaae65e6ae94859
2020-11-27 08:26:24 +00:00
Default is `iife`, a self-executing function, suitable for inclusion as a <script> tag.
sourceMap
: Whether to generate source maps. Enum, currently only `inline` (we will improve that).
### Import JS code from /assets
{{< new-in "0.78.0" >}}
Since Hugo `v0.78.0` `js.Build` has full support for the virtual union file system in [Hugo Modules](/hugo-modules/). You can see some simple examples in this [test project](https://github.com/gohugoio/hugoTestProjectJSModImports), but in short this means that you can do this:
```js
import { hello } from 'my/module';
```
And it will resolve to the top-most `index.{js,ts,tsx,jsx}` inside `assets/my/module` in the layered file system.
```js
import { hello3 } from 'my/module/hello3';
```
Will resolve to `hello3.{js,ts,tsx,jsx}` inside `assets/my/module`.
Squashed 'docs/' changes from 57c1d1a67..1de7a358c 1de7a358c Clarify that "with" blocks do not render with empty values (#1287) b48de8b0a Update js.md e0124e4b1 Update js.md 087b39d74 Update hosting-on-render.md (#1286) 8f02b5412 Update js.md (#1284) 8dd8a8d1d Add link to "Build Websites with Hugo" book (#1174) ae2dc138a Fix typo in page bundles (#1283) ab14bfec3 Update configuration directory section 17da77ff1 Update multilingual.md (#1280) 5bce8db3a Fix for site-hierarchy image, issue #60 9d7a2366d Fix typo ad4210c41 Fix typo c88bc0383 Fix orphan branch url (#1262) 1cf6cf5b3 Hugo 0.78.2 538c3cb86 Merge branch 'tempv0.78.2' e5e07fc81 releaser: Add release notes to /docs for release of 0.78.2 120a61a47 Fixed wrong var assignment example 4cebbb1a7 Ignore remote JSON errors (for now) 618fcf9ba Add a link to modules config option 'replacements' e12722779 Fix typo ("wil" -> "will") (#1273) 0670e9894 Update js.md 5bde834cf Update GH docs to say "main" as default branch 26312f93d Update index.md eb6f51df1 Update js.md b890dc84d Merge branch 'tempv0.78.1' 6b73ea450 releaser: Add release notes to /docs for release of 0.78.1 46e582112 Update starter-kits.md (#1268) a62786235 Update 404 docs: GitLab auto-detects 404.html (#1173) cbd4fd2d9 Fix typo (#1271) 2ba3f9386 Update js.md 7b5109d90 Update js.md bc75bc962 Release 0.78.0 0b2e8b0f1 releaser: Add release notes to /docs for release of 0.78.0 9ecba8480 Merge commit 'b74591123eac47a20d1f26ff3e2d291cd9c5cfc0' 60a475df7 js: Add avoidTDZ option 3b895261f Make js.Build fully support modules git-subtree-dir: docs git-subtree-split: 1de7a358cac94ac09a513456bdaae65e6ae94859
2020-11-27 08:26:24 +00:00
Any imports starting with `.` is resolved relative to the current file:
```js
import { hello4 } from './lib';
```
For other files (e.g. `JSON`, `CSS`) you need to use the relative path including any extension, e.g:
```js
import * as data from 'my/module/data.json';
```
Any imports in a file outside `/assets` or that does not resolve to a component inside `/assets` will be resolved by [ESBuild](https://esbuild.github.io/) with the **project directory** as the resolve directory (used as the starting point when looking for `node_modules` etc.). Also see [hugo mod npm pack](/commands/hugo_mod_npm_pack/). If you have any imported NPM dependencies in your project, you need to make sure to run `npm install` before you run `hugo`.
Also note the new `params` option that can be passed from template to your JS files, e.g.:
```go-html-template
{{ $js := resources.Get "js/main.js" | js.Build (dict "params" (dict "api" "https://example.org/api")) }}
```
And then in your JS file:
```js
import * as params from '@params';
```
Squashed 'docs/' changes from 1de7a358c..ef9c4913c ef9c4913c Clean up and removal of outdated examples 46122c9aa add godot tutorials to showcase 06d1d1ea2 Update scss-sass.md 1fc63c100 Spelling fix in 0.79.1 release notes ad2f50e3d Update plainwords description (#1296) 33021d451 Update substr examples (#1304) 6b1cc59bb Release 0.80.0 521db8c6d Merge branch 'tempv0.80.0' 58626c2b3 releaser: Add release notes to /docs for release of 0.80.0 f81d118af dartsass: Dart Sass only supports `expanded` and `compressed` 7da6f54be Add Dart Sass support b1f2661bb Replace jsconfig.js with jsconfig.json 38de0c1a4 Update index.md 223ceae80 Update index.md f7ac0e59d Release v0.79.1 2d4583d43 Merge branch 'temp791-2' 1d34e609b releaser: Add release notes to /docs for release of 0.79.1 e26769988 Merge branch 'temp791' 75694d904 Fix Resource.ResourceType so it always returns MIME's main type 0f65d7783 Typo s/adds/add (#1298) 0b896b2c0 images: Add images.Overlay filter 0d4257dcd Clarify documentation on shimming fcf601ddf Update index.html 6bf9bc1c1 Update index.html 1ce76bf3a Update index.html e7d976eec Update index.html db2996e64 Update index.html 245e5bfc9 news: Add post about Apple M1 3ad4115ed tpl: Add title parameter to YouTube shortcode 76ed976f8 Added two useful extensions to the list (#1243) e5a30dd11 Update related.md 25cf8f48b Improve substr examples e16e57e9a Update path.Split.md 2749b88fd Update path.Split.md d76cad3ff Release 0.79.0 f5ccfbe98 releaser: Add release notes to /docs for release of 0.79.0 ebf1b87b0 Merge commit '9f1265fde4b9ef186148337c99f08601633b6056' 1f1e8f39c Allow setting the delimiter used for setting config via OS env, e.g. HUGO_ e9b1414dd deps: Update to github.com/evanw/esbuild 0.8.11 to 0.8.14 0f76cf66c docs: Regen docshelper 1ada5d47e Add menu params 1c120aef0 Revert "docs: Regenerate docshelper" 7b60b5624 docs: Regenerate docshelper git-subtree-dir: docs git-subtree-split: ef9c4913cdcf95d62ec12d872f412f97e55a55ad
2021-01-20 11:47:49 +00:00
Hugo will, by default, generate a `assets/jsconfig.json` file that maps the imports. This is useful for navigation/intellisense help inside code editors, but if you don't need/want it, you can [turn it off](/getting-started/configuration/#configure-build).
Squashed 'docs/' changes from 57c1d1a67..1de7a358c 1de7a358c Clarify that "with" blocks do not render with empty values (#1287) b48de8b0a Update js.md e0124e4b1 Update js.md 087b39d74 Update hosting-on-render.md (#1286) 8f02b5412 Update js.md (#1284) 8dd8a8d1d Add link to "Build Websites with Hugo" book (#1174) ae2dc138a Fix typo in page bundles (#1283) ab14bfec3 Update configuration directory section 17da77ff1 Update multilingual.md (#1280) 5bce8db3a Fix for site-hierarchy image, issue #60 9d7a2366d Fix typo ad4210c41 Fix typo c88bc0383 Fix orphan branch url (#1262) 1cf6cf5b3 Hugo 0.78.2 538c3cb86 Merge branch 'tempv0.78.2' e5e07fc81 releaser: Add release notes to /docs for release of 0.78.2 120a61a47 Fixed wrong var assignment example 4cebbb1a7 Ignore remote JSON errors (for now) 618fcf9ba Add a link to modules config option 'replacements' e12722779 Fix typo ("wil" -> "will") (#1273) 0670e9894 Update js.md 5bde834cf Update GH docs to say "main" as default branch 26312f93d Update index.md eb6f51df1 Update js.md b890dc84d Merge branch 'tempv0.78.1' 6b73ea450 releaser: Add release notes to /docs for release of 0.78.1 46e582112 Update starter-kits.md (#1268) a62786235 Update 404 docs: GitLab auto-detects 404.html (#1173) cbd4fd2d9 Fix typo (#1271) 2ba3f9386 Update js.md 7b5109d90 Update js.md bc75bc962 Release 0.78.0 0b2e8b0f1 releaser: Add release notes to /docs for release of 0.78.0 9ecba8480 Merge commit 'b74591123eac47a20d1f26ff3e2d291cd9c5cfc0' 60a475df7 js: Add avoidTDZ option 3b895261f Make js.Build fully support modules git-subtree-dir: docs git-subtree-split: 1de7a358cac94ac09a513456bdaae65e6ae94859
2020-11-27 08:26:24 +00:00
### Include Dependencies In package.json / node_modules
Any imports in a file outside `/assets` or that does not resolve to a component inside `/assets` will be resolved by [ESBuild](https://esbuild.github.io/) with the **project directory** as the resolve directory (used as the starting point when looking for `node_modules` etc.). Also see [hugo mod npm pack](/commands/hugo_mod_npm_pack/). If you have any imported NPM dependencies in your project, you need to make sure to run `npm install` before you run `hugo`.
{{< new-in "0.78.1" >}} From Hugo `0.78.1` the start directory for resolving NPM packages (aka. packages that live inside a `node_modules` folder) is always the main project folder.
**Note:** If you're developing a theme/component that is supposed to be imported and depends on dependencies inside `package.json`, we recommend reading about [hugo mod npm pack](/commands/hugo_mod_npm_pack/), a tool to consolidate all the NPM dependencies in a project.
### Examples
```go-html-template
{{ $built := resources.Get "js/index.js" | js.Build "main.js" }}
```
Or with options:
```go-html-template
{{ $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 type="text/javascript" src="{{ $built.RelPermalink }}" defer></script>
```
Squashed 'docs/' changes from 4895c29c5..9abd3043a 9abd3043a Add docs for shimming JS libraries 6a1c8dcd7 Update sitemap-template.md (#1245) 37c397332 Update frontends.md a0f86f6df Update configuration.md bb00cb2c1 Update page-bundles.md 773212de6 Restructure and simplify fcba7dddf Some minor clarifications of weight sorting 759b967fc Update configuration-markup.md 56708f0b7 module import path remove slash at end 59f4f4acd Doc: Fix typo in hugo command faacf2e97 Clarify pagination documentation (#1208) d8eb60887 netlify: Bump to 0.75.1 8cedf6231 Merge branch 'temp751' 188e2bf56 releaser: Add release notes to /docs for release of 0.75.1 c96d4b7a3 Update index.md 1a9d192f7 Update index.md 32731b916 Update index.md a5bfa0c9a Restore the ... home page b6850bf96 Release 0.75.0 d6e5e624f releaser: Add release notes to /docs for release of 0.75.0 8cd6b4f47 typo: already -> already 2cb2b22bb Merge commit '534ae9c57a902aea9ed6e62390dec11fa74b7122' e3525de23 docs: Regen docs helper fd746dd83 docs: Regenerate CLI docs e20127980 Add "hugo mod npm pack" 8e82c7ce1 markup/highlight: Add support to linkable line anchors on Chroma 21e94911b markup/asciidocext: Fix AsciiDoc TOC with code 50b8dace5 modules: Add noVendor to module config d05b541fe modules: Make ignoreVendor a glob pattern c946082e7 docs: Update replaceRE func 149054341 docs: Update replace func d917567df docs: Update merge function f1e093c92 docs: Regen CLI docs c7bac967d docs: Regen docs helper 7a38f7a45 Merge commit '7d7771b673e5949f554515a2c236b23192c765c8' 1a5a7263a markup/asciidoc: Add support for .TableOfContents git-subtree-dir: docs git-subtree-split: 9abd3043a9214b390e8cc148f4588bf630620851
2020-10-06 14:22:20 +00:00