Skip to content

Commit

Permalink
Update docs
Browse files Browse the repository at this point in the history
  • Loading branch information
@jgoz
jgoz committed May 21, 2024
1 parent 16c89d9 commit 153cf75
Show file tree
Hide file tree
Showing 7 changed files with 31 additions and 31 deletions.
16 changes: 8 additions & 8 deletions packages/esbd/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -244,7 +244,7 @@ Take the following HTML entry point as an example:

```html
<!-- index.html entry point -->
<!DOCTYPE html>
<!doctype html>
<html>
<head>
<link rel="apple-touch-icon" href="./assets/favicon.png" />
Expand All @@ -269,7 +269,7 @@ The output for `index.html` will look something like this:

```html
<!-- index.html output -->
<!DOCTYPE html>
<!doctype html>
<html>
<head>
<link rel="apple-touch-icon" href="favicon.png" />
Expand All @@ -292,7 +292,7 @@ Entry name attributes can optionally reference values that appear in the `define

```html
<!-- index.html entry point -->
<!DOCTYPE html>
<!doctype html>
<html>
<head>
<!-- Will be written as "styles.css" -->
Expand Down Expand Up @@ -369,11 +369,11 @@ Note that these esbuild options are ignored:
<!-- markdown-interpolate: node ../../scripts/docs.mjs ./src/config.ts EsbdSpecificOptions -->
| Name | Type | Default | Description |
| ---- | ---- | ------- | ----------- |
| cleanOutdir | `boolean` | `false` | Keep the output directory clean.<br><br>On the initial build, the output directory will be cleaned before the build starts.<br><br>When in watch mode (either directly or via `node-dev`/`serve`), output files will be tracked across builds and any files that are no longer produced by esbuild will be removed from the output directory. This ensures that no stale files are left behind when content hash changes cause files to be renamed or removed. Note that this is usually only relevant when ESM/splitting is enabled. |
| copy | `[from: string, to?: string][]` | - | Files to copy to the output directory during the build.<br><br>Each entry is a tuple representing the source file path to copy and, optionally, the destination file path.<br><br>Source paths may be absolute or relative to `absWorkingDir`. Destination paths may be absolute or relative to `outdir`. If no destination path is provided, the source file will be copied to `outdir` with the same name.<br><br>If `esbd` is started in a watch mode (serve, node-dev, or build --watch), source files will be watched and copied whenever they change.<br><br>Note that `copy` does not support glob patterns. |
| ignoreAssets | `boolean` | - | By default, assets (images, manifests, scripts, etc.) referenced by `<link>`, `<style>` and `<script>` tags in the HTML template will be collected as esbuild assets if their `src` attributes are specified as relative paths. The asset paths will be resolved relative to the *template file* and will be copied to the output directory, taking `publicPath` into consideration if it has been set.<br><br>Absolute paths or URIs will be ignored.<br><br>To ignore all `src` attributes and avoid collecting discovered assets, set this option to `true`. |
| cleanOutdir | `boolean` | `false` | Keep the output directory clean.<br><br>On the initial build, the output directory will be cleaned before the build starts.<br><br>When in watch mode (either directly or via `node-dev`/`serve`), output files will be tracked across builds and any files that are no longer produced by esbuild will be removed from the output directory. This ensures that no stale files are left behind when content hash changes cause files to be renamed or removed. Note that this is usually only relevant when ESM/splitting is enabled. |
| copy | `[from: string, to?: string][]` | - | Files to copy to the output directory during the build.<br><br>Each entry is a tuple representing the source file path to copy and, optionally, the destination file path.<br><br>Source paths may be absolute or relative to `absWorkingDir`. Destination paths may be absolute or relative to `outdir`. If no destination path is provided, the source file will be copied to `outdir` with the same name.<br><br>If `esbd` is started in a watch mode (serve, node-dev, or build --watch), source files will be watched and copied whenever they change.<br><br>Note that `copy` does not support glob patterns. |
| cssChunkFilter | `(absFilePath: string) => undefined \| null \| boolean` | - | Predicate function that determines whether a CSS output file should be added to the written HTML entry point.<br><br>Esbd makes a best effort to determine which output files should be referenced as `<script>` and `<link rel="stylesheet">` tags in the HTML entry point. By default, CSS output files will be cross-referenced with CSS and JS entry points defined in HTML. Both CSS files that are referenced directly in HTML and those that are referenced indirectly from JS entry points will be included.<br><br>In some cases, more CSS files will need to be included than the default algorithm can detect, so this function can be used to be more specific since it will receive every CSS output file produced by esbuild.<br><br>This function receives an output file path and should return a value indicating whether that file should be referenced in the HTML output. If the function returns `null` or `undefined`, the default algorithm will be used. |
| ignoreAssets | `boolean` | - | By default, assets (images, manifests, scripts, etc.) referenced by `<link>`, `<style>` and `<script>` tags in the HTML template will be collected as esbuild assets if their `src` attributes are specified as relative paths. The asset paths will be resolved relative to the *template file* and will be copied to the output directory, taking `publicPath` into consideration if it has been set.<br><br>Absolute paths or URIs will be ignored.<br><br>To ignore all `src` attributes and avoid collecting discovered assets, set this option to `true`. |
| [integrity](https://developer.mozilla.org/en-US/docs/Web/Security/Subresource_Integrity) | `"sha256" \| "sha384" \| "sha512"` | - | If specified, a cryptographic digest for each file referenced by a `<link>` or `<script>` tag will be calculated using the specified algorithm and added as an `integrity` attribute on the associated tag. |
| name | `string` | - | Name of this configuration.<br><br>This is required for configurations that appear in an array. |
| cssChunkFilter | `(absFilePath: string) => undefined \| null \| boolean` | - | Predicate function that determines whether a CSS output file should be added to the written HTML entry point.<br><br>Esbd makes a best effort to determine which output files should be referenced as `<script>` and `<link rel="stylesheet">` tags in the HTML entry point. By default, CSS output files will be cross-referenced with CSS and JS entry points defined in HTML. Both CSS files that are referenced directly in HTML and those that are referenced indirectly from JS entry points will be included.<br><br>In some cases, more CSS files will need to be included than the default algorithm can detect, so this function can be used to be more specific since it will receive every CSS output file produced by esbuild.<br><br>This function receives an output file path and should return a value indicating whether that file should be referenced in the HTML output. If the function returns `null` or `undefined`, the default algorithm will be used. |
| name | `string` | - | Name of this configuration.<br><br>This is required for configurations that appear in an array. |
<!-- end -->
<!-- prettier-ignore-end -->
2 changes: 1 addition & 1 deletion packages/esbuild-overlay/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -48,6 +48,6 @@ Displays an overlay with the supplied error messages and returns a function that
| Name | Type | Default | Description |
| ---- | ---- | ------- | ----------- |
| errors (*) | `Message[]` | - | Error messages to display. |
| openFileURL | `string` | - | If provided, this URL will be opened when the user clicks on the overlay.<br><br>This can be used to open the source file of the error or warning. |
| openFileURL | `string` | - | If provided, this URL will be opened when the user clicks on the overlay.<br><br>This can be used to open the source file of the error or warning. |
<!-- end -->
<!-- prettier-ignore-end -->
26 changes: 13 additions & 13 deletions packages/esbuild-plugin-html/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -45,16 +45,16 @@ At the bare minimum, the provided template should have a `doctype`, `html`, `hea
<!-- markdown-interpolate: node ../../scripts/docs.mjs ./src/html-plugin.ts HtmlPluginOptions -->
| Name | Type | Default | Description |
| ---- | ---- | ------- | ----------- |
| template (*) | `string` | - | Path to the HTML template to use (required).<br><br>If a relative path is provided, it will be resolved relative to the `absWorkingDir` build option (falling back to `process.cwd()`). |
| chunks | `"entry" \| (outputPath: string, output: Object) => boolean` | `"entry"` | Filters chunks that should be included as `<link>` or `<script>` tags in the HTML output.<br><br>If the string "entry" is given (default), all entry points defined in esbuild options will be included. Note that CSS entry points will only be included if they are specified explicitly in esbuild options; being dependencies of a JS entry point is not sufficient.<br><br>"chunks" may also be provided as a function that receives all outputs, not just entry points. Returning true will include a reference to the chunk in HTML, false will exclude it. |
| [crossorigin](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/crossorigin) | `"anonymous" \| "use-credentials"` | - | Defines how generated `<link>` and `<script>` tags handle cross-origin requests. |
| [defer](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/script#attr-defer) | `boolean` | - | Sets the `defer` attribute on generated script tags. |
| define | `Record<string, string>` | - | Values that will be substituted in the HTML output.<br><br>Given the following value for `define`:<br><br>``` define: { FOO: 'foo', BAR: 'bar', } ```<br><br>The HTML template may use `{{FOO}}` and `{{BAR}}` wherever those values should be substituted.<br><br>Note that unlike the `define` option in esbuild, strings should not be wrapped in `JSON.stringify`, since values will be substituted directly into the output. This means if any values are used in strings inside of inline `<script>` elements, they should be wrapped in quotes inside of the script. E.g.,<br><br>```html <script> const foo = "{{FOO}}"; </script> ``` |
| filename | `string` | - | Output filename.<br><br>By default, the filename will be the same as the basename of the template file. |
| ignoreAssets | `boolean` | - | By default, assets (images, manifests, scripts, etc.) referenced by `<link>`, `<style>` and `<script>` tags in the HTML template will be collected as esbuild assets if their `src` attributes are specified as relative paths. The asset paths will be resolved relative to the *template file* and will be copied to the output directory, taking `publicPath` into consideration if it has been set.<br><br>Absolute paths or URIs will be ignored.<br><br>To ignore all `src` attributes and avoid collecting discovered assets, set this option to `true`. |
| template (*) | `string` | - | Path to the HTML template to use (required).<br><br>If a relative path is provided, it will be resolved relative to the `absWorkingDir` build option (falling back to `process.cwd()`). |
| chunks | `"entry" \| (outputPath: string, output: Object) => boolean` | `"entry"` | Filters chunks that should be included as `<link>` or `<script>` tags in the HTML output.<br><br>If the string "entry" is given (default), all entry points defined in esbuild options will be included. Note that CSS entry points will only be included if they are specified explicitly in esbuild options; being dependencies of a JS entry point is not sufficient.<br><br>"chunks" may also be provided as a function that receives all outputs, not just entry points. Returning true will include a reference to the chunk in HTML, false will exclude it. |
| [crossorigin](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/crossorigin) | `"anonymous" \| "use-credentials"` | - | Defines how generated `<link>` and `<script>` tags handle cross-origin requests.<br><br>If left undefined, no attribute will be emitted. |
| [defer](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/script#attr-defer) | `boolean` | - | Sets the `defer` attribute on generated script tags.<br><br>If `scriptPlacement` is set to `head-*`, this will default to `true` but it can be set explicitly to `false` to override that behavior.<br><br>If esbuild is configured with `format: 'esm'`, `<script>` tags will be emitted as `type="module"` which implicitly sets `defer`. In that case, this setting will have no effect. |
| define | `Record<string, string>` | - | Values that will be substituted in the HTML output.<br><br>Given the following value for `define`:<br><br>``` define: { FOO: 'foo', BAR: 'bar', } ```<br><br>The HTML template may use `{{FOO}}` and `{{BAR}}` wherever those values should be substituted.<br><br>Note that unlike the `define` option in esbuild, strings should not be wrapped in `JSON.stringify`, since values will be substituted directly into the output. This means if any values are used in strings inside of inline `<script>` elements, they should be wrapped in quotes inside of the script. E.g.,<br><br>```html <script> const foo = "{{FOO}}"; </script> ``` |
| filename | `string` | - | Output filename.<br><br>By default, the filename will be the same as the basename of the template file. |
| ignoreAssets | `boolean` | - | By default, assets (images, manifests, scripts, etc.) referenced by `<link>`, `<style>` and `<script>` tags in the HTML template will be collected as esbuild assets if their `src` attributes are specified as relative paths. The asset paths will be resolved relative to the *template file* and will be copied to the output directory, taking `publicPath` into consideration if it has been set.<br><br>Absolute paths or URIs will be ignored.<br><br>To ignore all `src` attributes and avoid collecting discovered assets, set this option to `true`. |
| [integrity](https://developer.mozilla.org/en-US/docs/Web/Security/Subresource_Integrity) | `"sha256" \| "sha384" \| "sha512"` | - | If specified, a cryptographic digest for each file referenced by a `<link>` or `<script>` tag will be calculated using the specified algorithm and added as an `integrity` attribute on the associated tag. |
| linkPosition | `"above" \| "below"` | `"below"` | Where to emit `<link>` elements for CSS chunks.<br><br>Possible values:<li>`"above"` &mdash; inside `<head>` element, above existing `<link>`s and `<style>`s<li>`"below"` &mdash; inside `<head>` element, below existing `<link>`s and `<style>`s<br><br>`<link>` elements are always emitted to `<head>`. |
| scriptPlacement | `"head-above" \| "head-below" \| "body-above" \| "body-below"` | `"head-below"` | Where to emit `<script>` elements for JS chunks.<br><br>Possible values:<li>`"head-above"` &mdash; inside `<head>` element, above existing `<script>`s<li>`"head-below"` &mdash; inside `<head>` element, below existing `<script>`s<li>`"body-above"` &mdash; inside `<body>` element, above existing `<script>`s<li>`"body-below"` &mdash; inside `<body>` element, below existing `<script>`s<br><br>When emitted to `<head>`, the `defer` option will be implicitly set to `true`. If you wish to disable this behavior, set `defer: false`. |
| linkPosition | `"above" \| "below"` | `"below"` | Where to emit `<link>` elements for CSS chunks.<br><br>Possible values:<li>`"above"` &mdash; inside `<head>` element, above existing `<link>`s and `<style>`s<li>`"below"` &mdash; inside `<head>` element, below existing `<link>`s and `<style>`s<br><br>`<link>` elements are always emitted to `<head>`. |
| scriptPlacement | `"head-above" \| "head-below" \| "body-above" \| "body-below"` | `"head-below"` | Where to emit `<script>` elements for JS chunks.<br><br>Possible values:<li>`"head-above"` &mdash; inside `<head>` element, above existing `<script>`s<li>`"head-below"` &mdash; inside `<head>` element, below existing `<script>`s<li>`"body-above"` &mdash; inside `<body>` element, above existing `<script>`s<li>`"body-below"` &mdash; inside `<body>` element, below existing `<script>`s<br><br>When emitted to `<head>`, the `defer` option will be implicitly set to `true`. If you wish to disable this behavior, set `defer: false`. |
<!-- end -->
<!-- prettier-ignore-end -->

Expand All @@ -63,7 +63,7 @@ At the bare minimum, the provided template should have a `doctype`, `html`, `hea
#### Bare Minimum:

```html
<!DOCTYPE html>
<!doctype html>
<html>
<head></head>
<body></body>
Expand All @@ -73,7 +73,7 @@ At the bare minimum, the provided template should have a `doctype`, `html`, `hea
#### With external referenced assets (will not be copied):

```html
<!DOCTYPE html>
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8" />
Expand Down Expand Up @@ -107,7 +107,7 @@ At the bare minimum, the provided template should have a `doctype`, `html`, `hea
#### With local referenced assets (will be copied):

```html
<!DOCTYPE html>
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8" />
Expand Down Expand Up @@ -150,7 +150,7 @@ At the bare minimum, the provided template should have a `doctype`, `html`, `hea
#### With values that will be replaced by `define` option:

```html
<!DOCTYPE html>
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8" />
Expand Down
6 changes: 3 additions & 3 deletions packages/esbuild-plugin-html/src/html-plugin.ts
View file
Original file line number Diff line number Diff line change
Expand Up @@ -70,17 +70,16 @@ export interface HtmlPluginOptions {

/**
* Defines how generated `<link>` and `<script>` tags handle cross-origin requests.
* @see {@link https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/crossorigin}
*
* If left undefined, no attribute will be emitted.
*
* @see {@link https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/crossorigin}
* @default undefined
*/
crossorigin?: Crossorigin;

/**
* Sets the `defer` attribute on generated script tags.
* @see {@link https://developer.mozilla.org/en-US/docs/Web/HTML/Element/script#attr-defer}
*
* If `scriptPlacement` is set to `head-*`, this will default to `true` but
* it can be set explicitly to `false` to override that behavior.
Expand All @@ -89,6 +88,7 @@ export interface HtmlPluginOptions {
* as `type="module"` which implicitly sets `defer`. In that case, this setting
* will have no effect.
*
* @see {@link https://developer.mozilla.org/en-US/docs/Web/HTML/Element/script#attr-defer}
* @default undefined
*/
defer?: boolean;
Expand Down Expand Up @@ -151,8 +151,8 @@ export interface HtmlPluginOptions {
* If specified, a cryptographic digest for each file referenced by a `<link>` or
* `<script>` tag will be calculated using the specified algorithm and added as an
* `integrity` attribute on the associated tag.
* @see {@link https://developer.mozilla.org/en-US/docs/Web/Security/Subresource_Integrity}
*
* @see {@link https://developer.mozilla.org/en-US/docs/Web/Security/Subresource_Integrity}
* @default undefined
*/
integrity?: HashAlgorithm;
Expand Down
Loading

0 comments on commit 153cf75

Please sign in to comment.