Issue Reporting Overview

Relevant source files

• .devcontainer/devcontainer.json
• .github/ISSUE_TEMPLATE/bug_report.yml
• .github/ISSUE_TEMPLATE/config.yml
• .github/ISSUE_TEMPLATE/feature_request.yml
• .github/ISSUE_TEMPLATE/lib_change.yml
• .github/ISSUE_TEMPLATE/module_resolution.yml
• .github/ISSUE_TEMPLATE/other.yml
• .github/ISSUE_TEMPLATE/types-not-correct-in-with-callback.md
• .github/dependabot.yml
• .github/pull_request_template.md
• .github/workflows/close-issues.yml
• .github/workflows/pr-modified-files.yml
• CONTRIBUTING.md
• README.md
• scripts/hooks/post-checkout
• scripts/hooks/pre-commit
• scripts/link-hooks.mjs
• src/lib/README.md

This page summarizes the issue reporting process for the TypeScript repository at microsoft/TypeScript, covering the available issue templates, how to choose among them, and the automated workflows that manage issue lifecycle. It covers the mechanics of filing issues, not the process of contributing code fixes — for that, see Pull Request Process. For details on specific issue types, see Bug Reports, Feature Requests, Library Definition Changes, and Module Resolution Issues.

Note: As of late 2025, active development has moved to microsoft/typescript-go Pull requests to this repository are only merged for critical 6.x issues. Issue reporting for behavioral bugs still applies here.

---

Before Filing an Issue

CONTRIBUTING.md7-27 specifies three mandatory pre-filing steps:

Step	Action	Why
1	Read the FAQ	Many apparent bugs are documented intended behaviors
2	Search existing issues (GitHub search or site:github.com/microsoft/TypeScript <keywords>)	Avoids duplicates; search closed issues too
3	Determine if it's a question	Questions belong on Stack Overflow or the TypeScript Community Discord, not the issue tracker

Search tips from CONTRIBUTING.md16-22:

• Include closed issues in your search scope — a duplicate may have been closed under a different title.
• Search for synonyms: an issue affecting interfaces likely also affects type aliases and classes.
• For crashes, search for the topmost function names from the call stack.

---

Issue Template Reference

The repository provides structured templates under .github/ISSUE_TEMPLATE/ that GitHub enforces when creating new issues. Blank (free-form) issues are disabled via .github/ISSUE_TEMPLATE/config.yml2

Decision flowchart for selecting an issue template:

Sources: CONTRIBUTING.md1-51 .github/ISSUE_TEMPLATE/config.yml .github/ISSUE_TEMPLATE/bug_report.yml .github/ISSUE_TEMPLATE/feature_request.yml .github/ISSUE_TEMPLATE/module_resolution.yml .github/ISSUE_TEMPLATE/lib_change.yml .github/ISSUE_TEMPLATE/types-not-correct-in-with-callback.md .github/ISSUE_TEMPLATE/other.yml

---

Available Issue Templates

Template File	Display Name	Primary Use
bug_report.yml	Bug report	Compiler, checker, or language service defects
feature_request.yml	Feature request	New language or compiler features
module_resolution.yml	Module resolution	Import/resolution failures or mismatches
lib_change.yml	Library change	Fixes to lib.es*.d.ts or other built-in declarations
types-not-correct-in-with-callback.md	Types not correct in/with callback	Pre-empts duplicate reports on known narrowing behavior
other.yml	Other	Anything not captured by the above; may be closed without explanation

Sources: .github/ISSUE_TEMPLATE/

---

Template Details

Bug Report (bug_report.yml)

Required fields defined in .github/ISSUE_TEMPLATE/bug_report.yml:

Field	ID	Required
Search terms used	search_terms	Yes
Version and regression info	version_info	Yes
TypeScript Playground link	playground_link	No
Code sample	code	No
Actual behavior	actual_behavior	Yes
Expected behavior	expected_behavior	Yes

Version information guidance .github/ISSUE_TEMPLATE/bug_report.yml27-45:

• Try the nightly build (typescript@next) before filing; the bug may already be fixed.
• Use every-ts for bisecting to the specific commit that introduced the regression.
• Use the Playground to test against TypeScript versions back to 3.3.

Effective code samples .github/ISSUE_TEMPLATE/bug_report.yml66-80:

• Keep samples short (20–30 lines).
• Avoid external library dependencies; those are typically issues with the library's type definitions, not TypeScript itself.
• Make the incorrectness apparent from reading the sample alone.

