document generated tsconfig.json, move compilerOptions into user conf…

…ig (#4633) * document generated tsconfig.json * remove non-essential stuff, tweak description of importsNotUsedAsValues * add user config * update default jsconfig * simplify generated tsconfig * changeset
sveltejs · Apr 18, 2022 · 2bb2ab0 · 2bb2ab0
1 parent d3d837b
commit 2bb2ab0
Show file tree

Hide file tree

Showing 5 changed files with 91 additions and 25 deletions.
diff --git a/.changeset/sixty-seas-report.md b/.changeset/sixty-seas-report.md
@@ -0,0 +1,5 @@
+---
+'create-svelte': patch
+---
+
+[breaking] move non-essential TypeScript compilerOptions into user-editable config
diff --git a/documentation/docs/15-types.md b/documentation/docs/15-types.md
@@ -6,7 +6,7 @@ title: Types
 
 ### Generated types
 
-The [`RequestHandler`](#sveltejs-kit-requesthandler) and [`Load`](#sveltejs-kit-load) types both accept a `Params` argument allowing you to type the `params` object. For example this endpoint expects `foo`, `bar` and `baz` params:
+The `RequestHandler` and `Load` types both accept a `Params` argument allowing you to type the `params` object. For example this endpoint expects `foo`, `bar` and `baz` params:
 
 ```js
 /// file: src/routes/[foo]/[bar]/[baz].js
@@ -38,7 +38,7 @@ export type RequestHandler<Body = any> = GenericRequestHandler<
 export type Load<
 	InputProps extends Record<string, any> = Record<string, any>,
 	OutputProps extends Record<string, any> = InputProps
-> = GenericLoad<{ foo: string; bar: string; baz: string }, InputProps, OutputProps>
+> = GenericLoad<{ foo: string; bar: string; baz: string }, InputProps, OutputProps>;
 ```
 
 These files can be imported into your endpoints and pages as siblings, thanks to the [`rootDirs`](https://www.typescriptlang.org/tsconfig#rootDirs) option in your TypeScript configuration:
@@ -74,3 +74,48 @@ export async function get({ params }) {
 > For this to work, your own `tsconfig.json` or `jsconfig.json` should extend from the generated `.svelte-kit/tsconfig.json` (where `.svelte-kit` is your [`outDir`](/docs/configuration#outdir)):
 >
 >     { "extends": "./.svelte-kit/tsconfig.json" }
+
+#### Default tsconfig.json
+
+The generated `.svelte-kit/tsconfig.json` file contains a mixture of options. Some are generated programmatically based on your project configuration, and should generally not be overridden without good reason:
+
+```json
+/// file: .svelte-kit/tsconfig.json
+{
+	"compilerOptions": {
+		"baseUrl": "..",
+		"paths": {
+			"$lib": "src/lib",
+			"$lib/*": "src/lib/*"
+		},
+		"rootDirs": ["..", "./types"]
+	},
+	"include": ["../src/**/*.js", "../src/**/*.ts", "../src/**/*.svelte"],
+	"exclude": ["../node_modules/**", "./**"]
+}
+```
+
+Others are required for SvelteKit to work properly, and should also be left untouched unless you know what you're doing:
+
+```json
+/// file: .svelte-kit/tsconfig.json
+{
+	"compilerOptions": {
+		// this ensures that types are explicitly
+		// imported with `import type`, which is
+		// necessary as svelte-preprocess cannot
+		// otherwise compile components correctly
+		"importsNotUsedAsValues": "error",
+
+		// Vite compiles one TypeScript module
+		// at a time, rather than compiling
+		// the entire module graph
+		"isolatedModules": true,
+
+		// TypeScript cannot 'see' when you
+		// use an imported value in your
+		// markup, so we need this
+		"preserveValueImports": true
+	}
+}
+```
diff --git a/packages/create-svelte/shared/+checkjs/jsconfig.json b/packages/create-svelte/shared/+checkjs/jsconfig.json
@@ -1,6 +1,17 @@
 {
 	"extends": "./.svelte-kit/tsconfig.json",
 	"compilerOptions": {
-		"checkJs": true
+		"allowJs": true,
+		"checkJs": true,
+		"esModuleInterop": true,
+		"forceConsistentCasingInFileNames": true,
+		"lib": ["es2020", "DOM"],
+		"moduleResolution": "node",
+		"module": "es2020",
+		"resolveJsonModule": true,
+		"skipLibCheck": true,
+		"sourceMap": true,
+		"strict": true,
+		"target": "es2020"
 	}
 }
diff --git a/packages/create-svelte/shared/+typescript/tsconfig.json b/packages/create-svelte/shared/+typescript/tsconfig.json
@@ -1,3 +1,17 @@
 {
-	"extends": "./.svelte-kit/tsconfig.json"
+	"extends": "./.svelte-kit/tsconfig.json",
+	"compilerOptions": {
+		"allowJs": true,
+		"checkJs": true,
+		"esModuleInterop": true,
+		"forceConsistentCasingInFileNames": true,
+		"lib": ["es2020", "DOM"],
+		"moduleResolution": "node",
+		"module": "es2020",
+		"resolveJsonModule": true,
+		"skipLibCheck": true,
+		"sourceMap": true,
+		"strict": true,
+		"target": "es2020"
+	}
 }
diff --git a/packages/kit/src/core/sync/write_tsconfig.js b/packages/kit/src/core/sync/write_tsconfig.js
@@ -38,32 +38,23 @@ export function write_tsconfig(config) {
 		JSON.stringify(
 			{
 				compilerOptions: {
-					moduleResolution: 'node',
-					module: 'es2020',
-					lib: ['es2020', 'DOM'],
-					target: 'es2020',
-					// svelte-preprocess cannot figure out whether you have a value or a type, so tell TypeScript
-					// to enforce using \`import type\` instead of \`import\` for Types.
-					importsNotUsedAsValues: 'error',
-					// TypeScript doesn't know about import usages in the template because it only sees the
-					// script of a Svelte file. Therefore preserve all value imports. Requires TS 4.5 or higher.
-					preserveValueImports: true,
-					isolatedModules: true,
-					resolveJsonModule: true,
-					// To have warnings/errors of the Svelte compiler at the correct position,
-					// enable source maps by default.
-					sourceMap: true,
-					esModuleInterop: true,
-					skipLibCheck: true,
-					forceConsistentCasingInFileNames: true,
+					// generated options
 					baseUrl: config_relative('.'),
-					allowJs: true,
-					checkJs: true,
 					paths: {
 						$lib: [project_relative(config.kit.files.lib)],
 						'$lib/*': [project_relative(config.kit.files.lib + '/*')]
 					},
-					rootDirs: [config_relative('.'), './types']
+					rootDirs: [config_relative('.'), './types'],
+
+					// essential options
+					// svelte-preprocess cannot figure out whether you have a value or a type, so tell TypeScript
+					// to enforce using \`import type\` instead of \`import\` for Types.
+					importsNotUsedAsValues: 'error',
+					// Vite compiles modules one at a time
+					isolatedModules: true,
+					// TypeScript doesn't know about import usages in the template because it only sees the
+					// script of a Svelte file. Therefore preserve all value imports. Requires TS 4.5 or higher.
+					preserveValueImports: true
 				},
 				include,
 				exclude: [config_relative('node_modules/**'), './**']