fix(devkit): return null for ESM dependencies instead of throwing error in ensurePackage (#17195)

docs/generated/devkit/nx_devkit.md

@@ -1161,6 +1161,7 @@ ensurePackage(tree, '@nx/jest', nxVersion);
 
 This install the @nx/jest@<nxVersion> and return the module
 When running with --dryRun, the function will throw when dependencies are missing.
+Returns null for ESM dependencies. Import them with a dynamic import instead.
 
 #### Parameters
 
@@ -1180,11 +1181,12 @@ When running with --dryRun, the function will throw when dependencies are missin
 ▸ **ensurePackage**<`T`\>(`pkg`, `version`): `T`
 
 Ensure that dependencies and devDependencies from package.json are installed at the required versions.
+Returns null for ESM dependencies. Import them with a dynamic import instead.
 
 For example:
 
 ```typescript
-ensurePackage(tree, '@nx/jest', nxVersion);
+ensurePackage('@nx/jest', nxVersion);
 ```
 
 #### Type parameters

docs/generated/packages/devkit/documents/nx_devkit.md

@@ -1161,6 +1161,7 @@ ensurePackage(tree, '@nx/jest', nxVersion);
 
 This install the @nx/jest@<nxVersion> and return the module
 When running with --dryRun, the function will throw when dependencies are missing.
+Returns null for ESM dependencies. Import them with a dynamic import instead.
 
 #### Parameters
 
@@ -1180,11 +1181,12 @@ When running with --dryRun, the function will throw when dependencies are missin
 ▸ **ensurePackage**<`T`\>(`pkg`, `version`): `T`
 
 Ensure that dependencies and devDependencies from package.json are installed at the required versions.
+Returns null for ESM dependencies. Import them with a dynamic import instead.
 
 For example:
 
 ```typescript
-ensurePackage(tree, '@nx/jest', nxVersion);
+ensurePackage('@nx/jest', nxVersion);
 ```
 
 #### Type parameters

packages/devkit/src/utils/package-json.ts

@@ -389,6 +389,7 @@ const packageMapCache = new Map<string, any>();
  * ```
  * This install the @nx/jest@<nxVersion> and return the module
  * When running with --dryRun, the function will throw when dependencies are missing.
+ * Returns null for ESM dependencies. Import them with a dynamic import instead.
  *
  * @param tree the file system tree
  * @param pkg the package to check (e.g. @nx/jest)
@@ -404,11 +405,13 @@ export function ensurePackage(
 
 /**
  * Ensure that dependencies and devDependencies from package.json are installed at the required versions.
+ * Returns null for ESM dependencies. Import them with a dynamic import instead.
  *
  * For example:
  * ```typescript
- * ensurePackage(tree, '@nx/jest', nxVersion)
+ * ensurePackage('@nx/jest', nxVersion)
  * ```
+ *
  * @param pkg the package to install and require
  * @param version the version to install if the package doesn't exist already
  */
@@ -440,7 +443,11 @@ export function ensurePackage<T extends any = any>(
   try {
     return require(pkg);
   } catch (e) {
-    if (e.code !== 'MODULE_NOT_FOUND') {
+    if (e.code === 'ERR_REQUIRE_ESM') {
+      // The package is installed, but is an ESM package.
+      // The consumer of this function can import it as needed.
+      return null;
+    } else if (e.code !== 'MODULE_NOT_FOUND') {
       throw e;
     }
   }
@@ -474,13 +481,23 @@ export function ensurePackage<T extends any = any>(
   // Re-initialize the added paths into require
   (Module as any)._initPaths();
 
-  const result = require(require.resolve(pkg, {
+  try {
-    paths: [tempDir],
+    const result = require(require.resolve(pkg, {
-  }));
+      paths: [tempDir],
+    }));
 
-  packageMapCache.set(pkg, result);
+    packageMapCache.set(pkg, result);
 
-  return result;
+    return result;
+  } catch (e) {
+    if (e.code === 'ERR_REQUIRE_ESM') {
+      // The package is installed, but is an ESM package.
+      // The consumer of this function can import it as needed.
+      packageMapCache.set(pkg, null);
+      return null;
+    }
+    throw e;
+  }
 }
 
 function addToNodePath(dir: string) {