fake-timers 7.1.x编译报错：Cannot find name 'queueMicrotask' 解决方案咨询

Hey Frans, let's work through this issue step by step since you're new to Node.js—no worries, this is a common type of problem with dependency chains and TypeScript configurations!

The error Cannot find name 'queueMicrotask' happens because queueMicrotask is a relatively modern API: it was added to Node.js in v11.0.0 and to most modern browsers in recent years. The @sinonjs/fake-timers@7.1.0 type definitions reference this global directly, but your TypeScript setup isn't configured to recognize it (either because your target environment is set to an older version, or your lib configuration doesn't include the necessary API set).

Here are a few actionable fixes, ordered by how clean they are:

1. Adjust Your TypeScript Configuration (Recommended) #

This is the best approach because it doesn't require modifying your dependency tree. Open your tsconfig.json and update these settings:

• Set target to at least ES2019 (since queueMicrotask is part of the ES2019 spec)
• Ensure lib includes ES2019 (for pure Node.js projects, pair this with @types/node for full Node.js type support)

Example tsconfig.json snippet:

{
  "compilerOptions": {
    "target": "ES2019",
    "lib": ["ES2019"],
    // ... other existing options
  }
}

If you haven't already, install @types/node as a dev dependency to get complete Node.js type definitions:

npm install --save-dev @types/node

2. Force-Lock @sinonjs/fake-timers to Version 7.0.5 #

If you don't want to adjust your TS config right now, you can force your dependency chain to use the older version that doesn't have this type issue. This is low-risk since 7.0.5 → 7.1.0 is a minor version update (no breaking changes are expected in minor releases).

For Yarn users #

Add a resolutions field to your package.json:

"resolutions": {
  "@sinonjs/fake-timers": "7.0.5"
}

Then run yarn install to apply the change.

For NPM users #

NPM doesn't natively support resolutions, so you'll need a helper package:

1. Install npm-force-resolutions as a dev dependency:

   npm install --save-dev npm-force-resolutions
   

2. Add a preinstall script and resolutions field to your package.json:

   "scripts": {
     "preinstall": "npx npm-force-resolutions"
   },
   "resolutions": {
     "@sinonjs/fake-timers": "7.0.5"
   }
   

3. Run npm install to apply the resolution.

Yes, this is indeed a bug in @sinonjs/fake-timers@7.1.0's type definitions. The maintainers likely missed adding a fallback or type declaration for environments that don't support queueMicrotask yet. You can check the project's GitHub issues to see if someone has already reported this—if not, feel free to submit a bug report (it helps the community!).

Typically, these kinds of minor type bugs get fixed quickly in a patch release (like 7.1.1 or higher). Once a fixed version is available, you can remove the resolution (if you used it) and upgrade the dependency normally.

Make sure you're running a supported Node.js version (LTS versions like 18.x or 20.x are best). Older versions (pre-11.0.0) don't have queueMicrotask natively, so even if you fix the TypeScript error, you might hit runtime issues. You can check your Node.js version with node -v.

内容的提问来源于stack exchange，提问作者Frans