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

BuiltinTargets

BuiltinTargets.envVarDefinitions : tapable.SyncHook

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.

Kind: static property of BuiltinTargets
See

Param 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.'
      }
    ]
  })
});

BuiltinTargets.transformModules : tapable.AsyncSeriesHook

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.

Kind: static property of BuiltinTargets
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" ]}
}));

BuiltinTargets.webpackCompiler : tapable.SyncHook

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.

Kind: static property of BuiltinTargets
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!');
  });
});

BuiltinTargets.specialFeatures : tapable.SyncHook

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.

Kind: static property of BuiltinTargets
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 };
})

BuiltinTargets.transformUpward : tapable.AsyncSeriesHook

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.

Kind: static property of BuiltinTargets

Param 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', '')
})

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.

Kind: global typedef

Param Type Description
addTransform addTransform Callback to add a transform.

addTransform : function

Callback to add a transform.

Kind: global typedef
See: TransformRequest

Param Type Description
transformRequest Buildpack/WebpackTools~TransformRequest Request to apply a transform to a file provided by this dependency.

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.

Kind: global typedef

Param Type Description
compiler webpack.Compiler The webpack compiler instance

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.

Kind: global typedef

Param Type Description
featuresByModule Object.<string, SpecialBuildFlags> An object mapping of module names to their special build flags

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

Kind: global typedef

Param Type Description
definition object Parsed UPWARD definition object.

For implementation details View Source.