Consider async JS-plugins in docs (#1326)

* Consider async JS-plugins in docs

* Update add-custom-javascript.md

* Add JavaScript to spellcheck allow list

* Update add-custom-javascript.md

* Apply suggestions from code review

Co-authored-by: Su <[email protected]>

* Fix typo

---------

Co-authored-by: Su <[email protected]>

.wordlist.txt

@@ -712,6 +712,7 @@ iterable
 iteratively
 jargons
 javascript
+JavaScript
 JestJS
 JetBrains
 Jira

guides/plugins/plugins/storefront/add-custom-javascript.md

@@ -88,16 +88,35 @@ You can also bind your plugin to a DOM element by providing a css selector:
 
 ```javascript
 // <plugin root>/src/Resources/app/storefront/src/main.js
- // Import all necessary Storefront plugins
- import ExamplePlugin from './example-plugin/example-plugin.plugin';
+// Import all necessary Storefront plugins
+import ExamplePlugin from './example-plugin/example-plugin.plugin';
 
- // Register your plugin via the existing PluginManager
- const PluginManager = window.PluginManager;
- PluginManager.register('ExamplePlugin', ExamplePlugin, '[data-example-plugin]');
+// Register your plugin via the existing PluginManager
+const PluginManager = window.PluginManager;
+PluginManager.register('ExamplePlugin', ExamplePlugin, '[data-example-plugin]');
 ```
 
 In this case the plugin just gets executed if the HTML document contains at least one element with the `data-example-plugin` attribute. You can then use `this.el` inside your plugin to access the DOM element your plugin is bound to.
 
+## Registering an async plugin
+
+You can also register an async JS-plugin. Instead of importing a JS-plugin file at the top of your `main.js`, you can provide a dynamic import inside `PluginManager.register()`.
+The import path can remain the same as the synchronous import.
+
+```javascript
+// <plugin root>/src/Resources/app/storefront/src/main.js
+
+// Register your plugin via the existing PluginManager using a dynamic import
+const PluginManager = window.PluginManager;
+PluginManager.register('ExamplePlugin', () => import('./example-plugin/example-plugin.plugin'), '[data-example-plugin]');
+```
+
+If an async/dynamic import is provided, then the JS-plugin will be recognized as async by the PluginManager automatically. 
+This means that, the registered JS-plugin will not be included in the main bundled JavaScript (storefront.js) by default. The JS-plugin will only be downloaded on-demand if the plugin selector (`[data-example-plugin]`) is found on the current page, see [Loading your plugin](#loading-your-plugin).
+
+Using an async JS-plugin can be helpful when the plugin is not supposed to be loaded on every page and should only be loaded when it is actually needed. This can reduce the size of the initially loaded JavaScript in the browser.
+When using the "normal" import (`import ExamplePlugin from './example-plugin/example-plugin.plugin';`) in comparison, the JS-plugin will always be included in the JavaScript on all pages.
+
 ### Loading your plugin
 
 The following will create a new template with a very short explanation. If you're looking for more information on what's going on here, head over to our guide about [Customizing templates](customize-templates).
@@ -220,7 +239,7 @@ Now you want to overwrite the value `slider.mouseDrag` with your plugin. The var
 
 For JavaScript you normally would have two locations where your `*.js` files are located. You have your `main.js` as an entry point inside of the following directory: `<plugin root>/src/Resources/app/storefront/src`.
 
-Shopware will then compile the JavaScript and save the compiled version at `<plugin root>/src/Resources/app/storefront/dist/storefront/js/<plugin-name>.js`. This file will be recognized automatically by Shopware.
+Shopware will then compile the JavaScript and save the compiled version at `<plugin root>/src/Resources/app/storefront/dist/storefront/js/<plugin-name>/<plugin-name>.js`. These files will be recognized automatically by Shopware.
 
 Make sure to ship the compiled file with your plugin as well.
 

guides/plugins/plugins/storefront/override-existing-javascript.md

@@ -101,6 +101,17 @@ const PluginManager = window.PluginManager;
 PluginManager.override('CookiePermission', MyCookiePermission, '[data-cookie-permission]');
 ```
 
+::: info
+If the plugin you want to override is an async plugin, the import of your override plugin has to be async as well. See also [Registering an async plugin](./add-custom-javascript.md#registering-an-async-plugin)
+:::
+
+```javascript
+const PluginManager = window.PluginManager;
+
+// If the plugin "CookiePermission" is registered async, you also override it with an async/dynamic import
+PluginManager.override('CookiePermission', () => import('./my-cookie-permission/my-cookie-permission.plugin'), '[data-cookie-permission]');
+```
+
 ### Testing your changes
 
 To see your changes you have to build the Storefront. Use the following command and reload your Storefront.