feat: update CLI options for improved linking process

Author: nima-taheri-mongodb

DEVELOPER.md

@@ -72,19 +72,27 @@ We use @testing-library/react for writing tests locally. This library helps mock
 
 ### Linking
 
-We also have a link script, such that you can test components that are in development in environments beyond Storybook. To do so, run `yarn run link -- [path-to-application]`.
+We provide a `link` script to help you test in-development components within environments outside of Storybook. To do this, run:
 
-Note: There are some known issues using `yarn link` from yarn workspaces. Using Verdaccio, while more involved, is the more reliable and recommended approach for testing in an external project.
+```
+yarn run link --to=[path-to-application]
+```
 
-### Using a local registry (Verdaccio)
+If you encounter issues while linking, try the following troubleshooting flags:
 
-Publishing test versions to a local registry can be helpful when you need to make changes and test in an external app (or other library). To do this, you can install and use [Verdaccio](https://verdaccio.org/)
+- When linking multiple packages with `--scope` or multiple `--packages` options, link processes run in parallel by default. If you experience failures, add the `--no-parallel` flag to run the linking tasks sequentially, which can help avoid race conditions.
 
-#### 1. Install `verdaccio`
+- If you are using a Node version manager such as `asdf` or `nvm`, add the `--launch-env="$(env)"` flag. This ensures the link script spawns commands using your current shell’s environment, preventing environment pollutions that may happen through the tooling of the version manager.
 
-```bash
-yarn install --global verdaccio
-```
+- In your external project, make sure your module resolver picks up `'react'` from your own `node_modules` (not from LeafyGreen’s). If using webpack, you can enforce this by adding an alias in your webpack configuration:
+
+  ```js
+  resolve: {
+    alias: {
+      react: path.dirname(require.resolve('react/package.json'))
+    },
+  },
+  ```
 
 #### 2. Start `verdaccio`, and make note on the localhost port (should be `http://localhost:4873/` by default)
 
@@ -115,12 +123,12 @@ You should expect to see the following line in that file. (if not you can add it
 Ensure all packages are built, then navigate to some package and manually publish:
 
 ```bash
-pnpm build;
+yarn build;
 cd packages/<package-name>;
-pnpm publish;
+yarn publish;
 ```
 
-To ensure you are pointing to the correct registry, you can add the `--dry-run` flag to the `pnpm publish` command. This command should echo:
+To ensure you are pointing to the correct registry, you can add the `--dry-run` flag to the `yarn publish` command. This command should echo:
 
 ```
 npm notice Publishing to http://localhost:4873

tools/cli/src/index.ts

@@ -83,10 +83,23 @@ cli
     'When running from a consuming application, defines the source of linked packages',
   )
   .option('-v --verbose', 'Prints additional information to the console', false)
-  .option('--scope <name>', 'The NPM organization')
+  .option(
+    '--no-parallel',
+    'Run the link command sequentially for each package. Useful for debugging or when the parallel approach fails',
+    true,
+  )
+  .option(
+    '--launch-env <launchEnv>',
+    'A string of environment variable lines as `KEY=VALUE`, separated by a newline. ' +
+      'Only the specified environment variables will be used during npm link commands in the source and destination directories. ' +
+      'This is useful to workaround environment variable pollution by tools such as version managers (e.g., asdf) or script runners (e.g., pnpm) that interfere with `npm link`. ' +
+      'We recommend using --launch-env="$(env)" to use your original shell environment.',
+    undefined,
+  )
+  .option('--scope <name>', 'The NPM organization, e.g. @lg-charts')
   .option(
     '--packages <names...>',
-    'Specific package names (requires `scope` option, or full package name)',
+    'Specific package names (requires `scope` option, or full package name) e.g. `@lg-charts/core` or `core` if @lg-charts is the scope',
   )
   .action(linkPackages);
 

tools/link/src/link.ts

@@ -13,13 +13,32 @@ interface LinkOptions {
   verbose: boolean;
   to?: string;
   from?: string;
+  parallel?: boolean;
+  launchEnv?: string;
 }
 
 export async function linkPackages(
   dest: string | undefined,
   opts: LinkOptions,
 ) {
-  const { verbose, scope: scopeFlag, packages, to, from } = opts;
+  const {
+    verbose,
+    scope: scopeFlag,
+    packages,
+    to,
+    from,
+    parallel,
+    launchEnv: launchEnvString,
+  } = opts;
+  let launchEnv: NodeJS.ProcessEnv | undefined;
+
+  if (launchEnvString) {
+    const keyValuePairs = launchEnvString
+      .split('\n')
+      .filter(line => line.trim() && line.includes('='))
+      .map(line => line.trim().split(/=(.*)/));
+    launchEnv = Object.fromEntries(keyValuePairs);
+  }
 
   const rootDir = process.cwd();
 
@@ -81,6 +100,8 @@ export async function linkPackages(
           destination,
           packages,
           verbose,
+          parallel,
+          launchEnv,
         ),
       );
     }

tools/link/src/utils/createLinkFrom.ts

@@ -10,6 +10,7 @@ import { PackageDetails } from './types';
 interface CreateLinkOptions extends PackageDetails {
   verbose?: boolean;
   packageManager?: SupportedPackageManager;
+  env?: NodeJS.ProcessEnv;
 }
 
 /**
@@ -24,6 +25,7 @@ export async function createLinkFrom(
     packageName,
     packageManager,
     verbose,
+    env,
   }: CreateLinkOptions,
 ): Promise<void> {
   const scopeSrc = scopePath;
@@ -44,6 +46,7 @@ export async function createLinkFrom(
         name: `link_src:${packageName}`,
         cwd: path.join(packagesDirectory, packageName),
         verbose,
+        env,
       });
     } catch (_) {
       throw new Error(`Couldn't create link for package: ${packageName}`);

tools/link/src/utils/install.ts

@@ -8,6 +8,7 @@ export async function installPackages(
   options?: {
     packageManager?: SupportedPackageManager;
     verbose?: boolean;
+    env?: NodeJS.ProcessEnv;
   },
 ): Promise<void> {
   if (fsx.existsSync(path)) {
@@ -18,6 +19,7 @@ export async function installPackages(
         name: 'install',
         cwd: path,
         verbose: options?.verbose,
+        env: options?.env,
       });
     } catch (err) {
       throw new Error(`Error installing packages\n` + err);

tools/link/src/utils/linkPackageTo.ts

@@ -8,6 +8,7 @@ interface LinkPackagesToOptions
   extends Pick<PackageDetails, 'scopeName' | 'packageName'> {
   verbose?: boolean;
   packageManager?: SupportedPackageManager;
+  env?: NodeJS.ProcessEnv;
 }
 
 /**
@@ -16,7 +17,13 @@ interface LinkPackagesToOptions
  */
 export async function linkPackageTo(
   destination: string,
-  { scopeName, packageName, verbose, packageManager }: LinkPackagesToOptions,
+  {
+    scopeName,
+    packageName,
+    verbose,
+    packageManager,
+    env,
+  }: LinkPackagesToOptions,
 ): Promise<void> {
   const fullPackageName = `${scopeName}/${packageName}`;
   // eslint-disable-next-line no-console
@@ -30,6 +37,7 @@ export async function linkPackageTo(
       name: `link_dst:${packageName}`,
       cwd: destination,
       verbose,
+      env,
     });
   } catch (_) {
     throw new Error(`Couldn't link package: ${fullPackageName}`);

tools/link/src/utils/linkPackagesForScope.ts

@@ -19,6 +19,8 @@ export async function linkPackagesForScope(
   destination: string,
   packages?: Array<string>,
   verbose?: boolean,
+  parallel?: boolean,
+  launchEnv?: NodeJS.ProcessEnv,
 ): Promise<void> {
   const node_modulesDir = path.join(destination, 'node_modules');
 
@@ -39,7 +41,11 @@ export async function linkPackagesForScope(
         installedPkg =>
           !ignorePackages.includes(installedPkg) &&
           (!packages ||
-            packages.some(pkgFlag => pkgFlag.includes(installedPkg))),
+            packages.some(
+              pkgFlag =>
+                pkgFlag === `${scopeName}/${installedPkg}` ||
+                pkgFlag === installedPkg,
+            )),
       );
 
       /** Create links */
@@ -48,17 +54,23 @@ export async function linkPackagesForScope(
           ` Creating links to ${formatLog.scope(scopeName)} packages...`,
         ),
       );
-      await Promise.all(
-        packagesToLink.map(pkg => {
-          createLinkFrom(source, {
-            scopeName,
-            scopePath,
-            packageName: pkg,
-            verbose,
-            packageManager: destinationPackageManager,
-          });
-        }),
-      );
+      const linkFromSource = (pkg: string) =>
+        createLinkFrom(source, {
+          scopeName,
+          scopePath,
+          packageName: pkg,
+          verbose,
+          packageManager: destinationPackageManager,
+          env: launchEnv,
+        });
+
+      if (parallel) {
+        await Promise.all(packagesToLink.map(linkFromSource));
+      } else {
+        for (const pkg of packagesToLink) {
+          await linkFromSource(pkg);
+        }
+      }
 
       /** Connect link */
       console.log(
@@ -68,16 +80,22 @@ export async function linkPackagesForScope(
           )} packages to ${chalk.blue(formatLog.path(destination))}...`,
         ),
       );
-      await Promise.all(
-        packagesToLink.map((pkg: string) =>
-          linkPackageTo(destination, {
-            scopeName,
-            packageName: pkg,
-            packageManager: destinationPackageManager,
-            verbose,
-          }),
-        ),
-      );
+      const linkToDestination = (pkg: string) =>
+        linkPackageTo(destination, {
+          scopeName,
+          packageName: pkg,
+          packageManager: destinationPackageManager,
+          verbose,
+          env: launchEnv,
+        });
+
+      if (parallel) {
+        await Promise.all(packagesToLink.map(linkToDestination));
+      } else {
+        for (const pkg of packagesToLink) {
+          await linkToDestination(pkg);
+        }
+      }
     } else {
       console.error(
         chalk.gray(
@@ -93,14 +111,19 @@ export async function linkPackagesForScope(
     console.error(chalk.yellow(`${formatLog.path('node_modules')} not found.`));
     // TODO: Prompt user to install instead of just running it
 
-    await installPackages(destination);
+    await installPackages(destination, {
+      verbose,
+      env: launchEnv,
+    });
 
     await linkPackagesForScope(
       { scopeName, scopePath },
       destination,
       source,
       packages,
       verbose,
+      parallel,
+      launchEnv,
     );
   }
 }