📝 Docs: Explain pnpm and declaration emit awkwardness

[danvk]

Bug Report Checklist

• I have tried restarting my IDE and the issue persists.
• I have pulled the latest main branch of the repository.
• I have searched for related issues and found none that matched my issue.

Expected

I expected to be able to define a helper module that imported vitest without error:

import { vi } from "vitest";

export const mockError = () =>
	vi.spyOn(console, "error").mockImplementation(() => undefined);

Actual

I got an extremely cryptic error:

import { vi } from "vitest";

export const mockError = () =>
//           ~~~~~~~~~
// The inferred type of 'mockError' cannot be named without a reference to 
// '.pnpm/@[email protected]/node_modules/@vitest/spy'.
// This is likely not portable. A type annotation is necessary. ts(2742)
	vi.spyOn(console, "error").mockImplementation(() => undefined);

Additional Info

Here's an example of this error happening:

• failing build: https://github.com/danvk/gravlax/actions/runs/7545323899/job/20540667198
• failing commit: danvk/gravlax@86b060c

The gist seems to be that declaration: true and pnpm don't work very well together. There are many, many issues about this on the TypeScript issue tracker. The original is microsoft/TypeScript#29808.

This seems to be the canonical comment discussing workarounds: microsoft/TypeScript#47663 (comment)

In my case I just turned off .d.ts emit, though this isn't ideal.

Dropping pnpm seems a little drastic, but this isn't great and create-typescript-app pushes you towards this error with its defaults. At the very least there could be something about this in the FAQ. A link to that comment in particular would have saved me some time today.

[JoshuaKGoldberg]

A link to that comment in particular would have saved me some time today.

Yeah 😬 as you said, this is really a TypeScript limitation with pnpm-style linking and I don't have any great workarounds myself. I think the right resolution would be a docs issue.

For visibility to any readers: what's happening here is TypeScript thinks it can't reasonably generate a .d.ts file that contains the mockError. This is because...

1. mockError's type comes from the "vitest" package
2. "vitest" is not an explicit dependency of the published package (just a devDependency)
3. TypeScript is complaining that the published .d.ts file would need to refer to a package that may not exist in scope when referencing

In other words, TypeScript thinks mockError might be used by production consumers (it doesn't know it's test-only and not exported through the index.ts).

[JoshuaKGoldberg]

@all-contributors please add @danvk for ideas.

🤖 Beep boop! This comment was added automatically by all-contributors-auto-action.
Not all contributions can be detected from Git & GitHub alone. Please comment any missing contribution types this bot missed.
...and of course, thank you for contributing! 💙

[allcontributors]

@JoshuaKGoldberg

I've put up a pull request to add @danvk! 🎉

I couldn't determine any contributions to add, did you specify any contributions?
Please make sure to use valid contribution names.