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:

Clear setup section in existing docs - step-by-step TypeScript + Mocha setup
Common configuration examples - working tsconfig.json and .mocharc.json examples
Troubleshooting section - solutions to the most frequent issues I've seen
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.

Nov 10 '25 07:11 ashvin2005

can you please assign me ?

Nov 10 '25 19:11 omkarhole

@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.

Nov 10 '25 20:11 JoshuaKGoldberg

Hi @JoshuaKGoldberg I’ve raised PR #5530

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

Nov 11 '25 08:11 ashvin2005

@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

Nov 11 '25 13:11 JoshuaKGoldberg

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.

Nov 21 '25 04:11 mark-wiemer

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

Nov 27 '25 14:11 JoshuaKGoldberg