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.

transformUpwardIntercept ⇒ Promise

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

envValidationInterceptor ⇒ Boolean

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.

BuiltinTargets
- .envVarDefinitions : tapable.SyncHook
- .transformModules : tapable.AsyncSeriesHook
- .webpackCompiler : tapable.SyncHook
- .specialFeatures : tapable.SyncHook
- .transformUpward : tapable.AsyncSeriesHook
- .validateEnv : tapable.AsyncParallelHook

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

Name	Type	Description
envVarDefinitions	`object`	The variable definitions object. Modify in place.

Example (Add config fields for your extension)

targets.of('@magento/pwa-buildpack').envVarDefinitions.tap(defs => {
  defs.sections.push({
    name: 'My Extension Settings',
    variables: [
      {
        name: 'MY_EXTENSION_API_KEY',
        type: 'str',
        desc: 'API key for remote service access.'
      }
    ]
  })
});
Copied to your clipboard
targets.of('@magento/pwa-buildpack').envVarDefinitions.tap(defs => {
  defs.sections.push({
    name: 'My Extension Settings',
    variables: [
      {
        name: 'MY_EXTENSION_API_KEY',
        type: 'str',
        desc: 'API key for remote service access.'
      }
    ]
  })
});

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

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

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

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

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

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

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

Name	Type
interceptor	`transformUpwardIntercept`

Example (Send empty responses in maintenance mode.)

targets.of('@magento/pwa-buildpack').transformUpward.tap(def => {
  const guardMaintenanceMode = (prop, inline) => {
    def[prop] = {
      when: [
        {
          matches: 'env.MAINTENANCE_MODE',
          pattern: '.',
          use: { inline }
        }
      ],
      default: def[prop]
    }
  }

  guardMaintenanceMode('status', 503);
  guardMaintenanceMode('body', '')
})
Copied to your clipboard
targets.of('@magento/pwa-buildpack').transformUpward.tap(def => {
  const guardMaintenanceMode = (prop, inline) => {
    def[prop] = {
      when: [
        {
          matches: 'env.MAINTENANCE_MODE',
          pattern: '.',
          use: { inline }
        }
      ],
      default: def[prop]
    }
  }

  guardMaintenanceMode('status', 503);
  guardMaintenanceMode('body', '')
})

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

Name	Type
validator	`envValidationInterceptor`

Example

targets.of('@magento/pwa-buildpack').validateEnv.tapPromise(validateBackendUrl);
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

Name	Type	Description
addTransform	`addTransform`	Callback to add a transform.

Callback to add a transform.

See: TransformRequest
Parameters

Name	Type	Description
transformRequest	`Buildpack/WebpackTools~TransformRequest`	Request 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

Name	Type	Description
compiler	`webpack.Compiler`	The 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

Name	Type	Description
featuresByModule	`Object.<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.

Returns: Parameters

Name	Type	Description
definition	`object`	Parsed UPWARD definition object.

Intercept function signature for the validateEnv target.

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

Name	Type	Description
config.env	`Object`	Project ENV
config.onFail	`function`	On fail callback
config.debug	`function`	Debug function to be used for additional reporting in debug mode

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

EnvVarDefinition object

Targetables

Last updated 9/13/2023

Was this helpful?

Yes

Targets

Overview.css-83mclq{margin-left:var(--spectrum-global-dimension-size-100);}

Overview