From 8bd90e4d87a22c61ed1cdc5e06b29bba51bfe427 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Fran=C3=A7ois=20Moreau?= <grillonbleu@gmail.com>
Date: Wed, 14 May 2025 10:34:31 -0400
Subject: [PATCH] Clarify allowed syntax in tsconfig.json
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

It would be helpful to explicitly state the syntax tsconfig.json affords. The most official reference I’ve found about comments being allowed is [TypeScript issue 4987](https://github.com/Microsoft/TypeScript/issues/4987) being tagged "fixed". For trailing comments, the best I’ve found is [a comment](https://github.com/microsoft/TypeScript/issues/20384#issuecomment-348552936).

Comments are quite valuable in config files and that possibility deserves to be better known. Furthermore this undocumented leniency has tripped up IDEs in the past, validating `tsconfig.json` as strict JSON.
---
 .../copy/en/project-config/tsconfig.json.md   | 24 +++++++++++++++++++
 1 file changed, 24 insertions(+)

diff --git a/packages/documentation/copy/en/project-config/tsconfig.json.md b/packages/documentation/copy/en/project-config/tsconfig.json.md
index 8bfc6c7cc0e6..5e0af0fad2d3 100644
--- a/packages/documentation/copy/en/project-config/tsconfig.json.md
+++ b/packages/documentation/copy/en/project-config/tsconfig.json.md
@@ -102,6 +102,30 @@ The `"compilerOptions"` property can be omitted, in which case the compiler's de
 
 To learn more about the hundreds of configuration options in the [TSConfig Reference](/tsconfig).
 
+## File format
+
+`tsconfig.json` files are interpreted as JSON with some exceptions:
+
+* Both single line `//` and multiline `/* ... */` comments are allowed.
+* Trailing commas are allowed as well.
+
+```json tsconfig
+{
+  /**
+   * This is a valid tsconfig.json
+   */
+  "extends": "@tsconfig/node12/tsconfig.json",
+
+  "compilerOptions": {
+    "preserveConstEnums": true, // Do not erase const enum declarations in generated code.
+  },
+
+  "include": ["src/**/*"],
+  "exclude": ["**/*.spec.ts"],
+}
+```
+
+
 ## Schema
 
 The `tsconfig.json` Schema can be found at [the JSON Schema Store](http://json.schemastore.org/tsconfig).