adds ability to whitelist devDeps of the package to be installed ahead of running the transform

Author: Daniel Del Core

.changeset/cold-penguins-deny.md

@@ -0,0 +1,5 @@
+---
+'@hypermod/types': minor
+---
+
+Adds dependencies property to the type definition + adds comments explaining all of the properties

.changeset/pretty-shrimps-hunt.md

@@ -0,0 +1,6 @@
+---
+'@hypermod/fetcher': minor
+'@hypermod/cli': minor
+---
+
+Adds experimental dependency property for whitelisting devdeps in co-located modules

packages/cli/src/main.ts

@@ -3,6 +3,7 @@ import semver from 'semver';
 import chalk from 'chalk';
 import findUp from 'find-up';
 import inquirer from 'inquirer';
+import fs from 'fs-extra';
 import { PluginManager, PluginManagerOptions } from 'live-plugin-manager';
 import { installPackage } from '@antfu/install-pkg';
 
@@ -25,9 +26,16 @@ const ExperimentalModuleLoader = () => ({
   require: (packageName: string) => require(packageName),
   getInfo: (packageName: string) => {
     const entryPath = require.resolve(packageName);
+    const location = entryPath.split(packageName)[0] + packageName;
+    const packageJsonRaw = fs.readFileSync(
+      path.join(location, 'package.json'),
+      'utf8',
+    );
+
     return {
-      location: entryPath.split(packageName)[0] + packageName,
-      entryPath: entryPath,
+      location,
+      entryPath,
+      pkgJson: JSON.parse(packageJsonRaw),
     };
   },
 });

packages/fetcher/src/index.ts

@@ -147,6 +147,18 @@ export async function fetchRemotePackage(
     const pkg = packageManager.require(packageName);
     const configExport = resolveConfigExport(pkg);
 
+    // Install whitelisted deps
+    // @ts-expect-error legacy module loader doesn't know about these properties
+    if (info.pkgJson) {
+      await Promise.all(
+        configExport.dependencies?.map(dep => {
+          // @ts-expect-error legacy module loader doesn't know about these properties
+          const version = info.pkgJson.devDependencies[dep];
+          return packageManager.install(`${dep}@${version}`);
+        }) ?? [],
+      );
+    }
+
     if (configExport.transforms || configExport.presets) {
       return {
         filePath: info.location,

packages/types/src/index.ts

@@ -1,9 +1,50 @@
 export interface Config {
+  /**
+   * Targets represent the packages that the hypermod package is providing transforms to.
+   * This is useful for filtering and grouping codemods based on the target package.
+   *
+   * For example, a hypermod package that is targetting react and react-dom would have
+   * the following targets: ['react', 'react-dom'].
+   */
   targets?: string[];
+
+  /**
+   * Github usernames of the maintainers
+   */
   maintainers?: string[];
+
+  /**
+   * Description of the hypermod package, please explain the intetion of the package.
+   */
   description?: string;
+
+  /**
+   * Transforms are the main building blocks of a codemod. When a hypermod package
+   * is targetting a specific package / focus area, transforms represent the
+   * migrations between versions of the target package.
+   *
+   * Example react v16 -> v17, or react-dom v16 -> v17
+   */
   transforms?: Record<string, string>;
+
+  /**
+   * Presets represent transforms that have no association with a specific
+   * version of a package / focus area. These should be generic and reusable.
+   *
+   * Example: Format imports, remove console logs, etc.
+   */
   presets?: Record<string, string>;
+
+  /**
+   * A list of dependencies to be installed before running the transform.
+   * These are useful when co-locating codemods with an existing package
+   * and want to whitelist devDependencies to be installed.
+   *
+   * Note: the versions installed are based on the package.json
+   *
+   * Example: dependencies: ['@hypermod/utils', 'postcss', 'postcss-less']
+   */
+  dependencies?: string[];
 }
 
 export type CodeshiftConfig = Config;

website/docs/configuration.mdx

@@ -65,3 +65,15 @@ Targets list the packages that the codemod package targets.
 This is useful for Hypermod packages that have codemods targeting multiple related packages at the same time, such as packages from a monorepo.
 
 For example: `targets: ['@foo/bar', '@foo/baz']`
+
+### `dependencies`
+
+(Experimental feature, this will only work when the `--experimental-loader` flag is specified)
+
+A list of dependencies to be installed before running the transform. These are useful when co-locating codemods with an existing
+package and want to specify a whitelist of `devDependencies` to be installed only when run via `@hypermod/cli`.
+This avoids codemod-related dependencies from unnecessarily increasing the bundlesize for regular consumers of the package.
+
+Note: the versions installed are based on what's specified in the `package.json`
+
+Example: `dependencies: ['@hypermod/utils', 'postcss', 'postcss-less']`