feat(core): pnpm support

[erickzhao]

Closes #2633
Closes #3574

ref #3813

This PR aims to provide a basic level of pnpm support for Electron Forge.

Context

Under the hood, Forge's init and import commands use a Node.js package manager to install dependencies and otherwise execute commands. The logic is set up to use yarn if detected, and falls back to npm otherwise.

With the proliferation of alternative package managers in recent years, one of the most popular requests on our issue tracker was to support pnpm (#2633).

However, this required a decent amount of refactoring since we relied on the unmaintained (yarn-or-npm) package to perform this package manager detection. This locked us out of support for other package managers until this utility was completely refactored.

Prior art

Big thanks to @makeryi and @goosewobbler for opening their respective PRs attempting support (#3351 and #3574).

Based on their efforts, I first landed #3813, which replaces yarn-or-npm with the more generalized detect-package-manager package without changing the API signature for our utility APIs.

This PR follows that up by replacing our package manager utilities (which still only supported yarn or npm) with a generic package manager detection system that returns the current package manager as well as its associated commands and flags.

Implementation

Package manager detection

The core of this PR refactors the yarn-or-npm file in @electron-forge/core-utils to instead be a generic package-manager util.

Instead of returning just the name of the package manager, resolving which package manager to use also returns its install command as well as the command flags we may want to use.

forge/packages/utils/core-utils/src/package-manager.ts

Lines 6 to 28 in 1592d85

	export type SupportedPackageManager = 'yarn' | 'npm' | 'pnpm';
	export type PMDetails = { executable: SupportedPackageManager; install: string; dev: string; exact: string };
	const MANAGERS: Record<SupportedPackageManager, PMDetails> = {
	yarn: {
	executable: 'yarn',
	install: 'add',
	dev: '--dev',
	exact: '--exact',
	},
	npm: {
	executable: 'npm',
	install: 'install',
	dev: '--save-dev',
	exact: '--save-exact',
	},
	pnpm: {
	executable: 'pnpm',
	install: 'add',
	dev: '--save-dev',
	exact: '--save-exact',
	},
	};

Note

In theory, we could do away with these objects for now because the shorthand <pm> install -E -D works across npm, yarn, and pnpm. However, this setup future-proofs us against future commands/flags that we'd want to add that aren't necessarily compatible.

The behaviour for resolvePackageManager now differs. If an unsupported package manager is detected via NODE_INSTALLER or detect-package-manager, we default to npm instead of whatever the detected system package manager is.

This solves the case where we'd detect an unsupported package manager (e.g. bun).

node-linker=hoisted

Out of the box, pnpm provides improved disk space efficiency and install speed because it symlinks all dependencies and stores them in a central location on disk (see Motivation section of the pnpm docs for more details).

However, Forge expects node_modules to exist on disk at specific locations because we bundle all production npm dependencies into the Electron app when packaging.

To that end, we expect the config to be node-linker=hoisted when running Electron Forge. I added a clause to check-system.ts to ensure this by checking the value of pnpm config get node-linker.

forge/packages/api/cli/src/util/check-system.ts

Lines 30 to 36 in 1592d85

	async function checkPnpmNodeLinker() {
	const nodeLinkerValue = await spawnPackageManager(['config', 'get', 'node-linker']);
	if (nodeLinkerValue !== 'hoisted') {
	throw new Error('When using pnpm, `node-linker` must be set to "hoisted". Run `pnpm config set node-linker hoisted` to set this config value.');
	}
	}

This setting is added out of the box when initializing Forge templates with pnpm via .npmrc:

forge/packages/template/base/tmpl/.npmrc

Line 1 in 1592d85

node-linker = hoisted

forge/packages/template/base/src/BaseTemplate.ts

Lines 65 to 67 in 1592d85

	if (pm.executable === 'pnpm') {
	rootFiles.push('.npmrc');
	}

pnpm workspaces

I think we actually already supported pnpm workspaces via:

forge/packages/utils/core-utils/src/electron-version.ts

Lines 21 to 33 in f084010

	async function findAncestorNodeModulesPath(dir: string, packageName: string): Promise<string | undefined> {
	d('Looking for a lock file to indicate the root of the repo');
	const lockPath = await findUp(['package-lock.json', 'yarn.lock', 'pnpm-lock.yaml'], { cwd: dir, type: 'file' });
	if (lockPath) {
	d(`Found lock file: ${lockPath}`);
	const nodeModulesPath = path.join(path.dirname(lockPath), 'node_modules', packageName);
	if (await fs.pathExists(nodeModulesPath)) {
	return nodeModulesPath;
	}
	}
	return Promise.resolve(undefined);
	}

Supported pnpm version ranges

I'm not sure if v8.0.0 is a correct lower bound for pnpm, but it's the lowest version they have for their documentation so I'm assuming something has to do with their support policy.

Testing

This PR expands the existing test suite to also support pnpm (mostly in api.slow.spec.ts).

Note

Previously, we actually didn't test packaging/making for npm. This PR has the side effect of fully testing the API across all supported package managers, which does bring up the Time to Green for our CI.

[erickzhao]

Using the default reporter both gives us a clearer idea of the failures in CI and prevents us from hitting the 10-minute CircleCI no output timeout.

[erickzhao]

Could also do this in corepack in theory, but I found this to be easier to grok.

[erickzhao]

I don't know if this is necessary, but the Node compatibility matrix in the pnpm docs only lists up to pnpm 8 so I feel like this is a decent lower bound: https://pnpm.io/installation#compatibility

[erickzhao]

These functions were refactored out into a single checkPackageManager utility.

[erickzhao]

Is a change in API signatures for @electron-forge/core-utils a breaking change? If it is, I can add a temporary shim for these utils and deprecate them.