feat(plugins-manager): support a wrapPlugin property for adding

Author: daKmoR

.changeset/odd-pumpkins-rhyme.md

@@ -0,0 +1,5 @@
+---
+'plugins-manager': patch
+---
+
+Add a "hidden" feature in addPlugin that if you attach a `wrapPlugin` property to the returning function it will call `wrapPlugin` on the plugin before adding it.

docs/docs/tools/plugins-manager.md

@@ -112,16 +112,13 @@ addPlugin(MyClass, { otherProp: 'new name' }); // ts error
 
 Many plugin systems require you to either execute a plugin function like in `rollup`.
 
-<!-- prettier-ignore-start -->
 ```js
 import json from '@rollup/plugin-json';
 
-/** @type {import('rocket/cli').RocketCliConfig} */
-export default ({
+export default /** @type {import('rocket/cli').RocketCliConfig} */ ({
   plugins: [json({ preferConst: true })],
 });
 ```
-<!-- prettier-ignore-end -->
 
 or add it in a special way like in `eleventy`
 
@@ -254,6 +251,18 @@ addPlugin(myPlugin, { myFlag: true }); // ts ok
 addPlugin(myPlugin, { notExisting: true }); // ts error
 ```
 
+Note: There is a "hidden" feature in addPlugin that if you attach a `wrapPlugin` property to the returning function it will call `wrapPlugin` on the plugin before adding it.
+
+```js
+// example auto wrap rollup plugins for @web/dev-server
+import { fromRollup } from '@web/dev-server-rollup';
+
+const userSetupFunctions = [addPlugin(json)].map(mod => {
+  mod.wrapPlugin = fromRollup;
+  return mod;
+});
+```
+
 ## Adjusting Plugin Options
 
 Adjusting options means to either

packages/plugins-manager/src/addPlugin.js

@@ -1,3 +1,4 @@
+/* eslint-disable @typescript-eslint/ban-ts-comment */
 /**
  * @template {import('../types/main').Plugin} T
  * @param {T} plugin
@@ -12,6 +13,10 @@ export function addPlugin(plugin, options = {}, { how = 'after', location = 'bot
     if (plugins === undefined) {
       plugins = [];
     }
+
+    // @ts-ignore
+    const usePlugin = addPluginFn.wrapPlugin ? addPluginFn.wrapPlugin(plugin) : plugin;
+
     // only add if name is not already in the meta plugin list
     if (plugins.findIndex(pluginObj => pluginObj.plugin === plugin) === -1) {
       let index = -1;
@@ -40,7 +45,7 @@ export function addPlugin(plugin, options = {}, { how = 'after', location = 'bot
       }
 
       plugins.splice(index, 0, {
-        plugin,
+        plugin: usePlugin,
         options,
       });
     }

packages/plugins-manager/test-node/addPlugin.test.js

@@ -109,4 +109,18 @@ describe('addPlugin', () => {
     });
     expect(config.plugins).to.deep.equal(['-- newFirst last Plugin --']);
   });
+
+  it('[advanced] can add a `wrapPlugin` property to the function itself which will call it on the plugin on init', async () => {
+    function myWrapper(plugin) {
+      return () => 'wrapped' + plugin();
+    }
+
+    const config = applyPlugins({
+      setupPlugins: [addPlugin(insertPlugin)].map(mod => {
+        mod.wrapPlugin = myWrapper;
+        return mod;
+      }),
+    });
+    expect(config.plugins).to.deep.equal(['wrapped-- first last Plugin --']);
+  });
 });