Feature Request (feature_request.yml)

Feature requests must pass a viability checklist .github/ISSUE_TEMPLATE/feature_request.yml28-47 before any other fields are filled in. All six criteria are required checkboxes:

1. Not a breaking change in existing TypeScript/JavaScript code
2. Does not change the runtime behavior of existing JavaScript code
3. Can be implemented without emitting different JS based on types of expressions
4. Is not a runtime feature (library functionality, non-ECMAScript syntax, etc.)
5. Is not a request to add a new utility type
6. Agrees with the TypeScript Design Goals

Required fields: search_terms, suggestion_summary, motivating_example, use_cases.

From CONTRIBUTING.md40-51 useful content for suggestions includes:

• A description of the problem being solved
• An overview of the solution
• Code examples showing what would and would not be an error
• Code examples of generated JavaScript output (if applicable)
• Precedent from other languages

Module Resolution (module_resolution.yml)

Module resolution reports have the highest evidence burden of any template .github/ISSUE_TEMPLATE/module_resolution.yml30-39 They require:

1. A cloneable demo repository
2. A selected defect kind from a dropdown
3. A code sample demonstrating the defect
4. Output of tsc --showConfig
5. Output of tsc --traceResolution
6. package.json of the importing module
7. package.json of the target module

Key constraint: The repository must reproduce using tsc directly, not through third-party wrappers (vue-tsc, ngc, expo, etc.) .github/ISSUE_TEMPLATE/module_resolution.yml30-31

Library Change (lib_change.yml)

For issues with lib.es*.d.ts or similar built-in declaration files. Required fields are: compilation target, current library setting, description of the missing/incorrect definition, and a sample code block.

Important redirect: DOM-related declarations (lib.dom.d.ts, webworker.generated.d.ts) are maintained in the separate TypeScript-DOM-lib-generator repository. Issues about those types should be filed there. See Library Definition Changes for more detail.

Narrowing Behavior Pre-emption (types-not-correct-in-with-callback.md)

.github/ISSUE_TEMPLATE/types-not-correct-in-with-callback.md is a special template that acts as documentation rather than an intake form. It covers two behaviors that generate frequent duplicate reports but are intentional:

1. Narrowings are not respected inside callbacks — because the narrowed value could change between the narrowing check and the callback invocation.
2. Function calls do not reset narrowings — narrowings persist across calls even to functions that could theoretically mutate the narrowed value.

Both behaviors are tracked under issue #9998 New issues on this topic are typically closed as duplicates.

Other (other.yml)

.github/ISSUE_TEMPLATE/other.yml requires only an acknowledgement checkbox and a free-text comment field. Issues filed here may be closed without elaboration at maintainer discretion.

---

Automated Issue Lifecycle Management

Several automated systems act on issues after they are filed.

Auto-Close Workflow

The workflow defined in .github/workflows/close-issues.yml runs daily at 01:00 UTC. It automatically closes issues that:

• Have been open with no recent activity (no updates in the past 2 days), and
• Carry one of the following labels:

Label	Meaning
Duplicate	Same as an existing issue
Unactionable	Cannot be acted on as filed
Not a Defect	Behavior is correct
External	Problem is outside TypeScript itself
Working as Intended	Confirmed intended behavior
Question	Usage question, not a bug or suggestion
Out of Scope	Outside project design goals
Declined	Feature/fix explicitly rejected
Won't Fix	Not planned for resolution
Too Complex	Implementation complexity exceeds benefit
Design Limitation	Architectural constraint, not a defect

Closure reason is set to "not planned" with an automated comment.

Sources: .github/workflows/close-issues.yml

---

Issue Template to Code Entity Map

The following diagram maps each issue template to the code areas and external resources most relevant to investigating that class of issue.

Sources: .github/ISSUE_TEMPLATE/bug_report.yml .github/ISSUE_TEMPLATE/feature_request.yml .github/ISSUE_TEMPLATE/module_resolution.yml .github/ISSUE_TEMPLATE/lib_change.yml CONTRIBUTING.md156-174

---

Community and Questions

Questions should not be filed as issues. .github/ISSUE_TEMPLATE/config.yml presents two community links when opening an issue:

• Stack Overflow — tagged typescript
• TypeScript Community Discord — https://discord.gg/typescript

The TypeScript FAQ wiki page is also linked directly from the issue template chooser and is the first reference to consult for common scenarios before filing any issue.