TargetableESModule

An ECMAScript module that can be changed by a third party.

This class presents a convenient API for consumers to add common transforms to ES Modules in a semantic way.

TargetableESModule
- .addImport(statement) ⇒ SingleImportStatement
- .uniqueIdentifier(binding) ⇒ string
- .wrapWithFile([exportName], wrapperModule) ⇒ this

Adds a static import statement to the module source code, thus importing a new dependency.

This method automatically deduplicates attempts to add imports that would override earlier import bindings. If a collision is detected, it renames the binding before inserting it.

Returns: SingleImportStatement — An instance of the SingleImportStatement class.

Parameters

Name	Type	Description
statement	`string` \| `SingleImportStatement`	A string representing the import statement, or a SingleImportStatement representing it.

Generates a unique identifier for a given binding. Not guaranteed safe, but good enough in a pinch.

Returns: Parameters

Name	Type	Description
binding	`string`	The binding to change.

Pass exports of this module through a wrapper module.

Chainable
Returns: Parameters

Name	Type	Description
[exportName]	`string`	Name of export to wrap. If not provided, will wrap the default export.
wrapperModule	`string`	Package-absolute import path to the wrapper module.

Source Code: pwa-studio/packages/pwa-buildpack/lib/WebpackTools/targetables/TargetableESModule.js

Examples

Code examples for the TargetableESModule class.

Add and use import statements

Calling the addImport() function returns a SingleImportStatement object. Use this object to refer to the component in your code.

const logger = esModule.addImport('import logger from "./logger"');
esModule.insertAfterSource("./logger';\n", `${logger.binding}('startup')`);
Copied to your clipboard
const logger = esModule.addImport('import logger from "./logger"');
esModule.insertAfterSource("./logger';\n", `${logger.binding}('startup')`);

The SingleImportStatement class overrides its toString() method to return the value of its .binding property, so you can use the object itself in your templates

const logger = esModule.addImport('import logger from "./logger"');
esModule.insertAfterSource("./logger';\n", `${logger}('startup')`);
Copied to your clipboard
const logger = esModule.addImport('import logger from "./logger"');
esModule.insertAfterSource("./logger';\n", `${logger}('startup')`);

Import statement limits

The addImport() function can only handle import statements with a single binding.

For example, the following code is allowed because it only binds VeniaButton in the statement:

import { Button as VeniaButton } from "@magento/venia/lib/components/Button";
Copied to your clipboard
import { Button as VeniaButton } from "@magento/venia/lib/components/Button";

The following would not be allowed, since it adds two bindings (VeniaButton and Carousel):

import { Button as VeniaButton, Carousel } from "@magento/venia";
Copied to your clipboard
import { Button as VeniaButton, Carousel } from "@magento/venia";

Import conflicts

A conflict occcurs when an import statement uses a binding that already belongs to another existing import statement. For example, you add the logger import statement in a previous example to a file that already imports another logger module. When this happens, the TargetableESModule class rebinds the logger object to a different, unique name, such as logger$$2.

Wrap a module

Use the wrapWithFile() function to wrap an exported module with another module from a specified file.

// Create a TargetableESModule linked to the useProductFullDetail.js file
const useProductFullDetails = targetables.esModule(
  "@magento/peregrine/lib/talons/ProductFullDetail/useProductFullDetail.js"
);

// Wrap the `useProductFullDetail` named export from the file with
// the default export of `src/targets/wrapper.js` in the `myExtension` package.
useProductFullDetails.wrapWithFile(
  "useProductFullDetail",
  "myExtension/src/targets/wrapper"
);
Copied to your clipboard
// Create a TargetableESModule linked to the useProductFullDetail.js file
const useProductFullDetails = targetables.esModule(
  "@magento/peregrine/lib/talons/ProductFullDetail/useProductFullDetail.js"
);

// Wrap the `useProductFullDetail` named export from the file with
// the default export of `src/targets/wrapper.js` in the `myExtension` package.
useProductFullDetails.wrapWithFile(
  "useProductFullDetail",
  "myExtension/src/targets/wrapper"
);