From 3ddfc3839d23e1dbc915712485da07633cd511a6 Mon Sep 17 00:00:00 2001 From: James Calcaben Date: Wed, 17 Jun 2020 13:48:23 -0500 Subject: [PATCH 01/22] Add buildpack configuration file to reference doc generator script --- .../scripts/create-reference-docs/config/buildpack.js | 6 ++++++ pwa-devdocs/scripts/create-reference-docs/config/index.js | 3 ++- 2 files changed, 8 insertions(+), 1 deletion(-) create mode 100644 pwa-devdocs/scripts/create-reference-docs/config/buildpack.js diff --git a/pwa-devdocs/scripts/create-reference-docs/config/buildpack.js b/pwa-devdocs/scripts/create-reference-docs/config/buildpack.js new file mode 100644 index 0000000000..3e6d4f5f9e --- /dev/null +++ b/pwa-devdocs/scripts/create-reference-docs/config/buildpack.js @@ -0,0 +1,6 @@ +module.exports = [ + { + target: 'pwa-buildpack/lib/BuildBus/declare-base.js', + type: 'function' + } +] \ No newline at end of file diff --git a/pwa-devdocs/scripts/create-reference-docs/config/index.js b/pwa-devdocs/scripts/create-reference-docs/config/index.js index 4118578085..cbfe45687e 100644 --- a/pwa-devdocs/scripts/create-reference-docs/config/index.js +++ b/pwa-devdocs/scripts/create-reference-docs/config/index.js @@ -1,8 +1,9 @@ const peregrineFiles = require('./peregrine'); const veniaFiles = require('./venia'); const pagebuilderFiles = require('./pagebuilder'); +const buildpackFiles = require('./buildpack'); -let files = [].concat(peregrineFiles, veniaFiles, pagebuilderFiles); +let files = [].concat(peregrineFiles, veniaFiles, pagebuilderFiles, buildpackFiles); module.exports = { baseGitHubPath: From db283be3555d6e465d7680fadc68d0f42e8acba4 Mon Sep 17 00:00:00 2001 From: James Calcaben Date: Wed, 17 Jun 2020 15:05:59 -0500 Subject: [PATCH 02/22] Add topic for buildpack target ref docs --- .../src/pwa-buildpack/reference/targets/index.md | 13 +++++++++++++ 1 file changed, 13 insertions(+) create mode 100644 pwa-devdocs/src/pwa-buildpack/reference/targets/index.md diff --git a/pwa-devdocs/src/pwa-buildpack/reference/targets/index.md b/pwa-devdocs/src/pwa-buildpack/reference/targets/index.md new file mode 100644 index 0000000000..51cb07ec6d --- /dev/null +++ b/pwa-devdocs/src/pwa-buildpack/reference/targets/index.md @@ -0,0 +1,13 @@ +--- +title: Extensibility Targets +--- + +{: .bs-callout .bs-callout-info} +These wrappable talons are currently only available in the `develop` branch of the PWA Studio project. + + + +{% include auto-generated/pwa-buildpack/lib/BuildBus/declare-base.md %} From f7fe22549066daa34c4e3558238f6812ac774aaf Mon Sep 17 00:00:00 2001 From: James Calcaben Date: Wed, 24 Jun 2020 10:18:20 -0500 Subject: [PATCH 03/22] Add module transform config ref docs and add to nav --- .../scripts/create-reference-docs/config/buildpack.js | 4 ++++ pwa-devdocs/src/_data/buildpack-api.yml | 6 ++++++ .../reference/moduletransformconfig/index.md | 10 ++++++++++ .../src/pwa-buildpack/reference/targets/index.md | 3 ++- 4 files changed, 22 insertions(+), 1 deletion(-) create mode 100644 pwa-devdocs/src/pwa-buildpack/reference/moduletransformconfig/index.md diff --git a/pwa-devdocs/scripts/create-reference-docs/config/buildpack.js b/pwa-devdocs/scripts/create-reference-docs/config/buildpack.js index 3e6d4f5f9e..e49d70d13a 100644 --- a/pwa-devdocs/scripts/create-reference-docs/config/buildpack.js +++ b/pwa-devdocs/scripts/create-reference-docs/config/buildpack.js @@ -2,5 +2,9 @@ module.exports = [ { target: 'pwa-buildpack/lib/BuildBus/declare-base.js', type: 'function' + }, + { + target: 'pwa-buildpack/lib/WebpackTools/ModuleTransformConfig.js', + type: 'function' } ] \ No newline at end of file diff --git a/pwa-devdocs/src/_data/buildpack-api.yml b/pwa-devdocs/src/_data/buildpack-api.yml index 4825ceb88a..71f659fc5f 100644 --- a/pwa-devdocs/src/_data/buildpack-api.yml +++ b/pwa-devdocs/src/_data/buildpack-api.yml @@ -21,9 +21,15 @@ entries: - label: Environment variables url: /pwa-buildpack/reference/environment-variables/ + - label: Extensibility Targets + url: /pwa-buildpack/reference/targets/ + - label: MagentoResolver url: /pwa-buildpack/reference/magento-resolver/ + - label: ModuleTransformConfig + url: /pwa-buildpack/reference/moduletransformconfig/ + - label: MagentoRootComponentsPlugin url: /pwa-buildpack/reference/root-components-plugin/ diff --git a/pwa-devdocs/src/pwa-buildpack/reference/moduletransformconfig/index.md b/pwa-devdocs/src/pwa-buildpack/reference/moduletransformconfig/index.md new file mode 100644 index 0000000000..8922eeb1c6 --- /dev/null +++ b/pwa-devdocs/src/pwa-buildpack/reference/moduletransformconfig/index.md @@ -0,0 +1,10 @@ +--- +title: ModuleTransformConfig +--- + + + +{% include auto-generated/pwa-buildpack/lib/WebpackTools/ModuleTransformConfig.md %} diff --git a/pwa-devdocs/src/pwa-buildpack/reference/targets/index.md b/pwa-devdocs/src/pwa-buildpack/reference/targets/index.md index 51cb07ec6d..df6ecbb769 100644 --- a/pwa-devdocs/src/pwa-buildpack/reference/targets/index.md +++ b/pwa-devdocs/src/pwa-buildpack/reference/targets/index.md @@ -3,11 +3,12 @@ title: Extensibility Targets --- {: .bs-callout .bs-callout-info} -These wrappable talons are currently only available in the `develop` branch of the PWA Studio project. +These targets are currently only available in the `develop` branch of the PWA Studio project. + {% include auto-generated/pwa-buildpack/lib/BuildBus/declare-base.md %} From d840b659b0b884763665fbd1e317aae56fec8425 Mon Sep 17 00:00:00 2001 From: James Calcaben Date: Wed, 24 Jun 2020 10:18:29 -0500 Subject: [PATCH 04/22] Revise js docs --- .../lib/BuildBus/declare-base.js | 171 +++++++++++------- .../lib/WebpackTools/ModuleTransformConfig.js | 5 +- 2 files changed, 112 insertions(+), 64 deletions(-) diff --git a/packages/pwa-buildpack/lib/BuildBus/declare-base.js b/packages/pwa-buildpack/lib/BuildBus/declare-base.js index 9fdae0d51f..8c2540e7bb 100644 --- a/packages/pwa-buildpack/lib/BuildBus/declare-base.js +++ b/packages/pwa-buildpack/lib/BuildBus/declare-base.js @@ -10,7 +10,6 @@ * @namespace {Object} BuiltinTargets * * @memberof @magento/pwa-buildpack - * */ const { SOURCE_SEP } = require('./Target'); module.exports = targets => { @@ -19,22 +18,19 @@ module.exports = targets => { */ const builtins = { /** - * @callback envVarIntercept - * @param {Object} defs - The envVarDefinitions.json structure. - * @returns {undefined} - Interceptors of `envVarDefinitions` may mutate - * the definitions object. Any returned value will be ignored. - */ - - /** - * Collects definitions and documentation for project-wide configuration - * values. The environment variable schema in `envVarDefinitions.json` - * is extensible. Extensions are often configurable, and they can - * integrate their configuration with the project-wide environment - * variables system by tapping `envVarDefinitions`. - * - * @type {tapable.SyncHook} - * @param {envVarIntercept} callback - * @memberof BuiltinTargets + * Collects the definitions and documentation for project-wide configuration + * values based on the `envVarDefinitions.json` file. + * + * The environment variable schema object from this file is extensible + * using an [envVarDefinitions intercept function]{@link envVarIntercept}. + * + * Intercept this target in your project to integrate your extension configuration + * with the project-wide environment variable system. + * + * @see [envVarDefinitions intercept function]{@link envVarIntercept} + * + * @member {tapable.SyncHook} + * * @example Add config fields for your extension * targets.of('@magento/pwa-buildpack').envVarDefinitions.tap(defs => { * defs.sections.push({ @@ -52,30 +48,20 @@ module.exports = targets => { */ envVarDefinitions: new targets.types.Sync(['definitions']), - /** - * @callback addTransform - * @param {Buildpack/WebpackTools~TransformRequest} transformRequest - - * Request to apply a transform to a file provided by this dependency. - */ - - /** - * @callback transformModuleIntercept - * @param {addTransform} addTransform - Callback to add a transform. - * @returns {undefined} - Interceptors of `transformModules` should call - * the `addTransform()` callback. Any returned value will be ignored. - */ - /** * Collects requests to intercept and modify individual files from this - * dependency. Only files from the currently requesting dependency may + * dependency. + * + * Only files from the currently requesting dependency may * be transformed. - * **This is a very low-level extension point; it should be used as a + * + * NOTE: This is a very low-level extension point. It should be used as a * building block for higher-level extensions that expose functional - * areas rather than files on disk.** + * areas rather than files on disk. + * + * @see [transformModules intercept function]{@link transformModulesIntercept} * - * @type {tapable.SyncHook} - * @param {transformModuleIntercept} - * @memberof BuiltinTargets + * @member {tapable.SyncHook} * * @example Strip unnecessary Lodash code from a specific JS module. * targets.of('@magento/pwa-buildpack').transformModules.tap(addTransform => addTransform({ @@ -87,22 +73,17 @@ module.exports = targets => { */ transformModules: new targets.types.Sync(['requestTransform']), - /** - * @callback webpackCompilerIntercept - * @param {webpack.Compiler} compiler - The Webpack compiler instance - * @returns {undefined} - Interceptors of `webpackCompiler` should tap - * hooks on the provided `compiler` object. Any returned value will be - * ignored. - */ - /** * * Calls interceptors whenever a Webpack Compiler object is created. * This almost always happens once per build, even in dev mode. + * + * Use an [intercept function]{@link webpackCompilerIntercept} on this target + * to access the [webpack compiler]{@link https://webpack.js.org/api/compiler-hooks/}. + * + * @see [webpackCompiler intercept function]{@link webpackCompilerIntercept} * - * @type {tapable.SyncHook} - * @param {webpackCompilerIntercept} callback - * @memberof BuiltinTargets + * @member {tapable.SyncHook} * * @example Tap the compiler's `watchRun` hook. * targets.of('@magento/pwa-buildpack').webpackCompiler.tap(compiler => { @@ -114,29 +95,28 @@ module.exports = targets => { */ webpackCompiler: new targets.types.Sync(['compiler']), - /** - * @callback specialFeaturesIntercept - * @param {Object.} - * @returns {undefined} - Interceptors do no need to return. - */ - /** * Collects flags for special build features that dependency packages - * want to use. If your extension uses ES Modules instead of CommonJS in + * want to use. + * + * If your extension uses ES Modules instead of CommonJS in * its frontend code (as most should), Webpack will not parse and build - * the modules by default; it will expect extension code to be CommonJS + * the modules by default. It will expect extension code to be CommonJS * style and will not process the ES Modules. + * + * Use a [specialFeatures intercept function]{@link specialFeaturesIntercept} + * to add special build features for the modules used in your project. * - * @example Declare that your extension contains CSS modules. - * targets.of('@magento/pwa-buildpack').specialFeatures.tap(special => { - * specialFeatures['my-module'] = { cssModules: true }; - * }) + * @see [specialFeatures intercept function]{@link specialFeaturesIntercept} * + * @see [Special flags in `configureWebpack()`]{@link http://pwastudio.io/pwa-buildpack/reference/configure-webpack/#special-flags} * - * @see {configureWebpack} - * @type {tapable.SyncHook} - * @param {Object<(string, boolean)>} featureFlags - * @memberof BuiltinTargets + * @member {tapable.SyncHook} + * + * @example Declare that your extension contains CSS modules. + * targets.of('@magento/pwa-buildpack').specialFeatures.tap(featuresByModule => { + * featuresByModule['my-module'] = { cssModules: true }; + * }) */ specialFeatures: new targets.types.Sync(['special']) }; @@ -158,11 +138,14 @@ module.exports = targets => { * registered interceptor to its own callback, bound to its own module root * as an extra argument. Then, we can make sure all requested files for * transform belong to the module doing the requesting. + * */ builtins.transformModules.intercept({ /** * With the "register" meta-interceptor, we can mess with the arguments * that subsequent interceptors receive. + * + * @ignore */ register: tapInfo => { /** @@ -196,3 +179,65 @@ module.exports = targets => { targets.declare(builtins); }; + +/** Type definitions related to: envVarDefinitions */ + +/** + * Intercept function signature for the enVarDefinitions target. + * + * Interceptors of `envVarDefinitions` may mutate the definitions object. + * These functions do not need to return a value. + * + * @callback envVarDefinitionsIntercept + * + * @param {Object} defs - The definition object based on the `envVarDefinitions.json` file. + */ + +/** Type definitions related to: transformModules */ + +/** + * Intercept function signature for the transformModules target. + * + * Interceptors of `transformModules` should call the [`addTransform()`]{@link addTransform} + * callback to add module specific transformers. + * Any returned value will be ignored. + * + * @callback transformModulesIntercept + * @param {addTransform} addTransform - Callback to add a transform. + */ + +/** + * Callback to add a transform. + * + * @see [TransformRequest]{@link https://pwastudio.io/pwa-buildpack/reference/moduletransformconfig/#buildpackwebpacktoolstransformrequest--object} + * + * @callback addTransform + * @param {Buildpack/WebpackTools~TransformRequest} transformRequest - + * [Request]{@link https://pwastudio.io/pwa-buildpack/reference/moduletransformconfig/#buildpackwebpacktoolstransformrequest--object} + * to apply a transform to a file provided by this dependency. + */ + +/** Type definitions related to: webpackCompiler */ + +/** + * Intercept function signature for the webpackCompiler target. + * + * Interceptors of `webpackCompiler` should tap hooks on the provided + * `compiler` object. Any returned value will be ignored. + * + * @callback webpackCompilerIntercept + * @param {webpack.Compiler} compiler - The [webpack compiler]{@link https://webpack.js.org/api/compiler-hooks/} instance + */ + +/** Type definitions related to: specialFeatures */ + +/** + * Intercept function signature for the specialFeatures target. + * + * Interceptors of the `specialFeatures` target can use the mapping object provided + * to map special build flags to their project modules. + * + * @callback specialFeaturesIntercept + * @param {Object.} featuresByModule - + * An object mapping of module names to their special build flags + */ diff --git a/packages/pwa-buildpack/lib/WebpackTools/ModuleTransformConfig.js b/packages/pwa-buildpack/lib/WebpackTools/ModuleTransformConfig.js index 33b0e573ed..dc0041b4bc 100644 --- a/packages/pwa-buildpack/lib/WebpackTools/ModuleTransformConfig.js +++ b/packages/pwa-buildpack/lib/WebpackTools/ModuleTransformConfig.js @@ -8,6 +8,7 @@ const path = require('path'); * Instruction to the Webpack transform loader to pass a given file through a * transform function implemented in a given Node module, with an optional set * of configuration values that will be passed to the transform function. + * * @prop {string} type - Type of transform. `'babel'` expects a Babel plugin as the `transformModule`. `"source"` expects a Webpack loader. * @prop {string} requestor - Name of the file doing the requesting. * @prop {string} fileToTransform - Relative path to the file in this module @@ -74,8 +75,8 @@ class ModuleTransformConfig { /** * * Add a request to transform a file in the build. + * * @param {TransformRequest} req - Request object - * @memberof ModuleTransformConfig */ add({ requestor, fileToTransform, transformModule, type, options }) { let absTransformModule; @@ -113,6 +114,8 @@ class ModuleTransformConfig { } /** * Resolve paths and emit as JSON. + * + * @returns {object} Configuration object */ async toLoaderOptions() { const byType = { From 5f9c304818e780d1c997eb88d674f71ae6e7c2eb Mon Sep 17 00:00:00 2001 From: James Calcaben Date: Wed, 24 Jun 2020 11:55:37 -0500 Subject: [PATCH 05/22] Add other reference topics --- .../create-reference-docs/config/buildpack.js | 16 ++++++++++++++++ pwa-devdocs/src/_data/buildpack-api.yml | 15 ++++++++++++--- .../reference/{ => buildbus}/targets/index.md | 0 3 files changed, 28 insertions(+), 3 deletions(-) rename pwa-devdocs/src/pwa-buildpack/reference/{ => buildbus}/targets/index.md (100%) diff --git a/pwa-devdocs/scripts/create-reference-docs/config/buildpack.js b/pwa-devdocs/scripts/create-reference-docs/config/buildpack.js index e49d70d13a..306f3e1435 100644 --- a/pwa-devdocs/scripts/create-reference-docs/config/buildpack.js +++ b/pwa-devdocs/scripts/create-reference-docs/config/buildpack.js @@ -6,5 +6,21 @@ module.exports = [ { target: 'pwa-buildpack/lib/WebpackTools/ModuleTransformConfig.js', type: 'function' + }, + { + target: 'pwa-buildpack/lib/BuildBus/TargetProvider.js', + type: 'function' + }, + { + target: 'pwa-buildpack/lib/BuildBus/BuildBus.js', + type: 'function' + }, + { + target: 'pwa-buildpack/lib/BuildBus/Target.js', + type: 'function' + }, + { + target: 'pwa-buildpack/lib/BuildBus/mapHooksToTargets.js', + type: 'function' } ] \ No newline at end of file diff --git a/pwa-devdocs/src/_data/buildpack-api.yml b/pwa-devdocs/src/_data/buildpack-api.yml index 71f659fc5f..ef71ac6d44 100644 --- a/pwa-devdocs/src/_data/buildpack-api.yml +++ b/pwa-devdocs/src/_data/buildpack-api.yml @@ -1,5 +1,17 @@ title: PWA Buildpack API entries: + - label: BuildBus + url: /pwa-buildpack/reference/buildbus/ + entries: + - label: Extensibility Targets + url: /pwa-buildpack/reference/buildbus/targets/ + - label: mapHooksToTarget + url: /pwa-buildpack/reference/buildbus/maphookstotargets/ + - label: Target + url: /pwa-buildpack/reference/buildbus/target/ + - label: TargetProvider + url: /pwa-buildpack/reference/buildbus/targetprovider/ + - label: Buildpack CLI url: /pwa-buildpack/reference/buildpack-cli/ entries: @@ -21,9 +33,6 @@ entries: - label: Environment variables url: /pwa-buildpack/reference/environment-variables/ - - label: Extensibility Targets - url: /pwa-buildpack/reference/targets/ - - label: MagentoResolver url: /pwa-buildpack/reference/magento-resolver/ diff --git a/pwa-devdocs/src/pwa-buildpack/reference/targets/index.md b/pwa-devdocs/src/pwa-buildpack/reference/buildbus/targets/index.md similarity index 100% rename from pwa-devdocs/src/pwa-buildpack/reference/targets/index.md rename to pwa-devdocs/src/pwa-buildpack/reference/buildbus/targets/index.md From a56436812c6416051a515154d3dc7dd8a9dbaedd Mon Sep 17 00:00:00 2001 From: James Calcaben Date: Wed, 24 Jun 2020 11:56:00 -0500 Subject: [PATCH 06/22] Add initial files for the new ref topics --- .../src/pwa-buildpack/reference/buildbus/index.md | 10 ++++++++++ .../reference/buildbus/maphookstotargets/index.md | 11 +++++++++++ .../pwa-buildpack/reference/buildbus/target/index.md | 10 ++++++++++ .../reference/buildbus/targetprovider/index.md | 10 ++++++++++ 4 files changed, 41 insertions(+) create mode 100644 pwa-devdocs/src/pwa-buildpack/reference/buildbus/index.md create mode 100644 pwa-devdocs/src/pwa-buildpack/reference/buildbus/maphookstotargets/index.md create mode 100644 pwa-devdocs/src/pwa-buildpack/reference/buildbus/target/index.md create mode 100644 pwa-devdocs/src/pwa-buildpack/reference/buildbus/targetprovider/index.md diff --git a/pwa-devdocs/src/pwa-buildpack/reference/buildbus/index.md b/pwa-devdocs/src/pwa-buildpack/reference/buildbus/index.md new file mode 100644 index 0000000000..0b0d698589 --- /dev/null +++ b/pwa-devdocs/src/pwa-buildpack/reference/buildbus/index.md @@ -0,0 +1,10 @@ +--- +title: BuildBus +--- + + + +{% include auto-generated/pwa-buildpack/lib/BuildBus/BuildBus.md %} diff --git a/pwa-devdocs/src/pwa-buildpack/reference/buildbus/maphookstotargets/index.md b/pwa-devdocs/src/pwa-buildpack/reference/buildbus/maphookstotargets/index.md new file mode 100644 index 0000000000..2ee381f296 --- /dev/null +++ b/pwa-devdocs/src/pwa-buildpack/reference/buildbus/maphookstotargets/index.md @@ -0,0 +1,11 @@ +--- +title: mapHooksToTargets +--- + + + + +{% include auto-generated/pwa-buildpack/lib/BuildBus/mapHooksToTargets.md %} diff --git a/pwa-devdocs/src/pwa-buildpack/reference/buildbus/target/index.md b/pwa-devdocs/src/pwa-buildpack/reference/buildbus/target/index.md new file mode 100644 index 0000000000..ae781f66ac --- /dev/null +++ b/pwa-devdocs/src/pwa-buildpack/reference/buildbus/target/index.md @@ -0,0 +1,10 @@ +--- +title: Target +--- + + + +{% include auto-generated/pwa-buildpack/lib/BuildBus/Target.md %} diff --git a/pwa-devdocs/src/pwa-buildpack/reference/buildbus/targetprovider/index.md b/pwa-devdocs/src/pwa-buildpack/reference/buildbus/targetprovider/index.md new file mode 100644 index 0000000000..3bca7f0d26 --- /dev/null +++ b/pwa-devdocs/src/pwa-buildpack/reference/buildbus/targetprovider/index.md @@ -0,0 +1,10 @@ +--- +title: TargetProvider +--- + + + +{% include auto-generated/pwa-buildpack/lib/BuildBus/TargetProvider.md %} From c54808ce121e8366117de52ace20530937e8eaed Mon Sep 17 00:00:00 2001 From: James Calcaben Date: Wed, 24 Jun 2020 11:56:23 -0500 Subject: [PATCH 07/22] Revise jsdocs for BuildBus and TargetProvider --- .../pwa-buildpack/lib/BuildBus/BuildBus.js | 23 ++++++++----------- .../lib/BuildBus/TargetProvider.js | 2 +- 2 files changed, 11 insertions(+), 14 deletions(-) diff --git a/packages/pwa-buildpack/lib/BuildBus/BuildBus.js b/packages/pwa-buildpack/lib/BuildBus/BuildBus.js index 71351f4bf2..c010f1f16f 100644 --- a/packages/pwa-buildpack/lib/BuildBus/BuildBus.js +++ b/packages/pwa-buildpack/lib/BuildBus/BuildBus.js @@ -22,9 +22,8 @@ const busCache = new Map(); const INVOKE_FLAG = Symbol.for('FORCE_BUILDBUS_CREATE_FACTORY'); /** - * Manager of dependencies' participation in project builds and tasks. Broker - * for dependencies with Targets to interact with each other. - * + * Manages dependency participation in project builds and tasks. + * It connects dependencies with Targets and lets them interact with each other. */ class BuildBus extends Trackable { /** @@ -32,7 +31,6 @@ class BuildBus extends Trackable { * * @static * @param {string} context - Root directory whose BuildBus to delete. - * @returns {undefined} */ static clear(context) { const absContext = path.resolve(context); @@ -42,15 +40,14 @@ class BuildBus extends Trackable { * Remove all cached BuildBus objects. * * @static - * @returns {undefined} */ static clearAll() { busCache.clear(); } /** * Get or create the BuildBus for the given context. - * This factory is the supported way to construct BuildBuses. - * It caches BuildBuses and connects them to the logging infrastructure. + * This factory is the supported way to construct BuildBus instances. + * It caches the instances and connects them to the logging infrastructure. * * @example Get or create the BuildBus for the package.json file in `./project-dir`, then bind targets, then call a target. * ```js @@ -59,7 +56,7 @@ class BuildBus extends Trackable { * bus.getTargetsOf('my-extension').myTarget.call(); * ``` * - * @param {string} context - Root directory whose BuildBus to get or create. + * @param {string} context - Root directory of the BuildBus to get or create. * @returns {BuildBus} */ static for(context) { @@ -118,8 +115,8 @@ class BuildBus extends Trackable { return `pwa-studio.targets.${phase}`; } /** - * Method which connects TargetProviders to each other. BuildBus passes - * this method to TargetProvider as its `getExternalTargets` callback. + * Connects TargetProviders to each other. BuildBus passes + * this method to TargetProvider as its `getExternalTargets()` callback. * * @private * @param {Object} requestor - Dependency requesting the targets. @@ -148,7 +145,7 @@ class BuildBus extends Trackable { * `targets.of()` methods. * * @param {string} depName - Dependency whose targets to retrieve. - * @returns {Object.<(string, Target)>} TargetProvider for the dependency. + * @returns {Object.} TargetProvider for the dependency. */ getTargetsOf(depName) { return this._getTargets(depName).own; @@ -156,10 +153,10 @@ class BuildBus extends Trackable { /** * Run the two defined phases, `declare` and `intercept`, in order. * This binds all targets which the BuildBus can find by analyzing - * dependencies in the project package file.. + * dependencies in the project package file. * * @chainable - * @returns Returns the instance (chainable). + * @returns {BuildBus} Returns this instance (chainable). */ init() { this.runPhase('declare'); diff --git a/packages/pwa-buildpack/lib/BuildBus/TargetProvider.js b/packages/pwa-buildpack/lib/BuildBus/TargetProvider.js index 3847ed83d5..7cb2e38c32 100644 --- a/packages/pwa-buildpack/lib/BuildBus/TargetProvider.js +++ b/packages/pwa-buildpack/lib/BuildBus/TargetProvider.js @@ -166,7 +166,7 @@ class TargetProvider extends Trackable { /** * Constructors for the different Target classes. * @memberof TargetProvider - * @type {Object.} */ TargetProvider.prototype.types = types; From 8d899f87d547f45586aad7f7e6fe595aacae0307 Mon Sep 17 00:00:00 2001 From: James Calcaben Date: Wed, 24 Jun 2020 12:34:13 -0500 Subject: [PATCH 08/22] Revise JSDocs for the mapHooksToTarget file --- packages/pwa-buildpack/lib/BuildBus/mapHooksToTargets.js | 9 +++++++-- .../reference/buildbus/maphookstotargets/index.md | 1 - 2 files changed, 7 insertions(+), 3 deletions(-) diff --git a/packages/pwa-buildpack/lib/BuildBus/mapHooksToTargets.js b/packages/pwa-buildpack/lib/BuildBus/mapHooksToTargets.js index 408223dbe3..5f5f4798a1 100644 --- a/packages/pwa-buildpack/lib/BuildBus/mapHooksToTargets.js +++ b/packages/pwa-buildpack/lib/BuildBus/mapHooksToTargets.js @@ -33,6 +33,7 @@ const VALID_TYPES = new Map(); * Dictionary of Tapable Hook classes to expose under these new names. * @public * @type {Object.} + * @see [Tapable]{@link https://github.com/webpack/tapable} */ const types = {}; @@ -65,8 +66,8 @@ const hasSyncHookInterface = hook => * More robust than doing `instanceof` checks; allows hooks to be proxied and * otherwise hacked by dependencies. * @public - * @param {object} hookLike - Is it hook-ish? - * @returns {boolean} + * @param {object} hookLike - Does it look and act like a Tapable hook? + * @returns {boolean} True if the object looks like a Tapable hook. False otherwise. */ const appearsToBeTapable = hookLike => hookLike && @@ -79,6 +80,10 @@ const appearsToBeTapable = hookLike => * Tapable Hooks supported, returns the name of that Hook (without 'Hook' on * the end). Otherwise, returns ''. * @public + * + * @param {object} hook Potental Tapable hook object + * + * @returns {string} The name of the hook without 'Hook' on the end or `` */ const getTapableType = hook => VALID_TYPES.get(hook.constructor) || ''; diff --git a/pwa-devdocs/src/pwa-buildpack/reference/buildbus/maphookstotargets/index.md b/pwa-devdocs/src/pwa-buildpack/reference/buildbus/maphookstotargets/index.md index 2ee381f296..2a1ca25ec4 100644 --- a/pwa-devdocs/src/pwa-buildpack/reference/buildbus/maphookstotargets/index.md +++ b/pwa-devdocs/src/pwa-buildpack/reference/buildbus/maphookstotargets/index.md @@ -7,5 +7,4 @@ The reference doc content is generated automatically from the source code. To update this section, update the doc blocks in the source code --> - {% include auto-generated/pwa-buildpack/lib/BuildBus/mapHooksToTargets.md %} From 0933bcb245e927053cc02649de1fc1df90cc179b Mon Sep 17 00:00:00 2001 From: James Calcaben Date: Wed, 24 Jun 2020 14:28:02 -0500 Subject: [PATCH 09/22] Revise JSDocs on the Target file --- packages/pwa-buildpack/lib/BuildBus/Target.js | 48 +++++++++++++++++-- 1 file changed, 43 insertions(+), 5 deletions(-) diff --git a/packages/pwa-buildpack/lib/BuildBus/Target.js b/packages/pwa-buildpack/lib/BuildBus/Target.js index 6404fa1549..0ceccc32d1 100644 --- a/packages/pwa-buildpack/lib/BuildBus/Target.js +++ b/packages/pwa-buildpack/lib/BuildBus/Target.js @@ -17,7 +17,6 @@ const interceptionTypes = { * Target instead of the literal Tapable instance. This enables * better logging, error checking, and validation. * - * @class Target * @extends {Trackable} */ class Target extends Trackable { @@ -67,7 +66,10 @@ class Target extends Trackable { * provided arguments. Returns the final value if it's a Waterfall target, * or the value returned by the first interceptor that returns a value if * it's a Bail target. - * @memberof Target + * + * @param {...object} args Function argument for the wrapped Tapable Hook function + * + * @return {*} Returns whatever the underlying Tapable Hook returns. */ call(...args) { this.track('beforeCall', { type: 'sync', args }); @@ -82,7 +84,10 @@ class Target extends Trackable { * order. Last argument must be a callback. It will be invoked when all * interceptors have run, or when the first returning interceptor has run * if it's a Bail target. - * @memberof Target + * + * @param {...object} args Function argument for the wrapped Tapable Hook function + * + * @return {*} Returns whatever the underlying Tapable Hook returns. */ callAsync(...incomingArgs) { const callbackIndex = incomingArgs.length - 1; @@ -99,7 +104,10 @@ class Target extends Trackable { * Run `.intercept(options)` on the underlying Tapable Hook. * Can register meta-interceptors for other activity on this target. * Use only for logging and debugging. - * @memberof Target + * + * @param {...object} args Function argument for the wrapped Tapable Hook function + * + * @return {*} Returns whatever the underlying Tapable Hook returns. */ intercept(options) { this.track('intercept', { @@ -115,6 +123,10 @@ class Target extends Trackable { * the Target type, calls interceptors in parallel or in series. Returns a * promise. It will be fulfilled when all interceptors have run, or when * the first returning interceptor has run if it's a Bail target. + * + * @param {...object} args Function argument for the wrapped Tapable Hook function + * + * @return {*} Returns whatever the underlying Tapable Hook returns. */ promise(...args) { this.track('beforeCall', { type: 'promise', args }); @@ -124,17 +136,43 @@ class Target extends Trackable { }); } /** - * + * Runs the `tap()` function on a target + * + * @param {string|object} name string or object containing the name of the interceptor + * @param {function} interceptor interceptor function + * + * @return {*} Returns whatever the underlying Tapable Hook returns. */ tap(name, interceptor) { return this._invokeTap('tap', name, interceptor); } + /** + * Runs the `tapAsync()` function on a target + * + * @param {string|object} name string or object containing the name of the interceptor + * @param {function} interceptor interceptor function + * + * @return {*} Returns whatever the underlying Tapable Hook returns. + */ tapAsync(name, interceptor) { return this._invokeTap('tapAsync', name, interceptor); } + /** + * Runs the `tapPromise()` function on a target + * + * @param {string|object} name string or object containing the name of the interceptor + * @param {function} interceptor interceptor function + * + * @return {*} Returns whatever the underlying Tapable Hook returns. + */ tapPromise(name, interceptor) { return this._invokeTap('tapPromise', name, interceptor); } + /** + * Provides the JSON object representation of this target + * + * @returns {object} JSON object + */ toJSON() { const json = super.toJSON(); if (json) { From 1cbeadf14c81d1639e88755355414d3cc25e774a Mon Sep 17 00:00:00 2001 From: James Calcaben Date: Wed, 24 Jun 2020 15:32:09 -0500 Subject: [PATCH 10/22] Revise JSDocs in TargetProvider --- .../lib/BuildBus/TargetProvider.js | 31 ++++++++++--------- 1 file changed, 17 insertions(+), 14 deletions(-) diff --git a/packages/pwa-buildpack/lib/BuildBus/TargetProvider.js b/packages/pwa-buildpack/lib/BuildBus/TargetProvider.js index 7cb2e38c32..7352b898b3 100644 --- a/packages/pwa-buildpack/lib/BuildBus/TargetProvider.js +++ b/packages/pwa-buildpack/lib/BuildBus/TargetProvider.js @@ -21,23 +21,28 @@ const { */ /** - * Mediates between a BuildBus and an "extension" package participating in the - * BuildBus declare/intercept lifecycle. The `targets` object used by declare - * and intercept functions is a TargetProvider. Each extension receives its own - * TargetProvider, which provides methods for declaring its own targets, - * intercepting its own targets, and intercepting the targets of other - * extensions. + * Handles interactions between a BuildBus and an "extension" package + * participating in the BuildBus declare/intercept lifecycle. + * + * The `targets` object used by declare and intercept functions is a TargetProvider. + * Each extension receives its own TargetProvider, which provides methods for + * declaring its own targets, intercepting its own targets, and intercepting the + * targets of other extensions. * - * @class TargetProvider * @extends {Trackable} */ class TargetProvider extends Trackable { /** * Creates an instance of TargetProvider. - * @param {BuildBus|function} bus - BuildBus using this TargetProvider. Alternately, can be a function which will be used for logging. + * + * @constructs + * + * @param {BuildBus|function} bus - BuildBus using this TargetProvider, or alternately, a logging function. * @param {Object} dep - The package which owns this TargetProvider. * @param {string} dep.name - Name of the package which owns this. - * @param {getExternalTargets} getExternalTargets - Function this TargetProvider will use to retrieve external packages when they are requested with `.of()`. Should usually be a delegate to {@link BuildBus#_requestTargets} + * @param {getExternalTargets} getExternalTargets - Function this TargetProvider will use to retrieve external packages when they are requested with `.of()`. + * Should usually be a delegate to BuildBus's [`getExternalTargets()`]{@link http://pwastudio.io/pwa-buildpack/reference/buildbus/targetprovider/#buildpackbuildbusgetexternaltargets--targetprovider} + * * @memberof TargetProvider */ constructor(bus, dep, getExternalTargets) { @@ -72,13 +77,12 @@ class TargetProvider extends Trackable { ); } /** - * Call in the declare phase to register targets that this package and + * Call this function in the declare phase to register targets that this package and * other packages can intercept. * * @param {Object.} declarations - An object whose keys are * the names of targets to declare, and whose properties are newly * constructed Targets. - * @memberof TargetProvider */ declare(declarations) { if (this.phase !== 'declare') { @@ -117,14 +121,13 @@ class TargetProvider extends Trackable { } } /** - * Call in the intercept phase to get the targets of other packages, which - * can then be intercepted by calling `.tap` methods on them. + * Call this function in the intercept phase to get the targets of other packages, which + * can then be intercepted by calling `.tap()` methods on them. * * @param {string} depName - The package whose targets you want to retrieve. * @returns {Object.} - An object whose keys are the names * of the requested package's targets, and whose values are the target * objects. - * @memberof TargetProvider */ of(depName) { if (this.phase !== 'intercept') { From 67f3d8eaf7bab207a7f2dbfb897f4695554ec8c9 Mon Sep 17 00:00:00 2001 From: James Calcaben Date: Wed, 24 Jun 2020 15:59:33 -0500 Subject: [PATCH 11/22] Minor fixes --- .../pwa-buildpack/lib/BuildBus/TargetProvider.js | 12 ++++++++---- .../pwa-buildpack/lib/BuildBus/declare-base.js | 4 ++-- .../lib/WebpackTools/ModuleTransformConfig.js | 16 +++++++++------- .../pwa-buildpack/reference/buildbus/index.md | 3 +++ .../buildbus/maphookstotargets/index.md | 3 +++ .../reference/buildbus/target/index.md | 3 +++ .../reference/buildbus/targetprovider/index.md | 3 +++ .../reference/buildbus/targets/index.md | 1 - .../reference/moduletransformconfig/index.md | 3 +++ 9 files changed, 34 insertions(+), 14 deletions(-) diff --git a/packages/pwa-buildpack/lib/BuildBus/TargetProvider.js b/packages/pwa-buildpack/lib/BuildBus/TargetProvider.js index 7352b898b3..3d8c511e78 100644 --- a/packages/pwa-buildpack/lib/BuildBus/TargetProvider.js +++ b/packages/pwa-buildpack/lib/BuildBus/TargetProvider.js @@ -10,10 +10,14 @@ const { } = require('./mapHooksToTargets'); /** - * Respond to a request from a {@link TargetProvider} to retrieve a different - * (external) TargetProvider. When using a TargetProvider disconnected from a - * {@link BuildBus}, this callback is necessary if anything requests external - * targets on the TargetProvider using {@link TargetProvider#of}. + * Respond to a request from a [TargetProvider]{@link https://pwastudio.io/pwa-buildpack/reference/buildbus/targetprovider/} + * to retrieve a different(external) TargetProvider. + * + * When using a TargetProvider disconnected from a + * [BuildBus]{@link https://pwastudio.io/pwa-buildpack/reference/buildbus/}, + * this callback is necessary if anything requests external + * targets on the TargetProvider using `TargetProvider.of()`. + * * @callback getExternalTargets * @param {TargetProvider} requestor - TargetProvider making the request. * @param {string} requested - External targets being requested. diff --git a/packages/pwa-buildpack/lib/BuildBus/declare-base.js b/packages/pwa-buildpack/lib/BuildBus/declare-base.js index 8c2540e7bb..92f6f04f53 100644 --- a/packages/pwa-buildpack/lib/BuildBus/declare-base.js +++ b/packages/pwa-buildpack/lib/BuildBus/declare-base.js @@ -22,12 +22,12 @@ module.exports = targets => { * values based on the `envVarDefinitions.json` file. * * The environment variable schema object from this file is extensible - * using an [envVarDefinitions intercept function]{@link envVarIntercept}. + * using an [envVarDefinitions intercept function]{@link envVarDefinitionsIntercept}. * * Intercept this target in your project to integrate your extension configuration * with the project-wide environment variable system. * - * @see [envVarDefinitions intercept function]{@link envVarIntercept} + * @see [envVarDefinitions intercept function]{@link envVarDefinitionsIntercept} * * @member {tapable.SyncHook} * diff --git a/packages/pwa-buildpack/lib/WebpackTools/ModuleTransformConfig.js b/packages/pwa-buildpack/lib/WebpackTools/ModuleTransformConfig.js index dc0041b4bc..a63fae7f8e 100644 --- a/packages/pwa-buildpack/lib/WebpackTools/ModuleTransformConfig.js +++ b/packages/pwa-buildpack/lib/WebpackTools/ModuleTransformConfig.js @@ -8,7 +8,7 @@ const path = require('path'); * Instruction to the Webpack transform loader to pass a given file through a * transform function implemented in a given Node module, with an optional set * of configuration values that will be passed to the transform function. - * + * * @prop {string} type - Type of transform. `'babel'` expects a Babel plugin as the `transformModule`. `"source"` expects a Webpack loader. * @prop {string} requestor - Name of the file doing the requesting. * @prop {string} fileToTransform - Relative path to the file in this module @@ -28,12 +28,14 @@ const path = require('path'); /** * Configuration builder for module transforms. Accepts TransformRequests * and emits loader config objects for Buildpack's custom transform loaders. - * - * @param {MagentoResolver} resolver - Resolver to use when finding real paths of - * modules requested. - * @param {string} localProjectName - The name of the PWA project being built, taken from the package.json `name` field. */ class ModuleTransformConfig { + /** + * @constructs + * @param {MagentoResolver} resolver - Resolver to use when finding real paths of + * modules requested. + * @param {string} localProjectName - The name of the PWA project being built, taken from the package.json `name` field. + */ constructor(resolver, localProjectName) { this._resolver = resolver; this._localProjectName = localProjectName; @@ -75,7 +77,7 @@ class ModuleTransformConfig { /** * * Add a request to transform a file in the build. - * + * * @param {TransformRequest} req - Request object */ add({ requestor, fileToTransform, transformModule, type, options }) { @@ -114,7 +116,7 @@ class ModuleTransformConfig { } /** * Resolve paths and emit as JSON. - * + * * @returns {object} Configuration object */ async toLoaderOptions() { diff --git a/pwa-devdocs/src/pwa-buildpack/reference/buildbus/index.md b/pwa-devdocs/src/pwa-buildpack/reference/buildbus/index.md index 0b0d698589..61cbff263a 100644 --- a/pwa-devdocs/src/pwa-buildpack/reference/buildbus/index.md +++ b/pwa-devdocs/src/pwa-buildpack/reference/buildbus/index.md @@ -2,6 +2,9 @@ title: BuildBus --- +{: .bs-callout .bs-callout-info} +This API is currently only available in the `develop` branch of the PWA Studio project. + - {% include auto-generated/pwa-buildpack/lib/BuildBus/declare-base.md %} diff --git a/pwa-devdocs/src/pwa-buildpack/reference/moduletransformconfig/index.md b/pwa-devdocs/src/pwa-buildpack/reference/moduletransformconfig/index.md index 8922eeb1c6..2a383af50f 100644 --- a/pwa-devdocs/src/pwa-buildpack/reference/moduletransformconfig/index.md +++ b/pwa-devdocs/src/pwa-buildpack/reference/moduletransformconfig/index.md @@ -2,6 +2,9 @@ title: ModuleTransformConfig --- +{: .bs-callout .bs-callout-info} +This API is currently only available in the `develop` branch of the PWA Studio project. + + +{% include auto-generated/buildpack/reference/envVarDefinitions.md %} diff --git a/pwa-devdocs/src/pwa-buildpack/reference/environment-variables/definitions-api/index.md b/pwa-devdocs/src/pwa-buildpack/reference/environment-variables/definitions-api/index.md new file mode 100644 index 0000000000..c0a2bda81a --- /dev/null +++ b/pwa-devdocs/src/pwa-buildpack/reference/environment-variables/definitions-api/index.md @@ -0,0 +1,10 @@ +--- +title: Environment variable definition API +--- + + + +{% include auto-generated/pwa-buildpack/lib/Utilities/getEnvVarDefinitions.md %} diff --git a/pwa-devdocs/src/pwa-buildpack/reference/environment-variables/index.md b/pwa-devdocs/src/pwa-buildpack/reference/environment-variables/index.md index 73984fdf06..ce18f0e754 100644 --- a/pwa-devdocs/src/pwa-buildpack/reference/environment-variables/index.md +++ b/pwa-devdocs/src/pwa-buildpack/reference/environment-variables/index.md @@ -1,11 +1,11 @@ --- -title: Environment variables +title: Environment variable definitions --- - +Environment variable definitions are used for validation and documentation of the [configuration management system](/pwa-buildpack/configuration-management/) of PWA Studio. -{% include auto-generated/buildpack/reference/envVarDefinitions.md %} +Build scripts normally use the [values set in the current environment]({%link pwa-buildpack/reference/buildpack-cli/load-env/index.md %}#loadenvironmentdirorenv-logge), but it's sometimes necessary to use the definitions themselves, such as when an extension defines its own global config variables. +There are two ways to access the environment variable definitions object. Third-party code should use the builtin target [`envVarDefinitions`]({%link pwa-buildpack/reference/buildbus/targets/index.md %}#module_BuiltinTargets.envVarDefinitions) when adding definitions. + +Core Buildpack code uses [`getEnvVarDefinitions(context)`](./reference), which builds environment variable definitions for the project by starting with [core variables](./core) and then calling the `envVarDefinitions` target so that installed extensions can add their own. diff --git a/pwa-devdocs/src/tutorials/pwa-studio-fundamentals/production-launch-checklist/index.md b/pwa-devdocs/src/tutorials/pwa-studio-fundamentals/production-launch-checklist/index.md index 43b8f87221..6105432ed7 100644 --- a/pwa-devdocs/src/tutorials/pwa-studio-fundamentals/production-launch-checklist/index.md +++ b/pwa-devdocs/src/tutorials/pwa-studio-fundamentals/production-launch-checklist/index.md @@ -58,8 +58,8 @@ Lighthouse is available through Chrome's DevTools, as a command line script, as See the [Lighthouse][] page for detailed instructions on how to use each form of the tool. [magento cloud deployment]: <{%link tutorials/cloud-deploy/index.md %}> -[environment variables]: <{%link pwa-buildpack/reference/environment-variables/index.md %}> -[`magento_backend_url`]: <{%link pwa-buildpack/reference/environment-variables/index.md %}#magento_backend_url> -[`checkout_braintree_token`]: <{%link pwa-buildpack/reference/environment-variables/index.md %}#checkout_braintree_token> +[environment variables]: <{%link pwa-buildpack/reference/environment-variables/core-definitions/index.md %}> +[`magento_backend_url`]: <{%link pwa-buildpack/reference/environment-variables/core-definitions/index.md %}#magento_backend_url> +[`checkout_braintree_token`]: <{%link pwa-buildpack/reference/environment-variables/core-definitions/index.md %}#checkout_braintree_token> [lighthouse]: https://developers.google.com/web/tools/lighthouse/ From 66388a1a1750acde9cbb88fd29e7c8b46b8027dd Mon Sep 17 00:00:00 2001 From: James Calcaben Date: Fri, 24 Jul 2020 13:35:38 -0500 Subject: [PATCH 16/22] Make changes based on feedback and removed 'in develop' notice --- .../lib/BuildBus/declare-base.js | 5 +++- pwa-devdocs/src/_data/buildpack-api.yml | 28 +++++++++++-------- .../pwa-buildpack/reference/buildbus/index.md | 3 -- .../buildbus/maphookstotargets/index.md | 13 --------- .../reference/buildbus/target/index.md | 3 -- .../buildbus/targetprovider/index.md | 3 -- .../reference/buildbus/targets/index.md | 3 -- .../reference/moduletransformconfig/index.md | 3 -- 8 files changed, 21 insertions(+), 40 deletions(-) delete mode 100644 pwa-devdocs/src/pwa-buildpack/reference/buildbus/maphookstotargets/index.md diff --git a/packages/pwa-buildpack/lib/BuildBus/declare-base.js b/packages/pwa-buildpack/lib/BuildBus/declare-base.js index fbbca3d3fc..2246f0778f 100644 --- a/packages/pwa-buildpack/lib/BuildBus/declare-base.js +++ b/packages/pwa-buildpack/lib/BuildBus/declare-base.js @@ -27,6 +27,9 @@ module.exports = targets => { * Intercept this target in your project to integrate your extension configuration * with the project-wide environment variable system. * + * + * @see [envVarDefinitions topic]{@link http://pwastudio.io/pwa-buildpack/reference/environment-variables/} + * * @member {tapable.SyncHook} * * @example Add config fields for your extension @@ -185,7 +188,7 @@ module.exports = targets => { * Interceptors of `envVarDefinitions` may mutate the definitions object. * These functions do not need to return a value. * - * @see [EnvVarDefinitions]{@link /pwa-buildpack/reference/environment-variables/definitions-api/#envvardefinitions--object} + * @see [EnvVarDefinitions]{@link http://pwastudio.io/pwa-buildpack/reference/environment-variables/definitions-api/#envvardefinitions--object} * * @callback envVarDefinitionsIntercept * @param {EnvVarDefinitions} defs - The definitions object diff --git a/pwa-devdocs/src/_data/buildpack-api.yml b/pwa-devdocs/src/_data/buildpack-api.yml index b859e26280..4adc826f44 100644 --- a/pwa-devdocs/src/_data/buildpack-api.yml +++ b/pwa-devdocs/src/_data/buildpack-api.yml @@ -1,14 +1,23 @@ title: PWA Buildpack API entries: - - label: BuildBus - url: /pwa-buildpack/reference/buildbus/ + - label: Extensibility entries: - - label: Extensibility Targets - url: /pwa-buildpack/reference/buildbus/targets/ - - label: Target - url: /pwa-buildpack/reference/buildbus/target/ - - label: TargetProvider - url: /pwa-buildpack/reference/buildbus/targetprovider/ + - label: BuildBus + url: /pwa-buildpack/reference/buildbus/ + entries: + + - label: BuildBus Targets + url: /pwa-buildpack/reference/buildbus/targets/ + + - label: ModuleTransformConfig + url: /pwa-buildpack/reference/moduletransformconfig/ + + - label: Target + url: /pwa-buildpack/reference/buildbus/target/ + + - label: TargetProvider + url: /pwa-buildpack/reference/buildbus/targetprovider/ + - label: Buildpack CLI url: /pwa-buildpack/reference/buildpack-cli/ @@ -40,9 +49,6 @@ entries: - label: MagentoResolver url: /pwa-buildpack/reference/magento-resolver/ - - label: ModuleTransformConfig - url: /pwa-buildpack/reference/moduletransformconfig/ - - label: MagentoRootComponentsPlugin url: /pwa-buildpack/reference/root-components-plugin/ diff --git a/pwa-devdocs/src/pwa-buildpack/reference/buildbus/index.md b/pwa-devdocs/src/pwa-buildpack/reference/buildbus/index.md index 61cbff263a..0b0d698589 100644 --- a/pwa-devdocs/src/pwa-buildpack/reference/buildbus/index.md +++ b/pwa-devdocs/src/pwa-buildpack/reference/buildbus/index.md @@ -2,9 +2,6 @@ title: BuildBus --- -{: .bs-callout .bs-callout-info} -This API is currently only available in the `develop` branch of the PWA Studio project. - - -{% include auto-generated/pwa-buildpack/lib/BuildBus/mapHooksToTargets.md %} diff --git a/pwa-devdocs/src/pwa-buildpack/reference/buildbus/target/index.md b/pwa-devdocs/src/pwa-buildpack/reference/buildbus/target/index.md index 591a98b9a1..ae781f66ac 100644 --- a/pwa-devdocs/src/pwa-buildpack/reference/buildbus/target/index.md +++ b/pwa-devdocs/src/pwa-buildpack/reference/buildbus/target/index.md @@ -2,9 +2,6 @@ title: Target --- -{: .bs-callout .bs-callout-info} -This API is currently only available in the `develop` branch of the PWA Studio project. - - -{% include auto-generated/pwa-buildpack/lib/BuildBus/declare-base.md %} diff --git a/pwa-devdocs/src/pwa-buildpack/reference/environment-variables/core-definitions/index.md b/pwa-devdocs/src/pwa-buildpack/reference/environment-variables/core-definitions/index.md index 9718f3bb69..47d1add86d 100644 --- a/pwa-devdocs/src/pwa-buildpack/reference/environment-variables/core-definitions/index.md +++ b/pwa-devdocs/src/pwa-buildpack/reference/environment-variables/core-definitions/index.md @@ -2,7 +2,15 @@ title: Core environment variable definitions --- -Environment variables defined by PWA Studio core code. Extensions may define their own variables as well. +Environment variable definitions are used for validation and documentation of the [configuration management system][] of PWA Studio. + +Build scripts normally use the [values set in the current environment][], but it is sometimes necessary to use the definitions themselves, such as when an extension defines its own global config variables. + +There are two ways to access the environment variable definitions object: + +- Third-party code should use the builtin target [`envVarDefinitions`][] when adding definitions. +- Core Buildpack code uses [`getEnvVarDefinitions()`][], which builds environment variable definitions for the project. + It starts with core variables listed below and then calls the `envVarDefinitions` target so installed extensions can add their own variables. {% include auto-generated/buildpack/reference/envVarDefinitions.md %} + +[configuration management system]: {%link pwa-buildpack/configuration-management/index.md %} +[`envvardefinitions`]: {%link pwa-buildpack/reference/targets/index.md %}#module_BuiltinTargets.envVarDefinitions +[core variables]: {%link pwa-buildpack/reference/environment-variables/core-definitions/index.md %} +[values set in the current environment]: {%link pwa-buildpack/reference/buildpack-cli/load-env/index.md %}#loadenvironmentdirorenv-logge + +[`getenvvardefinitions()`]: https://github.com/magento/pwa-studio/blob/develop/packages/pwa-buildpack/lib/Utilities/getEnvVarDefinitions.js diff --git a/pwa-devdocs/src/pwa-buildpack/reference/environment-variables/index.md b/pwa-devdocs/src/pwa-buildpack/reference/environment-variables/index.md deleted file mode 100644 index cd0789d657..0000000000 --- a/pwa-devdocs/src/pwa-buildpack/reference/environment-variables/index.md +++ /dev/null @@ -1,20 +0,0 @@ ---- -title: Environment variable definitions ---- - -Environment variable definitions are used for validation and documentation of the [configuration management system][] of PWA Studio. - -Build scripts normally use the [values set in the current environment][], but it is sometimes necessary to use the definitions themselves, such as when an extension defines its own global config variables. - -There are two ways to access the environment variable definitions object: - -- Third-party code should use the builtin target [`envVarDefinitions`][] when adding definitions. -- Core Buildpack code uses [`getEnvVarDefinitions()`][], which builds environment variable definitions for the project. - It starts with [core variables][] and then calls the `envVarDefinitions` target so installed extensions can add their own variables. - -[configuration management system]: {%link pwa-buildpack/configuration-management/index.md %} -[`envvardefinitions`]: {%link pwa-buildpack/reference/buildbus/targets/index.md %}#module_BuiltinTargets.envVarDefinitions -[core variables]: {%link pwa-buildpack/reference/environment-variables/core-definitions/index.md %} -[values set in the current environment]: {%link pwa-buildpack/reference/buildpack-cli/load-env/index.md %}#loadenvironmentdirorenv-logge - -[`getenvvardefinitions()`]: https://github.com/magento/pwa-studio/blob/develop/packages/pwa-buildpack/lib/Utilities/getEnvVarDefinitions.js \ No newline at end of file diff --git a/pwa-devdocs/src/pwa-buildpack/reference/buildbus/index.md b/pwa-devdocs/src/pwa-buildpack/reference/extension-framework/index.md similarity index 100% rename from pwa-devdocs/src/pwa-buildpack/reference/buildbus/index.md rename to pwa-devdocs/src/pwa-buildpack/reference/extension-framework/index.md diff --git a/pwa-devdocs/src/pwa-buildpack/reference/buildbus/target/index.md b/pwa-devdocs/src/pwa-buildpack/reference/extension-framework/target/index.md similarity index 100% rename from pwa-devdocs/src/pwa-buildpack/reference/buildbus/target/index.md rename to pwa-devdocs/src/pwa-buildpack/reference/extension-framework/target/index.md diff --git a/pwa-devdocs/src/pwa-buildpack/reference/buildbus/targetprovider/index.md b/pwa-devdocs/src/pwa-buildpack/reference/extension-framework/targetprovider/index.md similarity index 100% rename from pwa-devdocs/src/pwa-buildpack/reference/buildbus/targetprovider/index.md rename to pwa-devdocs/src/pwa-buildpack/reference/extension-framework/targetprovider/index.md diff --git a/pwa-devdocs/src/pwa-buildpack/reference/magento-resolver/index.md b/pwa-devdocs/src/pwa-buildpack/reference/magento-resolver/index.md index 13e01e0880..1fd62b8e0d 100644 --- a/pwa-devdocs/src/pwa-buildpack/reference/magento-resolver/index.md +++ b/pwa-devdocs/src/pwa-buildpack/reference/magento-resolver/index.md @@ -15,7 +15,7 @@ Currently, MagentoResolver does very little, but it's likely that the Magento de **Parameters:** -* `options:`[`LocalProjectLocation`] - Configuration object that describes where the PWA storefront folders are located. +* `options:` - Configuration object that describes where the PWA storefront folders are located. Must have a `root` property set to the context (root directory) of the project. **Return:** @@ -63,4 +63,3 @@ The example provided uses the newer, cleaner `async/await` syntax instead of usi [`resolve`]: https://webpack.js.org/configuration/resolve/ [Promise]: https://webpack.js.org/configuration/configuration-types/#exporting-a-promise -[`LocalProjectLocation`]: {%link pwa-buildpack/reference/object-types/index.md %}#localprojectlocation \ No newline at end of file diff --git a/pwa-devdocs/src/pwa-buildpack/reference/object-types/index.md b/pwa-devdocs/src/pwa-buildpack/reference/object-types/index.md deleted file mode 100644 index 5201660c54..0000000000 --- a/pwa-devdocs/src/pwa-buildpack/reference/object-types/index.md +++ /dev/null @@ -1,17 +0,0 @@ ---- -title: Object types ---- - -This is a list of common object types shared between the PWA-Buildpack modules. - -## `LocalProjectLocation` - -| Property: Type | Description | -| ---------------- | ---------------------------------------------------------------------------- | -| `root: string` | The absolute path of the project's root directory on the working filesystem. | -| `output: string` | The directory where webpack should output any built assets. | -{:style="table-layout:auto"} - -### Output location - -If the value for `LocalProjectLocation.output` is relative, the location is resolved from `root`. \ No newline at end of file diff --git a/pwa-devdocs/src/pwa-buildpack/reference/pwa-dev-server/index.md b/pwa-devdocs/src/pwa-buildpack/reference/pwa-dev-server/index.md index 311422135c..44c81717e1 100644 --- a/pwa-devdocs/src/pwa-buildpack/reference/pwa-dev-server/index.md +++ b/pwa-devdocs/src/pwa-buildpack/reference/pwa-dev-server/index.md @@ -80,4 +80,3 @@ Browse to the `/graphiql` path on your PWADevServer to use this feature. [`exactDomain: string`]: #exactdomain [GraphQL Playground feature]: #graphql-playground-feature [GraphQL Playground]: https://github.com/prisma/graphql-playground -[`LocalProjectLocation`]: {%link pwa-buildpack/reference/object-types/index.md %}#localprojectlocation diff --git a/pwa-devdocs/src/pwa-buildpack/reference/serviceworker-plugin/index.md b/pwa-devdocs/src/pwa-buildpack/reference/serviceworker-plugin/index.md index 053cf8c8d2..ab4986a6a7 100644 --- a/pwa-devdocs/src/pwa-buildpack/reference/serviceworker-plugin/index.md +++ b/pwa-devdocs/src/pwa-buildpack/reference/serviceworker-plugin/index.md @@ -27,7 +27,7 @@ The `PluginOptions` object contains the following properties: | Property: Type | Description | | --------------------------------------- | ---------------------------------------------------------------------------------- | | `env:`[`EnvironmentObject`] | **Required.** An object that represents the current environment. | -| `paths:`[`LocalProjectLocation`] | **Required.** Configuration object that describes where public assets are located. | +| `paths: object` | **Required.** Map of important project locations. Must at least contain a `root` property set to the context (root directory) of the project. | | `enableServiceWorkerDebugging: boolean` | Toggles [service worker debugging]. | | `serviceWorkerFilename: string` | **Required.** The name of the ServiceWorker file this project creates. | | `runtimeCacheAssetPath: string` | A remote URL or root path to assets the ServiceWorker should cache during runtime. | @@ -84,6 +84,5 @@ When this value is set to `false`, the ServiceWorker is disabled to prevent cach [Google Workbox Webpack Plugin]: https://developers.google.com/web/tools/workbox/guides/generate-service-worker/ -[`LocalProjectLocation`]: {%link pwa-buildpack/reference/object-types/index.md %}#localprojectlocation [`EnvironmentObject`]: #environmentobject -[service worker debugging]: #service-worker-debugging \ No newline at end of file +[service worker debugging]: #service-worker-debugging diff --git a/pwa-devdocs/src/pwa-buildpack/reference/targets/index.md b/pwa-devdocs/src/pwa-buildpack/reference/targets/index.md new file mode 100644 index 0000000000..f52d2f1557 --- /dev/null +++ b/pwa-devdocs/src/pwa-buildpack/reference/targets/index.md @@ -0,0 +1,22 @@ +--- +title: Extensibility Targets +--- + +Buildpack's targets follow the same Target API as other packages' targets, but they play a unique role. Buildpack targets are the fundamental "roots" of the PWA Studio Target system. + +All other Targets operate by intercepting other Targets. +Targets can only be called when Buildpack core code creates a BuildBus, which it does for every build and for many commands. +Extensions will then run their declare and intercept files, attaching interceptor functions to each others' dependencies. +Still, nothing _calls_ targets to run any interceptors until Buildpack begins the process, by directly invoking one of its _own_ targets. + +The Buildpack targets are therefore very generic and low-level. They are meant to be used as building blocks for higher-level targets which provide a convenient API for some common business purpose, such as adding routing or navigation logic. + +Even deeper than Buildpack targets are the very similar Hooks that make up [Webpack's plugin system](https://v4.webpack.js.org/api/plugins/). Interceptors can use Buildpack's `webpackCompiler` target to acquire a reference to the Webpack Compiler object for each build, and can then do anything a Webpack plugin can do. +Because of their similarity in form and function, the PWA Studio Targets system integrates seamlessly into the larger Webpack ecosystem as a commerce-driven superset of its functionality. + + + +{% include auto-generated/pwa-buildpack/lib/BuildBus/declare-base.md %} diff --git a/pwa-devdocs/src/tutorials/pwa-studio-fundamentals/project-setup/index.md b/pwa-devdocs/src/tutorials/pwa-studio-fundamentals/project-setup/index.md index 4abbd75b94..131fe07dfe 100644 --- a/pwa-devdocs/src/tutorials/pwa-studio-fundamentals/project-setup/index.md +++ b/pwa-devdocs/src/tutorials/pwa-studio-fundamentals/project-setup/index.md @@ -134,7 +134,7 @@ If you encounter any other issues, ask the Magento community in the [#PWA][] Sla [venia concept storefront]: {%link venia-pwa-concept/index.md %} [`create-custom-origin`]: {%link pwa-buildpack/reference/buildpack-cli/create-custom-origin/index.md %} [buildpack cli]: {%link pwa-buildpack/reference/buildpack-cli/index.md %} -[environment variables]: {%link pwa-buildpack/reference/environment-variables/index.md %} +[environment variables]: {%link pwa-buildpack/reference/environment-variables/core-definitions/index.md %} [pwa buildpack troubleshooting]: {%link pwa-buildpack/troubleshooting/index.md %}#untrusted-ssl-cert [interactive questionnaire screen-shot]: {%link tutorials/pwa-studio-fundamentals/project-setup/images/interactive-questionnaire.png %} [prerequisites screen-shot]: {%link tutorials/pwa-studio-fundamentals/project-setup/images/prerequisites.png %} From 9cf20febcfc050d9d2390ec6b96fa2e6aaffdfa0 Mon Sep 17 00:00:00 2001 From: James Calcaben Date: Mon, 27 Jul 2020 12:11:51 -0500 Subject: [PATCH 19/22] Fix links in doc blocks --- .../lib/Utilities/getEnvVarDefinitions.js | 21 ++++++++++++------- 1 file changed, 14 insertions(+), 7 deletions(-) diff --git a/packages/pwa-buildpack/lib/Utilities/getEnvVarDefinitions.js b/packages/pwa-buildpack/lib/Utilities/getEnvVarDefinitions.js index 365434949e..9b7d985185 100644 --- a/packages/pwa-buildpack/lib/Utilities/getEnvVarDefinitions.js +++ b/packages/pwa-buildpack/lib/Utilities/getEnvVarDefinitions.js @@ -5,7 +5,9 @@ const debug = require('debug')('pwa-buildpack:getEnvVarDefinitions'); /** * Get the list of environment definitions. - * Calling this function will invoke the [`envVarDefinitions`](/pwa-buildpack/reference/buildbus/targets/#module_BuiltinTargets.envVarDefinitions) target, passing the list of [built-in environment variables](/pwa-buildpack/reference/environment-variables/core-definitions/) to all interceptors. + * Calling this function will invoke the [`envVarDefinitions`]{@link http://pwastudio.io/pwa-buildpack/reference/buildbus/targets/#module_BuiltinTargets.envVarDefinitions} + * target, passing the list of [built-in environment variables]{@link http://pwastudio.io/pwa-buildpack/reference/environment-variables/core-definitions/} + * to all interceptors. * Any installed dependencies that intercept this target may add to or modify the list of environment variables. * * @public @@ -48,9 +50,11 @@ module.exports = getEnvVarDefinitions; * Defines the global settings of the project as a list of typed environment variables. * Includes a set of changes made to the environment variables in recent versions, to aid with migration and upgrades. * - * `EnvVarDefinitions` are used by [`loadEnvironment()`](/pwa-buildpack/reference/buildpack-cli/load-env/#loadenvironmentdirorenv-logger) to validate the currently defined values in the environment. + * `EnvVarDefinitions` are used by [`loadEnvironment()`]{@link http://pwastudio.io/pwa-buildpack/reference/buildpack-cli/load-env/#loadenvironmentdirorenv-logger} + * to validate the currently defined values in the environment. * - * `EnvVarDefinitions` are also used by [`createDotEnvFile()`](/pwa-buildpack/reference/buildpack-cli/create-env-file/#createdotenvfiledirectory-options) to generate an extensively commented `.env` file for a project. + * `EnvVarDefinitions` are also used by [`createDotEnvFile()`]{@link http://pwastudio.io/pwa-buildpack/reference/buildpack-cli/create-env-file/#createdotenvfiledirectory-options} + * to generate an extensively commented `.env` file for a project. * * @typedef {Object} EnvVarDefinitions * @property {EnvVarDefsSection[]} sections List of sections, or sub-lists of definitions grouped under a title. @@ -71,17 +75,20 @@ module.exports = getEnvVarDefinitions; /** * A definition of an environment variable that will be used somewhere else in the project, in the backend and/or the frontend. * - * Must define a name, type and description. Optionally, may define a `default` which is set implicitly, an `example` for documentation, and/or an array of `choices` to limit the valid values. + * Must define a name, type and description. Optionally, may define a `default` which is set implicitly, an `example` for documentation, + * and/or an array of `choices` to limit the valid values. * - * The recommended way to access the current environment values in build scripts and interceptors is through the [Configuration](/pwa-buildpack/reference/buildpack-cli/load-env/#configuration-object) object returned by [`loadEnvironment()`](/pwa-buildpack/reference/buildpack-cli/load-env/#loadenvironmentdirorenv-logger). + * The recommended way to access the current environment values in build scripts and interceptors is through the + * [Configuration]{@link http://pwastudio.io/pwa-buildpack/reference/buildpack-cli/load-env/#configuration-object} + * object returned by [`loadEnvironment()`]{@link http://pwastudio.io/pwa-buildpack/reference/buildpack-cli/load-env/#loadenvironmentdirorenv-logger}. * * **Note:** Any build environment will have hundreds of environment variables _set_, most of which are unrelated to the build process. * Any environment variable during the build is accessible via `process.env` in NodeJS. - * However, only the variables defined by `EnvVarDefinition` entries will be available in the frontend, via the [Webpack EnvironmentPlugin](https://webpack.js.org/plugins/environment-plugin/). + * However, only the variables defined by `EnvVarDefinition` entries will be available in the frontend, via the [Webpack EnvironmentPlugin]{@link https://webpack.js.org/plugins/environment-plugin/}. * * @typedef {Object} EnvVarDefinition * @property {String} name Name of the environment variable. Must be in SCREAMING_SNAKE_CASE and contain only alphanumeric characters. - * @property {String} type Type of the environment variable. Can be any type supported by the [envalid](https://www.npmjs.com/package/envalid#validator-types) library. + * @property {String} type Type of the environment variable. Can be any type supported by the [envalid]{@link https://www.npmjs.com/package/envalid#validator-types} library. * @property {String} desc Human-readable description of what the environment variable does. * @property {Array} [choices] An array of acceptable answers. All values in the array must be of the type specified in `type`. * @property {String} default Default value if the variable is not set in the environment. From 704948941631c67c40f5d040afd19959abd8c532 Mon Sep 17 00:00:00 2001 From: James Zetlen Date: Mon, 27 Jul 2020 16:06:03 -0500 Subject: [PATCH 20/22] doc: fix typo in Target docblock --- packages/pwa-buildpack/lib/BuildBus/Target.js | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/pwa-buildpack/lib/BuildBus/Target.js b/packages/pwa-buildpack/lib/BuildBus/Target.js index 1a939954cf..3211816c55 100644 --- a/packages/pwa-buildpack/lib/BuildBus/Target.js +++ b/packages/pwa-buildpack/lib/BuildBus/Target.js @@ -151,7 +151,7 @@ class Target extends Trackable { return this._invokeTap('tap', name, interceptor); } /** - * Adds an callback-style asynchronous interceptor to the Target. The interceptor will receive a callback function as its last argument. Only supported on Async targets. + * Adds a callback-style asynchronous interceptor to the Target. The interceptor will receive a callback function as its last argument. Only supported on Async targets. * * @param {string|object} name string or object containing the name of the interceptor * @param {function} interceptor interceptor function From c649817ff908bbd526c79a1290ef219463d60765 Mon Sep 17 00:00:00 2001 From: James Zetlen Date: Mon, 3 Aug 2020 12:39:00 -0500 Subject: [PATCH 21/22] docs: revise buildpack devdocs (#2598) --- .../lib/BuildBus/declare-base.js | 92 +++++++++---------- .../lib/WebpackTools/ModuleTransformConfig.js | 79 +++++++++++----- pwa-devdocs/src/_data/buildpack-api.yml | 4 +- .../reference/moduletransformconfig/index.md | 10 -- .../pwa-buildpack/reference/targets/index.md | 9 +- .../reference/transform-requests/index.md | 18 ++++ 6 files changed, 127 insertions(+), 85 deletions(-) delete mode 100644 pwa-devdocs/src/pwa-buildpack/reference/moduletransformconfig/index.md create mode 100644 pwa-devdocs/src/pwa-buildpack/reference/transform-requests/index.md diff --git a/packages/pwa-buildpack/lib/BuildBus/declare-base.js b/packages/pwa-buildpack/lib/BuildBus/declare-base.js index cc9b2e672a..8d9f986544 100644 --- a/packages/pwa-buildpack/lib/BuildBus/declare-base.js +++ b/packages/pwa-buildpack/lib/BuildBus/declare-base.js @@ -15,23 +15,24 @@ const { SOURCE_SEP } = require('./Target'); module.exports = targets => { /** * @exports BuiltinTargets + * */ const builtins = { /** - * Collects the definitions and documentation for project-wide configuration - * values based on the `envVarDefinitions.json` file. + * Called to collect the definitions and documentation for project-wide + * configuration values. Core environment variables are defined in the + * [`envVarDefinitions.json` file]{@link /pwa-buildpack/reference/environment-variables/core-definitions/}. * - * The environment variable schema object from this file is extensible - * using an [envVarDefinitions intercept function]{@link envVarDefinitionsIntercept}. + * Intercept this target in your project to add new environment + * variables, typed and documented. This integrates your extension + * configuration with the project-wide environment variable system. * - * Intercept this target in your project to integrate your extension configuration - * with the project-wide environment variable system. + * @see [Variable definition schema]{@link /pwa-buildpack/reference/environment-variables/definitions-api/} + * @see [Core variable definitions]{@link /pwa-buildpack/reference/environment-variables/core-definitions/} * - * - * @see [envVarDefinitions topic]{@link http://pwastudio.io/pwa-buildpack/reference/environment-variables/} - * + * @param {object} envVarDefinitions The [variable definitions object]{@link /pwa-buildpack/reference/environment-variables/definitions-api/}. + * Modify in place. * @member {tapable.SyncHook} - * * @example Add config fields for your extension * targets.of('@magento/pwa-buildpack').envVarDefinitions.tap(defs => { * defs.sections.push({ @@ -50,15 +51,16 @@ module.exports = targets => { envVarDefinitions: new targets.types.Sync(['definitions']), /** - * Collects requests to intercept and modify individual files from this - * dependency. + * Called when configuring the loading and processing rules for Webpack. * - * Since the storefront developer is in charge of important dependencies, + * Interceptors receive a function `addTransform()`. They may call this function to request that Webpack process _a particular file_ with a particular transform module. + * + * Since the storefront developer is in charge of important dependencies, * the interceptor files in the storefront project itself should be able to * transform ANY file from ANY dependency. * However, interceptor files in the storefront dependencies are prevented * from modifying files from other dependencies. - * + * * NOTE: This is a very low-level extension point. It should be used as a * building block for higher-level extensions that expose functional * areas rather than files on disk. @@ -81,7 +83,7 @@ module.exports = targets => { * * Calls interceptors whenever a Webpack Compiler object is created. * This almost always happens once per build, even in dev mode. - * + * * Use an [intercept function]{@link webpackCompilerIntercept} on this target * to access the [webpack compiler]{@link https://webpack.js.org/api/compiler-hooks/}. * @@ -106,13 +108,13 @@ module.exports = targets => { * the modules by default. It will expect extension code to be CommonJS * style and will not process the ES Modules. * Likewise, if your extension uses CSS Modules, you must add the `cssModules` flag using this target. - * Use a [specialFeatures intercept function]{@link specialFeaturesIntercept} + * Use a [specialFeatures intercept function]{@link specialFeaturesIntercept} * to add special build features for the modules used in your project. * * @see [Special flags in `configureWebpack()`]{@link http://pwastudio.io/pwa-buildpack/reference/configure-webpack/#special-flags} * * @member {tapable.SyncHook} - * + * * @example Declare that your extension contains CSS modules. * targets.of('@magento/pwa-buildpack').specialFeatures.tap(featuresByModule => { * featuresByModule['my-module'] = { cssModules: true }; @@ -120,12 +122,6 @@ module.exports = targets => { */ specialFeatures: new targets.types.Sync(['special']), - /** - * @callback transformUpwardIntercept - * @param {object} Parsed UPWARD definition object. - * @returns {Promise} - Interceptors do not need to return. - */ - /** * Exposes the fully merged UPWARD definition for fine tuning. The * UpwardIncludePlugin does a simple shallow merge of the upward.yml @@ -154,9 +150,8 @@ module.exports = targets => { * }) * * - * @type {tapable.AsyncSeriesHook} + * @member {tapable.AsyncSeriesHook} * @param {transformUpwardIntercept} interceptor - * @memberof BuiltinTargets */ transformUpward: new targets.types.AsyncSeries(['definitions']) }; @@ -220,20 +215,6 @@ module.exports = targets => { targets.declare(builtins); }; -/** Type definitions related to: envVarDefinitions */ - -/** - * Passed as the first parameter to interceptors of the `envVarDefinitions` object. - * - * Interceptors of `envVarDefinitions` may mutate the definitions object. - * These functions do not need to return a value. - * - * @see [EnvVarDefinitions]{@link http://pwastudio.io/pwa-buildpack/reference/environment-variables/definitions-api/#envvardefinitions--object} - * - * @callback envVarDefinitionsIntercept - * @param {EnvVarDefinitions} defs - The definitions object - */ - /** Type definitions related to: transformModules */ /** @@ -249,12 +230,12 @@ module.exports = targets => { /** * Callback to add a transform. - * - * @see [TransformRequest]{@link https://pwastudio.io/pwa-buildpack/reference/moduletransformconfig/#buildpackwebpacktoolstransformrequest--object} - * + * + * @see [TransformRequest]{@link https://pwastudio.io/pwa-buildpack/reference/transform-requests/#addTransform} + * * @callback addTransform * @param {Buildpack/WebpackTools~TransformRequest} transformRequest - - * [Request]{@link https://pwastudio.io/pwa-buildpack/reference/moduletransformconfig/#buildpackwebpacktoolstransformrequest--object} + * [Request]{@link https://pwastudio.io/pwa-buildpack/reference/transform-requests/#addTransform} * to apply a transform to a file provided by this dependency. */ @@ -262,10 +243,10 @@ module.exports = targets => { /** * Intercept function signature for the webpackCompiler target. - * + * * Interceptors of `webpackCompiler` should tap hooks on the provided * `compiler` object. Any returned value will be ignored. - * + * * @callback webpackCompilerIntercept * @param {webpack.Compiler} compiler - The [webpack compiler]{@link https://webpack.js.org/api/compiler-hooks/} instance */ @@ -274,7 +255,7 @@ module.exports = targets => { /** * Intercept function signature for the specialFeatures target. - * + * * Interceptors of the `specialFeatures` target can use the mapping object provided * to map special build flags to their project modules. * @@ -282,3 +263,22 @@ module.exports = targets => { * @param {Object.} featuresByModule - * An object mapping of module names to their special build flags */ + +/** Type definitions related to: transformUpward */ + +/** + * Intercept function signature for the transformUpward target. + * + * Interceptors of the `transformUpward` target receive the parsed UPWARD + * definition as a plain JavaScript object. Mutate that object in place to + * change the final `upward.yml` output by the build. + * + * This Target can be used asynchronously. If you need to do asynchronous work + * to get what you need to modify the UPWARD definition (for example, a network + * request) then you can provide an `async` function as interceptor (or simply + * return a Promise from any function). + * + * @callback transformUpwardIntercept + * @param {object} definition - Parsed UPWARD definition object. + * @returns {Promise} + */ diff --git a/packages/pwa-buildpack/lib/WebpackTools/ModuleTransformConfig.js b/packages/pwa-buildpack/lib/WebpackTools/ModuleTransformConfig.js index a63fae7f8e..9e19ed9090 100644 --- a/packages/pwa-buildpack/lib/WebpackTools/ModuleTransformConfig.js +++ b/packages/pwa-buildpack/lib/WebpackTools/ModuleTransformConfig.js @@ -1,28 +1,61 @@ -/** - * @module Buildpack/WebpackTools - */ const path = require('path'); /** - * @typedef {Object} TransformRequest - * Instruction to the Webpack transform loader to pass a given file through a - * transform function implemented in a given Node module, with an optional set - * of configuration values that will be passed to the transform function. + * @typedef {function(TransformRequest)} addTransform + * Add a request to transform a file in the build. This function is passed as + * the first argument to an interceptor of the `transformModules` target. * - * @prop {string} type - Type of transform. `'babel'` expects a Babel plugin as the `transformModule`. `"source"` expects a Webpack loader. - * @prop {string} requestor - Name of the file doing the requesting. - * @prop {string} fileToTransform - Relative path to the file in this module - * to be transformed when it is loaded by the compilation. - * @prop {string} transformModule - The Node module that exports the transform - * function to use. Node will resolve this relative to project root. - * @prop {object} [options] - Config values to send to the transform function. - * _Note: Options should be serializable to JSON as Webpack loader options._ + * @param {TransformRequest} req - Instruction object for the requested + * transform, including the transform to apply, the target source code, and + * other options. + * + * @returns null */ +/** @enum {string} */ +const TransformType = { + /** + * Process the _source code_ of `fileToTransform` through the + * `transformModule` as text. When applying a `source` TransformRequest, + * Buildpack will use the `transformModule` as a [Webpack + * loader](https://v4.webpack.js.org/api/loaders/), so it must implement + * that interface. Any Webpack loader can be used as a `transformModule` + * for `source` TransformRequests. + * + * `source` transforms are fast and can run on source code of any language, + * but they aren't as precise and safe as AST-type transforms when modifying + * code. + */ + source: 'source', + /** + * Process the _abstract syntax tree_ of the ES module specified by `fileToTransform` through the `transformModule` as a [Babel AST](https://github.com/babel/babel/blob/master/packages/babel-parser/ast/spec.md). + * When applying a `babel` TransformRequest, Buildpack will use the + * `transformModule` as a [Babel plugin](https://github.com/jamiebuilds/babel-handbook), so it must implement that interface. Any Babel plugin can be used as a `transformModule` for `babel` TransformRequests. + * + * `babel` transforms are powerful and versatile, giving the transformer + * much more insight into the structure of the source code to modify. + * However, they are slower than `source` transforms, and they can only work + * on ES Modules. + */ + babel: 'babel' +}; + /** - * @typedef {Object.} configSerialized - * A map of filenames of modules to be wrapped, to FileExportWrappers declaring - * which exports of those modules will be wrapped with what. + * @typedef {Object} TransformRequest + * Instruction for configuring Webpack to apply custom transformations to one + * particular file. The [`configureWebpack()` function]{@link /pwa-buildpack/reference/configure-webpack/} + * gathers TransformRequests from all interceptors of the `transformModules` + * target and turns them into a configuration of Webpack [module + * rules](https://v4.webpack.js.org/configuration/module/#modulerules). + * + * @prop {TransformType} type - The type of transformation to apply. + * @prop {string} requestor - Name of the module making this request. Used for debugging purposes. + * @prop {string} fileToTransform - Resolvable path to the file to be transformed itself, the same path that you'd use in `import` or `require()`. + * @prop {string} transformModule - Absolute path to the Node module that will actually be doing the transforming. This path may be resolved using different + * rules at different times, so it's best for this path to always be absolute. + * @prop {object} [options] - Config values to send to the transform function. + * _Note: Options should be serializable to JSON as Webpack loader options + * and/or Babel plugin options.._ */ /** @@ -30,7 +63,12 @@ const path = require('path'); * and emits loader config objects for Buildpack's custom transform loaders. */ class ModuleTransformConfig { + /** @borrows TransformType as types */ + static get types() { + return TransformType; + } /** + * @private * @constructs * @param {MagentoResolver} resolver - Resolver to use when finding real paths of * modules requested. @@ -75,10 +113,7 @@ class ModuleTransformConfig { : path.join(requestor, fileToTransform); } /** - * - * Add a request to transform a file in the build. - * - * @param {TransformRequest} req - Request object + * @borrows addTransform as add */ add({ requestor, fileToTransform, transformModule, type, options }) { let absTransformModule; diff --git a/pwa-devdocs/src/_data/buildpack-api.yml b/pwa-devdocs/src/_data/buildpack-api.yml index da8a9ae57d..7e6115e655 100644 --- a/pwa-devdocs/src/_data/buildpack-api.yml +++ b/pwa-devdocs/src/_data/buildpack-api.yml @@ -4,10 +4,10 @@ entries: entries: - label: Targets url: /pwa-buildpack/reference/targets/ - - label: ModuleTransformConfig - url: /pwa-buildpack/reference/moduletransformconfig/ - label: EnvVarDefinitions url: /pwa-buildpack/reference/environment-variables/definitions-api/ + - label: Transform Requests + url: /pwa-buildpack/reference/transform-requests/ # # TODO: when i document this # - label: WrapEsmLoader # url: /pwa-buildpack/reference/webpack-tools/loaders/wrap-esm-loader/ diff --git a/pwa-devdocs/src/pwa-buildpack/reference/moduletransformconfig/index.md b/pwa-devdocs/src/pwa-buildpack/reference/moduletransformconfig/index.md deleted file mode 100644 index 8922eeb1c6..0000000000 --- a/pwa-devdocs/src/pwa-buildpack/reference/moduletransformconfig/index.md +++ /dev/null @@ -1,10 +0,0 @@ ---- -title: ModuleTransformConfig ---- - - - -{% include auto-generated/pwa-buildpack/lib/WebpackTools/ModuleTransformConfig.md %} diff --git a/pwa-devdocs/src/pwa-buildpack/reference/targets/index.md b/pwa-devdocs/src/pwa-buildpack/reference/targets/index.md index f52d2f1557..eb5b2ce59e 100644 --- a/pwa-devdocs/src/pwa-buildpack/reference/targets/index.md +++ b/pwa-devdocs/src/pwa-buildpack/reference/targets/index.md @@ -1,15 +1,14 @@ --- -title: Extensibility Targets +title: Built-in Targets --- Buildpack's targets follow the same Target API as other packages' targets, but they play a unique role. Buildpack targets are the fundamental "roots" of the PWA Studio Target system. All other Targets operate by intercepting other Targets. -Targets can only be called when Buildpack core code creates a BuildBus, which it does for every build and for many commands. -Extensions will then run their declare and intercept files, attaching interceptor functions to each others' dependencies. -Still, nothing _calls_ targets to run any interceptors until Buildpack begins the process, by directly invoking one of its _own_ targets. +BuildBus runs the declare and intercept phases by itself. +But nothing _calls_ targets to run any interceptors until Buildpack begins the process, by directly invoking one of its _own_ targets. -The Buildpack targets are therefore very generic and low-level. They are meant to be used as building blocks for higher-level targets which provide a convenient API for some common business purpose, such as adding routing or navigation logic. +The Buildpack targets are therefore very generic and low-level. They are meant to be used as building blocks for higher-level feature targets, such as adding routing or navigation logic. Even deeper than Buildpack targets are the very similar Hooks that make up [Webpack's plugin system](https://v4.webpack.js.org/api/plugins/). Interceptors can use Buildpack's `webpackCompiler` target to acquire a reference to the Webpack Compiler object for each build, and can then do anything a Webpack plugin can do. Because of their similarity in form and function, the PWA Studio Targets system integrates seamlessly into the larger Webpack ecosystem as a commerce-driven superset of its functionality. diff --git a/pwa-devdocs/src/pwa-buildpack/reference/transform-requests/index.md b/pwa-devdocs/src/pwa-buildpack/reference/transform-requests/index.md new file mode 100644 index 0000000000..1f1abe35a7 --- /dev/null +++ b/pwa-devdocs/src/pwa-buildpack/reference/transform-requests/index.md @@ -0,0 +1,18 @@ +--- +title: Transform Requests +--- + +The built-in [`transformModules`][] target is a powerful way to customize the build process for a partiular file or set of files. +Many common Targets are implemented using the `transformModules` target and a custom transformer module. + +Interceptors of this target receive a single function as their first argument. This is the `addTransform` function documented below. + + + +{% include auto-generated/pwa-buildpack/lib/WebpackTools/ModuleTransformConfig.md %} + + +[`transformModules`]: {%link pwa-buildpack/reference/targets/index.md %}#module_BuiltinTargets.transformModules From d40f3e3be0531faa5b0544ac37ef64b53963f46e Mon Sep 17 00:00:00 2001 From: James Calcaben Date: Mon, 3 Aug 2020 14:52:07 -0500 Subject: [PATCH 22/22] Fix links --- packages/pwa-buildpack/lib/BuildBus/declare-base.js | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/packages/pwa-buildpack/lib/BuildBus/declare-base.js b/packages/pwa-buildpack/lib/BuildBus/declare-base.js index 8d9f986544..aa094a25d2 100644 --- a/packages/pwa-buildpack/lib/BuildBus/declare-base.js +++ b/packages/pwa-buildpack/lib/BuildBus/declare-base.js @@ -21,16 +21,16 @@ module.exports = targets => { /** * Called to collect the definitions and documentation for project-wide * configuration values. Core environment variables are defined in the - * [`envVarDefinitions.json` file]{@link /pwa-buildpack/reference/environment-variables/core-definitions/}. + * [`envVarDefinitions.json` file]{@link http://pwastudio.io/pwa-buildpack/reference/environment-variables/core-definitions/}. * * Intercept this target in your project to add new environment * variables, typed and documented. This integrates your extension * configuration with the project-wide environment variable system. * - * @see [Variable definition schema]{@link /pwa-buildpack/reference/environment-variables/definitions-api/} - * @see [Core variable definitions]{@link /pwa-buildpack/reference/environment-variables/core-definitions/} + * @see [Variable definition schema]{@link http://pwastudio.io/pwa-buildpack/reference/environment-variables/definitions-api/} + * @see [Core variable definitions]{@link http://pwastudio.io/pwa-buildpack/reference/environment-variables/core-definitions/} * - * @param {object} envVarDefinitions The [variable definitions object]{@link /pwa-buildpack/reference/environment-variables/definitions-api/}. + * @param {object} envVarDefinitions The [variable definitions object]{@link http://pwastudio.io/pwa-buildpack/reference/environment-variables/definitions-api/}. * Modify in place. * @member {tapable.SyncHook} * @example Add config fields for your extension