Edit in GitHubLog an issue

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.

Overview#

All other Targets operate by intercepting other 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 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. 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.

Modules

BuiltinTargets

Typedefs

transformModulesIntercept : function

Intercept function signature for the transformModules target.

Interceptors of transformModules should call the addTransform() callback to add module specific transformers. Any returned value will be ignored.

addTransform : function

Callback to add a transform.

webpackCompilerIntercept : function

Intercept function signature for the webpackCompiler target.

Interceptors of webpackCompiler should tap hooks on the provided compiler object. Any returned value will be ignored.

specialFeaturesIntercept : function

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.

transformUpwardInterceptPromise

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).

envValidationInterceptorBoolean

Intercept function signature for the validateEnv target.

Interceptors of the validateEnv target receive a config object. The config object contains the project env, an onFail callback and the debug function to be used in case of the debug mode to log more inforamtion to the console.

This Target can be used asynchronously in the parallel mode. If a validator needs to stop the process immediately, it can throw an error. If it needs to report an error but not stop the whole process, it can do so by calling the onFail function with the error message it wants to report. It can call the onFail multiple times if it wants to report multiple errors.

All the errors will be queued and printed into the console at the end of the validation process and the build process will be stopeed.

Called to collect the definitions and documentation for project-wide configuration values. Core environment variables are defined in the envVarDefinitions.json file.

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

Parameters

NameTypeDescription
envVarDefinitionsobjectThe variable definitions object. Modify in place.

Example (Add config fields for your extension)

Copied to your clipboard
1targets.of('@magento/pwa-buildpack').envVarDefinitions.tap(defs => {
2 defs.sections.push({
3 name: 'My Extension Settings',
4 variables: [
5 {
6 name: 'MY_EXTENSION_API_KEY',
7 type: 'str',
8 desc: 'API key for remote service access.'
9 }
10 ]
11 })
12});

Called when configuring the loading and processing rules for Webpack.

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.

See: transformModules intercept function
Example (Strip unnecessary Lodash code from a specific JS module.)

Copied to your clipboard
1targets.of('@magento/pwa-buildpack').transformModules.tap(addTransform => addTransform({
2 type: 'babel',
3 fileToTransform: './lib/uses-pipeline-syntax.js',
4 transformModule: 'babel-plugin-lodash',
5 options: { id: ["async", "lodash-bound" ]}
6}));

Calls interceptors whenever a Webpack Compiler object is created. This almost always happens once per build, even in dev mode.

Use an intercept function on this target to access the webpack compiler.

Example (Tap the compiler's `watchRun` hook.)

Copied to your clipboard
1targets.of('@magento/pwa-buildpack').webpackCompiler.tap(compiler => {
2 compiler.hooks.watchRun.tapPromise(async () => {
3 compiler.getInfrastructureLogger('my-extension')
4 .info('I do something special in the dev server!');
5 });
6});

Collects flags for special build features that dependency packages 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 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 to add special build features for the modules used in your project.

See: Special flags in configureWebpack()
Example (Declare that your extension contains CSS modules.)

Copied to your clipboard
1targets.of('@magento/pwa-buildpack').specialFeatures.tap(featuresByModule => {
2 featuresByModule['my-module'] = { cssModules: true };
3})

Exposes the fully merged UPWARD definition for fine tuning. The UpwardIncludePlugin does a simple shallow merge of the upward.yml files in every package which sets the upward: true flag in the specialFeatures object. After that is complete, UpwardIncludePlugin calls this target with the parsed and merged definition.

Parameters

NameType
interceptortransformUpwardIntercept

Example (Send empty responses in maintenance mode.)

Copied to your clipboard
1targets.of('@magento/pwa-buildpack').transformUpward.tap(def => {
2 const guardMaintenanceMode = (prop, inline) => {
3 def[prop] = {
4 when: [
5 {
6 matches: 'env.MAINTENANCE_MODE',
7 pattern: '.',
8 use: { inline }
9 }
10 ],
11 default: def[prop]
12 }
13 }
14
15 guardMaintenanceMode('status', 503);
16 guardMaintenanceMode('body', '')
17})

Collect all ENV validation functions that will run against the project's ENV. The functions can be async and they will run in parallel. If a validation function wants to stop the whole process for instance in case of a serious security issue, it can do so by throwing an error. If it wants to report an error, it can do so by using the onFail callback provided as an argument. A validation function can submit multiple errors by calling the onFail function multiple times. All the errors will be queued into an array and displayed on the console at the end of the process.

Parameters

NameType
validatorenvValidationInterceptor

Example

Copied to your clipboard
targets.of('@magento/pwa-buildpack').validateEnv.tapPromise(validateBackendUrl);

Intercept function signature for the transformModules target.

Interceptors of transformModules should call the addTransform() callback to add module specific transformers. Any returned value will be ignored.

Parameters

NameTypeDescription
addTransformaddTransformCallback to add a transform.

Callback to add a transform.

See: TransformRequest
Parameters

NameTypeDescription
transformRequestBuildpack/WebpackTools~TransformRequestRequest to apply a transform to a file provided by this dependency.

Intercept function signature for the webpackCompiler target.

Interceptors of webpackCompiler should tap hooks on the provided compiler object. Any returned value will be ignored.

Parameters

NameTypeDescription
compilerwebpack.CompilerThe webpack compiler instance

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.

Parameters

NameTypeDescription
featuresByModuleObject.<string, SpecialBuildFlags>An object mapping of module names to their special build flags

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).

Returns: Parameters

NameTypeDescription
definitionobjectParsed UPWARD definition object.

Intercept function signature for the validateEnv target.

Interceptors of the validateEnv target receive a config object. The config object contains the project env, an onFail callback and the debug function to be used in case of the debug mode to log more inforamtion to the console.

This Target can be used asynchronously in the parallel mode. If a validator needs to stop the process immediately, it can throw an error. If it needs to report an error but not stop the whole process, it can do so by calling the onFail function with the error message it wants to report. It can call the onFail multiple times if it wants to report multiple errors.

All the errors will be queued and printed into the console at the end of the validation process and the build process will be stopeed.

Returns: Parameters

NameTypeDescription
config.envObjectProject ENV
config.onFailfunctionOn fail callback
config.debugfunctionDebug function to be used for additional reporting in debug mode

Source Code: pwa-studio/packages/pwa-buildpack/lib/BuildBus/declare-base.js

  • Privacy
  • Terms of Use
  • Do not sell my personal information
  • AdChoices
Copyright © 2022 Adobe. All rights reserved.