mirror/hugo
1
0
Fork 0
mirror of https://github.com/gohugoio/hugo.git synced 2025-08-30 22:39:58 +02:00
Code Issues Packages Projects Releases Wiki Activity

Merge commit '35dec7c96f7ee3eb17dd444f7067f0c776fb56ae'

Browse Source
This commit is contained in:
Bjørn Erik Pedersen
2023-12-04 15:24:01 +01:00
parent 9f978d387f 35dec7c96f
commit d19ed4d4e6
810 changed files with 24147 additions and 7766 deletions
Download Patch File Download Diff File Expand all files Collapse all files

60
docs/content/en/hugo-pipes/js.md
View File

@@ -1,7 +1,7 @@
---
title: js.Build
linkTitle: JavaScript building
description: Process a JavaScript file with [ESBuild](https://github.com/evanw/esbuild).
description: Bundle, transpile, tree shake, and minify JavaScript resources.
categories: [asset management]
keywords: []
menu:
@@ -9,7 +9,10 @@ menu:
parent: hugo-pipes
weight: 60
weight: 60
signatures: ["js.Build RESOURCE [OPTIONS]"]
action:
aliases: []
returnType: resource.Resource
signatures: ['js.Build [OPTIONS] RESOURCE']
---
## Usage
@@ -18,12 +21,12 @@ Any JavaScript resource file can be transpiled and "tree shaken" using `js.Build
### Options
targetPath [string]
: If not set, the source path will be used as the base target path.
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.
params [map or slice]
: Params that can be imported as JSON in your JS files, e.g.:
params
: (`map` or `slice`) 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")) }}
@@ -36,14 +39,14 @@ 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.
minify
: (`bool`) Let `js.Build` handle the minification.
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
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
: (`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:
```go-html-template
{{ $shims := dict "react" "js/shims/react.js" "react-dom" "js/shims/react-dom.js" }}
@@ -69,29 +72,28 @@ import * as React from 'react'
import * as ReactDOM from 'react-dom';
```
target [string]
: The language target.
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
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
: (`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]
: The output format.
format
: (`string`) The output format.
One of: `iife`, `cjs`, `esm`.
Default is `iife`, a self-executing function, suitable for inclusion as a <script> tag.
Default is `iife`, a self-executing function, suitable for inclusion as a `<script>` tag.
sourceMap [string]
: Whether to generate `inline` or `external` source maps from esbuild. External source maps will be written to the target with the output file name + ".map". Input source maps can be read from js.Build and node modules and combined into the output source maps. By default, source maps are not created.
sourceMap
: (`string`) Whether to generate `inline` or `external` source maps from esbuild. External source maps will be written to the target with the output file name + ".map". Input source maps can be read from js.Build and node modules and combined into the output source maps. By default, source maps are not created.
### Import JS code from /assets
@@ -121,7 +123,7 @@ For other files (e.g. `JSON`, `CSS`) you need to use the relative path including
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`.
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.:
@@ -136,15 +138,15 @@ import * as params from '@params';
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).
### 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`.
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`.
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.
{{% 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.
{{% /note %}}
### Examples