Document js.Build

[bep]

For the options, see:

https://godoc.org/github.com/gohugoio/hugo/resources/resource_transformers/js#Options

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

=> "js/main.js"

{{ $js := resources.Get "js/main.ts" | js.Build "mypath.js" }}

{{ $js := resources.Get "js/main.ts" | js.Build (dict "targetPath" "mypath.js" "externals" (slice "react" "react-dom") "minify"{ true) }}

Keywords from the above:

• The target will always be a *.js file -- if not set it will use the input as a template
• The loader will be determined by the MIME type/file extension: Current valid extensions are js, ts, jsx, tsx.

I would love some help on getting some basic documentation about this great new feature. Any takers? I think it belongs as a new page in the "Hugo Pipes" section: "JavaScript Building" or something.

Addon: I think an important disclaimer in this docs is that is currently does not fully support Hugo's union filesystem. I will work to get a proper fix for that, but if you have a theme component, I suspect that you need to build that to /resources/_gen to make it work. It walks upwards to find node_module folders, which is also worth noting.

[regisphilibert]

I'd love to help, but my understanding of bundlers, transpile etc... is limited.

For example, I would think that, because ESBuild transpiles, Babel is not needed anymore? But then I miss on the concept of Babel's preset and how they translate in the ESBuild universe...

[bep]

But then I miss on the concept of Babel's preset and how they translate in the ESBuild universe...

The closest mapping from Babel's presets are the target option:

   // The language target.
    // One of: es2015, es2016, es2017, es2018, es2019, es2020 or esnext.
    // Default is esnext.
    Target string

So, esbuild also supports having browsers as target, but Hugo does not support that (at least not yet).

A preset in Babel may look like this:

{
  "targets": {
    "chrome": "58",
    "ie": "11"
  }
}

As I said, we may add the browser option, too, but I suspect it's easier to just target some minimal es* version, e.g.:

{{ $js := resources.Get "js/main.ts" | js.Build (dict "targetPath" "mypath.js" "target" "es2016") }}

Which will produce compatible code for these browsers:

https://kangax.github.io/compat-table/es2016plus/

esnext (default) will, I assume, let any new language feature stay as is.

[regisphilibert]

I'm trying this out with some use cases and I have trouble using it with React at the moment: From ESBuild doc:

If you're using esbuild to bundle React yourself instead of including it with a Githubissues.

Githubissues is a development platform for aggregating issues.