Do not throw away tsconfig.json comments (#13458)

This pull request updates our TypeScript verification process to not wipe out potentially vital user comments.

Introducing a prompt process was mostly a side effect of users wanting to keep comments.
There's no reason we really need this prompt, as answering no would refuse to boot the Next.js server anyway.

---

Fixes #8128
Closes #11440

packages/next/compiled/comment-json/LICENSE

@@ -0,0 +1,21 @@
+Copyright (c) 2013 kaelzhang <>, contributors
+http://kael.me/
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

packages/next/compiled/comment-json/package.json

@@ -0,0 +1 @@
+{"name":"comment-json","main":"index.js","author":"kaelzhang","license":"MIT"}

packages/next/lib/verifyTypeScriptSetup.ts

@@ -1,19 +1,13 @@
+import { promises as fsPromises } from 'fs'
+import { writeFile } from 'fs-extra'
 import chalk from 'next/dist/compiled/chalk'
-import fs from 'fs'
+import * as CommentJson from 'next/dist/compiled/comment-json'
 import os from 'os'
 import path from 'path'
-
 import { fileExists } from './file-exists'
 import { recursiveReadDir } from './recursive-readdir'
 import { resolveRequest } from './resolve-request'
 
-function writeJson(fileName: string, object: object): Promise<void> {
-  return fs.promises.writeFile(
-    fileName,
-    JSON.stringify(object, null, 2).replace(/\n/g, os.EOL) + os.EOL
-  )
-}
-
 async function hasTypeScript(dir: string): Promise<boolean> {
   const typescriptFiles = await recursiveReadDir(
     dir,
@@ -105,7 +99,7 @@ export async function verifyTypeScriptSetup(
 
   let firstTimeSetup = false
   if (hasTsConfig) {
-    const tsConfig = await fs.promises
+    const tsConfig = await fsPromises
       .readFile(tsConfigPath, 'utf8')
       .then((val) => val.trim())
     firstTimeSetup = tsConfig === '' || tsConfig === '{}'
@@ -176,13 +170,11 @@ export async function verifyTypeScriptSetup(
     )
     console.log()
 
-    await writeJson(tsConfigPath, {})
+    await writeFile(tsConfigPath, '{}' + os.EOL)
   }
 
-  const messages = []
-  let appTsConfig
-  let parsedTsConfig
-  let parsedCompilerOptions
+  let resolvedTsConfig
+  let resolvedCompilerOptions
   try {
     const { config: readTsConfig, error } = ts.readConfigFile(
       tsConfigPath,
@@ -193,14 +185,14 @@ export async function verifyTypeScriptSetup(
       throw new Error(ts.formatDiagnostic(error, formatDiagnosticHost))
     }
 
-    appTsConfig = readTsConfig
+    resolvedTsConfig = readTsConfig
 
     // Get TS to parse and resolve any "extends"
     // Calling this function also mutates the tsconfig, adding in "include" and
     // "exclude", but the compilerOptions remain untouched
-    parsedTsConfig = JSON.parse(JSON.stringify(readTsConfig))
+    const throwAwayConfig = JSON.parse(JSON.stringify(readTsConfig))
     const result = ts.parseJsonConfigFileContent(
-      parsedTsConfig,
+      throwAwayConfig,
       ts.sys,
       path.dirname(tsConfigPath)
     )
@@ -219,7 +211,7 @@ export async function verifyTypeScriptSetup(
       )
     }
 
-    parsedCompilerOptions = result.options
+    resolvedCompilerOptions = result.options
   } catch (e) {
     if (e && e.name === 'SyntaxError') {
       console.error(
@@ -236,28 +228,33 @@ export async function verifyTypeScriptSetup(
     return
   }
 
-  if (appTsConfig.compilerOptions == null) {
-    appTsConfig.compilerOptions = {}
+  const userTsConfigContent = await fsPromises.readFile(tsConfigPath, {
+    encoding: 'utf8',
+  })
+  const userTsConfig = CommentJson.parse(userTsConfigContent)
+  if (userTsConfig.compilerOptions == null) {
+    userTsConfig.compilerOptions = {}
     firstTimeSetup = true
   }
 
+  const messages = []
   for (const option of Object.keys(compilerOptions)) {
     const { parsedValue, value, suggested, reason } = compilerOptions[option]
 
     const valueToCheck = parsedValue === undefined ? value : parsedValue
     const coloredOption = chalk.cyan('compilerOptions.' + option)
 
     if (suggested != null) {
-      if (parsedCompilerOptions[option] === undefined) {
-        appTsConfig.compilerOptions[option] = suggested
+      if (resolvedCompilerOptions[option] === undefined) {
+        userTsConfig.compilerOptions[option] = suggested
         messages.push(
           `${coloredOption} to be ${chalk.bold(
             'suggested'
           )} value: ${chalk.cyan.bold(suggested)} (this can be changed)`
         )
       }
-    } else if (parsedCompilerOptions[option] !== valueToCheck) {
-      appTsConfig.compilerOptions[option] = value
+    } else if (resolvedCompilerOptions[option] !== valueToCheck) {
+      userTsConfig.compilerOptions[option] = value
       messages.push(
         `${coloredOption} ${chalk.bold(
           valueToCheck == null ? 'must not' : 'must'
@@ -268,12 +265,12 @@ export async function verifyTypeScriptSetup(
   }
 
   // tsconfig will have the merged "include" and "exclude" by this point
-  if (parsedTsConfig.exclude == null) {
-    appTsConfig.exclude = ['node_modules']
+  if (resolvedTsConfig.exclude == null) {
+    userTsConfig.exclude = ['node_modules']
   }
 
-  if (parsedTsConfig.include == null) {
-    appTsConfig.include = ['next-env.d.ts', '**/*.ts', '**/*.tsx']
+  if (resolvedTsConfig.include == null) {
+    userTsConfig.include = ['next-env.d.ts', '**/*.ts', '**/*.tsx']
   }
 
   if (messages.length > 0) {
@@ -299,13 +296,17 @@ export async function verifyTypeScriptSetup(
       })
       console.warn()
     }
-    await writeJson(tsConfigPath, appTsConfig)
+    await fsPromises.writeFile(
+      tsConfigPath,
+      CommentJson.stringify(userTsConfig, null, 2) + os.EOL
+    )
   }
 
   // Reference `next` types
   const appTypeDeclarations = path.join(dir, 'next-env.d.ts')
-  if (!fs.existsSync(appTypeDeclarations)) {
-    fs.writeFileSync(
+  const hasAppTypeDeclarations = await fileExists(appTypeDeclarations)
+  if (!hasAppTypeDeclarations) {
+    await fsPromises.writeFile(
       appTypeDeclarations,
       '/// <reference types="next" />' +
         os.EOL +

packages/next/package.json

@@ -126,6 +126,7 @@
     "@types/babel__template": "7.0.2",
     "@types/babel__traverse": "7.0.10",
     "@types/ci-info": "2.0.0",
+    "@types/comment-json": "1.1.1",
     "@types/compression": "0.0.36",
     "@types/content-type": "1.1.3",
     "@types/cookie": "0.3.3",
@@ -166,6 +167,7 @@
     "cache-loader": "4.1.0",
     "chalk": "2.4.2",
     "ci-info": "watson/ci-info#f43f6a1cefff47fb361c88cf4b943fdbcaafe540",
+    "comment-json": "3.0.2",
     "compression": "1.7.4",
     "conf": "5.0.0",
     "content-type": "1.0.4",

packages/next/taskfile.js

@@ -517,6 +517,14 @@ export async function ncc_terser_webpack_plugin(task, opts) {
     .target('compiled/terser-webpack-plugin')
 }
 
+externals['comment-json'] = 'next/dist/compiled/comment-json'
+export async function ncc_comment_json(task, opts) {
+  await task
+    .source(opts.src || relative(__dirname, require.resolve('comment-json')))
+    .ncc({ packageName: 'comment-json', externals })
+    .target('compiled/comment-json')
+}
+
 externals['path-to-regexp'] = 'next/dist/compiled/path-to-regexp'
 export async function path_to_regexp(task, opts) {
   await task
@@ -592,6 +600,7 @@ export async function ncc(task) {
       'ncc_webpack_dev_middleware',
       'ncc_webpack_hot_middleware',
       'ncc_terser_webpack_plugin',
+      'ncc_comment_json',
     ])
 }
 

packages/next/types/misc.d.ts

@@ -220,6 +220,10 @@ declare module 'next/dist/compiled/terser-webpack-plugin' {
   import m from 'terser-webpack-plugin'
   export = m
 }
+declare module 'next/dist/compiled/comment-json' {
+  import m from 'comment-json'
+  export = m
+}
 
 declare module 'autodll-webpack-plugin' {
   import webpack from 'webpack'