Improve TypeScript setup documentation

[ashvin2005]

Improve TypeScript setup documentation

Issue

I've been using Mocha with TypeScript in several projects and noticed the documentation could be clearer for developers getting started with this combination. While the current docs mention TypeScript briefly, there's room for improvement in helping developers avoid common setup pitfalls.

Current challenges I've observed:

• Initial setup confusion: Getting ts-node working correctly with Mocha
• Configuration questions: Proper tsconfig.json settings for testing
• Type import issues: How to properly import Mocha's types
• Common errors: "Cannot find module" and compilation issues

I see these questions regularly on Stack Overflow and in Discord, which suggests the documentation could be more helpful.

What I'd like to contribute

I'd like to add a focused TypeScript setup guide that covers the most common use cases and pain points I've encountered:

1. Clear setup section in existing docs - step-by-step TypeScript + Mocha setup
2. Common configuration examples - working tsconfig.json and .mocharc.json examples
3. Troubleshooting section - solutions to the most frequent issues I've seen
4. Simple working examples - a few practical test files that demonstrate the setup

This would be focused and practical rather than comprehensive - just enough to get developers past the initial hurdles.

Why this would be helpful

From my experience and what I've seen in community discussions:

• Reduces the "TypeScript + Mocha not working" support questions
• Gets developers productive faster with a working setup
• Shows Mocha works great with TypeScript (which isn't always obvious)
• Could reduce some of the migration to other test runners

Implementation approach

I'm thinking of a focused addition to the existing documentation rather than a massive overhaul:

• Add a "TypeScript" section to the current docs
• Include 2-3 working configuration examples
• Add a simple troubleshooting section for common issues
• Maybe add one or two example test files to the examples directory

I'd keep it concise and maintainable - just covering the essential setup that trips people up.

Would this kind of documentation addition be welcome? I'm happy to work on it if the maintainers think it would be useful.

I can start with a simple setup guide and see how that goes, or if you have specific areas you'd like me to focus on, I'm open to suggestions.

[omkarhole]

can you please assign me ?

[JoshuaKGoldberg]

@ashvin2005 thanks for the suggestion. I agree with the high-level idea, having specific callouts for something very common like TypeScript does seem like an omission to me. The report has a lot of high-level points that could use some more details, so going through the specific implementation notes in order...

Add a "TypeScript" section to the current docs

👍 from me. +1 that especially now that Node.js has native type stripping support, this should help folks who're used to using ts-node/tsx/etc.

Add 2-3 working configuration examples
Maybe add one or two example test files to the examples directory

http://github.com/mochajs/mocha-examples has four, what specifically would you like to see covered that's not yet?

(n.b. they do look out of date; I think updating them would be a good separate issue from this too ~ https://github.com/mochajs/mocha-examples/issues)

Add a simple troubleshooting section for common issues

What common issues are you thinking of?

---

@omkarhole please see https://github.com/mochajs/mocha/blob/main/.github/CONTRIBUTING.md. Once issues are labeled with status: accepting prs they can be worked on by anybody. We don't have any kind of assignment system.

[ashvin2005]

Hi @JoshuaKGoldberg
I’ve raised PR #5530

Please review it when you get a chance and merge if everything looks good. Thanks!

[JoshuaKGoldberg]

@ashvin2005 let's wait just a bit, I want to give a other members of the Mocha team time to lend their opinions here too. 🙂 I appreciate the enthusiasm, though!

Just quickly looking at #5530, a few notes:

• You don't need to be so verbose in your issue & PR descriptions.
  • If I had to guess, I'd say you were authoring them with AI? I'd strongly recommend seeing how other issues & PRs in this repository look -especially those filed recently and/or by team members- and aligning yours with their level of clarity and verbosity.
• There are quite a few ways to run Mocha with TypeScript, including some I mentioned in my first response. ts-node is not the latest and greatest. You'll want to study up on them.
  • I believe "just" using Node.js-native type stripping is now preferred over ts-node, as it's built-in, faster, etc.
  • I suspect the guide should mention a few different approaches as "alternately, you might want these" - and list their pros & cons

[mark-wiemer]

Yes, I think this is a good idea, let's limit this for now to a simple "hello world" with TypeScript using Node.js-native type stripping, plus a link to the mocha-examples typescript package. If there are specific "gotchas" beyond that feel free to call them out here and we can see whether they should be in the site itself or in a new mocha-examples package.

[JoshuaKGoldberg]

Marking as accepting PRs. @ashvin2005 what do you think about our last two comments?