docs: add TypeScript setup guide

[ashvin2005]

Add documentation for using Mocha with TypeScript to help developers avoid common setup issues.

• Add TypeScript configuration examples
• Include basic test examples
• Cover common troubleshooting issues
• Add package.json and tsconfig.json templates

This addresses frequent questions about TypeScript setup that come up in issues and community discussions.

---

PR Checklist

• [x] Addresses an existing open issue: fixes #5529
• [x] That issue was marked as status: accepting prs
• [x] Steps in CONTRIBUTING.md were taken

---

Overview

This PR introduces a new “TypeScript Setup” section in Mocha’s documentation that provides a step-by-step guide for integrating Mocha with TypeScript.

The new content includes:

• Example configurations for tsconfig.json, .mocharc.json, and test scripts
• Sample TypeScript test files demonstrating setup and execution
• A troubleshooting section covering common TypeScript-related issues (e.g., “Cannot find module”, missing type definitions, and ts-node configuration)

This documentation aims to make it easier for developers—especially newcomers—to quickly get Mocha running in TypeScript projects without encountering common configuration pitfalls.

[linux-foundation-easycla[bot]]

The committers listed above are authorized under a signed CLA.

• :white_check_mark: login: ashvin2005 / name: Ashvin Tiwari (3e973822ae879a6741988dad0f1c02e2b4903219, edcf3fce66941b50a54e26086fe819cb79e846a8, f15c57666bbd8ca5a31b597492c3c809ae4630fd)

[mark-wiemer]

At the highest level, we'll want these docs to be present in both the current site and the new site (https://mochajs.org/next), you can refer to the PRs around https://github.com/mochajs/mocha/issues/5248 for reference

[JoshuaKGoldberg]

👋 Just checking in @ashvin2005, is this still something you have time for?

[ashvin2005]

Hi, @mark-wiemer , I've added the TypeScript documentation to both the current docs site and the new docs-next site as requested. The docs are now available in:

• docs/typescript.md (current site)
• docs-next/src/content/docs/explainers/typescript.mdx (new site)

Both contain the same content but formatted appropriately for each documentation system.

[mark-wiemer]

Thanks @ashvin2005 , is this still a draft PR or is it ready for review?

[codecov[bot]]

Codecov Report

:white_check_mark: All modified and coverable lines are covered by tests. :white_check_mark: Project coverage is 93.52%. Comparing base (9cc3ada) to head (3e97382).

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #5530   +/-   ##
=======================================
  Coverage   93.52%   93.52%           
=======================================
  Files          57       57           
  Lines        4465     4465           
  Branches      918      918           
=======================================
  Hits         4176     4176           
  Misses        289      289           

:umbrella: View full report in Codecov by Sentry.
:loudspeaker: Have feedback on the report? Share it here.

:rocket: New features to boost your workflow:

• :snowflake: Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• :package: JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[JoshuaKGoldberg]

Just a heads up, I don't think ready for re-review as https://github.com/mochajs/mocha/issues/5529#issuecomment-3513860936 has not been addressed.

[ashvin2005]

Hi @JoshuaKGoldberg @mark-wiemer,

I've updated the docs based on your feedback.