JavaScript

Lightna is built on native JavaScript without third-party libraries. Keeping the client side lightweight is recommended, but if you need a third-party library, you can integrate it through a custom module.

Lightna uses JavaScript with Webpack for module bundling. Webpack configurations are stored in YAML format, making them flexible, easy to override, disable, or extend across modules.

Webpack Configuration

The Webpack entry points and extensions are defined in webpack.yaml, located in the module’s root folder:

entry:
  common:
    component:
      my-component-1: vendor/module-name/common/MyClass1
      my-component-2: vendor/module-name/common/MyClass2
  product:
    component:
      my-product-component-1: vendor/module-name/product/MyProductClass1
      my-product-component-2: vendor/module-name/product/MyProductClass2
extend:
  vendor/another-module-name/common/MyAwesomeClass:
    my-extended-class: vendor/module-name/extend/MyAwesomeClassExtend

Entries

The entry key defines the list of Webpack entries and components that will be instantiated in those entries. You can create or extend common and page-specific JavaScript bundles here.

A common entry point is recommended for scripts used across multiple pages, while additional entries can handle page-specific functionality, such as a product or checkout page. If a part of the JavaScript code is large and only needed after a specific user action, avoid including it in the build. Instead, load it dynamically when required.

Each entry point in the Webpack configuration includes a component key containing individual components used on the page. Each component should be a JavaScript class. During the build process, it is instantiated in [entry-name].js.

Each listed component must have a unique key, serving as an alias that allows other modules to extend or modify it by updating the config or using YAML directives. The key is followed by the file path, without the extension.

Extensions

The extend key defines class extensions for base classes. Nested keys specify which class is being extended, with sub-keys mapping aliases to the corresponding extension file.
Learn more in the Extending JavaScript section.

Including JavaScript Files

To include a JavaScript file, add a block in the layout file that references the template where the script is included.

.head:
  .script:
    template: lightna/magento-frontend/page/head/js/common.phtml

In the template file, include the JavaScript file using the <script> tag. Use the asset method of the Url class to specify the file path. The file name corresponds to the entry point defined in Webpack.
For example, if the entry point is common, the file will be common.js and located at build/js/common.js.

<?php
/**
 * Import:
 * @var Lightna\Engine\Data\Url $url
 */
?>
<script type="text/javascript" src="<?= $url->asset('build/js/common.js') ?>" defer></script>

If multiple JavaScript files are needed, you can either add multiple blocks in the layout or include multiple <script> tags in the template. The first approach is recommended, as separate layout blocks provide better flexibility for managing and excluding scripts when needed.

JavaScript Assets

If a JavaScript file cannot be bundled with Webpack but is necessary, as a last resort, you can place it in the asset directory. It will be copied to a web-accessible folder and used as a regular asset.
For example, if my-library.js is in asset/js, its path will be vendor/module/js/my-library.js.

<?php
/**
 * Import:
 * @var Lightna\Engine\Data\Url $url
 */
?>
<script src="<?= $url->asset('vendor/module/js/my-library.js') ?>"></script>