TargetableESModule

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.

Kind: global class

targetableESModule.addImport(statement) ⇒ SingleImportStatement

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.

Kind: instance method of TargetableESModule
Returns: SingleImportStatement - An instance of the SingleImportStatement class.

Param Type Description
statement string | SingleImportStatement A string representing the import statement, or a SingleImportStatement representing it.

targetableESModule.uniqueIdentifier(binding) ⇒ string

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

Kind: instance method of TargetableESModule

Param Type Description
binding string The binding to change.

targetableESModule.wrapWithFile([exportName], wrapperModule) ⇒ this

Pass exports of this module through a wrapper module.

Kind: instance method of TargetableESModule
Chainable

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

For implementation details View Source.

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')`)

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')`)

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'

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

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'
);