From 7aa0f765a5d01fd000f906356a358d742da51e98 Mon Sep 17 00:00:00 2001 From: FND Date: Fri, 22 Mar 2019 16:08:31 +0100 Subject: [PATCH 1/3] documented configuration options --- README.md | 34 ++++++++++++++++++++++++++++++++++ 1 file changed, 34 insertions(+) diff --git a/README.md b/README.md index 5c7a6b7..f90f1ae 100644 --- a/README.md +++ b/README.md @@ -8,6 +8,40 @@ faucet-pipeline-js [faucet-pipeline](http://faucet-pipeline.org) plugin for bundling JavaScript modules, along with extensions for ESNext, JSX and TypeScript +note that this repository comprises multiple packages; those residing within +`pkg` are merely meta-packages to simplify dependency management for users + + +Features and Configuration +-------------------------- + +supported global features: + +* compacting +* Browserslist, determining transpilation targets +* source maps (inline) +* fingerprinting - NB: can be overriden with bundle-specific configuration + +bundle-specific configuration: + +| option | description | permitted values | examples | +| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- | ------------------------------------ | +| `source` (required) | references the entry-point module | file path
non-relative file paths are interpeted as identifiers for third-party packages | `"./src/index.js"` | +| `target` (required) | references the target bundle | relative file path | `"./dist/bundle.js"` | +| `compact` | activates bundle compression
NB: only takes effect if compacting is activated globally (typically via `--compact`) | `compact` (default), `minify` or `mangle` | | +| `sourcemaps` | if truthy, activates inline source-map generation
NB: only takes effect if source maps are activated globally (typically via `--sourcemaps`) | `false` suppresses source maps | | +| `format` | determines the bundle format | `iife` (default), `esm`, `umd`, `amd` or `commonjs` - all case-insensitive | | +| `exports` | determines the bundle's API; the value exported by `source` (if any) | | `"MYLIB"`, for IIFEs | +| `extensions` | additional file extensions for loading modules | | `[".jsx"]` | +| `externals` | determines which modules/packages to exclude from the bundle | an object whose key refers to the respective module/package name, the value refers to a corresponding global variable | `{ jquery: "jQuery" }` | +| `esnext` | if truthy, activates ESNext transpilation (typically determined by Browserslist) | | | +| `esnext.browserslist` | custom Browserslist entry selection | the name of the Browserslist group to select
`false` suppresses automatic configuration via Browserslist | `esnext: { browserslist: "legacy" }` | +| `esnext.exclude` | modules/packages for which to skip transpilation
this might be useful when importing distributions already optimized for ES5, for example | | `esnext: { exclude: ["jquery"] }` | +| `jsx` | if truthy, activates JSX transpilation
additionally accepts the same options as `esnext` | | | +| `jsx.pragma` | determines the function to use for JSX expressions | | `jsx: { pragma: "createElement" }` | +| `jsx.fragment` | determines the function to use for JSX fragments | | `jsx: { fragment: "Fragment" }` | +| `typescript` | if truthy, activates TypeScript transpilation
anything other than `true` will be passed through as TypeScript compiler options | | | + Contributing ------------ From 89c321cc0da2ffda651da517c6e217aab20f96ec Mon Sep 17 00:00:00 2001 From: FND Date: Fri, 10 May 2019 10:00:54 +0200 Subject: [PATCH 2/3] merged examples into and extended descriptions --- README.md | 34 +++++++++++++++++----------------- 1 file changed, 17 insertions(+), 17 deletions(-) diff --git a/README.md b/README.md index f90f1ae..fd731c0 100644 --- a/README.md +++ b/README.md @@ -24,23 +24,23 @@ supported global features: bundle-specific configuration: -| option | description | permitted values | examples | -| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- | ------------------------------------ | -| `source` (required) | references the entry-point module | file path
non-relative file paths are interpeted as identifiers for third-party packages | `"./src/index.js"` | -| `target` (required) | references the target bundle | relative file path | `"./dist/bundle.js"` | -| `compact` | activates bundle compression
NB: only takes effect if compacting is activated globally (typically via `--compact`) | `compact` (default), `minify` or `mangle` | | -| `sourcemaps` | if truthy, activates inline source-map generation
NB: only takes effect if source maps are activated globally (typically via `--sourcemaps`) | `false` suppresses source maps | | -| `format` | determines the bundle format | `iife` (default), `esm`, `umd`, `amd` or `commonjs` - all case-insensitive | | -| `exports` | determines the bundle's API; the value exported by `source` (if any) | | `"MYLIB"`, for IIFEs | -| `extensions` | additional file extensions for loading modules | | `[".jsx"]` | -| `externals` | determines which modules/packages to exclude from the bundle | an object whose key refers to the respective module/package name, the value refers to a corresponding global variable | `{ jquery: "jQuery" }` | -| `esnext` | if truthy, activates ESNext transpilation (typically determined by Browserslist) | | | -| `esnext.browserslist` | custom Browserslist entry selection | the name of the Browserslist group to select
`false` suppresses automatic configuration via Browserslist | `esnext: { browserslist: "legacy" }` | -| `esnext.exclude` | modules/packages for which to skip transpilation
this might be useful when importing distributions already optimized for ES5, for example | | `esnext: { exclude: ["jquery"] }` | -| `jsx` | if truthy, activates JSX transpilation
additionally accepts the same options as `esnext` | | | -| `jsx.pragma` | determines the function to use for JSX expressions | | `jsx: { pragma: "createElement" }` | -| `jsx.fragment` | determines the function to use for JSX fragments | | `jsx: { fragment: "Fragment" }` | -| `typescript` | if truthy, activates TypeScript transpilation
anything other than `true` will be passed through as TypeScript compiler options | | | +| option | description | permitted values | +| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- | +| `source` (required) | references the entry-point module (e.g. `"./src/index.js"`) | file path
non-relative file paths are interpeted as identifiers for third-party packages | +| `target` (required) | references the target bundle (e.g. `"./dist/bundle.js"`) | relative file path | +| `compact` | activates bundle compression
NB: only takes effect if compacting is activated globally (typically via `--compact`)
certain options require faucet-pipeline-jsmin | `compact` (default), `minify` or `mangle` | +| `sourcemaps` | if truthy, activates inline source-map generation
NB: only takes effect if source maps are activated globally (typically via `--sourcemaps`) | `false` suppresses source maps | +| `format` | determines the bundle format | `iife` (default), `esm`, `umd`, `amd` or `commonjs` - all case-insensitive | +| `exports` | determines the bundle's API; the name of the value exported by the `source` module, if any (e.g. `"MYLIB"`, which would become a global variable for IIFEs) | | +| `extensions` | additional file extensions for loading modules (e.g. `[".es"]`) | | +| `externals` | determines which modules/packages to exclude from the bundle (e.g. `{ jquery: "jQuery" }`) | an object whose key refers to the respective module/package name, the value refers to a corresponding global variable | +| `esnext` | if truthy, activates ESNext transpilation (typically determined by Browserslist)
requires faucet-pipeline-esnext | | +| `esnext.browserslist` | custom Browserslist entry selection (e.g. `esnext: { browserslist: "legacy" }`) | the name of the Browserslist group to select
`false` suppresses automatic configuration via Browserslist | +| `esnext.exclude` | modules/packages for which to skip transpilation
this might be useful when importing distributions already optimized for ES5, for example (e.g. `esnext: { exclude: ["jquery"] }`) | | +| `jsx` | if truthy, activates JSX transpilation (automatically adding `.jsx` file extensions)
additionally accepts the same options as `esnext`
requires faucet-pipeline-jsx | | +| `jsx.pragma` | determines the function to use for JSX expressions (e.g. `jsx: { pragma: "createElement" }`) | | +| `jsx.fragment` | determines the function to use for JSX fragments (e.g. `jsx: { fragment: "Fragment" }`) | | +| `typescript` | if truthy, activates TypeScript transpilation (automatically adding `.ts` file extensions)
anything other than `true` will be passed through as TypeScript compiler options
requires faucet-pipeline-typescript | | Contributing From 004c92d6795e713d5a04e0f1464c3a4ada862af0 Mon Sep 17 00:00:00 2001 From: FND Date: Fri, 10 May 2019 10:17:58 +0200 Subject: [PATCH 3/3] re-ordered options, putting less frequently used ones towards the bottom apart from `extensions` (which should rarely be necessary), this seems pretty arbitrary though --- README.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index fd731c0..da5768f 100644 --- a/README.md +++ b/README.md @@ -28,12 +28,10 @@ bundle-specific configuration: | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- | | `source` (required) | references the entry-point module (e.g. `"./src/index.js"`) | file path
non-relative file paths are interpeted as identifiers for third-party packages | | `target` (required) | references the target bundle (e.g. `"./dist/bundle.js"`) | relative file path | -| `compact` | activates bundle compression
NB: only takes effect if compacting is activated globally (typically via `--compact`)
certain options require faucet-pipeline-jsmin | `compact` (default), `minify` or `mangle` | -| `sourcemaps` | if truthy, activates inline source-map generation
NB: only takes effect if source maps are activated globally (typically via `--sourcemaps`) | `false` suppresses source maps | | `format` | determines the bundle format | `iife` (default), `esm`, `umd`, `amd` or `commonjs` - all case-insensitive | | `exports` | determines the bundle's API; the name of the value exported by the `source` module, if any (e.g. `"MYLIB"`, which would become a global variable for IIFEs) | | -| `extensions` | additional file extensions for loading modules (e.g. `[".es"]`) | | | `externals` | determines which modules/packages to exclude from the bundle (e.g. `{ jquery: "jQuery" }`) | an object whose key refers to the respective module/package name, the value refers to a corresponding global variable | +| `compact` | activates bundle compression
NB: only takes effect if compacting is activated globally (typically via `--compact`)
certain options require faucet-pipeline-jsmin | `compact` (default), `minify` or `mangle` | | `esnext` | if truthy, activates ESNext transpilation (typically determined by Browserslist)
requires faucet-pipeline-esnext | | | `esnext.browserslist` | custom Browserslist entry selection (e.g. `esnext: { browserslist: "legacy" }`) | the name of the Browserslist group to select
`false` suppresses automatic configuration via Browserslist | | `esnext.exclude` | modules/packages for which to skip transpilation
this might be useful when importing distributions already optimized for ES5, for example (e.g. `esnext: { exclude: ["jquery"] }`) | | @@ -41,6 +39,8 @@ bundle-specific configuration: | `jsx.pragma` | determines the function to use for JSX expressions (e.g. `jsx: { pragma: "createElement" }`) | | | `jsx.fragment` | determines the function to use for JSX fragments (e.g. `jsx: { fragment: "Fragment" }`) | | | `typescript` | if truthy, activates TypeScript transpilation (automatically adding `.ts` file extensions)
anything other than `true` will be passed through as TypeScript compiler options
requires faucet-pipeline-typescript | | +| `sourcemaps` | if truthy, activates inline source-map generation
NB: only takes effect if source maps are activated globally (typically via `--sourcemaps`) | `false` suppresses source maps | +| `extensions` | additional file extensions for loading modules (e.g. `[".es"]`) | | Contributing